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

package/lib/algorithm/html/get-selectors-by-content-model-category.js

@@ -1,3 +1,11 @@
+/**
+ * Retrieves the CSS selectors associated with a content model category from the spec definitions.
+ * These selectors can be used to match elements that belong to the given category.
+ *
+ * @param specs - The full markup language specification
+ * @param category - The content model category identifier (e.g., `#flow`, `#interactive`)
+ * @returns A readonly array of CSS selector strings for the category, or an empty array if the category is not defined
+ */
 export function getSelectorsByContentModelCategory(specs, category) {
     const selectors = specs.def['#contentModels'][category];
     return selectors ?? [];

package/lib/algorithm/html/is-nothing-content-model.d.ts

@@ -1,5 +1,12 @@
 /**
+ * Determines whether an element uses the "nothing" content model, meaning it
+ * must not contain any content. This includes void elements as well as
+ * `<iframe>` and `<template>` elements.
+ *
  * @see https://html.spec.whatwg.org/multipage/dom.html#the-nothing-content-model
  * @see https://html.spec.whatwg.org/multipage/indices.html#elements-3
+ *
+ * @param el - The DOM element to check
+ * @returns `true` if the element has the "nothing" content model
  */
 export declare function isNothingContentModel(el: Element): boolean;

package/lib/algorithm/html/is-nothing-content-model.js

@@ -1,7 +1,14 @@
 import { isVoidElement } from './is-void-element.js';
 /**
+ * Determines whether an element uses the "nothing" content model, meaning it
+ * must not contain any content. This includes void elements as well as
+ * `<iframe>` and `<template>` elements.
+ *
  * @see https://html.spec.whatwg.org/multipage/dom.html#the-nothing-content-model
  * @see https://html.spec.whatwg.org/multipage/indices.html#elements-3
+ *
+ * @param el - The DOM element to check
+ * @returns `true` if the element has the "nothing" content model
  */
 export function isNothingContentModel(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types

package/lib/algorithm/html/is-palpable-elements.d.ts

@@ -1,4 +1,17 @@
 import type { MLMLSpec } from '../../types/index.js';
+/**
+ * Determines whether an element is considered palpable content. Palpable elements
+ * are those that render something visible or meaningful to the user. Optionally
+ * extends the check to include SVG renderable elements and other exposable elements
+ * that do not belong to any standard content model category.
+ *
+ * @param el - The DOM element to check
+ * @param specs - The full markup language specification
+ * @param options - Optional flags to extend the palpable check
+ * @param options.extendsSvg - Whether to include SVG renderable elements (defaults to true)
+ * @param options.extendsExposableElements - Whether to include additional exposable elements like `<li>`, `<td>`, etc. (defaults to false)
+ * @returns `true` if the element is considered palpable content
+ */
 export declare function isPalpableElement(el: Element, specs: MLMLSpec, options?: {
     readonly extendsSvg?: boolean;
     readonly extendsExposableElements?: boolean;

package/lib/algorithm/html/is-palpable-elements.js

@@ -28,6 +28,19 @@ const exposableElementsThatAreNoBelongingAModel = [
     'thead',
     'tr',
 ];
+/**
+ * Determines whether an element is considered palpable content. Palpable elements
+ * are those that render something visible or meaningful to the user. Optionally
+ * extends the check to include SVG renderable elements and other exposable elements
+ * that do not belong to any standard content model category.
+ *
+ * @param el - The DOM element to check
+ * @param specs - The full markup language specification
+ * @param options - Optional flags to extend the palpable check
+ * @param options.extendsSvg - Whether to include SVG renderable elements (defaults to true)
+ * @param options.extendsExposableElements - Whether to include additional exposable elements like `<li>`, `<td>`, etc. (defaults to false)
+ * @returns `true` if the element is considered palpable content
+ */
 export function isPalpableElement(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, specs, options) {

package/lib/algorithm/html/is-void-element.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Determines whether an element is a void element as defined by the HTML specification.
+ * Void elements cannot have any contents (e.g., `<br>`, `<img>`, `<input>`).
+ *
+ * @see https://html.spec.whatwg.org/multipage/syntax.html#void-elements
+ *
+ * @param el - An object with a `localName` property representing the element's tag name
+ * @returns `true` if the element is a void element
+ */
 export declare function isVoidElement(el: {
     readonly localName: string;
 }): boolean;

package/lib/algorithm/html/is-void-element.js

@@ -16,6 +16,15 @@ const voidElements = new Set([
     'track',
     'wbr',
 ]);
+/**
+ * Determines whether an element is a void element as defined by the HTML specification.
+ * Void elements cannot have any contents (e.g., `<br>`, `<img>`, `<input>`).
+ *
+ * @see https://html.spec.whatwg.org/multipage/syntax.html#void-elements
+ *
+ * @param el - An object with a `localName` property representing the element's tag name
+ * @returns `true` if the element is a void element
+ */
 export function isVoidElement(el) {
     return voidElements.has(el.localName);
 }

package/lib/algorithm/html/may-be-focusable.d.ts

@@ -1,2 +1,12 @@
 import type { MLMLSpec } from '../../types/index.js';
+/**
+ * Determines whether an element may potentially be focusable, based on whether it matches
+ * interactive content selectors, has a `tabindex` attribute, or has a `contenteditable`
+ * attribute. This is a heuristic check that does not account for runtime state such as
+ * `disabled` or `inert` attributes.
+ *
+ * @param el - The DOM element to check
+ * @param specs - The full markup language specification containing interactive content definitions
+ * @returns `true` if the element may be focusable
+ */
 export declare function mayBeFocusable(el: Element, specs: MLMLSpec): boolean;

package/lib/algorithm/html/may-be-focusable.js

@@ -1,4 +1,14 @@
 import { getSelectorsByContentModelCategory } from './get-selectors-by-content-model-category.js';
+/**
+ * Determines whether an element may potentially be focusable, based on whether it matches
+ * interactive content selectors, has a `tabindex` attribute, or has a `contenteditable`
+ * attribute. This is a heuristic check that does not account for runtime state such as
+ * `disabled` or `inert` attributes.
+ *
+ * @param el - The DOM element to check
+ * @param specs - The full markup language specification containing interactive content definitions
+ * @returns `true` if the element may be focusable
+ */
 export function mayBeFocusable(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, specs) {

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,20 +11,85 @@ 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.
+ * Only the `name` property is required; all other properties are optional partial overrides.
+ * Attributes use `Partial<Attribute>` to allow specifying only changed fields.
+ */
 export type ExtendedElementSpec = Partial<Omit<ElementSpec, 'name' | 'attributes'>> & {
     readonly name: ElementSpec['name'];
     readonly attributes?: Readonly<Record<string, Partial<Attribute>>>;
 };
+/**
+ * A partial specification used for extending or customizing the base markup language spec.
+ * Typically provided by parser plugins or framework-specific spec packages (e.g., `@markuplint/vue-spec`).
+ */
 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
  */
 export type Cites = readonly string[];
+/**
+ * Internal definition data within a markup language spec, containing global attributes,
+ * ARIA role/property definitions for each version, and content model category mappings.
+ */
 export type SpecDefs = {
     readonly '#globalAttrs': {
         readonly [category: string]: Readonly<Record<string, Partial<Attribute>>>;
@@ -41,6 +106,7 @@ export type SpecDefs = {
 type ARIASpec = {
     readonly roles: readonly ARIARoleInSchema[];
     readonly graphicsRoles: readonly ARIARoleInSchema[];
+    readonly dpubRoles: readonly ARIARoleInSchema[];
     readonly props: readonly ARIAProperty[];
 };
 /**
@@ -124,6 +190,9 @@ type ElementSpecOmissionTags = {
 type ElementCondition = {
     readonly __WIP__: 'WORK_IN_PROGRESS';
 };
+/**
+ * Describes a single HTML/SVG attribute with its type, description, and status flags.
+ */
 export type Attribute = {
     readonly name: string;
     readonly type: ReadonlyDeep<AttributeType> | readonly ReadonlyDeep<AttributeType>[];
@@ -135,11 +204,26 @@ export type Attribute = {
     readonly nonStandard?: true;
 } & ExtendableAttributeSpec;
 type ExtendableAttributeSpec = Omit<ReadonlyDeep<AttributeJSON>, 'type'>;
+/**
+ * A fully resolved ARIA role with all its properties, requirements, and naming constraints.
+ */
 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;
@@ -149,18 +233,30 @@ export type ARIARole = {
     readonly ownedProperties: readonly ARIARoleOwnedProperties[];
     readonly prohibitedProperties: readonly string[];
 };
+/**
+ * An ARIA role as defined in the raw schema data. All properties are optional
+ * except `name`, since the schema may provide only partial role information.
+ */
 export type ARIARoleInSchema = Partial<ARIARole & {
     readonly description: string;
     readonly generalization: readonly string[];
 }> & {
     readonly name: string;
 };
+/**
+ * Describes a property owned by an ARIA role, including whether it is inherited,
+ * required, or deprecated.
+ */
 export type ARIARoleOwnedProperties = {
     readonly name: string;
     readonly inherited?: true;
     readonly required?: true;
     readonly deprecated?: true;
 };
+/**
+ * Describes an ARIA property or state, including its value type, enumeration values,
+ * global status, default value, conditional values per role, and equivalent HTML attributes.
+ */
 export type ARIAProperty = {
     readonly name: string;
     readonly type: 'property' | 'state';
@@ -176,14 +272,33 @@ export type ARIAProperty = {
     readonly equivalentHtmlAttrs?: readonly EquivalentHtmlAttr[];
     readonly valueDescriptions?: Readonly<Record<string, string>>;
 };
+/**
+ * The possible value types for ARIA attributes, as defined by the WAI-ARIA specification.
+ */
 export type ARIAAttributeValue = 'true/false' | 'tristate' | 'true/false/undefined' | 'ID reference' | 'ID reference list' | 'integer' | 'number' | 'string' | 'token' | 'token list' | 'URI';
+/**
+ * A union type of supported ARIA specification version strings, derived from the `ariaVersions` tuple.
+ */
 export type ARIAVersion = (typeof ariaVersions)[number];
+/**
+ * Describes an HTML attribute that is semantically equivalent to an ARIA property,
+ * enabling automatic mapping from HTML attributes to ARIA states/properties.
+ */
 export type EquivalentHtmlAttr = {
     readonly htmlAttrName: string;
     readonly isNotStrictEquivalent?: true;
     readonly value: string | null;
 };
+/**
+ * A function that tests whether an element matches a given CSS selector string.
+ * Typically bound to `Element.prototype.matches`.
+ */
 export type Matches = (selector: string) => boolean;
+/**
+ * The result of computing an element's ARIA role, containing the element reference,
+ * the resolved role specification (or null if no role applies), and an optional
+ * error type indicating issues during role computation.
+ */
 export type ComputedRole = {
     readonly el: Element;
     readonly role: (ARIARole & {
@@ -192,5 +307,9 @@ export type ComputedRole = {
     }) | null;
     readonly errorType?: RoleComputationError;
 };
+/**
+ * Error codes that may arise during ARIA role computation, indicating specific
+ * issues such as abstract roles, invalid context, or presentational conflicts.
+ */
 export type RoleComputationError = 'ABSTRACT' | 'GLOBAL_PROP_MUST_NOT_BE_PRESENTATIONAL' | 'IMPLICIT_ROLE_NAMESPACE_ERROR' | 'INTERACTIVE_ELEMENT_MUST_NOT_BE_PRESENTATIONAL' | 'INVALID_LANDMARK' | 'INVALID_REQUIRED_CONTEXT_ROLE' | 'NO_EXPLICIT' | 'NO_OWNER' | 'NO_PERMITTED' | 'REQUIRED_OWNED_ELEMENT_MUST_NOT_BE_PRESENTATIONAL' | 'ROLE_NO_EXISTS';
 export {};

package/lib/utils/aria-version.d.ts

@@ -1,2 +1,8 @@
+/**
+ * The supported ARIA specification versions as a readonly tuple.
+ */
 export declare const ariaVersions: readonly ["1.1", "1.2", "1.3"];
+/**
+ * The recommended default ARIA specification version to use when none is explicitly specified.
+ */
 export declare const ARIA_RECOMMENDED_VERSION = "1.2";

package/lib/utils/aria-version.js

@@ -1,2 +1,8 @@
+/**
+ * The supported ARIA specification versions as a readonly tuple.
+ */
 export const ariaVersions = ['1.1', '1.2', '1.3'];
+/**
+ * The recommended default ARIA specification version to use when none is explicitly specified.
+ */
 export const ARIA_RECOMMENDED_VERSION = '1.2';

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.d.ts

@@ -1,8 +1,26 @@
 import type { MLMLSpec, Attribute } from '../types/index.js';
 import type { NamespaceURI } from '@markuplint/ml-ast';
+/**
+ * Retrieves the merged attribute specifications for an element identified by its local name
+ * and namespace. Combines global attributes from the relevant categories with the element's
+ * own attribute definitions. Results are cached by the namespace-qualified element name.
+ *
+ * @param localName - The local tag name of the element
+ * @param namespace - The namespace URI of the element, or null for HTML namespace
+ * @param schema - The full markup language specification containing attribute definitions
+ * @returns A sorted array of attribute specifications for the element, or null if the element is not found in the schema
+ */
 export declare function getAttrSpecs(localName: string, namespace: NamespaceURI | null, schema: MLMLSpec): readonly Attribute[] | null;
 type HasName = {
     readonly name: string;
 };
+/**
+ * Compares two items by name in a case-insensitive manner, suitable for use as
+ * a sort comparator. Accepts either objects with a `name` property or plain strings.
+ *
+ * @param a - The first item to compare (object with `name` property or a string)
+ * @param b - The second item to compare (object with `name` property or a string)
+ * @returns A negative number if `a` comes before `b`, positive if after, or 0 if equal
+ */
 export declare function nameCompare(a: HasName | string, b: HasName | string): 1 | -1 | 0;
 export {};