vigla 0.0.0 → 0.2.0

package/src/compiler/analysis/validate/a11y/attributes.ts

@@ -0,0 +1,252 @@
+import { aria, type ARIAProperty, type ARIAPropertyDefinition } from 'aria-query';
+import type { Node, Property } from '../../../ir/nodes.ts';
+import type { Report } from '../report.ts';
+import {
+	isDisabled,
+	isHidden,
+	list,
+	parentIs,
+	staticValue,
+	type Facts,
+	type Static
+} from './facts.ts';
+import { closest } from './fuzzy.ts';
+import {
+	ariaRoles,
+	implicitRole,
+	isAbstract,
+	isInteractive,
+	isKnown,
+	isNonInteractive,
+	isPresentation,
+	isSemanticRoleElement,
+	requiredProps,
+	roleTokens,
+	type Interactivity
+} from './roles.ts';
+import {
+	ariaAttributeSet,
+	ariaAttributes,
+	interactiveHandlers,
+	interactiveRoleExceptions,
+	invisibleElements,
+	nestedImplicitSemantics
+} from './tables.ts';
+
+const heading = /^h[1-6]$/;
+const whitespace = /\s+/;
+
+export interface Pass {
+	readonly facts: Facts;
+	readonly interactivity: Interactivity;
+	readonly path: readonly Node[];
+	readonly report: Report;
+}
+
+function quoted(values: readonly (string | number | boolean)[]): string {
+	return list(values.map((value) => `"${value}"`));
+}
+
+function checkValue(
+	attribute: Property,
+	name: string,
+	schema: ARIAPropertyDefinition,
+	found: Static,
+	report: Report
+): void {
+	if (found === null) return;
+	const value = found === true ? '' : found;
+	const args = { attribute: name };
+	switch (schema.type) {
+		case 'id':
+		case 'string':
+			if (value === '') {
+				report.warn('a11y_incorrect_aria_attribute_type', attribute, {
+					...args,
+					type: 'non-empty string'
+				});
+			}
+			break;
+		case 'number':
+			if (value === '' || Number.isNaN(+value)) {
+				report.warn('a11y_incorrect_aria_attribute_type', attribute, { ...args, type: 'number' });
+			}
+			break;
+		case 'boolean':
+			if (value !== 'true' && value !== 'false') {
+				report.warn('a11y_incorrect_aria_attribute_type_boolean', attribute, args);
+			}
+			break;
+		case 'idlist':
+			if (value === '') report.warn('a11y_incorrect_aria_attribute_type_idlist', attribute, args);
+			break;
+		case 'integer':
+			if (value === '' || !Number.isInteger(+value)) {
+				report.warn('a11y_incorrect_aria_attribute_type_integer', attribute, args);
+			}
+			break;
+		case 'token': {
+			const values = (schema.values ?? []).map(String);
+			if (!values.includes(value.toLowerCase())) {
+				report.warn('a11y_incorrect_aria_attribute_type_token', attribute, {
+					...args,
+					values: quoted(values)
+				});
+			}
+			break;
+		}
+		case 'tokenlist': {
+			const values = (schema.values ?? []).map(String);
+			if (
+				value
+					.toLowerCase()
+					.split(whitespace)
+					.some((token) => !values.includes(token))
+			) {
+				report.warn('a11y_incorrect_aria_attribute_type_tokenlist', attribute, {
+					...args,
+					values: quoted(values)
+				});
+			}
+			break;
+		}
+		case 'tristate':
+			if (value !== 'true' && value !== 'false' && value !== 'mixed') {
+				report.warn('a11y_incorrect_aria_attribute_type_tristate', attribute, args);
+			}
+			break;
+	}
+}
+
+function checkAria(attribute: Property, name: string, pass: Pass): void {
+	const { facts, report } = pass;
+	if (invisibleElements.has(facts.name)) {
+		report.warn('a11y_aria_attributes', attribute, { name: facts.name });
+	}
+	const type = name.slice(5);
+	if (!ariaAttributeSet.has(type)) {
+		report.warn('a11y_unknown_aria_attribute', attribute, {
+			attribute: type,
+			suggestion: closest(type, ariaAttributes)
+		});
+	}
+	if (name === 'aria-hidden' && heading.test(facts.name)) {
+		report.warn('a11y_hidden', attribute, { name: facts.name });
+	}
+	const schema = aria.get(name as ARIAProperty);
+	if (schema !== undefined) checkValue(attribute, name, schema, staticValue(attribute), report);
+	if (
+		name === 'aria-activedescendant' &&
+		!facts.dynamic &&
+		pass.interactivity !== 'interactive' &&
+		!facts.map.has('tabindex') &&
+		!facts.spread
+	) {
+		report.warn('a11y_aria_activedescendant_has_tabindex', attribute);
+	}
+}
+
+function checkRoleToken(attribute: Property, role: string, pass: Pass): void {
+	const { facts, report } = pass;
+	const name = facts.name;
+	if (role && isAbstract(role)) {
+		report.warn('a11y_no_abstract_role', attribute, { role });
+	} else if (role && !isKnown(role)) {
+		report.warn('a11y_unknown_role', attribute, { role, suggestion: closest(role, ariaRoles) });
+	}
+
+	if (
+		role === implicitRole(facts) &&
+		!['ul', 'ol', 'li', 'menu'].includes(name) &&
+		!((name === 'a' || name === 'area') && !facts.map.has('href'))
+	) {
+		report.warn('a11y_no_redundant_roles', attribute, { role });
+	}
+	if (!parentIs(pass.path, ['section', 'article']) && role === nestedImplicitSemantics.get(name)) {
+		report.warn('a11y_no_redundant_roles', attribute, { role });
+	}
+
+	if (!facts.dynamic && !isSemanticRoleElement(role, facts)) {
+		const required = requiredProps(role);
+		if (
+			required !== undefined &&
+			!facts.spread &&
+			required.some((prop) => !facts.attributes.some((other) => other.name === prop))
+		) {
+			report.warn('a11y_role_has_required_aria_props', attribute, {
+				role,
+				props: list(
+					required.map((prop) => `"${prop}"`),
+					'and'
+				)
+			});
+		}
+	}
+
+	const interactive = pass.interactivity === 'interactive';
+	if (
+		!facts.spread &&
+		!isDisabled(facts) &&
+		!isHidden(facts) &&
+		!isPresentation(role) &&
+		isInteractive(role) &&
+		pass.interactivity === 'static' &&
+		!facts.map.get('tabindex') &&
+		[...facts.handlers].some((handler) => interactiveHandlers.has(handler))
+	) {
+		report.warn('a11y_interactive_supports_focus', facts.element, { role });
+	}
+	if (!facts.spread && interactive && (isNonInteractive(role) || isPresentation(role))) {
+		report.warn('a11y_no_interactive_element_to_noninteractive_role', facts.element, {
+			element: name,
+			role
+		});
+	}
+	if (
+		!facts.spread &&
+		pass.interactivity === 'non-interactive' &&
+		isInteractive(role) &&
+		!interactiveRoleExceptions.get(name)?.has(role)
+	) {
+		report.warn('a11y_no_noninteractive_element_to_interactive_role', facts.element, {
+			element: name,
+			role
+		});
+	}
+}
+
+export function checkAttributes(pass: Pass): void {
+	const { facts, report } = pass;
+	for (const attribute of facts.element.attributes) {
+		if (attribute.kind !== 'attribute') continue;
+		const name = attribute.name.toLowerCase();
+		if (name.startsWith('aria-')) checkAria(attribute, name, pass);
+		switch (name) {
+			case 'role': {
+				if (invisibleElements.has(facts.name)) {
+					report.warn('a11y_misplaced_role', attribute, { name: facts.name });
+				}
+				const value = staticValue(attribute);
+				if (typeof value !== 'string') break;
+				for (const role of roleTokens(value)) checkRoleToken(attribute, role, pass);
+				break;
+			}
+			case 'accesskey':
+				report.warn('a11y_accesskey', attribute);
+				break;
+			case 'autofocus':
+				if (facts.name !== 'dialog' && !parentIs(pass.path, ['dialog'])) {
+					report.warn('a11y_autofocus', attribute);
+				}
+				break;
+			case 'scope':
+				if (!facts.dynamic && facts.name !== 'th') report.warn('a11y_misplaced_scope', attribute);
+				break;
+			case 'tabindex': {
+				const value = Number(staticValue(attribute));
+				if (!Number.isNaN(value) && value > 0) report.warn('a11y_positive_tabindex', attribute);
+				break;
+			}
+		}
+	}
+}

