@markuplint/ml-spec 3.0.0-canary.5 → 3.0.0-dev.176

package/src/dom-traverse/get-computed-role.ts

@@ -1,181 +0,0 @@
-import type { ARIAVersion, ComputedRole, MLMLSpec } from '../types';
-
-import { ariaSpecs } from '../specs/aria-specs';
-import { isPresentational } from '../specs/is-presentational';
-
-import { getAttrSpecs } from './get-attr-specs';
-import { getExplicitRole } from './get-explicit-role';
-import { getImplicitRole } from './get-implicit-role';
-import { getNonPresentationalAncestor } from './get-non-presentational-ancestor';
-import { isRequiredOwnedElement } from './has-required-owned-elements';
-import { mayBeFocusable } from './may-be-focusable';
-
-export function getComputedRole(specs: Readonly<MLMLSpec>, el: Element, version: ARIAVersion): ComputedRole {
-	const implicitRole = getImplicitRole(specs, el, version);
-	const explicitRole = getExplicitRole(specs, el, version);
-	const computedRole = explicitRole.role ? explicitRole : implicitRole;
-
-	/**
-	 * Presentational Roles Conflict Resolution
-	 *
-	 * @see https://www.w3.org/TR/wai-aria/#conflict_resolution_presentation_none
-	 * @see https://w3c.github.io/aria/#conflict_resolution_presentation_none
-	 */
-
-	/**
-	 * > If the action of exposing the explicit role
-	 * > causes the accessibility tree to be malformed,
-	 * > the expected results are undefined.
-	 *
-	 * Determines whether the context is valid.
-	 * ⚠ THE SPECIFICATION HAS AN ISSUE
-	 * that has not decided whether the context is a parent or an ancestor.
-	 *
-	 * @see https://github.com/w3c/aria/issues/1033
-	 * @see https://github.com/w3c/aria/issues/748
-	 * @see https://github.com/w3c/aria/pull/1162
-	 * @see https://github.com/w3c/aria/pull/1213
-	 *
-	 * Currently, this process interprets that as A PARENT
-	 * because it wants to be near to HTML semantics.
-	 * However, the presentational role behaves transparently
-	 * according to the sample code in WAI-ARIA specification.
-	 */
-	if (computedRole.role?.requiredContextRole.length) {
-		const nonPresentationalAncestor = getNonPresentationalAncestor(el, specs, version);
-		if (!nonPresentationalAncestor.role) {
-			return {
-				el,
-				role: null,
-				errorType: 'NO_OWNER',
-			};
-		}
-		if (!computedRole.role?.requiredContextRole.includes(nonPresentationalAncestor.role.name)) {
-			return {
-				el,
-				role: null,
-				errorType: 'INVALID_REQUIRED_CONTEXT_ROLE',
-			};
-		}
-	}
-
-	if (computedRole.role && !isPresentational(computedRole.role.name)) {
-		return computedRole;
-	}
-
-	/**
-	 * > If an element is focusable,
-	 * > user agents MUST ignore the presentation/none role
-	 * > and expose the element with its implicit role,
-	 * > in order to ensure that the element is operable.
-	 *
-	 * With the issue: What does focusable or otherwise interactive mean](https://github.com/w3c/aria/issues/1192)
-	 *
-	 * - Focus: https://html.spec.whatwg.org/multipage/interaction.html#focus
-	 * - Interactive content: https://html.spec.whatwg.org/multipage/dom.html#interactive-content
-	 */
-	if (
-		/**
-		 * If interactive element
-		 *
-		 * 1. It may be focusable
-		 *
-		 * THIS CONDITION IS ALMOST MEANINGLESS.
-		 * Because it has already been determined that
-		 * the interactive elements can not specify the presentational role
-		 * in the previous processing that computes the permitted role (`getExplicitRole`).
-		 */
-		mayBeFocusable(el, specs) &&
-		/**
-		 * 2. No disabled
-		 */
-		!someAncestors(el, p => isEnabledAttr(p, specs, 'disabled')) &&
-		/**
-		 * 3. No inert
-		 */
-		!someAncestors(el, p => isEnabledAttr(p, specs, 'inert')) &&
-		/**
-		 * 4. No hidden
-		 */
-		!someAncestors(el, p => isEnabledAttr(p, specs, 'hidden'))
-	) {
-		return {
-			...implicitRole,
-			errorType: 'INTERACTIVE_ELEMENT_MUST_NOT_BE_PRESENTATIONAL',
-		};
-	}
-
-	/**
-	 * > If a required owned element has an explicit non-presentational role,
-	 * > user agents MUST ignore an inherited presentational role
-	 * > and expose the element with its explicit role.
-	 *
-	 * In other words,
-	 * if the element has `role=presentation` and
-	 * the role of the parent element has a required owned element,
-	 * `role=presentation` is to be ignored absolutely.
-	 */
-	if (explicitRole.role) {
-		const nonPresentationalAncestor = getNonPresentationalAncestor(el, specs, version);
-		if (nonPresentationalAncestor.role?.requiredOwnedElements.length) {
-			if (
-				nonPresentationalAncestor.role.requiredOwnedElements.some(expected => {
-					// const ancestor = nonPresentationalAncestor.el;
-					// const ancestorImplicitRole = getImplicitRole(specs, ancestor, version);
-					// console.log({ nonPresentationalAncestor, ancestorImplicitRole });
-					return isRequiredOwnedElement(implicitRole, expected, specs, version);
-				})
-			) {
-				return {
-					...implicitRole,
-					errorType: 'REQUIRED_OWNED_ELEMENT_MUST_NOT_BE_PRESENTATIONAL',
-				};
-			}
-		}
-	}
-
-	/**
-	 * > If an element has global WAI-ARIA states or properties,
-	 * > user agents MUST ignore the presentation role
-	 * > and instead expose the element's implicit role.
-	 * > However, if an element has only non-global,
-	 * > role-specific WAI-ARIA states or properties,
-	 * > the element MUST NOT be exposed
-	 * > unless the presentational role is inherited
-	 * > and an explicit non-presentational role is applied.
-	 */
-	const { props } = ariaSpecs(specs, version);
-	for (const attr of Array.from(el.attributes)) {
-		if (props.find(p => p.name === attr.name)?.isGlobal) {
-			return {
-				...implicitRole,
-				errorType: 'GLOBAL_PROP_MUST_NOT_BE_PRESENTATIONAL',
-			};
-		}
-	}
-
-	return computedRole;
-}
-
-/**
- * The attribute is available in its owner element,
- * it has the attribute.
- */
-function isEnabledAttr(el: Element, specs: MLMLSpec, attrName: string) {
-	const attrs = getAttrSpecs(el, specs);
-	const attr = attrs?.find(attr => attr.name === attrName);
-	return !!attr && el.hasAttribute(attrName);
-}
-
-/**
- * Determines whether some ancestors match the condition that the specified callback function.
- */
-function someAncestors(el: Element, predicate: (ancestor: Element) => boolean) {
-	const list: Element[] = [];
-	let current: Element | null = el;
-	while (current) {
-		list.push(current);
-		current = current.parentElement;
-	}
-	return list.some(predicate);
-}

