@markuplint/ml-spec 4.10.0 → 4.10.2

package/lib/types/index.d.ts

@@ -12,10 +12,19 @@ export interface MLMLSpec {
     readonly def: SpecDefs;
     readonly specs: readonly ElementSpec[];
 }
+/**
+ * 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>;
@@ -25,6 +34,10 @@ export type ExtendedSpec = {
  * 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>>>;
@@ -124,6 +137,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,6 +151,9 @@ 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;
@@ -149,18 +168,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 +207,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 +242,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/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 {};

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();
@@ -67,6 +77,14 @@ export function getAttrSpecs(localName, namespace, schema) {
     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-spec-by-tag-name.d.ts

@@ -1,2 +1,13 @@
 import type { ElementSpec } from '../types/index.js';
+/**
+ * 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, "name" | K> | 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/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/schema-to-spec.d.ts

@@ -1,10 +1,13 @@
 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;

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;

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,6 +1,6 @@
 {
 	"name": "@markuplint/ml-spec",
-	"version": "4.10.0",
+	"version": "4.10.2",
 	"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>",
@@ -31,15 +31,15 @@
 		"schema:prettier": "npx prettier --write \"./schemas/*.json\" \"./src/types/*.ts\" --log-level warn"
 	},
 	"dependencies": {
-		"@markuplint/ml-ast": "4.4.10",
-		"@markuplint/types": "4.8.0",
-		"dom-accessibility-api": "0.7.0",
+		"@markuplint/ml-ast": "4.4.11",
+		"@markuplint/types": "4.8.2",
+		"dom-accessibility-api": "0.7.1",
 		"is-plain-object": "5.0.0",
 		"type-fest": "4.41.0"
 	},
 	"devDependencies": {
-		"@markuplint/test-tools": "4.5.21",
+		"@markuplint/test-tools": "4.5.23",
 		"json-schema-to-typescript": "15.0.4"
 	},
-	"gitHead": "ae97eb2d31ecedf4f0800fbbf18588aad4ebca04"
+	"gitHead": "193ee7c1262bbed95424e38efdf1a8e56ff049f4"
 }