Skip to content

Commit 5792e1d

Browse files
committed
docs(is-native-element): disambiguate 'native' in the JSDoc
'Native' is overloaded in the web platform context. The util name remains isNativeElement (common convention in React/Vue/Angular ecosystems for 'platform-provided, not a component'), but the JSDoc now explicitly names three alternative meanings of 'native' that this util does NOT answer: - 'native accessibility' / 'widget-ness' — interactive-roles.js (aria-query widget taxonomy) - 'native interactive content' — html-interactive-content.js (HTML §3.2.5.2.7 content-model question) - 'natively focusable' — HTML §6.6.3 sequential focus navigation This util answers only: is this tag a first-class built-in element of HTML/SVG/MathML, rather than a component invocation or a scope-shadowed local binding? Callers compose it with the more specific utils when they need a narrower question.
1 parent 644f4ed commit 5792e1d

1 file changed

Lines changed: 18 additions & 0 deletions

File tree

lib/utils/is-native-element.js

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,24 @@ const ELEMENT_TAGS = new Set([...htmlTags, ...svgTags, ...mathmlTagNames]);
1717
* element — i.e. the tag name is in the authoritative list AND is not
1818
* shadowed by an in-scope binding.
1919
*
20+
* "Native" here means **spec-registered tag name** (in the HTML, SVG, or
21+
* MathML spec registries, reached via the `html-tags` / `svg-tags` /
22+
* `mathml-tag-names` packages). It is NOT the same as:
23+
*
24+
* - "native accessibility" / "widget-ness" — see `interactive-roles.js`
25+
* (aria-query widget taxonomy; an ARIA-tree-semantics question)
26+
* - "native interactive content" / "focus behavior" — see
27+
* `html-interactive-content.js` (HTML §3.2.5.2.7; an HTML-content-model
28+
* question about which tags can be nested inside what)
29+
* - "natively focusable" / sequential-focus — see HTML §6.6.3
30+
*
31+
* This util answers only: "is this tag a first-class built-in element of one
32+
* of the three markup-language standards, rather than a component invocation
33+
* or a shadowed local binding?" Callers compose it with the other utils
34+
* above when they need a more specific question (see e.g. `template-no-
35+
* noninteractive-tabindex`, which consults both this and
36+
* `html-interactive-content`).
37+
*
2038
* Returns false for:
2139
* - components (PascalCase, dotted, @-prefixed, this.-prefixed, ::-namespaced —
2240
* none of these tag names appear in the HTML/SVG/MathML lists)

0 commit comments

Comments
 (0)