@markuplint/ml-core 5.4.0 → 5.6.0

package/lib/ml-dom/helper/slot-assignment.js

@@ -0,0 +1,292 @@
+import { isShadowRoot } from '@markuplint/ml-spec';
+import { getDOMValue, getShadowHost, getShadowRootTemplate, HTML_NAMESPACE, isTransparent } from './tree-scope.js';
+const cache = new WeakMap();
+/**
+ * Whether the element is the HTML `slot` element: not the placeholder of a framework's component
+ * (`MLParser#slotElement`, and what the parser of a framework turns into a fragment).
+ *
+ * @param el - An element
+ * @returns `true` for the HTML `slot` element
+ */
+function isHTMLSlot(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el) {
+    return (el.localName === 'slot' &&
+        el.namespaceURI === HTML_NAMESPACE &&
+        !el.isFragment &&
+        el.ownerMLDocument.slotElement === 'html');
+}
+/**
+ * The string that the DOM has for an attribute that names a slot: `''` when it is missing, `null`
+ * when it is written as code.
+ *
+ * @param el - The element
+ * @param name - The attribute name (`name` of a `slot`, `slot` of a slottable)
+ * @returns The name, or `null` when it is not known
+ */
+function getSlotName(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, name) {
+    // An attribute that has no name node is a spread (`{...props}`), which may set it
+    if (el.attributes.some(attr => !attr.nameNode)) {
+        return null;
+    }
+    const attr = el.getAttributeNode(name);
+    if (!attr || attr.isAbsent) {
+        return '';
+    }
+    return getDOMValue(attr);
+}
+/**
+ * Collects the HTML `slot` elements of the shadow root in tree order, without entering the content of a
+ * `template` element, which is a tree of its own.
+ *
+ * @param parent - The shadow root, or an element in it
+ * @param slots - The slots found so far, which the walk appends to
+ * @param inBlock - Whether the walk went through a node that the engine renders away (a block or a
+ *   fragment), under which a slot may not be rendered
+ * @returns `false` when which slot is the first of its name is not known: a slot in such a node, or
+ *   one whose `name` is not known
+ */
+function collectSlots(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+parent, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+slots, inBlock) {
+    for (const child of parent.getPureChildNodes()) {
+        if (!child.is(child.ELEMENT_NODE) && !child.is(child.MARKUPLINT_PREPROCESSOR_BLOCK)) {
+            continue;
+        }
+        if (isTransparent(child)) {
+            if (!collectSlots(child, slots, true)) {
+                return false;
+            }
+            continue;
+        }
+        if (!child.is(child.ELEMENT_NODE)) {
+            continue;
+        }
+        if (isHTMLSlot(child)) {
+            // Whether it is rendered, and its `name`, are not known
+            if (inBlock || getSlotName(child, 'name') === null) {
+                return false;
+            }
+            slots.push(child);
+        }
+        // The content of a `template` element is a tree of its own, which has its own slots
+        if (!child.isHTMLTemplateElement && !collectSlots(child, slots, inBlock)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * The nodes that are the children of the host in the output, seen through what the engine renders away,
+ * the nodes in every branch of a conditional block included.
+ *
+ * @param parent - The host, or a node that the engine renders away in it
+ * @param nodes - The nodes found so far
+ * @param declaring - The `template` element that declares the shadow root, which is not a child of the host in the tree
+ * @returns `false` when the nodes are not known
+ */
+function collectSlottables(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+parent, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+nodes, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+declaring) {
+    for (const child of parent.getPureChildNodes()) {
+        if (child === declaring) {
+            continue;
+        }
+        if (child.is(child.MARKUPLINT_PREPROCESSOR_BLOCK)) {
+            // A block that has no behavior may be a marker of a language whose blocks the syntax tree does not nest
+            if (!child.blockBehavior || !collectSlottables(child, nodes, declaring)) {
+                return false;
+            }
+            continue;
+        }
+        if (child.is(child.ELEMENT_NODE)) {
+            if (isTransparent(child)) {
+                if (!collectSlottables(child, nodes, declaring)) {
+                    return false;
+                }
+                continue;
+            }
+            // What it renders may carry any `slot` attribute
+            if (child.isUnresolvedComponent()) {
+                return false;
+            }
+            nodes.push(child);
+            continue;
+        }
+        if (child.is(child.TEXT_NODE)) {
+            nodes.push(child);
+        }
+    }
+    return true;
+}
+/**
+ * Computes the assignment of the shadow root of a host.
+ *
+ * @param host - A shadow host
+ * @returns The assignment, or `null` when the host has no shadow root or any of the causes in the module
+ *   comment leaves the assignment unknown
+ */
+function compute(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+host) {
+    const root = host.declarativeShadowRoot;
+    const template = getShadowRootTemplate(host);
+    if (!root || !template) {
+        return null;
+    }
+    if (host.ownerMLDocument.slotElement !== 'html' || root.slotAssignment === 'manual') {
+        return null;
+    }
+    // A shadow root that a conditional wrapper may not render has no known slots
+    if (template.syntacticalParentNode !== host) {
+        return null;
+    }
+    const slotList = [];
+    if (!collectSlots(root, slotList, false)) {
+        return null;
+    }
+    const slottables = [];
+    if (!collectSlottables(host, slottables, template)) {
+        return null;
+    }
+    const names = new Map();
+    for (const slot of slotList) {
+        const name = getSlotName(slot, 'name');
+        if (name === null) {
+            return null;
+        }
+        names.set(slot, name);
+    }
+    const slots = new Map(slotList.map(slot => [slot, []]));
+    // The first slot of the shadow root, in tree order, that has each name
+    const firstSlotOfName = new Map();
+    for (const slot of slotList) {
+        const name = names.get(slot);
+        if (name !== undefined && !firstSlotOfName.has(name)) {
+            firstSlotOfName.set(name, slot);
+        }
+    }
+    const assigned = new Map();
+    for (const node of slottables) {
+        const name = node.is(node.ELEMENT_NODE) ? getSlotName(node, 'slot') : '';
+        if (name === null) {
+            return null;
+        }
+        const slot = firstSlotOfName.get(name) ?? null;
+        assigned.set(node, slot);
+        if (slot) {
+            slots.get(slot)?.push(node);
+        }
+    }
+    return { slots, assigned };
+}
+/**
+ * The assignment of a host, computed once: the document does not change after it is built, as the other
+ * getters about trees (`MLElement#declarativeShadowRoot`) assume, so the answer never goes stale.
+ *
+ * @param host - A shadow host
+ * @returns The assignment, or `null` when it is not known
+ */
+function getSlotAssignment(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+host) {
+    if (cache.has(host)) {
+        return cache.get(host) ?? null;
+    }
+    // The document does not change once it is built, as the other getters about trees assume
+    const assignment = compute(host);
+    cache.set(host, assignment);
+    return assignment;
+}
+/**
+ * The nodes a `slot` places.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param slot - An element
+ * @returns The assigned nodes in tree order (`[]` when it takes none), or `null` when the element is not an
+ *   HTML `slot` of a declarative shadow root whose assignment is known (see the module comment)
+ * @see https://dom.spec.whatwg.org/#dom-slot-assignednodes
+ */
+export function getAssignedNodes(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+slot) {
+    if (!isHTMLSlot(slot)) {
+        return null;
+    }
+    const root = slot.getRootNode();
+    if (!isShadowRoot(root)) {
+        return null;
+    }
+    return getSlotAssignment(root.host)?.slots.get(slot) ?? null;
+}
+/**
+ * The slot that places a node, as the flat tree has it.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param node - An element or a text node
+ * @returns The slot; `null` when the node is a child of a shadow host that no slot of its shadow root
+ *   takes, so that it is not rendered; `undefined` when the node is not a child of a shadow host, or the
+ *   assignment is not known
+ * @see https://dom.spec.whatwg.org/#find-a-slot
+ */
+export function getFlatTreeSlot(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+node) {
+    // The parent in the output: a block or a fragment that the engine renders away is not the parent
+    const host = getShadowHost(node);
+    if (!host?.declarativeShadowRoot) {
+        return undefined;
+    }
+    return getSlotAssignment(host)?.assigned.get(node);
+}
+/**
+ * The slot of an open shadow root that a node is assigned to.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param node - An element or a text node
+ * @returns The slot, or `null` when none takes the node, its shadow root is closed, or the assignment is not known
+ * @see https://dom.spec.whatwg.org/#dom-slotable-assignedslot
+ */
+export function getAssignedSlot(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+node) {
+    const slot = getFlatTreeSlot(node);
+    if (!slot) {
+        return null;
+    }
+    const root = slot.getRootNode();
+    return 'mode' in root && root.mode === 'open' ? slot : null;
+}
+/**
+ * The nodes a `slot` renders, with each assigned slot replaced by what that slot renders in turn, and the
+ * children of a slot that takes none in its place.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param slot - An element
+ * @returns The nodes, or `[]` when the assignment is not known
+ * @see https://dom.spec.whatwg.org/#find-flattened-slotables
+ */
+export function getFlattenedSlottables(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+slot) {
+    const assigned = getAssignedNodes(slot);
+    if (!assigned) {
+        return [];
+    }
+    const slottables = assigned.length > 0
+        ? assigned
+        : [...slot.childNodes].filter(node => node.is(node.ELEMENT_NODE) || node.is(node.TEXT_NODE));
+    return slottables.flatMap(node => node.is(node.ELEMENT_NODE) && getAssignedNodes(node) !== null ? getFlattenedSlottables(node) : [node]);
+}

package/lib/ml-dom/helper/tree-scope.d.ts

@@ -0,0 +1,130 @@
+import type { MLAttr } from '../node/attr.js';
+import type { MLElement } from '../node/element.js';
+import type { MLNode } from '../node/node.js';
+import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
+/**
+ * @module
+ *
+ * The tree of a node is what its `getRootNode()` returns: the document, the content of an
+ * HTML `template` element, or a declarative shadow root. An id is unique in a tree, and an id
+ * reference is resolved in a tree, as the specification says of "the element's tree".
+ *
+ * markuplint keeps the content of a `template` element as the children of the element (the
+ * syntax tree has no other place for it), so the boundary is made here and not by the shape of
+ * the tree: the queries of `MLParentNode`, `getRootNode()`, `treeParentElement`, the selector
+ * engine and `contains()` stop at it. `parentNode` / `parentElement` do not: the content
+ * model of a `template` element is validated against the elements that the syntax tree puts
+ * in it, so they go on to the `template` element. The algorithms of `@markuplint/ml-spec` walk up
+ * with `getTreeParentElement` / `getComposedParentElement`, which read `getRootNode()`, so the
+ * boundary made here is the boundary they stop at.
+ *
+ * @see https://dom.spec.whatwg.org/#concept-tree
+ * @see https://html.spec.whatwg.org/multipage/dom.html#the-id-attribute
+ * @see https://html.spec.whatwg.org/multipage/scripting.html#the-template-element
+ */
+export declare const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+/**
+ * Whether a declarative shadow root is attached to the parent element of a `template` element.
+ *
+ * - `attached`: it is. The `template` element is in no tree, and its content is the shadow root.
+ * - `not-attached`: it is not. The `template` element is an ordinary one of the tree it is in.
+ * - `unknown`: the markup alone does not tell. The parent element is not in the file (the template is at
+ *   the top of a partial), is a component, is a pretended component that drops its children or puts
+ *   them in a slot wrapper, or `shadowrootmode` is a dynamic value. markuplint does not
+ *   decide what it cannot decide, as it does with a dynamic value elsewhere: the element is treated as
+ *   in no tree, so its own id is not counted and the references of it are not reported.
+ */
+export type DeclarativeShadowRootAttachment = 'attached' | 'not-attached' | 'unknown';
+/**
+ * Whether `node` is skipped when the parent of a `template` element is looked for: what the
+ * template engine or the framework renders away (a block of a template language, a fragment of
+ * JSX, a `template` with a directive such as `v-if`) leaves its children to the next element
+ * above.
+ *
+ * `isRenderedAway` of `@markuplint/rules` (`src/helpers.ts`) decides the same of an element for the
+ * rules that walk up the ancestors: a kind added here belongs to it too.
+ *
+ * @param node - A node of the syntax tree
+ * @returns `true` if the node is not an element of the output
+ */
+export declare function isTransparent<T extends RuleConfigValue, O extends PlainData>(node: MLNode<T, O>): boolean;
+/**
+ * Whether the element is an HTML `template` element, which holds its children in `content`, a tree
+ * of its own.
+ *
+ * It is not when the element is a fragment, has a directive of a template engine, or the
+ * framework puts the children in the element itself (`templateContent: 'in-place'` of the spec).
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param el - An element
+ * @returns `true` if the children of the element belong to a tree of their own
+ */
+export declare function isHTMLTemplateElement<T extends RuleConfigValue, O extends PlainData>(el: MLElement<T, O>): boolean;
+/**
+ * The mode of the declarative shadow root that a `template` element asks for.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param template - An element
+ * @returns `open` or `closed`, or `null` when it is not an HTML `template` element, the
+ *   attribute is missing or invalid, or its value is dynamic
+ */
+export declare function getDeclarativeShadowRootMode<T extends RuleConfigValue, O extends PlainData>(template: MLElement<T, O>): 'open' | 'closed' | null;
+/**
+ * The element that the HTML parser makes the shadow host of a `template` element: its parent in
+ * the output, where what the engine renders away (see {@link isTransparent}) is skipped. It is the
+ * parent in the output of any node, so it is the host a light child is a child of.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param template - A `template` element, or any node whose parent in the output is wanted
+ * @returns The element, or `null` when the file has none above the node
+ */
+export declare function getShadowHost<T extends RuleConfigValue, O extends PlainData>(template: MLNode<T, O>): MLElement<T, O> | null;
+/**
+ * Whether a declarative shadow root is attached to the parent of a `template` element, by what
+ * the HTML parser does with the start tag of `template` and what the DOM does to attach a shadow
+ * root: the mode is `open` or `closed` (ASCII case-insensitive), the parent is an HTML element with
+ * a valid shadow host name (a valid custom element name, or one of the names the DOM lists), and no
+ * earlier `template` of the same parent has attached one.
+ *
+ * The file is taken as parsed as a document that was served, so declarative shadow roots are
+ * allowed. The parser would not attach one to the top level of a fragment parsed through `innerHTML`,
+ * but whether a file is that is not something its markup says.
+ *
+ * Known limitation: a custom element definition may disable the shadow root (`disable shadow`),
+ * which only the script that defines the element tells. It is taken as not disabled.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param template - An element
+ * @returns The state. An element that is not an HTML `template` element is `not-attached`
+ * @see https://html.spec.whatwg.org/multipage/parsing.html#parsing-main-inhead
+ * @see https://dom.spec.whatwg.org/#concept-attach-a-shadow-root
+ */
+export declare function getDeclarativeShadowRootAttachment<T extends RuleConfigValue, O extends PlainData>(template: MLElement<T, O>): DeclarativeShadowRootAttachment;
+/**
+ * The `template` element of a host whose declarative shadow root is attached, if there is one.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param host - An element
+ * @returns The `template` element whose content is the shadow root of the host, or `null`
+ */
+export declare function getShadowRootTemplate<T extends RuleConfigValue, O extends PlainData>(host: MLElement<T, O>): MLElement<T, O> | null;
+/**
+ * The string that the DOM has for an attribute: the value with the character references in the markup
+ * resolved, so that `a&#x62;` is `ab`. A value that is written as code is a string already, with no
+ * character reference in it.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param attr - An attribute, or `null` for one that is missing
+ * @param value - A part of the value of the attribute as it is written (one token of a list), which the
+ *   attribute decides on whether it has a character reference; the whole value by default
+ * @returns The string, or `null` when the attribute is missing, a directive, or its value is not known
+ *   until it is rendered (a dynamic value)
+ * @see https://html.spec.whatwg.org/multipage/dom.html#the-id-attribute
+ */
+export declare function getDOMValue<T extends RuleConfigValue, O extends PlainData>(attr: MLAttr<T, O> | null | undefined, value?: string): string | null;