@markuplint/ml-spec 5.4.0 → 5.5.0

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

@@ -5,9 +5,13 @@ const cache = new Map();
  * Results are cached for repeated lookups.
  *
  * Note: entries are returned as stored in the spec's `#contentModels` map
- * without CSS selector parsing — they are expected to be bare tag names or
- * tag-with-attribute selectors (e.g. `a[href]`); complex selectors are not
- * decomposed into tag names.
+ * without CSS selector parsing. Besides bare tag names they include selectors
+ * (`a[href]`, `hgroup:has(h1,h2,h3,h4,h5,h6)`, `style:first-child`), which are
+ * not decomposed into tag names; `#custom` and `#text` stand for custom elements
+ * and text. An entry ending in `:first-child` holds as the first child as the HTML
+ * Standard counts it, text included, which markuplint's own paths match with
+ * `contentModelFirstChildBase` and `isContentModelFirstChild` of
+ * `@markuplint/selector`; matched as a plain selector, it counts elements only.
  *
  * @param contentModel - The content model category identifier
  * @param def - The specification definitions containing content model mappings

package/lib/algorithm/html/select-display-size.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The display size of a `<select>`.
+ *
+ * > The display size of a select element is the result of applying the rules for parsing non-negative integers to the
+ * > value of the element's size attribute, if it has one and parsing it is successful. If applying those rules to the
+ * > attribute's value is not successful, or if the size attribute is absent, then the element's display size is 4 if
+ * > the element's multiple content attribute is present, and 1 otherwise.
+ *
+ * The value is whatever text the `size` attribute holds. Deciding that a template expression
+ * (`:size="n"`) is not known yet is up to the caller, which has the attribute node; this function
+ * reads the text as it is.
+ *
+ * @param size - The value of the `size` attribute, or `null` when it is absent
+ * @param hasMultiple - Whether the `multiple` attribute is present
+ * @returns The display size
+ * @see https://html.spec.whatwg.org/multipage/form-elements.html#concept-select-size
+ */
+export declare function getSelectDisplaySize(size: string | null, hasMultiple: boolean): number;
+/**
+ * The rules for parsing non-negative integers: leading ASCII whitespace is
+ * skipped, an optional `+` or `-` is read, then the leading run of ASCII
+ * digits; whatever follows the digits is ignored (`"3abc"` is 3, `"01"` is 1).
+ * No digits, or a negative number, is an error. `-0` is not less than zero.
+ *
+ * @param text - The attribute value, or `null` when it is absent
+ * @returns The number, or `null` for an error
+ * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#rules-for-parsing-non-negative-integers
+ */
+export declare function parseNonNegativeInteger(text: string | null): number | null;

package/lib/algorithm/html/select-display-size.js

@@ -0,0 +1,38 @@
+/**
+ * The display size of a `<select>`.
+ *
+ * > The display size of a select element is the result of applying the rules for parsing non-negative integers to the
+ * > value of the element's size attribute, if it has one and parsing it is successful. If applying those rules to the
+ * > attribute's value is not successful, or if the size attribute is absent, then the element's display size is 4 if
+ * > the element's multiple content attribute is present, and 1 otherwise.
+ *
+ * The value is whatever text the `size` attribute holds. Deciding that a template expression
+ * (`:size="n"`) is not known yet is up to the caller, which has the attribute node; this function
+ * reads the text as it is.
+ *
+ * @param size - The value of the `size` attribute, or `null` when it is absent
+ * @param hasMultiple - Whether the `multiple` attribute is present
+ * @returns The display size
+ * @see https://html.spec.whatwg.org/multipage/form-elements.html#concept-select-size
+ */
+export function getSelectDisplaySize(size, hasMultiple) {
+    return parseNonNegativeInteger(size) ?? (hasMultiple ? 4 : 1);
+}
+/**
+ * The rules for parsing non-negative integers: leading ASCII whitespace is
+ * skipped, an optional `+` or `-` is read, then the leading run of ASCII
+ * digits; whatever follows the digits is ignored (`"3abc"` is 3, `"01"` is 1).
+ * No digits, or a negative number, is an error. `-0` is not less than zero.
+ *
+ * @param text - The attribute value, or `null` when it is absent
+ * @returns The number, or `null` for an error
+ * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#rules-for-parsing-non-negative-integers
+ */
+export function parseNonNegativeInteger(text) {
+    const match = /^[\t\n\f\r ]*([+-]?)(\d+)/.exec(text ?? '');
+    if (!match) {
+        return null;
+    }
+    const value = Number(match[2]);
+    return match[1] === '-' && value !== 0 ? null : value;
+}

