@markuplint/ml-spec 4.10.0 → 4.10.2

package/docs/html-algorithms.md

@@ -0,0 +1,469 @@
+# HTML Content Model Algorithms
+
+## Overview
+
+The `@markuplint/ml-spec` package implements content model evaluation and element classification algorithms derived from the [HTML Living Standard](https://html.spec.whatwg.org/multipage/dom.html#content-models). These functions operate on the DOM `Element` interface together with `MLMLSpec` (the markuplint specification data) to determine what content an element may contain, whether an element is void, palpable, focusable, and more.
+
+All HTML algorithm functions are located under `src/algorithm/html/`.
+
+The content model category types, defined in `src/types/permitted-structures.ts`, cover **10 HTML categories** and **19 SVG categories**, forming the foundation of the content model system.
+
+## Content Model System
+
+### Category-to-Selector Mapping
+
+The spec definitions (`SpecDefs['#contentModels']`) map each `Category` string to a readonly array of CSS selector strings:
+
+```typescript
+type SpecDefs = {
+  readonly '#contentModels': {
+    readonly [model in Category]?: readonly string[];
+  };
+};
+```
+
+Each category maps to selectors that identify which elements belong to that category. For example:
+
+- `#flow` maps to `['a', 'abbr', 'address', ...]`
+- `#interactive` maps to `['a[href]', 'audio[controls]', ...]`
+
+Note that some selectors include attribute conditions (`a[href]`, `audio[controls]`), meaning an element's membership in a category can depend on its attributes. This is how the HTML Standard's conditional content models are represented.
+
+### Conditional Content Models
+
+An element's permitted content can vary based on its attributes. The `ContentModel` interface supports this:
+
+```typescript
+interface ContentModel {
+  contents: PermittedContentPattern[] | boolean;
+  descendantOf?: string;
+  conditional?: {
+    condition: string;
+    contents: PermittedContentPattern[] | boolean;
+  }[];
+}
+```
+
+When `conditional` is present, each condition's `condition` string is tested via `el.matches(condition)`. The first matching condition's `contents` value is used. If no condition matches, the default `contents` value applies.
+
+## Function Reference
+
+### 1. `getContentModel(el, specs)`
+
+**File:** `src/algorithm/html/get-content-model.ts`
+
+Retrieves the permitted content model for an element.
+
+```typescript
+function getContentModel(
+  el: Element,
+  specs: readonly Pick<ElementSpec, 'name' | 'contentModel'>[],
+): ReadonlyDeep<PermittedContentPattern[]> | boolean | null;
+```
+
+**Parameters:**
+
+| Parameter | Type                                                     | Description                                                 |
+| --------- | -------------------------------------------------------- | ----------------------------------------------------------- |
+| `el`      | `Element`                                                | The DOM element to retrieve the content model for           |
+| `specs`   | `readonly Pick<ElementSpec, 'name' \| 'contentModel'>[]` | Element specifications containing content model definitions |
+
+**Return value:**
+
+| Value                       | Meaning                                |
+| --------------------------- | -------------------------------------- |
+| `PermittedContentPattern[]` | Specific content rules for the element |
+| `true`                      | Any content is permitted               |
+| `false`                     | No content is permitted                |
+| `null`                      | No specification found for the element |
+
+**Behavior:**
+
+1. Checks the nested `Map<Specs, Map<Element, result>>` cache. If a cached result exists for the given specs reference and element instance, returns it immediately.
+2. Looks up the element's spec using `getSpec()`. If not found, caches and returns `null`.
+3. Iterates over `contentModel.conditional[]` (if present). For each condition, calls `el.matches(cond.condition)`.
+4. Returns the first matching condition's `contents`. If no condition matches, returns the default `contentModel.contents`.
+5. All results are cached before being returned.
+
+**Caching strategy:**
+
+The cache is a two-level `Map`: the outer map is keyed by the `specs` array reference, and the inner map is keyed by the `Element` instance. This ensures results are correctly invalidated when specs change while avoiding redundant computation for the same element.
+
+---
+
+### 2. `isPalpableElement(el, specs, options?)`
+
+**File:** `src/algorithm/html/is-palpable-elements.ts`
+
+Determines whether an element is considered palpable content -- elements that render something visible or meaningful to the user.
+
+```typescript
+function isPalpableElement(
+  el: Element,
+  specs: MLMLSpec,
+  options?: {
+    readonly extendsSvg?: boolean;
+    readonly extendsExposableElements?: boolean;
+  },
+): boolean;
+```
+
+**Parameters:**
+
+| Parameter                          | Type       | Default | Description                            |
+| ---------------------------------- | ---------- | ------- | -------------------------------------- |
+| `el`                               | `Element`  | --      | The DOM element to check               |
+| `specs`                            | `MLMLSpec` | --      | The full markup language specification |
+| `options.extendsSvg`               | `boolean`  | `true`  | Include `#SVGRenderable` elements      |
+| `options.extendsExposableElements` | `boolean`  | `false` | Include additional exposable elements  |
+
+**Exposable elements** (elements that are semantically meaningful but do not belong to the `#palpable` category):
+
+`body`, `dd`, `dt`, `figcaption`, `html`, `legend`, `li`, `optgroup`, `option`, `rp`, `rt`, `summary`, `tbody`, `td`, `tfoot`, `th`, `thead`, `tr`
+
+**Behavior:**
+
+1. Collects CSS selectors from the `#palpable` content model category.
+2. If `extendsSvg` is not `false` (default: `true`), appends `#SVGRenderable` selectors.
+3. If `extendsExposableElements` is `true` (default: `false`), appends the hardcoded list of exposable elements.
+4. Returns `true` if `el.matches()` succeeds against any of the collected selector strings.
+
+> **Warning:** This implementation involves the author's interpretation of the HTML specification. If you find inaccuracies, please file an issue at https://github.com/markuplint/markuplint/issues/new.
+
+---
+
+### 3. `isVoidElement(el)`
+
+**File:** `src/algorithm/html/is-void-element.ts`
+
+Checks whether an element is a void element as defined by the HTML specification. Void elements cannot have any contents.
+
+```typescript
+function isVoidElement(el: { readonly localName: string }): boolean;
+```
+
+**Parameter:**
+
+| Parameter | Type                             | Description                            |
+| --------- | -------------------------------- | -------------------------------------- |
+| `el`      | `{ readonly localName: string }` | Any object with a `localName` property |
+
+Note that this function accepts any object with a `localName` property, not just a DOM `Element`. This makes it usable in contexts where a full Element is not available.
+
+**Void elements (13):**
+
+`area`, `base`, `br`, `col`, `embed`, `hr`, `img`, `input`, `link`, `meta`, `source`, `track`, `wbr`
+
+The list is stored as a `Set` for O(1) lookup performance.
+
+**Spec:** https://html.spec.whatwg.org/multipage/syntax.html#void-elements
+
+---
+
+### 4. `isNothingContentModel(el)`
+
+**File:** `src/algorithm/html/is-nothing-content-model.ts`
+
+Determines whether an element uses the "nothing" content model, meaning it must not contain any content.
+
+```typescript
+function isNothingContentModel(el: Element): boolean;
+```
+
+**Parameter:**
+
+| Parameter | Type      | Description              |
+| --------- | --------- | ------------------------ |
+| `el`      | `Element` | The DOM element to check |
+
+**Behavior:**
+
+Returns `true` if the element is:
+
+- A **void element** (delegates to `isVoidElement()`), or
+- An `<iframe>` element, or
+- A `<template>` element
+
+While `<iframe>` and `<template>` are not void elements, they also use the "nothing" content model per the HTML specification -- their content is either replaced (iframe) or stored in a separate document fragment (template).
+
+**Spec:** https://html.spec.whatwg.org/multipage/dom.html#the-nothing-content-model
+
+---
+
+### 5. `mayBeFocusable(el, specs)`
+
+**File:** `src/algorithm/html/may-be-focusable.ts`
+
+Performs a heuristic check to determine whether an element may potentially be focusable.
+
+```typescript
+function mayBeFocusable(el: Element, specs: MLMLSpec): boolean;
+```
+
+**Parameters:**
+
+| Parameter | Type       | Description                            |
+| --------- | ---------- | -------------------------------------- |
+| `el`      | `Element`  | The DOM element to check               |
+| `specs`   | `MLMLSpec` | The full markup language specification |
+
+**Behavior:**
+
+Matches the element against the following selectors:
+
+1. All selectors from the `#interactive` content model category (retrieved via `getSelectorsByContentModelCategory()`)
+2. `[tabindex]` -- any element with a `tabindex` attribute
+3. `[contenteditable]:not([contenteditable="false" i])` -- contenteditable elements (case-insensitive comparison)
+
+Returns `true` if `el.matches()` succeeds against any of these selectors.
+
+**Limitations:**
+
+This is a static heuristic. It does **not** account for runtime state that could prevent focusability:
+
+- `disabled` attribute on form elements
+- `inert` attribute
+- Elements hidden via CSS (`display: none`, `visibility: hidden`)
+- Shadow DOM boundaries
+
+This function is primarily used by ARIA role computation to prevent presentational roles (`role="none"` / `role="presentation"`) from being applied to focusable elements, as per the WAI-ARIA specification.
+
+---
+
+### 6. `getSelectorsByContentModelCategory(specs, category)`
+
+**File:** `src/algorithm/html/get-selectors-by-content-model-category.ts`
+
+Direct accessor to retrieve the CSS selectors associated with a content model category.
+
+```typescript
+function getSelectorsByContentModelCategory(specs: MLMLSpec, category: Category): ReadonlyArray<string>;
+```
+
+**Parameters:**
+
+| Parameter  | Type       | Description                                                |
+| ---------- | ---------- | ---------------------------------------------------------- |
+| `specs`    | `MLMLSpec` | The full markup language specification                     |
+| `category` | `Category` | The content model category (e.g., `#flow`, `#interactive`) |
+
+**Return value:**
+
+A readonly array of CSS selector strings for the category, or an empty array if the category is not defined in the spec.
+
+**Implementation:**
+
+```typescript
+const selectors = specs.def['#contentModels'][category];
+return selectors ?? [];
+```
+
+This is a thin wrapper that provides null safety over direct property access.
+
+---
+
+### 7. `contentModelCategoryToTagNames(contentModel, def)`
+
+**File:** `src/algorithm/html/content-model-category-to-tag-names.ts`
+
+Converts a content model category to a sorted, frozen array of tag names belonging to that category.
+
+```typescript
+function contentModelCategoryToTagNames(contentModel: Category, def: MLMLSpec['def']): ReadonlyArray<string>;
+```
+
+**Parameters:**
+
+| Parameter      | Type              | Description                           |
+| -------------- | ----------------- | ------------------------------------- |
+| `contentModel` | `Category`        | The content model category identifier |
+| `def`          | `MLMLSpec['def']` | The specification definitions         |
+
+**Return value:**
+
+A `Object.freeze()`-d, sorted array of tag name strings. Returns a frozen empty array if the category is not defined or has no entries.
+
+**Caching:**
+
+Results are cached in a module-level `Map<Category, ReadonlyArray<string>>`. Once computed for a given category, the result is reused on subsequent calls.
+
+**Important note:** This function extracts tag names directly from the selector strings stored in the content model definitions. It does not perform CSS selector parsing -- the selectors in `#contentModels` are expected to be simple tag names or tag-with-attribute selectors. Complex selectors may not be correctly decomposed into tag names.
+
+## Content Model Categories
+
+### HTML Categories (10)
+
+| Category             | Description                           | Example Elements                                     |
+| -------------------- | ------------------------------------- | ---------------------------------------------------- |
+| `#text`              | Text content                          | Text nodes                                           |
+| `#phrasing`          | Inline-level content                  | `a`, `em`, `strong`, `span`, `img`                   |
+| `#flow`              | Block-level and inline content        | Nearly all body elements                             |
+| `#interactive`       | User-interactable content             | `a[href]`, `button`, `input`, `select`               |
+| `#heading`           | Section headings                      | `h1`, `h2`, `h3`, `h4`, `h5`, `h6`                   |
+| `#sectioning`        | Document structure sections           | `article`, `aside`, `nav`, `section`                 |
+| `#metadata`          | Metadata about the document           | `base`, `link`, `meta`, `script`, `style`, `title`   |
+| `#embedded`          | External content embedded in document | `audio`, `canvas`, `embed`, `iframe`, `img`, `video` |
+| `#palpable`          | Visible/meaningful content            | Most flow/phrasing elements except metadata          |
+| `#script-supporting` | Script infrastructure                 | `script`, `template`                                 |
+
+### SVG Categories (19)
+
+| Category                   | Description                                                                            |
+| -------------------------- | -------------------------------------------------------------------------------------- |
+| `#SVGAnimation`            | SVG animation elements (`animate`, `animateMotion`, etc.)                              |
+| `#SVGBasicShapes`          | Basic shape elements (`circle`, `ellipse`, `line`, `polygon`, `polyline`, `rect`)      |
+| `#SVGContainer`            | Container elements (`a`, `defs`, `g`, `marker`, `mask`, `svg`, `symbol`, etc.)         |
+| `#SVGDescriptive`          | Descriptive elements (`desc`, `metadata`, `title`)                                     |
+| `#SVGFilterPrimitive`      | Filter primitive elements (`feBlend`, `feColorMatrix`, `feGaussianBlur`, etc.)         |
+| `#SVGFont`                 | Font elements (deprecated: `font`, `font-face`, etc.)                                  |
+| `#SVGGradient`             | Gradient elements (`linearGradient`, `radialGradient`, `stop`)                         |
+| `#SVGGraphics`             | Graphics elements (shapes, images, text, etc.)                                         |
+| `#SVGGraphicsReferencing`  | Graphics referencing elements (`image`, `use`)                                         |
+| `#SVGLightSource`          | Light source elements (`feDistantLight`, `fePointLight`, `feSpotLight`)                |
+| `#SVGNeverRendered`        | Elements that are never rendered directly (`clipPath`, `defs`, `linearGradient`, etc.) |
+| `#SVGNone`                 | No content permitted                                                                   |
+| `#SVGPaintServer`          | Paint server elements (`linearGradient`, `pattern`, `radialGradient`, etc.)            |
+| `#SVGRenderable`           | Elements that can be rendered (`a`, `circle`, `g`, `rect`, `svg`, `text`, etc.)        |
+| `#SVGShape`                | Shape elements (`circle`, `ellipse`, `line`, `path`, `polygon`, `polyline`, `rect`)    |
+| `#SVGStructural`           | Structural elements (`defs`, `g`, `svg`, `symbol`, `use`)                              |
+| `#SVGStructurallyExternal` | Structurally external elements (`image`, `use`)                                        |
+| `#SVGTextContent`          | Text content elements (`text`, `textPath`, `tspan`)                                    |
+| `#SVGTextContentChild`     | Text content child elements (`textPath`, `tspan`)                                      |
+
+## PermittedContentPattern Format
+
+The `PermittedContentPattern` type is a discriminated union of six pattern types. These patterns are defined in `src/types/permitted-structures.ts` and are auto-generated from a JSON Schema.
+
+### Pattern Types
+
+#### `PermittedContentRequire`
+
+Specifies required content that must appear.
+
+```typescript
+interface PermittedContentRequire {
+  require: Model | PermittedContentPattern[];
+  min?: number;
+  max?: number;
+}
+```
+
+**Example:** An element that requires exactly one `<caption>`:
+
+```json
+{ "require": "caption", "min": 1, "max": 1 }
+```
+
+#### `PermittedContentOptional`
+
+Specifies content that may optionally appear.
+
+```typescript
+interface PermittedContentOptional {
+  optional: Model | PermittedContentPattern[];
+  max?: number;
+}
+```
+
+**Example:** An optional `<thead>`:
+
+```json
+{ "optional": "thead", "max": 1 }
+```
+
+#### `PermittedContentOneOrMore`
+
+Specifies content that must appear at least once (1..N).
+
+```typescript
+interface PermittedContentOneOrMore {
+  oneOrMore: Model | PermittedContentPattern[];
+  max?: number;
+}
+```
+
+**Example:** One or more `<tr>` elements:
+
+```json
+{ "oneOrMore": "tr" }
+```
+
+#### `PermittedContentZeroOrMore`
+
+Specifies content that may appear any number of times (0..N).
+
+```typescript
+interface PermittedContentZeroOrMore {
+  zeroOrMore: Model | PermittedContentPattern[];
+  max?: number;
+}
+```
+
+**Example:** Zero or more flow content children:
+
+```json
+{ "zeroOrMore": "#flow" }
+```
+
+#### `PermittedContentChoice`
+
+Specifies a choice between two to five alternative content patterns.
+
+```typescript
+interface PermittedContentChoice {
+  choice:
+    | [PermittedContentPattern[], PermittedContentPattern[]]
+    | [PermittedContentPattern[], PermittedContentPattern[], PermittedContentPattern[]]
+    | [
+        /* 4 alternatives */
+      ]
+    | [
+        /* 5 alternatives */
+      ];
+}
+```
+
+**Example:** Either flow content or `<param>` elements followed by flow content:
+
+```json
+{
+  "choice": [[{ "zeroOrMore": "#flow" }], [{ "oneOrMore": "param" }, { "zeroOrMore": "#flow" }]]
+}
+```
+
+#### `PermittedContentTransparent`
+
+Indicates that the element inherits its parent's content model (transparent content model).
+
+```typescript
+interface PermittedContentTransparent {
+  transparent: string;
+}
+```
+
+**Example:** The `<a>` element is transparent:
+
+```json
+{ "transparent": "a" }
+```
+
+### The `Model` Type
+
+The `require`, `optional`, `oneOrMore`, and `zeroOrMore` properties accept a `Model` value, which is defined as:
+
+```typescript
+type Model = ContentType | ContentType[];
+type ContentType = string | Category;
+```
+
+- A single string: either a tag name (e.g., `"div"`) or a category (e.g., `"#flow"`)
+- An array of strings: multiple permitted types (logical OR)
+
+## HTML Standard References
+
+- [Content models](https://html.spec.whatwg.org/multipage/dom.html#content-models)
+- [Void elements](https://html.spec.whatwg.org/multipage/syntax.html#void-elements)
+- [Interactive content](https://html.spec.whatwg.org/multipage/dom.html#interactive-content)
+- [Palpable content](https://html.spec.whatwg.org/multipage/dom.html#palpable-content)
+- [The nothing content model](https://html.spec.whatwg.org/multipage/dom.html#the-nothing-content-model)
+- [Element index](https://html.spec.whatwg.org/multipage/indices.html#elements-3)