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

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

@@ -1,6 +1,16 @@
 import { resolveNamespace } from './resolve-namespace.js';
 const cacheMap = new Map();
 const schemaCache = new WeakSet();
+/**
+ * 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 function getAttrSpecs(localName, namespace, schema) {
     if (!schemaCache.has(schema)) {
         cacheMap.clear();
@@ -59,14 +69,23 @@ 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;
 }
+/**
+ * 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 function nameCompare(a, b) {
     const nameA = typeof a === 'string' ? a : a.name.toUpperCase();
     const nameB = typeof b === 'string' ? b : b.name.toUpperCase();

package/lib/utils/get-attr-specs.d.ts

@@ -1,2 +1,11 @@
 import type { MLMLSpec } from '../types/index.js';
+/**
+ * Retrieves the attribute specifications for a DOM element by resolving its
+ * local name and namespace URI from the provided schema. This is a convenience
+ * wrapper around the spec-based `getAttrSpecs` that accepts a DOM element directly.
+ *
+ * @param el - The DOM element whose attribute specifications to retrieve
+ * @param schema - The full markup language specification containing attribute definitions
+ * @returns The array of attribute specifications for the element, or null if no spec exists
+ */
 export declare function getAttrSpecs(el: Element, schema: MLMLSpec): readonly import("../types/index.js").Attribute[] | null;

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

@@ -1,4 +1,13 @@
 import { getAttrSpecs as _getAttrSpecs } from './get-attr-specs-spec.js';
