@markuplint/ml-core 4.13.2 → 5.0.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/ARCHITECTURE.ja.md +524 -0
  2. package/ARCHITECTURE.md +524 -0
  3. package/CHANGELOG.md +52 -2
  4. package/README.md +5 -0
  5. package/SKILL.md +61 -0
  6. package/docs/linting-pipeline.ja.md +307 -0
  7. package/docs/linting-pipeline.md +307 -0
  8. package/docs/maintenance.ja.md +210 -0
  9. package/docs/maintenance.md +210 -0
  10. package/docs/ml-dom/attr.ja.md +103 -0
  11. package/docs/ml-dom/attr.md +103 -0
  12. package/docs/ml-dom/block.ja.md +272 -0
  13. package/docs/ml-dom/block.md +272 -0
  14. package/docs/ml-dom/document.ja.md +141 -0
  15. package/docs/ml-dom/document.md +141 -0
  16. package/docs/ml-dom/element.ja.md +176 -0
  17. package/docs/ml-dom/element.md +176 -0
  18. package/docs/ml-dom/helpers.ja.md +203 -0
  19. package/docs/ml-dom/helpers.md +203 -0
  20. package/docs/ml-dom/node.ja.md +199 -0
  21. package/docs/ml-dom/node.md +199 -0
  22. package/docs/ml-dom/others.ja.md +120 -0
  23. package/docs/ml-dom/others.md +120 -0
  24. package/docs/ml-dom/overview.ja.md +102 -0
  25. package/docs/ml-dom/overview.md +102 -0
  26. package/docs/ml-dom/pretender.ja.md +269 -0
  27. package/docs/ml-dom/pretender.md +269 -0
  28. package/docs/ml-dom/rule-mapping.ja.md +371 -0
  29. package/docs/ml-dom/rule-mapping.md +371 -0
  30. package/docs/ml-dom.ja.md +18 -0
  31. package/docs/ml-dom.md +18 -0
  32. package/docs/rule-system.ja.md +287 -0
  33. package/docs/rule-system.md +287 -0
  34. package/lib/convert-ruleset.d.ts +7 -0
  35. package/lib/convert-ruleset.js +7 -0
  36. package/lib/debug.d.ts +4 -0
  37. package/lib/debug.js +4 -0
  38. package/lib/index.d.ts +4 -3
  39. package/lib/index.js +1 -1
  40. package/lib/ml-core.d.ts +37 -1
  41. package/lib/ml-core.js +171 -82
  42. package/lib/ml-dom/helper/accname.d.ts +8 -0
  43. package/lib/ml-dom/helper/accname.js +71 -55
  44. package/lib/ml-dom/helper/create-node.js +1 -0
  45. package/lib/ml-dom/helper/get-indent.d.ts +4 -1
  46. package/lib/ml-dom/helper/get-indent.js +21 -30
  47. package/lib/ml-dom/node/attr.d.ts +65 -4
  48. package/lib/ml-dom/node/attr.js +151 -53
  49. package/lib/ml-dom/node/block.d.ts +23 -2
  50. package/lib/ml-dom/node/block.js +24 -1
  51. package/lib/ml-dom/node/child-node.d.ts +9 -0
  52. package/lib/ml-dom/node/child-node.js +9 -0
  53. package/lib/ml-dom/node/comment.d.ts +7 -0
  54. package/lib/ml-dom/node/comment.js +7 -0
  55. package/lib/ml-dom/node/document-fragment.d.ts +8 -0
  56. package/lib/ml-dom/node/document-fragment.js +8 -0
  57. package/lib/ml-dom/node/document-type.d.ts +22 -0
  58. package/lib/ml-dom/node/document-type.js +25 -0
  59. package/lib/ml-dom/node/document.d.ts +88 -7
  60. package/lib/ml-dom/node/document.js +128 -32
  61. package/lib/ml-dom/node/dom-token-list.js +17 -30
  62. package/lib/ml-dom/node/element-close-tag.js +1 -0
  63. package/lib/ml-dom/node/element.d.ts +151 -5
  64. package/lib/ml-dom/node/element.js +242 -50
  65. package/lib/ml-dom/node/node-store.js +6 -15
  66. package/lib/ml-dom/node/node.d.ts +19 -1
  67. package/lib/ml-dom/node/node.js +175 -166
  68. package/lib/ml-dom/node/parent-node.js +14 -30
  69. package/lib/ml-dom/node/rule-mapper.js +7 -20
  70. package/lib/ml-dom/node/text.d.ts +19 -0
  71. package/lib/ml-dom/node/text.js +21 -0
  72. package/lib/ml-dom/node/types.d.ts +68 -0
  73. package/lib/ml-dom/token/token.d.ts +42 -0
  74. package/lib/ml-dom/token/token.js +59 -39
  75. package/lib/ml-rule/create-rule.d.ts +17 -1
  76. package/lib/ml-rule/ml-rule-context.js +7 -11
  77. package/lib/ml-rule/ml-rule.d.ts +66 -1
  78. package/lib/ml-rule/ml-rule.js +95 -25
  79. package/lib/ml-rule/types.d.ts +41 -0
  80. package/lib/plugin/plugin.d.ts +8 -0
  81. package/lib/plugin/plugin.js +8 -0
  82. package/lib/plugin/types.d.ts +21 -0
  83. package/lib/ruleset/index.d.ts +10 -0
  84. package/lib/ruleset/index.js +13 -0
  85. package/lib/test/index.d.ts +42 -1
  86. package/lib/test/index.js +39 -2
  87. package/lib/types.d.ts +10 -1
  88. package/lib/violation-collector.d.ts +33 -0
  89. package/lib/violation-collector.js +48 -28
  90. package/lib/virtual-rule.d.ts +72 -0
  91. package/lib/virtual-rule.js +233 -0
  92. package/package.json +16 -13