package/lib/const/accname.d.ts

@@ -1,7 +1,7 @@
 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
+ * @see https://w3c.github.io/accname/#comp_embedded_control
  */
 export declare const EMBEDDED_CONTROL_ROLES: ReadonlySet<string>;
 /**

package/lib/const/accname.js

@@ -1,6 +1,6 @@
 /**
  * ARIA roles that are embedded controls per AccName Step 2C.
- * @see https://www.w3.org/TR/accname-1.2/#comp_embedded_control
+ * @see https://w3c.github.io/accname/#comp_embedded_control
  */
 export const EMBEDDED_CONTROL_ROLES = new Set([
     'textbox',

package/lib/index.d.ts

@@ -41,6 +41,7 @@ export * from './algorithm/aria/aria-specs.js';
 export * from './algorithm/aria/get-aria.js';
 export * from './algorithm/aria/get-role-spec.js';
 export * from './algorithm/aria/is-presentational.js';
+export * from './algorithm/dom/tree-boundary.js';
 export * from './algorithm/html/get-content-model.js';
 export * from './algorithm/html/may-be-focusable.js';
 export * from './algorithm/html/content-model-category-to-tag-names.js';
@@ -48,6 +49,7 @@ export * from './algorithm/html/get-selectors-by-content-model-category.js';
 export * from './algorithm/html/is-nothing-content-model.js';
 export * from './algorithm/html/is-palpable-elements.js';
 export * from './algorithm/html/is-void-element.js';
+export { getSelectDisplaySize } from './algorithm/html/select-display-size.js';
 export * from './utils/get-attr-specs.js';
 export * from './utils/get-spec.js';
 export * from './utils/get-spec-by-tag-name.js';

package/lib/index.js

@@ -43,6 +43,8 @@ export * from './algorithm/aria/aria-specs.js';
 export * from './algorithm/aria/get-aria.js';
 export * from './algorithm/aria/get-role-spec.js';
 export * from './algorithm/aria/is-presentational.js';
+// DOM algorithms
+export * from './algorithm/dom/tree-boundary.js';
 // HTML algorithms
 export * from './algorithm/html/get-content-model.js';
 export * from './algorithm/html/may-be-focusable.js';
@@ -51,6 +53,7 @@ export * from './algorithm/html/get-selectors-by-content-model-category.js';
 export * from './algorithm/html/is-nothing-content-model.js';
 export * from './algorithm/html/is-palpable-elements.js';
 export * from './algorithm/html/is-void-element.js';
+export { getSelectDisplaySize } from './algorithm/html/select-display-size.js';
 // Shared utilities
 export * from './utils/get-attr-specs.js';
 export * from './utils/get-spec.js';

package/lib/types/index.d.ts

@@ -2,7 +2,7 @@ import type { ARIA } from './aria.js';
 import type { AttributeJSON, AttributeType, ConditionalAttributeType, GlobalAttributes } from './attributes.js';
 import type { ContentModel, Category } from './permitted-structures.js';
 import type { ariaVersions } from '../utils/aria-version.js';
-import type { NamespaceURI } from '@markuplint/ml-ast';
+import type { ExpressionLanguage, LiteralValueDeclaration, NamespaceURI } from '@markuplint/ml-ast';
 import type { ReadonlyDeep } from 'type-fest';
 /**
  * markuplint Markup-language spec
@@ -12,6 +12,20 @@ export interface MLMLSpec {
     readonly def: SpecDefs;
     readonly specs: readonly ElementSpec[];
     readonly directivePatterns?: readonly DirectivePattern[];
+    /**
+     * Selectors of the elements that the framework moves to the `<head>` wherever they are written, so
+     * the content model of the element that contains them does not apply to them. An element in the
+     * `<head>` itself is not moved, and is judged as usual.
+     *
+     * React does so for `<title>`, `<meta>`, `<link>` and `<style>` under conditions the selectors
+     * express (`@markuplint/react-spec`):
+     *
+     * > React will always place the DOM element corresponding to the `<title>` component within the
+     * > document's `<head>`, regardless of where in the React tree it is rendered.
+     *
+     * @see https://react.dev/reference/react-dom/components/title#special-rendering-behavior
+     */
+    readonly movedToHead?: readonly string[];
     /**
      * Controls how `@markuplint/ml-core`'s `MLAttr` resolves attribute names.
      *
@@ -23,6 +37,30 @@ export interface MLMLSpec {
      *   names and IDL property names without suggesting either. Used by Svelte.
      */
     readonly acceptedAttrNames?: 'idl' | 'both';
+    /**
+     * Where the browser holds the children of a `template` element that the author wrote without
+     * a directive of the framework.
+     *
+     * - `'separate-tree'` (the default, as the HTML parser does it): in the `content` of the element, a
+     *   `DocumentFragment` that is a tree of its own. An id in it is unique in that tree only, and an
+     *   id reference in it is resolved in that tree only. A declarative shadow root (`shadowrootmode`)
+     *   may be attached to the parent element.
+     * - `'in-place'`: in the element itself, in the tree of the document. The framework creates the
+     *   element and appends the children to it through the DOM API, which never fills `content` and
+     *   never attaches a declarative shadow root: the `template` element is an ordinary element.
+     *
+     * Known limitations of `'in-place'`: React does not render the same tree when it hydrates server
+     * output (the server output has the children in `content`), and Vue puts them in `content` when
+     * it renders static markup as a string and replaces the element with its content when it hydrates.
+     */
+    readonly templateContent?: 'separate-tree' | 'in-place';
+    /**
+     * How the framework renders a literal in an attribute value that is written as code, where it
+     * differs from the default of `@markuplint/ml-core`: by kind of attribute, and by attribute name
+     * in `attrs`, in the form that a parser declares as well (see {@link LiteralValueDeclaration}).
+     * What differs on a custom element is in `customElements`.
+     */
+    readonly literalValues?: LiteralValueDeclaration;
 }
 /**
  * An element specification for extending or overriding parts of the base spec.
@@ -42,11 +80,25 @@ export type ExtendedSpec = {
     readonly def?: Partial<SpecDefs>;
     readonly specs?: readonly ExtendedElementSpec[];
     readonly directivePatterns?: readonly DirectivePattern[];
+    /**
+     * See {@link MLMLSpec.movedToHead}. Concatenated across merged specs, in the order of the specs.
+     */
+    readonly movedToHead?: readonly string[];
     /**
      * See {@link MLMLSpec.acceptedAttrNames}. Last-write-wins across merged
      * specs; omitting the property does not reset a previously set value.
      */
     readonly acceptedAttrNames?: 'idl' | 'both';
+    /**
+     * See {@link MLMLSpec.templateContent}. Last-write-wins across merged specs; omitting the
+     * property does not reset a previously set value.
+     */
+    readonly templateContent?: 'separate-tree' | 'in-place';
+    /**
+     * See {@link MLMLSpec.literalValues}. Merged by kind of attribute, by attribute name and by key,
+     * and the later spec wins on a key that two specs have.
+     */
+    readonly literalValues?: LiteralValueDeclaration;
 };
 /**
  * A declarative pattern for resolving framework-specific directive
@@ -86,9 +138,18 @@ export type DirectivePattern = {
      */
     readonly isDirective?: true;
     /**
-     * Whether this attribute has a dynamic value.
+     * Whether the value of this attribute is written as code (a binding). It is the source of
+     * `MLAttr#isExpressionValue`; whether the value is known is up to `MLAttr#isDynamicValue`, which
+     * reads the code.
      */
     readonly isDynamicValue?: true;