package/src/dom-traverse/get-content-model.ts

@@ -1,32 +0,0 @@
-import type { ElementSpec } from '../types';
-import type { PermittedContentPattern } from '../types/permitted-structures';
-
-import { getSpec } from './get-spec';
-
-type Specs = Pick<ElementSpec, 'name' | 'contentModel'>[];
-
-const cachesBySpecs = new Map<Specs, Map<Element, PermittedContentPattern[] | boolean | null>>();
-export function getContentModel(el: Element, specs: Pick<ElementSpec, 'name' | 'contentModel'>[]) {
-	const cacheByEl = cachesBySpecs.get(specs) ?? new Map<Element, PermittedContentPattern[] | boolean>();
-	const cached = cacheByEl.get(el);
-	if (cached) {
-		return cached;
-	}
-
-	const spec = getSpec<'contentModel'>(el, specs);
-	if (!spec) {
-		cacheByEl.set(el, null);
-		return null;
-	}
-
-	const conditions = spec.contentModel.conditional ?? [];
-	for (const cond of conditions) {
-		if (el.matches(cond.condition)) {
-			cacheByEl.set(el, cond.contents);
-			return cond.contents;
-		}
-	}
-
-	cacheByEl.set(el, spec.contentModel.contents);
-	return spec.contentModel.contents;
-}