package/src/compiler/analysis/validate/a11y/axobject-query.d.ts

@@ -0,0 +1,20 @@
+declare module 'axobject-query' {
+	interface Concept {
+		readonly name: string;
+		readonly attributes?: readonly { readonly name: string; readonly value?: string }[];
+	}
+
+	interface AXObject {
+		readonly type: string;
+	}
+
+	interface MapLike<Key, Value> {
+		entries(): [Key, Value][];
+		get(key: Key): Value | undefined;
+		keys(): Key[];
+	}
+
+	export const AXObjects: MapLike<string, AXObject>;
+	export const AXObjectRoles: MapLike<string, Set<{ readonly name: string }>>;
+	export const elementAXObjects: MapLike<Concept, Set<string>>;
+}

package/src/compiler/analysis/validate/a11y/elements.ts

@@ -0,0 +1,241 @@
+import type { DynamicElement, Element, Fragment, Node } from '../../../ir/nodes.ts';
+import type { Pass } from './attributes.ts';
+import { parentIs, staticText, staticValue, type Facts } from './facts.ts';
+import {
+	addressTypeTokens,
+	autofillContactFieldNameTokens,
+	autofillFieldNameTokens,
+	contactTypeTokens,
+	distractingElements,
+	headings,
+	labelable,
+	requiredAttributes
+} from './tables.ts';
+
+const javascriptUrl = /^\W*javascript:/i;
+const redundantAlt = /\b(image|picture|photo)\b/i;
+const notWhitespace = /[^ \t\r\n]/;
+const whitespace = /\s+/;
+
+function children(node: Node): readonly Fragment[] {
+	switch (node.kind) {
+		case 'element':
+		case 'component':
+		case 'dynamic-element':
+		case 'keyed-block':
+		case 'boundary':
+		case 'snippet':
+		case 'special':
+			return [node.body];
+		case 'branch':
+			return [...node.arms.map((arm) => arm.body), ...(node.fallback ? [node.fallback] : [])];
+		case 'keyed-list':
+		case 'unkeyed-list':
+			return node.fallback ? [node.body, node.fallback] : [node.body];
+		case 'async-block':
+			return [node.pending, node.resolved?.body, node.rejected?.body].filter(
+				(fragment): fragment is Fragment => fragment != null
+			);
+		case 'slot':
+			return [node.fallback];
+		default:
+			return [];
+	}
+}
+
+function hasAttribute(element: Element | DynamicElement, name: string): boolean {
+	return element.attributes.some(
+		(attribute) => attribute.kind === 'attribute' && attribute.name === name
+	);
+}
+
+function hasContent(element: Element | DynamicElement): boolean {
+	for (const node of element.body.nodes) {
+		if (node.kind === 'text' && node.data.trim() === '') continue;
+		if (node.kind === 'element' || node.kind === 'dynamic-element') {
+			if (hasAttribute(node, 'popover')) continue;
+			if (node.kind === 'element' && node.name === 'img' && hasAttribute(node, 'alt')) return true;
+			if (node.kind === 'element' && node.name === 'selectedcontent') return true;
+			if (!hasContent(node)) continue;
+		}
+		return true;
+	}
+	return false;
+}
+
+function hasControl(fragment: Fragment): boolean {
+	const pending: Fragment[] = [fragment];
+	for (let current = pending.pop(); current !== undefined; current = pending.pop()) {
+		for (const node of current.nodes) {
+			switch (node.kind) {
+				case 'dynamic-element':
+				case 'slot':
+				case 'component':
+				case 'render':
+					return true;
+				case 'element':
+					if (labelable.has(node.name) || node.name === 'slot') return true;
+			}
+			pending.push(...children(node));
+		}
+	}
+	return false;
+}
+
+function validAutocomplete(value: string | true | null): boolean {
+	if (value === true) return false;
+	if (!value) return true;
+	const tokens = value.trim().toLowerCase().split(whitespace);
+	let at = 0;
+	if (tokens[at]?.startsWith('section-')) at++;
+	if (addressTypeTokens.has(tokens[at] as string)) at++;
+	if (autofillFieldNameTokens.has(tokens[at] as string)) {
+		at++;
+	} else {
+		if (contactTypeTokens.has(tokens[at] as string)) at++;
+		if (!autofillContactFieldNameTokens.has(tokens[at] as string)) return false;
+		at++;
+	}
+	if (tokens[at] === 'webauthn') at++;
+	return at >= tokens.length;
+}
+
+function missing(pass: Pass, attributes: readonly string[], name = pass.facts.name): void {
+	const first = attributes[0] as string;
+	const article = /^[aeiou]/.test(first) || first === 'href' ? 'an' : 'a';
+	const sequence =
+		attributes.length > 1 ? `${attributes.slice(0, -1).join(', ')} or ${attributes.at(-1)}` : first;
+	pass.report.warn('a11y_missing_attribute', pass.facts.element, { name, article, sequence });
+}
+
+function labelled(facts: Facts): boolean {
+	return facts.map.has('aria-label') || facts.map.has('aria-labelledby') || facts.map.has('title');
+}
+
+function checkLink(pass: Pass): void {
+	const { facts, report } = pass;
+	const { element, map } = facts;
+	const hidden =
+		staticValue(map.get('aria-hidden')) === 'true' || staticValue(map.get('inert')) !== null;
+	if (!facts.spread && !hidden && !labelled(facts) && !hasContent(element)) {
+		report.warn('a11y_consider_explicit_label', element);
+	}
+	if (facts.name === 'button') return;
+	const href = map.get('href') || map.get('xlink:href');
+	if (href) {
+		const value = staticText(href);
+		if (value !== null && (value === '' || value === '#' || javascriptUrl.test(value))) {
+			report.warn('a11y_invalid_attribute', href, { href_value: value, href_attribute: href.name });
+		}
+	} else if (
+		!facts.spread &&
+		!staticValue(map.get('id')) &&
+		!staticValue(map.get('name')) &&
+		staticValue(map.get('aria-disabled')) !== 'true'
+	) {
+		missing(pass, ['href']);
+	}
+}
+
+function checkInput(pass: Pass): void {
+	const { facts, report } = pass;
+	const type = facts.map.get('type');
+	const typeValue = staticText(type);
+	if (typeValue === 'image' && !facts.spread) {
+		const required = ['alt', 'aria-label', 'aria-labelledby'];
+		if (!required.some((name) => facts.map.has(name)))
+			missing(pass, required, 'input type="image"');
+	}
+	const autocomplete = facts.map.get('autocomplete');
+	if (type && autocomplete) {
+		const value = staticValue(autocomplete);
+		if (!validAutocomplete(value)) {
+			report.warn('a11y_autocomplete_valid', autocomplete, {
+				value: String(value),
+				type: typeValue ?? '...'
+			});
+		}
+	}
+}
+
+function checkVideo(pass: Pass): void {
+	const { facts, report } = pass;
+	const hidden = facts.map.get('aria-hidden');
+	if (facts.map.has('muted') || (hidden && staticValue(hidden) === 'true') || facts.spread) return;
+	if (!facts.map.has('src')) return;
+	const track = facts.element.body.nodes.find(
+		(node): node is Element => node.kind === 'element' && node.name === 'track'
+	);
+	const captioned =
+		track?.attributes.some(
+			(attribute) =>
+				attribute.kind === 'spread' ||
+				(attribute.kind === 'attribute' &&
+					attribute.name === 'kind' &&
+					staticValue(attribute) === 'captions')
+		) ?? false;
+	if (!captioned) report.warn('a11y_media_has_caption', facts.element);
+}
+
+function checkFigure(pass: Pass): void {
+	const visible = pass.facts.element.body.nodes.filter(
+		(node) => node.kind !== 'comment' && (node.kind !== 'text' || notWhitespace.test(node.data))
+	);
+	const index = visible.findIndex((node) => node.kind === 'element' && node.name === 'figcaption');
+	if (index > 0 && index !== visible.length - 1) {
+		pass.report.warn('a11y_figcaption_index', visible[index] as Node);
+	}
+}
+
+export function checkElementRules(pass: Pass): void {
+	const { facts, report } = pass;
+	const { element, name } = facts;
+	switch (name) {
+		case 'a':
+		case 'button':
+			checkLink(pass);
+			break;
+		case 'input':
+			checkInput(pass);
+			break;
+		case 'img': {
+			const alt = staticText(facts.map.get('alt'));
+			const hidden = staticValue(facts.map.get('aria-hidden'));
+			if (alt && !hidden && !facts.spread && redundantAlt.test(alt)) {
+				report.warn('a11y_img_redundant_alt', element);
+			}
+			break;
+		}
+		case 'label':
+			if (!facts.spread && !facts.map.has('for') && !hasControl(element.body)) {
+				report.warn('a11y_label_has_associated_control', element);
+			}
+			break;
+		case 'video':
+			checkVideo(pass);
+			break;
+		case 'figcaption':
+			if (!parentIs(pass.path, ['figure'])) report.warn('a11y_figcaption_parent', element);
+			break;
+		case 'figure':
+			checkFigure(pass);
+			break;
+	}
+
+	if (!facts.spread && name !== 'a') {
+		const required = requiredAttributes.get(name);
+		if (required !== undefined && !required.some((attribute) => facts.map.has(attribute))) {
+			missing(pass, required);
+		}
+	}
+	if (distractingElements.has(name)) report.warn('a11y_distracting_elements', element, { name });
+	if (
+		!facts.spread &&
+		!labelled(facts) &&
+		!facts.contenteditableBinding &&
+		headings.has(name) &&
+		!hasContent(element)
+	) {
+		report.warn('a11y_missing_content', element, { name });
+	}
+}

