@markuplint/ml-spec 4.10.2 → 5.0.0-alpha.0

package/lib/algorithm/aria/has-required-owned-elements.js

@@ -1,9 +1,10 @@
-import { isPresentational } from './is-presentational.js';
+import { isTransparentForOwnership } from './is-presentational.js';
 import { getComputedRole } from './get-computed-role.js';
 import { getExplicitRole } from './get-explicit-role.js';
 import { getImplicitRole } from './get-implicit-role.js';
 /**
- * Checks whether an element satisfies the "Required Owned Elements" constraint
+ * Checks whether an element satisfies the "Allowed Accessibility Child Roles"
+ * constraint (called "Required Owned Elements" in ARIA 1.2)
  * defined by its computed ARIA role. An element satisfies this constraint if it
  * has `aria-owns`, or if any of its closest non-presentational descendants match
  * the required owned element roles.
@@ -29,10 +30,10 @@ el, specs, version) {
      * Otherwise, traverses descendants to find owned elements.
      */
     const computed = getComputedRole(specs, el, version);
-    if (!computed.role || computed.role.requiredOwnedElements.length === 0) {
+    if (!computed.role || computed.role.allowedAccessibilityChildRoles.length === 0) {
         return true;
     }
-    for (const expectRole of computed.role.requiredOwnedElements) {
+    for (const expectRole of computed.role.allowedAccessibilityChildRoles) {
         for (const owned of getClosestNonPresentationalDescendants(el, specs, version)) {
             if (isRequiredOwnedElement(owned.el, owned.role, expectRole, specs, version)) {
                 return true;
@@ -72,18 +73,20 @@ el, role, query, specs, version) {
 }
 /**
  * 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.
+ * This corresponds to the "Allowed Accessibility Child Roles" validation
+ * (called "Required Owned Elements" in ARIA 1.2).
  *
- * @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
+ * In ARIA 1.1/1.2, the spec had not decided whether the owned element
+ * is a child or a descendant. This implementation interprets that as
+ * A CHILD, but `presentation`/`none` elements are treated as transparent.
+ *
+ * ARIA 1.3 formally resolves this with the definitions of
+ * "accessibility child" and "accessibility parent", and additionally
+ * makes `generic` elements transparent.
  *
- * 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.
+ * @see https://w3c.github.io/aria/#mustContain
+ * @see https://github.com/w3c/aria/issues/1033
+ * @see https://github.com/w3c/aria/pull/1454
  */
 function getClosestNonPresentationalDescendants(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -92,7 +95,7 @@ el, specs, version) {
     for (const child of el.children) {
         const explicitRole = getExplicitRole(specs, child, version);
         const computed = explicitRole.role ? explicitRole : getImplicitRole(specs, child, version);
-        if (isPresentational(computed.role?.name)) {
+        if (isTransparentForOwnership(computed.role?.name, version)) {
             owned.push(...getClosestNonPresentationalDescendants(child, specs, version));
             continue;
         }

package/lib/algorithm/aria/is-presentational.d.ts

@@ -1,3 +1,4 @@
+import type { ARIAVersion } from '../../types/index.js';
 /**
  * Determines whether a given role name corresponds to a presentational role
  * (`"presentation"` or `"none"`), which indicates the element should be
@@ -7,3 +8,26 @@
  * @returns `true` if the role name is `"presentation"` or `"none"`, `false` otherwise
  */
 export declare function isPresentational(roleName?: string): boolean;
+/**
+ * Determines whether a given role is transparent for ownership traversal.
+ *
+ * **Version behavior:**
+ * - **ARIA 1.1/1.2:** Only `presentation`/`none` are transparent.
+ *   This matches the pre-existing behavior of `getClosestNonPresentationalDescendants`
+ *   and `getNonPresentationalAncestor`.
+ * - **ARIA 1.3:** `generic` is additionally transparent per the spec:
+ *   "user agents MUST ignore any intervening elements with the role
+ *   `generic` or `none`."
+ *
+ * **Note:** `matchesContextRole` calls this function unconditionally
+ * (without a version gate) so that `presentation`/`none` are always
+ * transparent, consistent with `getNonPresentationalAncestor`.
+ *
+ * @see https://w3c.github.io/aria/#mustContain — "Allowed Accessibility Child Roles" (called "Required Owned Elements" in ARIA 1.2)
+ * @see https://w3c.github.io/aria/#scope — "Required Accessibility Parent Role" (called "Required Context Role" in ARIA 1.2)
+ *
+ * @param roleName - The ARIA role name to check, or undefined
+ * @param version - The ARIA specification version
+ * @returns `true` if the role should be skipped during ownership traversal
+ */
+export declare function isTransparentForOwnership(roleName: string | undefined, version: ARIAVersion): boolean;

package/lib/algorithm/aria/is-presentational.js

@@ -12,3 +12,34 @@ export function isPresentational(roleName) {
     }
     return ['presentation', 'none'].includes(roleName);
 }
+/**
+ * Determines whether a given role is transparent for ownership traversal.
+ *
+ * **Version behavior:**
+ * - **ARIA 1.1/1.2:** Only `presentation`/`none` are transparent.
+ *   This matches the pre-existing behavior of `getClosestNonPresentationalDescendants`
+ *   and `getNonPresentationalAncestor`.
+ * - **ARIA 1.3:** `generic` is additionally transparent per the spec:
+ *   "user agents MUST ignore any intervening elements with the role
+ *   `generic` or `none`."
+ *
+ * **Note:** `matchesContextRole` calls this function unconditionally
+ * (without a version gate) so that `presentation`/`none` are always
+ * transparent, consistent with `getNonPresentationalAncestor`.
+ *
+ * @see https://w3c.github.io/aria/#mustContain — "Allowed Accessibility Child Roles" (called "Required Owned Elements" in ARIA 1.2)
+ * @see https://w3c.github.io/aria/#scope — "Required Accessibility Parent Role" (called "Required Context Role" in ARIA 1.2)
+ *
+ * @param roleName - The ARIA role name to check, or undefined
+ * @param version - The ARIA specification version
+ * @returns `true` if the role should be skipped during ownership traversal
+ */
+export function isTransparentForOwnership(roleName, version) {
+    if (isPresentational(roleName)) {
+        return true;
+    }
+    if (version === '1.3' && roleName === 'generic') {
+        return true;
+    }
+    return false;
+}

package/lib/algorithm/aria/matches-context-role.d.ts

@@ -1,10 +1,18 @@
 import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
 /**
- * Checks whether an element's parent hierarchy satisfies at least one of the
- * required context role conditions. Each condition string may describe a chain
- * of ancestor roles separated by ` > ` (e.g., `"list > group"`).
+ * Checks whether an element's parent hierarchy satisfies the
+ * "Required Accessibility Parent Role" (called "Required Context Role" in ARIA 1.2).
+ * Each condition string may describe a chain of ancestor roles separated by
+ * ` > ` (e.g., `"list > group"`).
  *
- * @param conditions - An array of required context role condition strings to match against
+ * TODO: This function only walks the DOM `parentElement` chain and does not
+ * consider `aria-owns` relationships. An element referenced by `aria-owns` on
+ * a remote ancestor should be treated as if it were an accessibility child of
+ * that ancestor. Implementing this requires a document-wide reverse lookup of
+ * `aria-owns` attributes, which is a separate architectural concern.
+ * See also: `has-required-owned-elements.ts` has a similar limitation.
+ *
+ * @param conditions - An array of required accessibility parent role condition strings to match against
  * @param ownedEl - The owned DOM element whose parent context is being validated
  * @param specs - The full markup language specification
  * @param version - The ARIA specification version to use

package/lib/algorithm/aria/matches-context-role.js

@@ -1,10 +1,19 @@
+import { isTransparentForOwnership } from './is-presentational.js';
 import { getComputedRole } from './get-computed-role.js';
 /**
- * Checks whether an element's parent hierarchy satisfies at least one of the
- * required context role conditions. Each condition string may describe a chain
- * of ancestor roles separated by ` > ` (e.g., `"list > group"`).
+ * Checks whether an element's parent hierarchy satisfies the
+ * "Required Accessibility Parent Role" (called "Required Context Role" in ARIA 1.2).
+ * Each condition string may describe a chain of ancestor roles separated by
+ * ` > ` (e.g., `"list > group"`).
  *
- * @param conditions - An array of required context role condition strings to match against
+ * TODO: This function only walks the DOM `parentElement` chain and does not
+ * consider `aria-owns` relationships. An element referenced by `aria-owns` on
+ * a remote ancestor should be treated as if it were an accessibility child of
+ * that ancestor. Implementing this requires a document-wide reverse lookup of
+ * `aria-owns` attributes, which is a separate architectural concern.
+ * See also: `has-required-owned-elements.ts` has a similar limitation.
+ *
+ * @param conditions - An array of required accessibility parent role condition strings to match against
  * @param ownedEl - The owned DOM element whose parent context is being validated
  * @param specs - The full markup language specification
  * @param version - The ARIA specification version to use
@@ -18,13 +27,37 @@ ownedEl, specs, version) {
 function matchesCondition(condition, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 parentEl, specs, version) {
-    const conditions = condition.split(/\s+>\s+/).reverse();
+    const conditions = condition.split(/\s+>\s+/).toReversed();
     while (conditions.length > 0) {
         if (!parentEl) {
             return false;
         }
-        const condition = conditions.shift();
         const parentRole = getComputedRole(specs, parentEl, version, true).role;
+        /**
+         * ARIA 1.3 ("Required Accessibility Parent Role"): "To determine
+         * whether an element has a parent with the required role, user agents
+         * MUST ignore any elements with the role `generic` or `none`."
+         *
+         * `presentation`/`none` are transparent in all ARIA versions to stay
+         * consistent with `getNonPresentationalAncestor` (which already skips
+         * them unconditionally). `generic` is additionally transparent in 1.3+
+         * per the spec.
+         *
+         * While the ARIA 1.1/1.2 specification text does not explicitly define
+         * this transparency for the context role check, applying it is a
+         * pragmatic choice: `getNonPresentationalAncestor` and `classifyChildren`
+         * (for owned elements) already skip `presentation`/`none` in all versions.
+         * Treating the context role check differently would create inconsistent
+         * behavior where a structure is valid from the parent's perspective
+         * (owned elements) but invalid from the child's perspective (context role).
+         *
+         * @see https://w3c.github.io/aria/#scope
+         */
+        if (isTransparentForOwnership(parentRole?.name, version)) {
+            parentEl = parentEl.parentElement;
+            continue;
+        }
+        const condition = conditions.shift();
         if (condition !== parentRole?.name) {
             return false;
         }

package/lib/algorithm/html/content-model-category-to-tag-names.js

@@ -14,7 +14,7 @@ export function contentModelCategoryToTagNames(contentModel, def) {
         return cached;
     }
     const tags = def['#contentModels'][contentModel];
-    const sortedTag = Object.freeze(tags && Array.isArray(tags) ? tags.sort() : []);
+    const sortedTag = Object.freeze(tags && Array.isArray(tags) ? tags.toSorted() : []);
     cache.set(contentModel, sortedTag);
     return sortedTag;
 }

package/lib/algorithm/html/get-content-model.d.ts

@@ -1,13 +1,15 @@
 import type { ElementSpec } from '../../types/index.js';
+import type { PermittedContentPattern } from '../../types/permitted-structures.js';
+import type { ReadonlyDeep } from 'type-fest';
 type Specs = readonly Pick<ElementSpec, 'name' | 'contentModel'>[];
 /**
  * Retrieves the permitted content model for an element. Evaluates any conditional
  * content models based on the element's current attributes (e.g., different content
- * models for `<ol>` vs `<ol reversed>`). Results are cached per element and spec set.
+ * models for `<ol>` vs `<ol reversed>`). Results are cached per element.
  *
  * @param el - The DOM element to retrieve the content model for
  * @param specs - The element specifications containing content model definitions
  * @returns The permitted content patterns array, a boolean (true for any content, false for no content), or null if no spec exists
  */
-export declare function getContentModel(el: Element, specs: Specs): boolean | readonly (import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentRequire> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentOptional> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentOneOrMore> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentZeroOrMore> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentChoice> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentTransparent>)[] | null;
+export declare function getContentModel(el: Element, specs: Specs): ReadonlyDeep<PermittedContentPattern[]> | boolean | null;
 export {};

package/lib/algorithm/html/get-content-model.js

@@ -1,9 +1,9 @@
 import { getSpec } from '../../utils/get-spec.js';
-const cachesBySpecs = new Map();
+const contentModelCache = new WeakMap();
 /**
  * Retrieves the permitted content model for an element. Evaluates any conditional
  * content models based on the element's current attributes (e.g., different content
- * models for `<ol>` vs `<ol reversed>`). Results are cached per element and spec set.
+ * models for `<ol>` vs `<ol reversed>`). Results are cached per element.
  *
  * @param el - The DOM element to retrieve the content model for
  * @param specs - The element specifications containing content model definitions
@@ -12,23 +12,22 @@ const cachesBySpecs = new Map();
 export function getContentModel(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, specs) {
-    const cacheByEl = cachesBySpecs.get(specs) ?? new Map();
-    const cached = cacheByEl.get(el);
+    const cached = contentModelCache.get(el);
     if (cached !== undefined) {
         return cached;
     }
     const spec = getSpec(el, specs);
     if (!spec) {
-        cacheByEl.set(el, null);
+        contentModelCache.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);
+            contentModelCache.set(el, cond.contents);
             return cond.contents;
         }
     }
-    cacheByEl.set(el, spec.contentModel.contents);
+    contentModelCache.set(el, spec.contentModel.contents);
     return spec.contentModel.contents;
 }

package/lib/const/accname.d.ts

@@ -0,0 +1,29 @@
+import type { AccnameElement } from '../algorithm/aria/accname/types.js';
+/**
+ * ARIA roles that are embedded controls per AccName Step 2C.
+ * @see https://www.w3.org/TR/accname-1.2/#comp_embedded_control
+ */
+export declare const EMBEDDED_CONTROL_ROLES: ReadonlySet<string>;
+/**
+ * Input types using label → title → placeholder name computation (HTML-AAM §4.1).
+ */
+export declare const TEXT_INPUT_TYPES: ReadonlySet<string>;
+/**
+ * Input types that behave as text-like controls (value attr → textContent).
+ * Subset of TEXT_INPUT_TYPES used for embedded control value extraction.
+ */
+export declare const TEXT_LIKE_INPUT_TYPES: ReadonlySet<string>;
+/** Default accessible name for input[type=submit] per HTML-AAM §4.1 */
+export declare const DEFAULT_SUBMIT_LABEL = "Submit";
+/** Default accessible name for input[type=reset] per HTML-AAM §4.1 */
+export declare const DEFAULT_RESET_LABEL = "Reset";
+/** Default accessible name for input[type=image] per HTML-AAM §4.1 */
+export declare const DEFAULT_IMAGE_LABEL = "Submit Query";
+/**
+ * Checks if a native HTML element is an embedded control (without role resolution).
+ * Centralizes the logic duplicated across accname-computation.ts, ml-core/accname.ts, test-helpers.ts.
+ *
+ * @param el - The element to check
+ * @returns True if the element is a native embedded control (textarea, select, or input with a value-producing type)
+ */
+export declare function isNativeEmbeddedControl(el: AccnameElement): boolean;

package/lib/const/accname.js

@@ -0,0 +1,76 @@
+/**
+ * ARIA roles that are embedded controls per AccName Step 2C.
+ * @see https://www.w3.org/TR/accname-1.2/#comp_embedded_control
+ */
+export const EMBEDDED_CONTROL_ROLES = new Set([
+    'textbox',
+    'combobox',
+    'listbox',
+    'spinbutton',
+    'slider',
+    'searchbox',
+]);
+/**
+ * Input types using label → title → placeholder name computation (HTML-AAM §4.1).
+ */
+export const TEXT_INPUT_TYPES = new Set([
+    'text',
+    'password',
+    'search',
+    'tel',
+    'url',
+    'email',
+    'number',
+    'date',
+    'month',
+    'week',
+    'time',
+    'datetime-local',
+    'color',
+    'range',
+    'file',
+]);
+/**
+ * Input types that behave as text-like controls (value attr → textContent).
+ * Subset of TEXT_INPUT_TYPES used for embedded control value extraction.
+ */
+export const TEXT_LIKE_INPUT_TYPES = new Set([
+    'text',
+    'search',
+    'tel',
+    'url',
+    'email',
+    'password',
+    'number',
+]);
+/** Default accessible name for input[type=submit] per HTML-AAM §4.1 */
+export const DEFAULT_SUBMIT_LABEL = 'Submit';
+/** Default accessible name for input[type=reset] per HTML-AAM §4.1 */
+export const DEFAULT_RESET_LABEL = 'Reset';
+/** Default accessible name for input[type=image] per HTML-AAM §4.1 */
+export const DEFAULT_IMAGE_LABEL = 'Submit Query';
+/**
+ * Checks if a native HTML element is an embedded control (without role resolution).
+ * Centralizes the logic duplicated across accname-computation.ts, ml-core/accname.ts, test-helpers.ts.
+ *
+ * @param el - The element to check
+ * @returns True if the element is a native embedded control (textarea, select, or input with a value-producing type)
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+export function isNativeEmbeddedControl(el) {
+    const { localName } = el;
+    if (localName === 'textarea' || localName === 'select') {
+        return true;
+    }
+    if (localName === 'input') {
+        const type = (el.getAttribute('type') ?? 'text').toLowerCase();
+        return (type !== 'hidden' &&
+            type !== 'button' &&
+            type !== 'submit' &&
+            type !== 'reset' &&
+            type !== 'image' &&
+            type !== 'checkbox' &&
+            type !== 'radio');
+    }
+    return false;
+}

package/lib/const/dom.d.ts

@@ -0,0 +1,8 @@
+/** DOM Node.ELEMENT_NODE */
+export declare const ELEMENT_NODE = 1;
+/** DOM Node.TEXT_NODE */
+export declare const TEXT_NODE = 3;
+/** SVG namespace URI */
+export declare const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+/** XHTML namespace URI */
+export declare const XHTML_NAMESPACE = "http://www.w3.org/1999/xhtml";

package/lib/const/dom.js

@@ -0,0 +1,8 @@
+/** DOM Node.ELEMENT_NODE */
+export const ELEMENT_NODE = 1;
+/** DOM Node.TEXT_NODE */
+export const TEXT_NODE = 3;
+/** SVG namespace URI */
+export const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+/** XHTML namespace URI */
+export const XHTML_NAMESPACE = 'http://www.w3.org/1999/xhtml';

package/lib/const/index.d.ts

@@ -0,0 +1,2 @@
+export { ELEMENT_NODE, TEXT_NODE, SVG_NAMESPACE, XHTML_NAMESPACE } from './dom.js';
+export { EMBEDDED_CONTROL_ROLES, TEXT_INPUT_TYPES, TEXT_LIKE_INPUT_TYPES, DEFAULT_SUBMIT_LABEL, DEFAULT_RESET_LABEL, DEFAULT_IMAGE_LABEL, isNativeEmbeddedControl, } from './accname.js';

package/lib/const/index.js

@@ -0,0 +1,2 @@
+export { ELEMENT_NODE, TEXT_NODE, SVG_NAMESPACE, XHTML_NAMESPACE } from './dom.js';
+export { EMBEDDED_CONTROL_ROLES, TEXT_INPUT_TYPES, TEXT_LIKE_INPUT_TYPES, DEFAULT_SUBMIT_LABEL, DEFAULT_RESET_LABEL, DEFAULT_IMAGE_LABEL, isNativeEmbeddedControl, } from './accname.js';

package/lib/index.d.ts

@@ -1,5 +1,7 @@
 export { getAttrSpecs as getAttrSpecsByNames } from './utils/get-attr-specs-spec.js';
 export * from './utils/aria-version.js';
+export { EMBEDDED_CONTROL_ROLES, isNativeEmbeddedControl } from './const/index.js';
+export * from './algorithm/aria/accname/index.js';
 export * from './algorithm/aria/accname-computation.js';
 export * from './algorithm/aria/get-computed-aria-props.js';
 export * from './algorithm/aria/get-computed-role.js';
@@ -24,6 +26,7 @@ export * from './utils/get-spec-by-tag-name.js';
 export * from './utils/schema-to-spec.js';
 export * from './utils/resolve-namespace.js';
 export * from './utils/validate-aria-version.js';
+export * from './utils/directive-resolver.js';
 export * from './types/index.js';
 export * from './types/aria.js';
 export * from './types/attributes.js';

package/lib/index.js

@@ -1,6 +1,9 @@
 export { getAttrSpecs as getAttrSpecsByNames } from './utils/get-attr-specs-spec.js';
 export * from './utils/aria-version.js';
+// Constants
+export { EMBEDDED_CONTROL_ROLES, isNativeEmbeddedControl } from './const/index.js';
 // ARIA algorithms
+export * from './algorithm/aria/accname/index.js';
 export * from './algorithm/aria/accname-computation.js';
 export * from './algorithm/aria/get-computed-aria-props.js';
 export * from './algorithm/aria/get-computed-role.js';
@@ -27,6 +30,7 @@ export * from './utils/get-spec-by-tag-name.js';
 export * from './utils/schema-to-spec.js';
 export * from './utils/resolve-namespace.js';
 export * from './utils/validate-aria-version.js';
+export * from './utils/directive-resolver.js';
 // Type definitions
 export * from './types/index.js';
 export * from './types/aria.js';

package/lib/types/index.d.ts

@@ -11,6 +11,8 @@ export interface MLMLSpec {
     readonly cites: Cites;
     readonly def: SpecDefs;
     readonly specs: readonly ElementSpec[];
+    readonly directivePatterns?: readonly DirectivePattern[];
+    readonly useIDLAttributeNames?: boolean;
 }
 /**
  * An element specification for extending or overriding parts of the base spec.
@@ -29,6 +31,56 @@ export type ExtendedSpec = {
     readonly cites?: Cites;
     readonly def?: Partial<SpecDefs>;
     readonly specs?: readonly ExtendedElementSpec[];
+    readonly directivePatterns?: readonly DirectivePattern[];
+    readonly useIDLAttributeNames?: boolean;
+};
+/**
+ * A declarative pattern for resolving framework-specific directive
+ * attributes to their canonical names and metadata. Stored as part
+ * of the spec, enabling "parser-less" framework support.
+ *
+ * The `pattern` is a regex string matched against the raw attribute name.
+ * Capture groups can be referenced in `potentialName` using `$1`, `$2`, etc.
+ */
+export type DirectivePattern = {
+    /**
+     * A regex string (without delimiters) matched against the raw attribute name.
+     * Must be a valid JavaScript RegExp pattern. Capture groups can be used
+     * for potentialName templates.
+     * @example "^(?:x-bind:|:)([^.]+)(?:\\.[^.]+)?$"
+     */
+    readonly pattern: string;
+    /**
+     * Optional regex flags (e.g., "i" for case-insensitive).
+     * @default "i"
+     */
+    readonly flags?: string;
+    /**
+     * Template for the resolved potentialName. References capture groups
+     * with $1, $2, etc. If omitted, the attribute is treated as a directive
+     * with no potentialName change.
+     * @example "on$1"  -- for `@click` -> `onclick`
+     * @example "$1"    -- for `:href` -> `href`
+     */
+    readonly potentialName?: string;
+    /**
+     * Whether this attribute is a framework directive.
+     */
+    readonly isDirective?: true;
+    /**
+     * Whether this attribute has a dynamic value.
+     */
+    readonly isDynamicValue?: true;
+    /**
+     * The semantic value type for matched attributes.
+     */
+    readonly valueType?: 'string' | 'number' | 'boolean' | 'code';
+    /**
+     * If true, the attribute can appear multiple times on the same element.
+     * Can also be a string array of potentialName values for which
+     * duplication is allowed (e.g., ['class', 'style']).
+     */
+    readonly isDuplicatable?: true | readonly string[];
 };
 /**
  * Reference URLs
@@ -54,6 +106,7 @@ export type SpecDefs = {
 type ARIASpec = {
     readonly roles: readonly ARIARoleInSchema[];
     readonly graphicsRoles: readonly ARIARoleInSchema[];
+    readonly dpubRoles: readonly ARIARoleInSchema[];
     readonly props: readonly ARIAProperty[];
 };
 /**
@@ -158,7 +211,19 @@ export type ARIARole = {
     readonly name: string;
     readonly isAbstract: boolean;
     readonly deprecated: boolean;
+    /** Required Accessibility Parent Role (ARIA 1.3 name) */
+    readonly requiredAccessibilityParentRole: readonly string[];
+    /** Allowed Accessibility Child Roles (ARIA 1.3 name) */
+    readonly allowedAccessibilityChildRoles: readonly string[];
+    /**
+     * @deprecated Use {@link ARIARole.requiredAccessibilityParentRole} instead.
+     * Retained for ARIA 1.2 backward compatibility.
+     */
     readonly requiredContextRole: readonly string[];
+    /**
+     * @deprecated Use {@link ARIARole.allowedAccessibilityChildRoles} instead.
+     * Retained for ARIA 1.2 backward compatibility.
+     */
     readonly requiredOwnedElements: readonly string[];
     readonly accessibleNameRequired: boolean;
     readonly accessibleNameFromAuthor: boolean;

package/lib/utils/directive-resolver.d.ts

@@ -0,0 +1,23 @@
+import type { DirectivePattern } from '../types/index.js';
+type CompiledDirectivePattern = {
+    readonly regex: RegExp;
+    readonly pattern: DirectivePattern;
+};
+/**
+ * Compiles directive patterns into RegExp objects, caching them
+ * by the patterns array reference for efficiency.
+ */
+export declare function compileDirectivePatterns(patterns: readonly DirectivePattern[]): readonly CompiledDirectivePattern[];
+export type DirectiveResolution = {
+    readonly potentialName?: string;
+    readonly isDirective?: true;
+    readonly isDynamicValue?: true;
+    readonly valueType?: 'string' | 'number' | 'boolean' | 'code';
+    readonly isDuplicatable?: boolean;
+};
+/**
+ * Resolves an attribute name against a list of compiled directive patterns.
+ * Returns the first match's resolution, or null if no pattern matches.
+ */
+export declare function resolveDirective(attrName: string, compiledPatterns: readonly CompiledDirectivePattern[]): DirectiveResolution | null;
+export {};

package/lib/utils/directive-resolver.js

@@ -0,0 +1,50 @@
+const cache = new WeakMap();
+/**
+ * Compiles directive patterns into RegExp objects, caching them
+ * by the patterns array reference for efficiency.
+ */
+export function compileDirectivePatterns(patterns) {
+    let compiled = cache.get(patterns);
+    if (!compiled) {
+        compiled = patterns.map(p => ({
+            regex: new RegExp(p.pattern, p.flags ?? 'i'),
+            pattern: p,
+        }));
+        cache.set(patterns, compiled);
+    }
+    return compiled;
+}
+/**
+ * Resolves an attribute name against a list of compiled directive patterns.
+ * Returns the first match's resolution, or null if no pattern matches.
+ */
+export function resolveDirective(attrName, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+compiledPatterns) {
+    for (const { regex, pattern } of compiledPatterns) {
+        regex.lastIndex = 0;
+        const match = regex.exec(attrName);
+        if (!match) {
+            continue;
+        }
+        let potentialName;
+        if (pattern.potentialName != null) {
+            potentialName = pattern.potentialName.replaceAll(/\$(\d+)/g, (_, idx) => (match[Number(idx)] ?? '').toLowerCase());
+        }
+        let isDuplicatable;
+        if (pattern.isDuplicatable === true) {
+            isDuplicatable = true;
+        }
+        else if (Array.isArray(pattern.isDuplicatable) && potentialName) {
+            isDuplicatable = pattern.isDuplicatable.includes(potentialName);
+        }
+        return {
+            potentialName,
+            isDirective: pattern.isDirective,
+            isDynamicValue: pattern.isDynamicValue,
+            valueType: pattern.valueType,
+            isDuplicatable,
+        };
+    }
+    return null;
+}

package/lib/utils/get-attr-specs-spec.js

@@ -69,11 +69,12 @@ export function getAttrSpecs(localName, namespace, schema) {
             ...attr,
         };
     }
-    const attrList = Object.keys(attrs).map(name => {
+    const attrList = Object.keys(attrs)
+        .map(name => {
         const attr = attrs[name];
         return { name, type: 'Any', ...attr };
-    });
-    attrList.sort(nameCompare);
+    })
+        .toSorted(nameCompare);
     cacheMap.set(localNameWithNS, attrList);
     return attrList;
 }