package/src/dom-traverse/get-explicit-role.ts

@@ -1,112 +0,0 @@
-import type { ARIAVersion, ComputedRole, MLMLSpec, RoleComputationError } from '../types';
-
-import { getRoleSpec } from '../specs/get-role-spec';
-import { resolveNamespace } from '../utils/resolve-namespace';
-
-import { getPermittedRoles } from './get-permitted-roles';
-
-export function getExplicitRole(specs: MLMLSpec, el: Element, version: ARIAVersion): ComputedRole {
-	const roleValue = el.getAttribute('role');
-	const roleNames = roleValue?.toLowerCase().trim().split(/\s+/g) || [];
-	const permittedRoles = getPermittedRoles(el, version, specs);
-	const { namespaceURI } = resolveNamespace(el.localName, el.namespaceURI);
-
-	let error: RoleComputationError = 'NO_EXPLICIT';
-
-	/**
-	 * Resolve from values and **Handling Author Errors**
-	 *
-	 * @see https://w3c.github.io/aria/#document-handling_author-errors_roles
-	 */
-	for (const roleName of roleNames) {
-		const spec = getRoleSpec(specs, roleName, namespaceURI, version);
-
-		/**
-		 * If `spec` is null, the role DOES NOT EXIST.
-		 *
-		 * > If the role attribute contains no tokens matching the name
-		 * > of a non-abstract WAI-ARIA role,
-		 * > the user agent MUST treat the element as
-		 * > if no role had been provided. For example,
-		 * > <table role="foo"> should be exposed
-		 * > in the same way as <table> and <input type="text" role="structure">
-		 * > in the same way as <input type="text">.
-		 */
-		if (!spec) {
-			error = 'ROLE_NO_EXISTS';
-			continue;
-		}
-
-		/**
-		 * > As stated in the Definition of Roles section,
-		 * > it is considered an authoring error to use abstract roles in content.
-		 * > User agents MUST NOT map abstract roles
-		 * > via the standard role mechanism of the accessibility API.
-		 */
-		if (spec.isAbstract) {
-			error = 'ABSTRACT';
-			continue;
-		}
-
-		/**
-		 * Whether the role is the permitted role according to ARIA in HTML.
-		 */
-		if (!permittedRoles.some(r => r.name === roleName)) {
-			error = 'NO_PERMITTED';
-			continue;
-		}
-
-		/**
-		 * > Certain landmark roles require names from authors.
-		 * > In situations where an author has not specified names for these landmarks,
-		 * > it is considered an authoring error.
-		 * > The user agent MUST treat such elements as if no role had been provided.
-		 * > If a valid fallback role had been specified,
-		 * > or if the element had an implicit ARIA role,
-		 * > then user agents would continue to expose that role, instead.
-		 */
-		if (isLandmarkRole(spec) && !isValidLandmarkRole(el, spec)) {
-			error = 'INVALID_LANDMARK';
-			continue;
-		}
-
-		/**
-		 * Otherwise
-		 */
-		return {
-			el,
-			role: {
-				...spec,
-				isImplicit: false,
-			},
-		};
-	}
-
-	return {
-		el,
-		role: null,
-		errorType: error,
-	};
-}
-
-function isLandmarkRole(role: NonNullable<ReturnType<typeof getRoleSpec>>) {
-	return role?.superClassRoles.some(su => su.name === 'landmark');
-}
-
-function isValidLandmarkRole(el: Element, role: NonNullable<ReturnType<typeof getRoleSpec>>) {
-	if (!role.accessibleNameRequired) {
-		return true;
-	}
-	if (role.accessibleNameFromAuthor) {
-		if (el.getAttribute('aria-label')) {
-			return true;
-		}
-		const id = el.getAttribute('aria-labelledby');
-		if (id && el.ownerDocument.getElementById(id)) {
-			return true;
-		}
-	}
-	// The landmark role does not require names from the content
-	// if (role.accessibleNameFromContent) {}
-	return false;
-}

package/src/dom-traverse/get-implicit-role.ts

