Typing and code improvements

[Jym77]

Typing, type safety, modularity, …

• Remove Err#get and Ok#getErr
  Add getUnsafe instead.

• Consider storing string literals duplicated in multiple places as string constants, like URLs like "about:blank"

• Export Diagnostic subclasses from alfa-rules, not just the is* functions.

• Add Maybe.toOption or similar way to convert from Maybe to Option

• Adding a D extends Diagnostic to rules
  Most classes in alfa-act wrap a Diagnostic (Outcomes, Question), or will produce one (Rule). We should add a type parameter D extends Diagnostic to these and make sure it is correctly propagated.

  This would ensure better type safety for consumers. Among other, if we change the specific diagnostic produced by a rule, a consumer with old code of an Outcome<… D …> (produced by a Rule<… D …>) would cause type mismatch when trying to consume an Outcome<… D' …> and avoid runtime error by trying to access fields that have changed.

  We might even be able to have several diagnostic parameters for rules and separate based on which outcome is produced.

• Collection predicates (every, …) should accept Refinement, not just Predicate; also need to be done for Array.

• Add a Teeable type for type who support .tee(callback), probably require Functor, Applicative, and extended types to also extend Teeable.

• Use import type where relevant to limit risks of circular imports (and make the intend obvious).

• Use exports maps in package.json files to force restrict the exposed API and enforce ADR 7. See package entry points.

  • Use imports from self-module rather than ../dist in tests.

• Export Question.Data from alfa-rules so it can be used by consumers (e.g. access the list of URI as a value, not just a type).

CSS polish and Math support

• Rework the registering of properties in a more straightforward way; should allow to update to TS 5.

• Add proper hashing to CSS Math expressions
  Currently doing nothing, need to hash Expression so that we can hash Calculation correctly.

• CSS Math expressions that are reduced to a Value should be turned into CSSValue(…) rather than Math(Value(…))

• Create an abstraction for Length | Math value (plus resolver) (same with other numeric types and combination with percentages). Maybe in alfa-style if not alfa-css. This would effectively solve Support calc() expressions in all properties #1202.

API improvements

• Turn isNone, isSome, … into getters?
  Or even into properties to avoid the function call altogether, although it is fairly inexpensive…

• We could have Open and Close be parametric in the type of delimiter (Open<Parenthesis>, …), likely with an Enum somewhere. That would enable us to have the type system enforce matching open and close delimiters.

  alfa/packages/alfa-css/src/syntax/block.ts

  Lines 87 to 98 in 24de3ed

  	export type Open =
  	| Token.OpenParenthesis
  	| Token.OpenSquareBracket
  	| Token.OpenCurlyBracket;
  	/**
  	* The tokens that are allowed to close a block.
  	*/
  	export type Close =
  	| Token.CloseParenthesis
  	| Token.CloseSquareBracket
  	| Token.CloseCurlyBracket;

• Had a wrapper Option = None | Some type so that !foo.isNone() correctly narrows to Some.

• Factor in a getElementById or equivalent, so we can cache the map; it is currently used when looking for aria-owns, when looking for aria-labelledby, and when looking for ID ref list attributes in R19.

• Replace usages of elementDescendants() with Query.getElementDescendants()

Polishing code, unifying standards

• Tests clean-up
  Many tests on attributes use a const target = element.attribute("foo").getUnsafe() structure that could be build bottom-up instead.

• We have a lot of rules targeting the full document using the same pattern:

  return fold(
    hasChild(isDocumentElement),
    () => [document],
    () => [],
    document
    );

  and it seems to be our main use of both hasChild and isDocumentElement.
  We should make a getDocumentElement helper to capture this pattern, likely of type Document => Option<Element>.

• hasDisplaySize should have proper overloads.

• hasInlineStyleProperty could be overloaded to also accept Predicate<Property.Name>, and several Property.Name (pass if all are declared in style).

• hasTextContent could be overloaded to accept a list of strings (pass if one of them exactly matches the text content).

• hasTabIndex could be overloaded to accept a list of numbers (pass if the tabindex is one of those)

• isIncludedInTheAccessibilityTree = not(isIgnored) could be introduced since it matches the rules better, and is how it's used most of the time. We might even want to get rid of isIgnored and directly write isIncludedInTheAccessibilityTree (inlining the negation).

• Remove useless layer of empty arg from hasUniqueId (turn it from a void => Predicate<Element> to a Predicate<Element>, aka Element => boolean).

• getOffsetParent: move definition of isStatic and isFixed together with isBody and isTabular. Not doable as they depend on device.

• R75 expectation could use both hasCascadedStyle and hasComputedStyle (and may need a hasSpecifiedStyle to be really clean).

• isPerceivable can use hasInclusiveDescendant.

• Go through all the parsers in alfa-css to see if they can be simplified and rewritten in terms of other parsers like delimited, option etc.

• Consider moving optional parameters into an options object or similar in

  alfa/packages/alfa-dom/src/h.ts

  Lines 36 to 38 in e7eaf8e

  	attributes?: Array<Attribute> | Record<string, string | boolean>,
  	children?: Array<Node | string>,
  	style?: Array<Declaration> | Record<string, string>

• Consider returning Result rather than Option in case of missing layout: Use layout to improve handling of interposed elements #1464 (comment)

• Incorporate WithFirstHeading into WithOtherHeading:

  alfa/packages/alfa-rules/src/sia-r61/rule.ts

  Line 83 in 77cdcc8

  export class WithFirstHeading extends Diagnostic {

Done

• alfa-rules/Flattened.Rule is ill named
  The union type of all rules (currently Flattened.Rule) should be moved out of the Flattened namespace. The flattened type of a rule (currently act.Rule<Input, Target, Question, Subject>) should instead be Flattened.Rule (with the union moved on the parameters).

• isTransparent can use hasComputedStyle.

• isInert could use hasComputedStyle.

• R71, R72, R85 could use hasComputedStyle.

• R74, R80 could likely use hasCascadedStyle.

• Updating to TS ⩾ 4.8.3 should let us clean https://github.com/Siteimprove/alfa/blob/main/packages/alfa-dom/src/jsx.ts#L34-L36

• Proper hash of Outcome

• Hide access to underlying array of Slice to avoid incorrect usage. Slice already exposes the necessary functionality for reading like get, first, rest etc. so no direct access to the underlying array should ever be needed. In particular the array property should not be visible and potentially we should not expose offset as well:

  alfa/packages/alfa-slice/src/slice.ts

  Lines 48 to 54 in 7c45b01

  	public get array(): ReadonlyArray<T> {
  	return this._array;
  	}
  	public get offset(): number {
  	return this._offset;
  	}