+    /**
+     * The language of the code that the value is written in. A value that is nothing but a literal is
+     * rendered as the framework renders it (see {@link MLMLSpec.literalValues}), which needs the
+     * attribute to be the one the pattern names (`potentialName`) and the value to be what the attribute
+     * becomes, not a condition or a binding target. A pattern without it is not read as a literal.
+     */
+    readonly expressionLanguage?: ExpressionLanguage;
     /**
      * The semantic value type for matched attributes.
      */

package/lib/types/permitted-structures.d.ts

@@ -14,9 +14,13 @@ export interface ContentModel {
     contents: PermittedContentPattern[] | boolean;
     descendantOf?: string;
     /**
-     * Elements that this element must NOT appear as a descendant of. Each entry is a CSS selector matching forbidden ancestor elements.
+     * Elements that this element must NOT appear as a descendant of. Each entry is a CSS selector matching forbidden ancestor elements. The walk up the tree stops at the content of a `template` element, which has no ancestors.
      */
     forbiddenAncestors?: string[];
+    /**
+     * Elements that this element's ancestors are limited to: every ancestor must match at least one entry. Each entry is a CSS selector, or `#custom` for a custom element (a component or an autonomous custom element). A selector can use `:aria(has no name)`, which is evaluated with the recommended ARIA version. The walk up the tree stops at the content of a `template` element, which has no ancestors.
+     */
+    permittedAncestors?: string[];
     /**
      * Attributes that must be unique among sibling elements of the same type. If this element has one of these attributes, no other sibling element of the same type may also have it. Example: `["default"]` for `<track>` — only one `<track>` per parent may have `default`.
      */

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

@@ -1,4 +1,5 @@
 import type { DirectivePattern } from '../types/index.js';
+import type { ExpressionLanguage } from '@markuplint/ml-ast';
 type CompiledDirectivePattern = {
     readonly regex: RegExp;
     readonly pattern: DirectivePattern;
@@ -11,7 +12,14 @@ export declare function compileDirectivePatterns(patterns: readonly DirectivePat
 export type DirectiveResolution = {
     readonly potentialName?: string;
     readonly isDirective?: true;
+    /**
+     * Whether the value is written as code (a binding). Whether its value is known is up to `MLAttr`.
+     */
     readonly isDynamicValue?: true;
+    /**
+     * Present only when the matched pattern declares it.
+     */
+    readonly expressionLanguage?: ExpressionLanguage;
     readonly valueType?: 'string' | 'number' | 'boolean' | 'code';
     readonly isDuplicatable?: boolean;
 };

package/lib/utils/directive-resolver.js

@@ -44,6 +44,7 @@ compiledPatterns) {
             isDynamicValue: pattern.isDynamicValue,
             valueType: pattern.valueType,
             isDuplicatable,
+            ...(pattern.expressionLanguage ? { expressionLanguage: pattern.expressionLanguage } : {}),
         };
     }
     return null;

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

@@ -1,4 +1,5 @@
 import type { ElementSpec, ExtendedSpec, MLMLSpec } from '../types/index.js';
+import type { LiteralValueDeclaration } from '@markuplint/ml-ast';
 /**
  * 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,
@@ -24,5 +25,8 @@ export declare function schemaToSpec(schemas: readonly [MLMLSpec, ...ExtendedSpe
     def: import("../types/index.js").SpecDefs;
     specs: readonly ElementSpec[];
     directivePatterns?: readonly import("../types/index.js").DirectivePattern[];
+    movedToHead?: readonly string[];
     acceptedAttrNames?: "idl" | "both";
+    templateContent?: "separate-tree" | "in-place";
+    literalValues?: LiteralValueDeclaration;
 };

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

@@ -78,9 +78,18 @@ export function schemaToSpec(schemas) {
         if (extendedSpec.directivePatterns) {
             result.directivePatterns = [...(result.directivePatterns ?? []), ...extendedSpec.directivePatterns];
         }
+        if (extendedSpec.movedToHead) {
+            result.movedToHead = [...(result.movedToHead ?? []), ...extendedSpec.movedToHead];
+        }
         if (extendedSpec.acceptedAttrNames != null) {
             result.acceptedAttrNames = extendedSpec.acceptedAttrNames;
         }
+        if (extendedSpec.templateContent != null) {
+            result.templateContent = extendedSpec.templateContent;
+        }
+        if (extendedSpec.literalValues) {
+            result.literalValues = mergeLiteralValues(result.literalValues, extendedSpec.literalValues);
+        }
         if (extendedSpec.specs) {
             const exSpecs = [...extendedSpec.specs];
             const specs = [];
@@ -121,3 +130,36 @@ function mergeAttrSpec(std, ex = {}) {
     }
     return result;
 }
+/**
+ * Merges the `literalValues` of two specs by kind of attribute, by attribute name and by key; the
+ * later spec wins on a key that both have. `customElements` is merged the same way.
+ */
+function mergeLiteralValues(base, ex) {
+    const { customElements: baseCustomElements, ...baseTable } = base ?? {};
+    const { customElements: exCustomElements, ...exTable } = ex;
+    return {
+        ...mergeLiteralValueTable(baseTable, exTable),
+        ...(baseCustomElements || exCustomElements
+            ? { customElements: mergeLiteralValueTable(baseCustomElements, exCustomElements) }
+            : {}),
+    };
+}
+function mergeLiteralValueTable(base = {}, ex = {}) {
+    const { attrs: baseAttrs, ...baseKinds } = base;
+    const { attrs: exAttrs, ...exKinds } = ex;
+    const attrs = { ...baseAttrs };
+    for (const [name, values] of Object.entries(exAttrs ?? {})) {
+        attrs[name] = { ...baseAttrs?.[name], ...values };
+    }
+    return {
+        ...mergeLiteralValueKinds(baseKinds, exKinds),
+        ...(baseAttrs || exAttrs ? { attrs } : {}),
+    };
+}
+function mergeLiteralValueKinds(base, ex) {
+    const result = { ...base };
+    for (const [kind, values] of Object.entries(ex)) {
+        result[kind] = { ...result[kind], ...values };
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/ml-spec",
-	"version": "5.4.0",
+	"version": "5.5.0",
 	"description": "Types and schema that specs of the Markup languages for markuplint",
 	"repository": {
 		"type": "git",
@@ -36,14 +36,15 @@
 		"schema:aria": "npx json2ts ./schemas/aria.schema.json --cwd ./schemas > ./src/types/aria.ts"
 	},
 	"dependencies": {
-		"@markuplint/ml-ast": "5.3.0",
-		"@markuplint/types": "5.4.0",
+		"@markuplint/ml-ast": "5.5.0",
+		"@markuplint/shared": "5.5.0",
+		"@markuplint/types": "5.5.0",
 		"is-plain-object": "^5.1.0",
 		"type-fest": "^5.10.0"
 	},
 	"devDependencies": {
-		"@markuplint/test-tools": "5.4.0",
+		"@markuplint/test-tools": "5.5.0",
 		"json-schema-to-typescript": "16.0.0"
 	},
-	"gitHead": "ab56aa8e12b67fbf793ddf1267aaba9fda90269d"
+	"gitHead": "fedebcfd56eaec4642e68643b2f9e10750d810e1"
 }