@@ -1,36 +0,0 @@
-import type { ARIAVersion, ComputedRole, MLMLSpec } from '../types';
-
-import { getImplicitRole as _getImplicitRole } from '../specs/get-implicit-role';
-import { getRoleSpec } from '../specs/get-role-spec';
-import { resolveNamespace } from '../utils/resolve-namespace';
-
-export function getImplicitRole(specs: Readonly<MLMLSpec>, el: Element, version: ARIAVersion): ComputedRole {
-	const implicitRole = getImplicitRoleName(el, version, specs);
-	if (implicitRole === false) {
-		// No Corresponding Role
-		return {
-			el,
-			role: null,
-		};
-	}
-	const { namespaceURI } = resolveNamespace(el.localName, el.namespaceURI);
-	const spec = getRoleSpec(specs, implicitRole, namespaceURI, version);
-	if (!spec) {
-		return {
-			el,
-			role: null,
-			errorType: 'IMPLICIT_ROLE_NAMESPACE_ERROR',
-		};
-	}
-	return {
-		el,
-		role: {
-			...spec,
-			isImplicit: true,
-		},
-	};
-}
-
-export function getImplicitRoleName(el: Element, version: ARIAVersion, specs: Readonly<MLMLSpec>) {
-	return _getImplicitRole(specs, el.localName, el.namespaceURI, version, el.matches.bind(el));
-}

package/src/dom-traverse/get-non-presentational-ancestor.ts

@@ -1,20 +0,0 @@
-import type { ARIAVersion, MLMLSpec } from '../types';
-
-import { isPresentational } from '../specs/is-presentational';
-
-import { getComputedRole } from './get-computed-role';
-
-export function getNonPresentationalAncestor(el: Element, specs: MLMLSpec, version: ARIAVersion) {
-	let ancestor: Element | null = el.parentElement;
-	while (ancestor) {
-		const ancestorRole = getComputedRole(specs, ancestor, version);
-		if (!isPresentational(ancestorRole.role?.name)) {
-			return ancestorRole;
-		}
-		ancestor = ancestor.parentElement;
-	}
-	return {
-		el: ancestor,
-		role: null,
-	};
-}

package/src/dom-traverse/get-permitted-roles.ts

@@ -1,7 +0,0 @@
-import type { ARIAVersion, MLMLSpec } from '../types';
-
-import { getPermittedRoles as _getPermittedRoles } from '../specs/get-permitted-roles';
-
-export function getPermittedRoles(el: Element, version: ARIAVersion, specs: Readonly<MLMLSpec>) {
-	return _getPermittedRoles(specs, el.localName, el.namespaceURI, version, el.matches.bind(el));
-}

package/src/dom-traverse/get-spec.ts

@@ -1,7 +0,0 @@
-import type { ElementSpec } from '../types';
-
-import { getSpecByTagName } from '../specs/get-spec-by-tag-name';
-
-export function getSpec<K extends keyof ElementSpec>(el: Element, specs: Pick<ElementSpec, 'name' | K>[]) {
-	return getSpecByTagName(specs, el.localName, el.namespaceURI);
-}

package/src/dom-traverse/has-required-owned-elements.ts