package/lib/ml-dom/node/element.d.ts CHANGED
@@ -3,17 +3,28 @@ import type { MLNamedNodeMap } from './named-node-map.js';
3
3
  import type { MLNode } from './node.js';
4
4
  import type { MLText } from './text.js';
5
5
  import type { ElementNodeType, PretenderContext } from './types.js';
6
- import type { ElementType, MLASTElement, NamespaceURI } from '@markuplint/ml-ast';
6
+ import type { ElementType, MLASTBlockBehavior, MLASTElement, NamespaceURI } from '@markuplint/ml-ast';
7
7
  import type { PlainData, Pretender, RegexSelector, RuleConfigValue, RuleInfo } from '@markuplint/ml-config';
8
8
  import type { ARIAVersion } from '@markuplint/ml-spec';
9
9
  import type { SelectorMatches } from '@markuplint/selector';
10
- import { MLToken } from '../token/token.js';
11
10
  import { MLAttr } from './attr.js';
12
11
  import { MLDomTokenList } from './dom-token-list.js';
13
12
  import { MLElementCloseTag } from './element-close-tag.js';
14
13
  import { MLParentNode } from './parent-node.js';
14
+ /**
15
+ * Represents a DOM Element node wrapper in the markuplint DOM tree.
16
+ * Provides access to element attributes, tag names, namespace, ARIA properties,
17
+ * accessibility information, pretender context, and CSS selector matching.
18
+ * This is the primary class used for linting HTML elements.
19
+ *
20
+ * @template T - The rule configuration value type
21
+ * @template O - The rule options type
22
+ */
15
23
  export declare class MLElement<T extends RuleConfigValue, O extends PlainData = undefined> extends MLParentNode<T, O, MLASTElement> implements Element, HTMLOrSVGElement, HTMLElement {
16
24
  #private;
25
+ /**
26
+ * The closing tag for this element, or null if the element is self-closing or void.
27
+ */
17
28
  readonly closeTag: MLElementCloseTag<T, O> | null;
18
29
  /**
19
30
  * Element type
@@ -23,17 +34,45 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
23
34
  * - `authored`: Authored element (JSX Element etc.) through the view framework or the template engine.
24
35
  */
25
36
  readonly elementType: ElementType;
37
+ /**
38
+ * Whether this element belongs to a non-HTML namespace (e.g., SVG or MathML).
39
+ */
26
40
  readonly isForeignElement: boolean;
41
+ /**
42
+ * Whether this element was implicitly created (e.g., an omitted `<body>` tag in HTML).
43
+ */
27
44
  readonly isOmitted: boolean;
45
+ /**
46
+ * The namespace URI of this element (e.g., `http://www.w3.org/1999/xhtml` for HTML elements).
47
+ */
28
48
  readonly namespaceURI: NamespaceURI;
29
49
  readonly ontouchcancel?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
30
50
  readonly ontouchend?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
31
51
  readonly ontouchmove?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
32
52
  readonly ontouchstart?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
53
+ /**
54
+ * The pretender context if this element is participating in pretender behavior,
55
+ * or null if it is not a pretender or pretended element.
56
+ */
33
57
  pretenderContext: PretenderContext<MLElement<T, O>, T, O> | null;
34
- readonly selfClosingSolidus: MLToken | null;
58
+ /**
59
+ * Block behavior associated with this element, if any.
60
+ */
61
+ readonly blockBehavior: MLASTBlockBehavior | null;
62
+ /**
63
+ * The tag close character string (e.g., `>` or `/>` or `%>`).
64
+ */
35
65
  readonly tagCloseChar: string;
66
+ /**
67
+ * The tag open character string (e.g., `<` or `<%`).
68
+ */
36
69
  readonly tagOpenChar: string;
70
+ /**
71
+ * Creates a new MLElement instance from an AST element node.
72
+ *
73
+ * @param astNode - The AST element node to wrap
74
+ * @param document - The owning document
75
+ */
37
76
  constructor(astNode: MLASTElement, document: MLDocument<T, O>);
38
77
  /**
39
78
  * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -467,6 +506,12 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
467
506
  * @see https://dom.spec.whatwg.org/#dom-slotable-assignedslot
468
507
  */
469
508
  get assignedSlot(): HTMLSlotElement | null;
509
+ /**
510
+ * **IT THROWS AN ERROR WHEN CALLING THIS.**
511
+ *
512
+ * @unsupported
513
+ * @implements DOM API: `Element`
514
+ */
470
515
  get attributeStyleMap(): StylePropertyMap;
471
516
  /**
472
517
  * @implements DOM API: `Element`
@@ -588,9 +633,15 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
588
633
  */
589
634
  get enterKeyHint(): string;
590
635
  /**
636
+ * Returns the fixed (potentially corrected) node name, which may differ from the
637
+ * original node name after lint fixes such as case normalization.
638
+ *
591
639
  * @implements `@markuplint/ml-core` API: `MLElement`
592
640
  */
593
641
  get fixedNodeName(): string;
642
+ /**
643
+ * Whether this element has any spread attributes (e.g., `{...props}` in JSX).
644
+ */
594
645
  get hasSpreadAttr(): boolean;
595
646
  /**
596
647
  * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -1560,6 +1611,9 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
1560
1611
  */
1561
1612
  get previousElementSibling(): MLElement<T, O> | null;
1562
1613
  /**
1614
+ * Returns the original raw element name exactly as it appears in the AST,
1615
+ * without any case normalization or pretender resolution.
1616
+ *
1563
1617
  * @implements `@markuplint/ml-core` API: `MLElement`
1564
1618
  */
1565
1619
  get rawName(): string;
@@ -1572,6 +1626,9 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
1572
1626
  */
1573
1627
  get role(): string;
1574
1628
  /**
1629
+ * Returns the rule configuration for this element, respecting the pretender context.
1630
+ * If the element is a pretended origin, returns the rule from the pretending element.
1631
+ *
1575
1632
  * @implements `@markuplint/ml-core` API: `MLNode`
1576
1633
  */
1577
1634
  get rule(): RuleInfo<T, O>;
@@ -1762,6 +1819,12 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
1762
1819
  * @implements DOM API: `Element`
1763
1820
  */
1764
1821
  computedStyleMap(): StylePropertyMapReadOnly;
1822
+ /**
1823
+ * Overrides the fixed node name for this element, used when the element's
1824
+ * tag name needs to be corrected during linting (e.g., case normalization).
1825
+ *
1826
+ * @param name - The new node name to set
1827
+ */
1765
1828
  fixNodeName(name: string): void;
1766
1829
  /**
1767
1830
  * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -1772,7 +1835,25 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
1772
1835
  */
1773
1836
  focus(options?: FocusOptions): void;
1774
1837
  /**
1838
+ * Returns the accessible name of this element, with per-element memoization.
1839
+ *
1840
+ * On the first call for a given ARIA version the full AccName Computation
1841
+ * algorithm runs (tree walk, `aria-labelledby` resolution, `<label>` lookup,
1842
+ * etc.) and the result is stored in {@link #accessibleNameCache}.
1843
+ * Subsequent calls for the same version return the cached value in O(1).
1844
+ *
1845
+ * **All callers that need the accessible name of an MLElement should use
1846
+ * this method** rather than importing `getAccname()` directly, so that
1847
+ * every consumer benefits from the shared cache. This includes the
1848
+ * `:aria(has name)` selector in `@markuplint/selector`, which uses
1849
+ * duck-typing to detect and call this method.
1850
+ *
1851
+ * Added as part of the fix for {@link https://github.com/markuplint/markuplint/issues/2179 | #2179}
1852
+ * to eliminate redundant AccName computation across rules.
1853
+ *
1775
1854
  * @implements `@markuplint/ml-core` API: `MLElement`
1855
+ * @param version - The ARIA specification version to use for computation
1856
+ * @returns The computed accessible name string (may be empty)
1776
1857
  */
1777
1858
  getAccessibleName(version: ARIAVersion): string;
1778
1859
  /**
@@ -1815,15 +1896,29 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
1815
1896
  */
1816
1897
  getAttributeNodeNS(namespace: string | null, localName: string): Attr | null;
1817
1898
  /**
1899
+ * Gets the attribute value from the original (non-pretended) attributes list,
1900
+ * bypassing any pretender context that might be active.
1901
+ *
1818
1902
  * @implements `@markuplint/ml-core` API: `MLElement`
1903
+ * @param attrName - The attribute name to look up (case-insensitive)
1904
+ * @returns The attribute value, or null if the attribute is not found
1819
1905
  */
1820
1906
  getAttributePretended(attrName: string): string | null;
1821
1907
  /**
1908
+ * Returns all attribute tokens matching the given name, including duplicates.
1909
+ * Unlike `getAttribute`, this returns the full `MLAttr` token objects.
1910
+ *
1822
1911
  * @implements `@markuplint/ml-core` API: `MLElement`
1912
+ * @param attrName - The attribute name to look up (case-insensitive)
1913
+ * @returns An array of matching attribute tokens
1823
1914
  */
1824
1915
  getAttributeToken(attrName: string): MLAttr<T, O>[];
1825
1916
  /**
1917
+ * Returns all attribute tokens for this element, respecting the pretender context.
1918
+ * If the element is pretending to be another, returns the pretender's attributes.
1919
+ *
1826
1920
  * @implements `@markuplint/ml-core` API: `MLElement`
1921
+ * @returns A frozen array of all attribute tokens
1827
1922
  */
1828
1923
  getAttributeTokens(): readonly MLAttr<T, O>[];
1829
1924
  /**
@@ -1834,6 +1929,13 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
1834
1929
  * @see https://www.w3.org/TR/cssom-view-1/#ref-for-dom-element-getboundingclientrect-1
1835
1930
  */
1836
1931
  getBoundingClientRect(): DOMRect;
1932
+ /**
1933
+ * Returns child elements and non-whitespace text nodes, skipping omitted elements
1934
+ * by flattening their children into the result. Results are cached for performance.
1935
+ *
1936
+ * @implements `@markuplint/ml-core` API: `MLElement`
1937
+ * @returns An array of child elements and non-whitespace text nodes
1938
+ */
1837
1939
  getChildElementsAndTextNodeWithoutWhitespaces(): (MLElement<T, O> | MLText<T, O>)[];
1838
1940
  /**
1839
1941
  * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -1870,7 +1972,10 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
1870
1972
  */
1871
1973
  getHTML(options?: any): string;
1872
1974
  /**
1975
+ * Returns the source location of the element's tag name (excluding the opening `<` character).
1976
+ *
1873
1977
  * @implements `@markuplint/ml-core` API: `MLElement`
1978
+ * @returns An object with `offset`, `line`, and `col` properties indicating where the name starts
1874
1979
  */
1875
1980
  getNameLocation(): {
1876
1981
  offset: number;
@@ -1896,13 +2001,21 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
1896
2001
  */
1897
2002
  hasAttributes(): boolean;
1898
2003
  /**
2004
+ * Checks whether this element has any mutable attributes, such as spread
2005
+ * attributes or attributes with dynamic values from template expressions.
2006
+ *
1899
2007
  * @implements `@markuplint/ml-core` API: `MLElement`
2008
+ * @returns True if any attribute is dynamic or lacks a name node (spread)
1900
2009
  */
1901
2010
  hasMutableAttributes(): boolean;
1902
2011
  /**
1903
- * This element has "Preprocessor Specific Block". In other words, Its children are potentially mutable.
2012
+ * Checks whether this element has children that are potentially mutable,
2013
+ * such as preprocessor-specific blocks, slot elements, or (optionally) elements
2014
+ * with dynamic attributes.
1904
2015
  *
1905
2016
  * @implements `@markuplint/ml-core` API: `MLElement`
2017
+ * @param attr - When true, also considers children with mutable attributes as mutable
2018
+ * @returns True if this element has potentially mutable children
1906
2019
  */
1907
2020
  hasMutableChildren(attr?: boolean): boolean;
1908
2021
  /**
@@ -1946,11 +2059,20 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
1946
2059
  */
1947
2060
  insertAdjacentText(where: InsertPosition, data: string): void;
1948
2061
  /**
2062
+ * Checks whether this element is a descendant of any element whose UUID
2063
+ * is in the given list, by walking up the parent element chain.
2064
+ *
1949
2065
  * @implements `@markuplint/ml-core` API: `MLElement`
2066
+ * @param uuidList - A list of element UUIDs to check against
2067
+ * @returns True if any ancestor element's UUID is in the list
1950
2068
  */
1951
2069
  isDescendantByUUIDList(uuidList: readonly string[]): boolean;
1952
2070
  /**
2071
+ * Checks whether this element has no meaningful child content
2072
+ * (only whitespace-only text nodes or no children at all).
2073
+ *
1953
2074
  * @implements `@markuplint/ml-core` API: `MLElement`
2075
+ * @returns True if the element has no non-whitespace child content
1954
2076
  */
1955
2077
  isEmpty(): boolean;
1956
2078
  /**
@@ -1958,9 +2080,22 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
1958
2080
  * @see https://dom.spec.whatwg.org/#ref-for-dom-element-matches%E2%91%A0
1959
2081
  */
1960
2082
  matches(selector: string, scope?: MLParentNode<T, O>): boolean;
2083
+ /**
2084
+ * Matches this element against a CSS selector or regex selector pattern,
2085
+ * returning detailed match results. When the element is a pretender,
2086
+ * it attempts to match both as the pretender and as the original element.
2087
+ *
2088
+ * @param selector - The CSS selector string or regex selector to match against
2089
+ * @param scope - An optional scope node for scoped selector matching
2090
+ * @returns The detailed match result including captured groups from regex selectors
2091
+ */
1961
2092
  matchMLSelector(selector: string | RegexSelector | undefined, scope?: MLParentNode<T, O>): SelectorMatches;
1962
2093
  /**
1963
- * Pretenders Initialization
2094
+ * Initializes the pretender context for this element based on the given pretender
2095
+ * configurations. If a matching pretender is found or the element has an `as` attribute,
2096
+ * sets up the pretender/pretended relationship between elements.
2097
+ *
2098
+ * @param pretenders - Optional array of pretender configurations to match against
1964
2099
  */
1965
2100
  pretending(pretenders?: readonly Pretender[]): void;
1966
2101
  /**
@@ -2108,11 +2243,22 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
2108
2243
  */
2109
2244
  showPopover(): void;
2110
2245
  /**
2246
+ * Returns a normalized string representation of this element including its tag name,
2247
+ * attributes, and child content. Whitespace-only text nodes are excluded.
2248
+ * The result is cached for repeated calls.
2249
+ *
2111
2250
  * @implements `@markuplint/ml-core` API: `MLElement`
2251
+ * @returns The normalized HTML string of this element
2112
2252
  */
2113
2253
  toNormalizeString(): string;
2114
2254
  /**
2255
+ * Returns a string representation of this element. When `fixed` is true,
2256
+ * returns the element with any lint fixes applied to the tag name,
2257
+ * attributes, and embedded comment nodes.
2258
+ *
2115
2259
  * @implements `@markuplint/ml-core` API: `MLElement`
2260
+ * @param fixed - When true, returns the fixed content; otherwise returns the original raw content
2261
+ * @returns The string content of this element
2116
2262
  */
2117
2263
  toString(fixed?: boolean): string;
2118
2264
  /**