+/**
+ * Retrieves the attribute specifications for a DOM element by resolving its
+ * local name and namespace URI from the provided schema. This is a convenience
+ * wrapper around the spec-based `getAttrSpecs` that accepts a DOM element directly.
+ *
+ * @param el - The DOM element whose attribute specifications to retrieve
+ * @param schema - The full markup language specification containing attribute definitions
+ * @returns The array of attribute specifications for the element, or null if no spec exists
+ */
 export function getAttrSpecs(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, schema) {

package/lib/utils/get-ns.d.ts

@@ -1,2 +1,9 @@
 import type { Namespace } from '@markuplint/ml-ast';
+/**
+ * Maps a full namespace URI string to its shorthand `Namespace` identifier.
+ * Returns `'html'` as the default for any unrecognized or null namespace.
+ *
+ * @param namespaceURI - The full namespace URI, or null
+ * @returns The shorthand namespace identifier (`'html'`, `'svg'`, `'mml'`, or `'xlink'`)
+ */
 export declare function getNS(namespaceURI: string | null): Namespace;

package/lib/utils/get-ns.js

@@ -1,3 +1,10 @@
+/**
+ * Maps a full namespace URI string to its shorthand `Namespace` identifier.
+ * Returns `'html'` as the default for any unrecognized or null namespace.
+ *
+ * @param namespaceURI - The full namespace URI, or null
+ * @returns The shorthand namespace identifier (`'html'`, `'svg'`, `'mml'`, or `'xlink'`)
+ */
 export function getNS(namespaceURI) {
     switch (namespaceURI) {
         case 'http://www.w3.org/2000/svg': {

package/lib/utils/get-spec-by-tag-name.d.ts

@@ -1,2 +1,13 @@
 import type { ElementSpec } from '../types/index.js';
-export declare function getSpecByTagName<K extends keyof ElementSpec = keyof ElementSpec>(specs: readonly Pick<ElementSpec, 'name' | K>[], localName: string, namespace: string | null): Pick<ElementSpec, "name" | K> | null;
+/**
+ * Looks up an element specification by its local tag name and namespace. The tag name
+ * is resolved to a namespace-qualified form (e.g., `"svg:circle"`) before searching.
+ * Results are cached by the namespace-qualified name for subsequent lookups.
+ *
+ * @template K - The keys of `ElementSpec` to include in the returned spec object (defaults to all keys)
+ * @param specs - The array of element specifications to search
+ * @param localName - The local tag name of the element
+ * @param namespace - The namespace URI string, or null for HTML namespace
+ * @returns The matching element specification, or null if not found
+ */
+export declare function getSpecByTagName<K extends keyof ElementSpec = keyof ElementSpec>(specs: readonly Pick<ElementSpec, 'name' | K>[], localName: string, namespace: string | null): Pick<ElementSpec, K | "name"> | null;

package/lib/utils/get-spec-by-tag-name.js

@@ -1,5 +1,16 @@
 import { resolveNamespace } from './resolve-namespace.js';
 const cache = new Map();
+/**
+ * Looks up an element specification by its local tag name and namespace. The tag name
+ * is resolved to a namespace-qualified form (e.g., `"svg:circle"`) before searching.
+ * Results are cached by the namespace-qualified name for subsequent lookups.
+ *
+ * @template K - The keys of `ElementSpec` to include in the returned spec object (defaults to all keys)
+ * @param specs - The array of element specifications to search
+ * @param localName - The local tag name of the element
+ * @param namespace - The namespace URI string, or null for HTML namespace
+ * @returns The matching element specification, or null if not found
+ */
 export function getSpecByTagName(specs, localName, namespace) {
     const { localNameWithNS } = resolveNamespace(localName, namespace ?? undefined);
     let spec = cache.get(localNameWithNS);

package/lib/utils/get-spec.d.ts

@@ -1,2 +1,12 @@
 import type { ElementSpec } from '../types/index.js';
-export declare function getSpec<K extends keyof ElementSpec>(el: Element, specs: readonly Pick<ElementSpec, 'name' | K>[]): Pick<ElementSpec, "name" | K> | null;
+/**
+ * Retrieves the element specification for a DOM element by looking up its local name
+ * and namespace URI in the provided specs array. This is a convenience wrapper around
+ * `getSpecByTagName` that accepts a DOM element directly.
+ *
+ * @template K - The keys of `ElementSpec` to include in the returned spec object
+ * @param el - The DOM element to look up
+ * @param specs - The array of element specifications to search
+ * @returns The matching element specification, or null if not found
+ */
+export declare function getSpec<K extends keyof ElementSpec>(el: Element, specs: readonly Pick<ElementSpec, 'name' | K>[]): Pick<ElementSpec, K | "name"> | null;

package/lib/utils/get-spec.js

@@ -1,4 +1,14 @@
 import { getSpecByTagName } from './get-spec-by-tag-name.js';
+/**
+ * Retrieves the element specification for a DOM element by looking up its local name
+ * and namespace URI in the provided specs array. This is a convenience wrapper around
+ * `getSpecByTagName` that accepts a DOM element directly.
+ *
+ * @template K - The keys of `ElementSpec` to include in the returned spec object
+ * @param el - The DOM element to look up
+ * @param specs - The array of element specifications to search
+ * @returns The matching element specification, or null if not found
+ */
 export function getSpec(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, specs) {

package/lib/utils/merge-array.d.ts

@@ -1,5 +1,15 @@
 type NamedDefinition = string | {
     readonly name: string;
 };
+/**
+ * Merges two arrays of named definitions by name, with items from `b` overriding
+ * matching items in `a`. When both items are objects, their properties are merged;
+ * when the overriding item is a string, the existing item is kept as-is.
+ *
+ * @template T - A named definition type (string or object with a `name` property)
+ * @param a - The base array of named definitions
+ * @param b - The array of named definitions to merge in, or null/undefined to skip
+ * @returns A new array with items from `b` merged into `a` by name
+ */
 export declare function mergeArray<T extends NamedDefinition>(a: readonly T[], b: readonly T[] | null | undefined): readonly T[];
 export {};

package/lib/utils/merge-array.js

@@ -1,3 +1,13 @@
+/**
+ * Merges two arrays of named definitions by name, with items from `b` overriding
+ * matching items in `a`. When both items are objects, their properties are merged;
+ * when the overriding item is a string, the existing item is kept as-is.
+ *
+ * @template T - A named definition type (string or object with a `name` property)
+ * @param a - The base array of named definitions
+ * @param b - The array of named definitions to merge in, or null/undefined to skip
+ * @returns A new array with items from `b` merged into `a` by name
+ */
 export function mergeArray(a, b) {
     if (!b) {
         return a;

package/lib/utils/resolve-namespace.d.ts

@@ -1,9 +1,22 @@
 import type { NamespaceURI, Namespace } from '@markuplint/ml-ast';
+/**
+ * Represents a fully resolved element name with its namespace information.
+ */
 type NamespacedElementName = {
     localNameWithNS: string;
     localName: string;
     namespace: Namespace;
     namespaceURI: NamespaceURI;
 };
+/**
+ * Resolves an element name and namespace URI into a normalized form containing
+ * the namespace-qualified name, bare local name, namespace shorthand, and full
+ * namespace URI. Handles explicit namespace prefixes (e.g., `"svg:circle"`) and
+ * falls back to HTML namespace when not specified. Results are cached.
+ *
+ * @param name - The element name, optionally prefixed with a namespace (e.g., `"svg:circle"` or `"div"`)
+ * @param namespaceURI - The namespace URI string, or null (defaults to XHTML namespace)
+ * @returns The resolved namespace information including qualified name, local name, namespace shorthand, and full URI
+ */
 export declare function resolveNamespace(name: string, namespaceURI?: string | null): NamespacedElementName;
 export {};

package/lib/utils/resolve-namespace.js

@@ -6,6 +6,16 @@ const namespaceURIMap = {
     mml: 'http://www.w3.org/1998/Math/MathML',
     xlink: 'http://www.w3.org/1999/xlink',
 };
+/**
+ * Resolves an element name and namespace URI into a normalized form containing
+ * the namespace-qualified name, bare local name, namespace shorthand, and full
+ * namespace URI. Handles explicit namespace prefixes (e.g., `"svg:circle"`) and
+ * falls back to HTML namespace when not specified. Results are cached.
+ *
+ * @param name - The element name, optionally prefixed with a namespace (e.g., `"svg:circle"` or `"div"`)
+ * @param namespaceURI - The namespace URI string, or null (defaults to XHTML namespace)
+ * @returns The resolved namespace information including qualified name, local name, namespace shorthand, and full URI
+ */
 export function resolveNamespace(name, namespaceURI = 'http://www.w3.org/1999/xhtml') {
     const cached = cache.get(name + namespaceURI);
     if (cached) {

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

@@ -1,4 +1,15 @@
 import type { ARIA } from '../types/aria.js';
 import type { ARIAVersion } from '../types/index.js';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Resolves an element's ARIA specification by merging version-specific overrides
+ * on top of the base properties. For each ARIA property (implicitRole, permittedRoles,
+ * etc.), the version-specific value takes precedence over the base value.
+ * `namingProhibited` is special-cased: ARIA 1.1 always uses the base value since
+ * `namingProhibited` was introduced in ARIA 1.2.
+ *
+ * @param aria - The element's full ARIA specification including version-specific blocks
+ * @param version - The ARIA specification version to resolve for
+ * @returns The resolved ARIA specification with version-specific overrides applied
+ */
 export declare function resolveVersion(aria: ReadonlyDeep<ARIA>, version: ARIAVersion): Omit<ReadonlyDeep<ARIA>, ARIAVersion>;

package/lib/utils/resolve-version.js

@@ -1,3 +1,14 @@
+/**
+ * Resolves an element's ARIA specification by merging version-specific overrides
+ * on top of the base properties. For each ARIA property (implicitRole, permittedRoles,
+ * etc.), the version-specific value takes precedence over the base value.
+ * `namingProhibited` is special-cased: ARIA 1.1 always uses the base value since
+ * `namingProhibited` was introduced in ARIA 1.2.
+ *
+ * @param aria - The element's full ARIA specification including version-specific blocks
+ * @param version - The ARIA specification version to resolve for
+ * @returns The resolved ARIA specification with version-specific overrides applied
+ */
 export function resolveVersion(aria, version) {
     const implicitRole = aria[version]?.implicitRole ?? aria.implicitRole;
     const permittedRoles = aria[version]?.permittedRoles ?? aria.permittedRoles;

package/lib/utils/schema-to-spec.d.ts

@@ -1,13 +1,18 @@
 import type { ElementSpec, ExtendedSpec, MLMLSpec } from '../types/index.js';
 /**
- * Merging HTML-spec schema and extended spec schemas
+ * Merges an HTML-spec schema with zero or more extended spec schemas into a single
+ * unified specification. Extended specs can add or override global attributes,
+ * ARIA definitions, content models, and element specifications.
  *
  * Ex: `@markuplint/html-spec` + `{ specs: { "\\.vue$": "@markuplint/vue-spec" } }` in configure files.
  *
- * @param schemas `MLDocument.schemas`
+ * @param schemas - A tuple where the first element is the base `MLMLSpec` and subsequent elements are extended specs to merge
+ * @returns The merged specification combining the base spec with all extensions
  */
 export declare function schemaToSpec(schemas: readonly [MLMLSpec, ...ExtendedSpec[]]): {
     cites: import("../types/index.js").Cites;
     def: import("../types/index.js").SpecDefs;
     specs: readonly ElementSpec[];
+    directivePatterns?: readonly import("../types/index.js").DirectivePattern[];
+    useIDLAttributeNames?: boolean;
 };

package/lib/utils/schema-to-spec.js

@@ -1,10 +1,13 @@
 import { mergeArray } from './merge-array.js';
 /**
- * Merging HTML-spec schema and extended spec schemas
+ * Merges an HTML-spec schema with zero or more extended spec schemas into a single
+ * unified specification. Extended specs can add or override global attributes,
+ * ARIA definitions, content models, and element specifications.
  *
  * Ex: `@markuplint/html-spec` + `{ specs: { "\\.vue$": "@markuplint/vue-spec" } }` in configure files.
  *
- * @param schemas `MLDocument.schemas`
+ * @param schemas - A tuple where the first element is the base `MLMLSpec` and subsequent elements are extended specs to merge
+ * @returns The merged specification combining the base spec with all extensions
  */
 export function schemaToSpec(schemas) {
     const [main, ...extendedSpecs] = schemas;
@@ -16,10 +19,12 @@ export function schemaToSpec(schemas) {
         if (extendedSpec.def) {
             const def = { ...result.def };
             if (extendedSpec.def['#globalAttrs']?.['#extends']) {
-                const gAttrs = { ...def['#globalAttrs'] };
-                gAttrs['#HTMLGlobalAttrs'] = {
-                    ...def['#globalAttrs']?.['#HTMLGlobalAttrs'],
-                    ...extendedSpec.def['#globalAttrs']?.['#extends'],
+                const gAttrs = {
+                    ...def['#globalAttrs'],
+                    '#HTMLGlobalAttrs': {
+                        ...def['#globalAttrs']?.['#HTMLGlobalAttrs'],
+                        ...extendedSpec.def['#globalAttrs']?.['#extends'],
+                    },
                 };
                 def['#globalAttrs'] = gAttrs;
             }
@@ -29,16 +34,19 @@ export function schemaToSpec(schemas) {
                         roles: mergeArray(def['#aria']['1.1'].roles, extendedSpec.def['#aria']['1.1'].roles),
                         props: mergeArray(def['#aria']['1.1'].props, extendedSpec.def['#aria']['1.1'].props),
                         graphicsRoles: mergeArray(def['#aria']['1.1'].graphicsRoles, extendedSpec.def['#aria']['1.1'].graphicsRoles),
+                        dpubRoles: mergeArray(def['#aria']['1.1'].dpubRoles, extendedSpec.def['#aria']['1.1'].dpubRoles),
                     },
                     '1.2': {
                         roles: mergeArray(def['#aria']['1.2'].roles, extendedSpec.def['#aria']['1.2'].roles),
                         props: mergeArray(def['#aria']['1.2'].props, extendedSpec.def['#aria']['1.2'].props),
                         graphicsRoles: mergeArray(def['#aria']['1.2'].graphicsRoles, extendedSpec.def['#aria']['1.2'].graphicsRoles),
+                        dpubRoles: mergeArray(def['#aria']['1.2'].dpubRoles, extendedSpec.def['#aria']['1.2'].dpubRoles),
                     },
                     '1.3': {
                         roles: mergeArray(def['#aria']['1.3'].roles, extendedSpec.def['#aria']['1.3'].roles),
                         props: mergeArray(def['#aria']['1.3'].props, extendedSpec.def['#aria']['1.3'].props),
                         graphicsRoles: mergeArray(def['#aria']['1.3'].graphicsRoles, extendedSpec.def['#aria']['1.3'].graphicsRoles),
+                        dpubRoles: mergeArray(def['#aria']['1.3'].dpubRoles, extendedSpec.def['#aria']['1.3'].dpubRoles),
                     },
                 };
             }
@@ -57,6 +65,12 @@ export function schemaToSpec(schemas) {
             }
             result.def = def;
         }
+        if (extendedSpec.directivePatterns) {
+            result.directivePatterns = [...(result.directivePatterns ?? []), ...extendedSpec.directivePatterns];
+        }
+        if (extendedSpec.useIDLAttributeNames != null) {
+            result.useIDLAttributeNames = extendedSpec.useIDLAttributeNames;
+        }
         if (extendedSpec.specs) {
             const exSpecs = [...extendedSpec.specs];
             const specs = [];

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

@@ -1,2 +1,9 @@
 import type { ARIAVersion } from '../types/index.js';
+/**
+ * Validates whether a string is a supported ARIA specification version.
+ * Acts as a type guard, narrowing the input to the `ARIAVersion` type when `true`.
+ *
+ * @param version - The version string to validate
+ * @returns `true` if the version is a supported ARIA version (e.g., '1.1', '1.2', '1.3')
+ */
 export declare function validateAriaVersion(version: string): version is ARIAVersion;

package/lib/utils/validate-aria-version.js

@@ -1,4 +1,11 @@
 import { ariaVersions } from './aria-version.js';
+/**
+ * Validates whether a string is a supported ARIA specification version.
+ * Acts as a type guard, narrowing the input to the `ARIAVersion` type when `true`.
+ *
+ * @param version - The version string to validate
+ * @returns `true` if the version is a supported ARIA version (e.g., '1.1', '1.2', '1.3')
+ */
 export function validateAriaVersion(version) {
     return ariaVersions.includes(version);
 }

package/package.json

@@ -1,10 +1,13 @@
 {
 	"name": "@markuplint/ml-spec",
-	"version": "4.10.1",
+	"version": "5.0.0-alpha.0",
 	"description": "Types and schema that specs of the Markup languages for markuplint",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
 	"license": "MIT",
+	"engines": {
+		"node": ">=22"
+	},
 	"type": "module",
 	"exports": {
 		".": {
@@ -31,15 +34,14 @@
 		"schema:prettier": "npx prettier --write \"./schemas/*.json\" \"./src/types/*.ts\" --log-level warn"
 	},
 	"dependencies": {
-		"@markuplint/ml-ast": "4.4.10",
-		"@markuplint/types": "4.8.1",
-		"dom-accessibility-api": "0.7.0",
+		"@markuplint/ml-ast": "5.0.0-alpha.0",
+		"@markuplint/types": "5.0.0-alpha.0",
 		"is-plain-object": "5.0.0",
-		"type-fest": "4.41.0"
+		"type-fest": "5.4.4"
 	},
 	"devDependencies": {
-		"@markuplint/test-tools": "4.5.22",
+		"@markuplint/test-tools": "5.0.0-alpha.0",
 		"json-schema-to-typescript": "15.0.4"
 	},
-	"gitHead": "6213ea30269ef404f030e67bbcc7fc7443ec1060"
+	"gitHead": "13dcfc84ec83d87360c720e253383b60767e1b56"
 }