@@ -1,85 +0,0 @@
-import type { ARIAVersion, ComputedRole, MLMLSpec } from '../types';
-
-import { isPresentational } from '../specs/is-presentational';
-
-import { getComputedRole } from './get-computed-role';
-import { getExplicitRole } from './get-explicit-role';
-import { getImplicitRole } from './get-implicit-role';
-
-export function hasRequiredOwnedElement(el: Element, specs: Readonly<MLMLSpec>, version: ARIAVersion): boolean {
-	/**
-	 * The element has aria-owns which means it may have owned elements.
-	 *
-	 * THIS CONDITION IS PARTIAL SUPPORT.
-	 */
-	if (el.hasAttribute('aria-owns')) {
-		// FIXME
-		return true;
-	}
-
-	/**
-	 * Otherwise, traverses descendants to find owned elements.
-	 */
-	const computed = getComputedRole(specs, el, version);
-	if (!computed.role || computed.role.requiredOwnedElements.length === 0) {
-		return true;
-	}
-	for (const expectRole of computed.role.requiredOwnedElements) {
-		for (const owned of getClosestNonPresentationalDescendants(el, specs, version)) {
-			if (isRequiredOwnedElement(owned, expectRole, specs, version)) {
-				return true;
-			}
-		}
-	}
-
-	return false;
-}
-
-export function isRequiredOwnedElement(owned: ComputedRole, query: string, specs: MLMLSpec, version: ARIAVersion) {
-	const [baseRole, owningRole] = query.split(' > ') as [string, string | undefined];
-	if (owned.role?.name !== baseRole) {
-		return false;
-	}
-
-	if (!owningRole) {
-		return true;
-	}
-
-	for (const owning of getClosestNonPresentationalDescendants(owned.el, specs, version)) {
-		if (owning.role?.name === owningRole) {
-			return true;
-		}
-	}
-
-	return false;
-}
-
-/**
- * Gets the list of closest non-presentational descendants.
- * ⚠ THE SPECIFICATION HAS AN ISSUE
- * that has not decided whether the owned element is a child or a descendant.
- *
- * @see https://github.com/w3c/aria/issues/1033
- * @see https://github.com/w3c/aria/issues/748
- * @see https://github.com/w3c/aria/pull/1162
- * @see https://github.com/w3c/aria/pull/1213
- *
- * Currently, this process interprets that as A CHILD
- * because it wants to be near to HTML semantics.
- * However, the presentational role behaves transparently
- * according to the sample code in WAI-ARIA specification.
- */
-function getClosestNonPresentationalDescendants(el: Element, specs: MLMLSpec, version: ARIAVersion): ComputedRole[] {
-	const owned: ComputedRole[] = [];
-	for (const child of Array.from(el.children)) {
-		const implicitRole = getImplicitRole(specs, child, version);
-		const explicitRole = getExplicitRole(specs, child, version);
-		const computed = explicitRole.role ? explicitRole : implicitRole;
-		if (isPresentational(computed.role?.name)) {
-			owned.push(...getClosestNonPresentationalDescendants(child, specs, version));
-			continue;
-		}
-		owned.push({ ...computed, el: child });
-	}
-	return owned;
-}

package/src/dom-traverse/is-exposed.ts