package/src/compiler/analysis/validate/a11y/facts.ts

@@ -0,0 +1,102 @@
+import type { DynamicElement, Element, Node, Property } from '../../../ir/nodes.ts';
+import { nameOf } from '../report.ts';
+import { contentEditableBindings } from './tables.ts';
+
+export type Static = string | true | null;
+
+export function staticValue(attribute: Property | undefined): Static {
+	if (attribute === undefined) return null;
+	const value = attribute.value;
+	if (value.kind === 'boolean') return true;
+	if (value.kind === 'text' && value.parts.length === 1 && value.parts[0]?.kind === 'text') {
+		return value.parts[0].data;
+	}
+	return null;
+}
+
+export function staticText(attribute: Property | undefined): string | null {
+	const value = staticValue(attribute);
+	return value === true ? null : value;
+}
+
+export function isEvent(attribute: Property): boolean {
+	return attribute.value.kind === 'expression' && attribute.name.startsWith('on');
+}
+
+export interface Facts {
+	readonly element: Element | DynamicElement;
+	readonly name: string;
+	readonly dynamic: boolean;
+	readonly map: ReadonlyMap<string, Property>;
+	readonly attributes: readonly Property[];
+	readonly handlers: ReadonlySet<string>;
+	readonly spread: boolean;
+	readonly contenteditable: boolean;
+	readonly contenteditableBinding: boolean;
+}
+
+export function elementName(element: Element | DynamicElement): string {
+	return element.kind === 'element' ? element.name : nameOf('element');
+}
+
+export function collect(element: Element | DynamicElement): Facts {
+	const map = new Map<string, Property>();
+	const attributes: Property[] = [];
+	const handlers = new Set<string>();
+	let spread = false;
+	let contenteditable = false;
+	let contenteditableBinding = false;
+	for (const attribute of element.attributes) {
+		if (attribute.kind === 'attribute') {
+			if (isEvent(attribute)) {
+				handlers.add(attribute.name.slice(2));
+			} else {
+				attributes.push(attribute);
+				map.set(attribute.name, attribute);
+				if (attribute.name === 'contenteditable') contenteditable = true;
+			}
+		} else if (attribute.kind === 'spread') {
+			spread = true;
+		} else if (attribute.kind === 'binding' && contentEditableBindings.has(attribute.name)) {
+			contenteditableBinding = true;
+		}
+	}
+	return {
+		element,
+		name: elementName(element),
+		dynamic: element.kind === 'dynamic-element',
+		map,
+		attributes,
+		handlers,
+		spread,
+		contenteditable,
+		contenteditableBinding
+	};
+}
+
+export function isHidden(facts: Facts): boolean {
+	if (facts.name === 'input' && staticValue(facts.map.get('type')) === 'hidden') return true;
+	const hidden = facts.map.get('aria-hidden');
+	if (hidden === undefined) return false;
+	const value = staticValue(hidden);
+	return value === null || value === true || value === 'true';
+}
+
+export function isDisabled(facts: Facts): boolean {
+	if (staticValue(facts.map.get('disabled'))) return true;
+	return staticValue(facts.map.get('aria-disabled')) === 'true';
+}
+
+export function parentIs(path: readonly Node[], names: readonly string[]): boolean {
+	for (let index = path.length - 1; index >= 0; index--) {
+		const parent = path[index];
+		if (parent?.kind === 'dynamic-element') return true;
+		if (parent?.kind === 'element') return names.includes(parent.name);
+	}
+	return false;
+}
+
+export function list(strings: readonly string[], conjunction = 'or'): string {
+	if (strings.length < 3) return strings.join(` ${conjunction} `);
+	return `${strings.slice(0, -1).join(', ')} ${conjunction} ${strings.at(-1)}`;
+}