@@ -1,196 +0,0 @@
-import type { ARIAVersion, MLMLSpec } from '../types';
-
-import { ariaSpecs } from '../specs/aria-specs';
-import { isPalpableElement } from '../specs/is-palpable-elements';
-import { isPresentational } from '../specs/is-presentational';
-
-import { getComputedRole } from './get-computed-role';
-
-/**
- * Detect including/excluding from the Accessibility Tree
- *
- * @see https://www.w3.org/TR/wai-aria-1.2/#accessibility_tree
- *
- * @param specs
- * @param el
- * @param version
- */
-export function isExposed(el: Element, specs: Readonly<MLMLSpec>, version: ARIAVersion): boolean {
-	// According to WAI-ARIA
-	if (isExcluding(el, specs, version)) {
-		return false;
-	}
-
-	// According to HTML and SVG Specs with **the author's interpretation**
-	{
-		if (!isPalpableElement(el, specs, { extendsSvg: true, extendsExposableElements: true })) {
-			return false;
-		}
-	}
-
-	// According to WAI-ARIA
-	{
-		const exposable = isIncluding(el, specs, version);
-		if (exposable) {
-			return true;
-		}
-	}
-
-	// Default
-	return true;
-}
-
-/**
- * Excluding Elements from the Accessibility Tree
- *
- * @see https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion
- *
- * @param specs
- * @param el
- * @param version
- */
-function isExcluding(el: Element, specs: Readonly<MLMLSpec>, version: ARIAVersion): boolean {
-	/**
-	 * The following elements are not exposed via the accessibility API and
-	 * user agents MUST NOT include them in the accessibility tree:
-	 * - Elements, including their descendent elements,
-	 *   that have host language semantics specifying
-	 *   that the element is not displayed, such as CSS display:none,
-	 *   visibility:hidden, or the HTML hidden attribute.
-	 */
-	{
-		let currentEl: Element | null = el;
-		while (currentEl) {
-			if (hasDisplayNodeOrVisibilityHidden(currentEl) || currentEl.hasAttribute('hidden')) {
-				return true;
-			}
-			currentEl = currentEl.parentElement;
-		}
-	}
-
-	/**
-	 * - Elements with none or presentation as the first role in the role attribute.
-	 *   However, their exclusion is conditional. In addition,
-	 *   the element's descendants and text content are generally included.
-	 *   These exceptions and conditions are documented in the presentation (role)
-	 *   section.
-	 */
-	if (isPresentational((el.getAttribute('role') || '').split(/\s+/)[0])) {
-		return true;
-	}
-
-	/**
-	 * If not already excluded from the accessibility tree per the above rules,
-	 * user agents SHOULD NOT include the following elements
-	 * in the accessibility tree:
-	 * - Elements, including their descendants, that have aria-hidden set to true.
-	 *   In other words, aria-hidden="true" on a parent overrides aria-hidden="false"
-	 *   on descendants.
-	 */
-	{
-		let currentEl: Element | null = el;
-		while (currentEl) {
-			if (currentEl.getAttribute('aria-hidden') === 'true') {
-				return true;
-			}
-			currentEl = currentEl.parentElement;
-		}
-	}
-
-	/**
-	 * - Any descendants of elements that have the characteristic
-	 *   "Children Presentational: True" unless the descendant
-	 *   is not allowed to be presentational because it meets one of
-	 *   the conditions for exception described in
-	 *   Presentational Roles Conflict Resolution.
-	 *   However, the text content of any excluded descendants is included.
-	 */
-	{
-		let currentEl = el.parentElement;
-		while (currentEl) {
-			const { role } = getComputedRole(specs, currentEl, version);
-			if (role?.childrenPresentational) {
-				return true;
-			}
-			currentEl = currentEl.parentElement;
-		}
-	}
-
-	return false;
-}
-
-/**
- * Including Elements in the Accessibility Tree
- *
- * If not excluded from or marked as hidden in the accessibility tree
- * per the rules above in Excluding Elements in the Accessibility Tree,
- * user agents MUST provide an accessible object in the accessibility tree
- * for DOM elements that meet any of the following criteria:
- *
- * @see https://www.w3.org/TR/wai-aria-1.2/#tree_inclusion
- *
- * @param specs
- * @param el
- * @param version
- */
-function isIncluding(el: Element, specs: Readonly<MLMLSpec>, version: ARIAVersion): boolean {
-	/**
-	 * > **meet any** of the following criteria:
-	 */
-	const results: boolean[] = [];
-
-	/**
-	 * Elements that are not hidden and may fire an accessibility API event,
-	 * including:
-	 * - Elements that are currently focused, even if the element or one of
-	 *   its ancestor elements has its aria-hidden attribute set to true.
-	 */
-	// 🚫 Can't detect the element is focused.
-	// results.push(true);
-
-	/**
-	 * - Elements that are a valid target of an aria-activedescendant attribute.
-	 */
-	// TODO: Compute aria-activedescendant.
-	// results.push(true);
-
-	/**
-	 * Elements that have an explicit role or a global WAI-ARIA attribute and
-	 * do not have aria-hidden set to true.
-	 * (See Excluding Elements in the Accessibility Tree for
-	 * additional guidance on aria-hidden.)
-	 */
-	if (el.getAttribute('aria-hidden') !== 'true') {
-		const globalAria = ariaSpecs(specs, version).props.filter(prop => prop.isGlobal);
-		const { role } = getComputedRole(specs, el, version);
-		// Has an explicit role
-		if (role && !role.isImplicit) {
-			results.push(true);
-		}
-		// Has a global WAI-ARIA attribute
-		for (const attr of Array.from(el.attributes)) {
-			if (globalAria.some(aria => aria.name === attr.localName)) {
-				results.push(true);
-				break;
-			}
-		}
-	}
-
-	/**
-	 * Elements that are not hidden and have an ID that is referenced
-	 * by another element via a WAI-ARIA property.
-	 */
-	// TODO: Compute refering ID.
-	// results.push(true);
-
-	return results.includes(true);
-}
-
-function hasDisplayNodeOrVisibilityHidden(el: Element) {
-	const style = el.getAttribute('style');
-	if (!style) {
-		return false;
-	}
-	// TODO: Improve accuracy
-	return /display\s*:\s*none|visibility\s*:\s*hidden/gi.test(style);
-}