@eslint-react/jsx 5.8.18 → 5.9.0

package/dist/index.js

@@ -6,7 +6,7 @@ import { P, match } from "ts-pattern";
 
 //#region src/collapse-multiline-text.ts
 /**
-* Collapse a multiline JSX text string following React's whitespace rules.
+* Collapse a multiline JSX text string following React's whitespace rules
 *
 * This mirrors Babel's `cleanJSXElementLiteralChild` algorithm:
 * 1. Split the raw text into lines.
@@ -14,19 +14,17 @@ import { P, match } from "ts-pattern";
 * 3. Trim leading spaces on non-first lines and trailing spaces on non-last lines.
 * 4. Collapse tabs into spaces.
 * 5. Append a single space after each non-last non-empty line.
-*
-* @param text - The raw JSX text string to collapse.
-* @returns The collapsed string, or `null` if the text contains only whitespace.
-*
+* @param text The raw JSX text string to collapse
+* @returns The collapsed string, or `null` if the text contains only whitespace
 * @see https://github.com/babel/babel/blob/main/packages/babel-types/src/utils/react/cleanJSXElementLiteralChild.ts
 */
 function collapseMultilineText(text) {
 	const lines = text.split(/\r\n|\n|\r/);
 	let lastNonEmptyLine = 0;
-	for (let i = 0; i < lines.length; i++) if (/[^ \t]/.exec(lines[i]) != null) lastNonEmptyLine = i;
+	for (let i = 0; i < lines.length; i++) if (/[^ \t]/.exec(lines[i] ?? "") != null) lastNonEmptyLine = i;
 	let str = "";
 	for (let i = 0; i < lines.length; i++) {
-		const line = lines[i];
+		const line = lines[i] ?? "";
 		const isFirstLine = i === 0;
 		const isLastLine = i === lines.length - 1;
 		const isLastNonEmptyLine = i === lastNonEmptyLine;
@@ -38,32 +36,20 @@ function collapseMultilineText(text) {
 			str += trimmedLine;
 		}
 	}
-	return str || null;
+	return str === "" ? null : str;
 }
 
 //#endregion
 //#region src/get-attribute-name.ts
 /**
-* Get the stringified name of a `JSXAttribute` node.
+* Get the stringified name of a `JSXAttribute` node
 *
 * Handles both simple identifiers and namespaced names:
-*
-* - `className`   -> `"className"`
-* - `aria-label`  -> `"aria-label"`
-* - `xml:space`   -> `"xml:space"`
-*
-* @param node - A `JSXAttribute` AST node.
-* @returns The attribute name as a plain string.
-*
-* @example
-* ```ts
-* import { getAttributeName } from "@eslint-react/jsx";
-*
-* // Inside a rule visitor:
-* JSXAttribute(node) {
-*   const name = getAttributeName(node); // "className"
-* }
-* ```
+* - `className` -> `"className"`
+* - `aria-label` -> `"aria-label"`
+* - `xml:space` -> `"xml:space"`
+* @param node A `JSXAttribute` AST node
+* @returns The attribute name as a plain string
 */
 function getAttributeName(node) {
 	if (node.name.type === AST_NODE_TYPES.JSXIdentifier) return node.name.name;
@@ -73,37 +59,24 @@ function getAttributeName(node) {
 //#endregion
 //#region src/find-attribute.ts
 /**
-* Find a JSX attribute (or spread attribute containing the property) by name
-* on a given element.
-*
-* Returns the **last** matching attribute to mirror React's behaviour where
-* later props win, or `undefined` when the attribute is not present.
-*
-* Spread attributes are resolved when possible: if the spread argument is an
-* identifier that resolves to an object expression, the object's properties
-* are searched for a matching key.
+* Find a JSX attribute (or spread attribute containing the property) by name on a given element
 *
-* @param context - The ESLint rule context (needed for variable resolution in
-*                  spread attributes).
-* @param element - The `JSXElement` node to search.
-* @param name    - The attribute name to look for (e.g. `"className"`).
-* @returns The matching `JSXAttribute` or `JSXSpreadAttribute`, or
-*          `undefined` when not found.
+* Returns the last matching attribute to mirror React's behavior where later props win,
+* or `undefined` when the attribute is not present.
 *
-* @example
-* ```ts
-* const attr = findAttribute(context, node, "sandbox");
-* if (attr != null) {
-*   // attribute (or spread containing it) exists on the element
-* }
-* ```
+* Spread attributes are resolved when possible: if the spread argument is an identifier
+* that resolves to an object expression, the object's properties are searched for a matching key.
+* @param context The ESLint rule context (needed for variable resolution in spread attributes)
+* @param element The `JSXElement` node to search
+* @param name The attribute name to look for (ex: "className")
+* @returns The matching `JSXAttribute` or `JSXSpreadAttribute`, or `undefined` when not found
 */
 function findAttribute(context, element, name) {
-	function findProperty(of, named) {
-		for (const property of of) {
-			if (property.type === AST_NODE_TYPES.Property && Extract.getPropertyName(property.key) === named) return property;
+	function findProperty(properties, name) {
+		for (const property of properties) {
+			if (property.type === AST_NODE_TYPES.Property && Extract.getPropertyName(property.key) === name) return property;
 			if (property.type === AST_NODE_TYPES.SpreadElement && property.argument.type === AST_NODE_TYPES.ObjectExpression) {
-				const found = findProperty(property.argument.properties, named);
+				const found = findProperty(property.argument.properties, name);
 				if (found != null) return found;
 			}
 		}
@@ -126,27 +99,14 @@ function findAttribute(context, element, name) {
 //#endregion
 //#region src/find-parent-attribute.ts
 /**
-* Walk **up** the AST from `node` to find the nearest ancestor that is a
-* `JSXAttribute` and (optionally) passes a predicate.
-*
-* This is useful when a rule visitor enters a deeply‑nested node (e.g. a
-* `Literal` inside an expression container) and needs to know which JSX
-* attribute it belongs to.
-*
-* @param node - The starting node for the upward search.
-* @param test - Optional predicate to filter candidate `JSXAttribute` nodes.
-*               When omitted every `JSXAttribute` ancestor matches.
-* @returns The first matching `JSXAttribute` ancestor, or `null` if none is
-*          found before reaching the root.
-*
-* @example
-* ```ts
-* // Inside a Literal visitor, find the owning attribute:
-* const attr = findParentAttribute(literalNode);
-* if (attr != null) {
-*   console.log(getAttributeName(attr));
-* }
-* ```
+* Walk up the AST from `node` to find the nearest ancestor that is a `JSXAttribute`
+* and (optionally) passes a predicate
+*
+* This is useful when a rule visitor enters a deeply nested node (ex: a `Literal`
+* inside an expression container) and needs to know which JSX attribute it belongs to.
+* @param node The starting node for the upward search
+* @param test Optional predicate to filter candidate `JSXAttribute` nodes. When omitted every `JSXAttribute` ancestor matches
+* @returns The first matching `JSXAttribute` ancestor, or `null` if none is found before reaching the root
 */
 function findParentAttribute(node, test = () => true) {
 	const guard = (n) => {
@@ -159,28 +119,14 @@ function findParentAttribute(node, test = () => true) {
 //#region src/resolve-attribute-value.ts
 /**
 * Resolve the value of a JSX attribute (or spread attribute) into a
-* {@link JsxAttributeValue} descriptor that can be inspected further.
-*
-* This is the low‑level building block – it operates on a single attribute
-* node that the caller has already located.  For the higher‑level "find by
-* name **and** resolve" combo, see {@link getAttributeValue}.
-*
-* @param context   - The ESLint rule context (needed for scope look‑ups).
-* @param attribute - A `JSXAttribute` or `JSXSpreadAttribute` node.
-* @returns A discriminated‑union descriptor of the attribute's value.
-*
-* @example
-* ```ts
-* import { findAttribute, resolveAttributeValue } from "@eslint-react/jsx";
-*
-* const attr = findAttribute(context, element, "sandbox");
-* if (attr != null) {
-*   const value = resolveAttributeValue(context, attr);
-*   if (value.kind === "literal") {
-*     console.log(value.toStatic());
-*   }
-* }
-* ```
+* {@link JsxAttributeValue} descriptor that can be inspected further
+*
+* This is the low-level building block; it operates on a single attribute
+* node that the caller has already located. For the higher-level "find by
+* name and resolve" combo, see {@link getAttributeValue}.
+* @param context The ESLint rule context (needed for scope look-ups)
+* @param attribute A `JSXAttribute` or `JSXSpreadAttribute` node
+* @returns A discriminated-union descriptor of the attribute's value
 */
 function resolveAttributeValue(context, attribute) {
 	if (attribute.type === AST_NODE_TYPES.JSXAttribute) return resolveJsxAttribute(context, attribute);
@@ -259,32 +205,19 @@ function resolveJsxSpreadAttribute(context, node) {
 //#endregion
 //#region src/get-attribute-static-value.ts
 /**
-* Find an attribute by name on a JSX element and collapse its value to a
-* plain JavaScript value in a single step.
+* Find an attribute by name on a JSX element and collapse its value to a plain
+* JavaScript value in a single step
 *
 * This is a convenience composition of {@link findAttribute} ->
-* {@link resolveAttributeValue} -> `toStatic()`, with automatic handling
-* of the `spreadProps` case (extracts the named property from the spread
-* object).
-*
-* Returns `undefined` when the attribute is absent **or** when its value
-* cannot be statically determined.
-*
-* @param context - The ESLint rule context.
-* @param element - The `JSXElement` node to inspect.
-* @param name    - The attribute name to look up (e.g. `"className"`).
-* @returns The static value of the attribute, or `undefined`.
-*
-* @example
-* ```ts
-* // <iframe sandbox="allow-scripts" />
-* const sandbox = getAttributeStaticValue(context, node, "sandbox");
-* // -> "allow-scripts"
-*
-* // <button type={dynamicVar} />
-* const type = getAttributeStaticValue(context, node, "type");
-* // -> undefined  (cannot be resolved statically)
-* ```
+* {@link resolveAttributeValue} -> `toStatic()`, with automatic handling of the
+* `spreadProps` case (extracts the named property from the spread object).
+*
+* Returns `undefined` when the attribute is absent or when its value cannot be
+* statically determined.
+* @param context The ESLint rule context
+* @param element The `JSXElement` node to inspect
+* @param name The attribute name to look up (ex: "className")
+* @returns The static value of the attribute, or `undefined`
 */
 function getAttributeStaticValue(context, element, name) {
 	const attr = findAttribute(context, element, name);
@@ -297,99 +230,62 @@ function getAttributeStaticValue(context, element, name) {
 //#endregion
 //#region src/get-attribute-value.ts
 /**
-* Find an attribute by name on a JSX element **and** resolve its value in a
-* single call.
+* Find an attribute by name on a JSX element and resolve its value in a single call
 *
 * This is a convenience composition of {@link findAttribute} and
 * {@link resolveAttributeValue} that eliminates the most common two-step
-* pattern in lint rules:
-*
-* ```ts
-* const attr = findAttribute(context, element, name);
-* if (attr == null) return;
-* const value = resolveAttributeValue(context, attr);
-* ```
-*
-* @param context - The ESLint rule context.
-* @param element - The `JSXElement` node to search.
-* @param name    - The attribute name to look up (e.g. `"className"`).
-* @returns A {@link JsxAttributeValue} descriptor, or `undefined` when the
-*          attribute is not present on the element.
-*
-* @example
-* ```ts
-* const value = getAttributeValue(context, node, "sandbox");
-* if (value?.kind === "literal") {
-*   console.log(value.toStatic()); // the literal value
-* }
-* ```
+* pattern in lint rules.
+* @param context The ESLint rule context
+* @param element The `JSXElement` node to search
+* @param name The attribute name to look up (ex: "className")
+* @returns A {@link JsxAttributeValue} descriptor, or `null` when the attribute is not present on the element
 */
 function getAttributeValue(context, element, name) {
 	const attr = findAttribute(context, element, name);
-	if (attr == null) return void 0;
+	if (attr == null) return null;
 	return resolveAttributeValue(context, attr);
 }
 
 //#endregion
 //#region src/is-whitespace.ts
 /**
-* Check whether a JSX child node is **whitespace padding** that React would
-* trim away during rendering.
+* Check whether a JSX child node is whitespace padding that React would
+* trim away during rendering
 *
 * A child is considered whitespace padding when it is a `JSXText` node whose
 * content is empty after applying React's whitespace normalization
 * (see {@link collapseMultilineText}, modelled after Babel's
 * `cleanJSXElementLiteralChild`). This is the whitespace that appears between
-* JSX tags purely for formatting:
-*
-* ```jsx
-* <div>
-*   <span />     ← the text between </span> and the next tag is padding
-*   <span />
-* </div>
-* ```
-*
-* @param node - A JSX child node.
-* @returns `true` when the node is purely formatting whitespace.
+* JSX tags purely for formatting.
+* @param node A JSX child node
+* @returns `true` when the node is purely formatting whitespace
 */
 function isWhitespace(node) {
 	if (node.type !== AST_NODE_TYPES.JSXText) return false;
 	return collapseMultilineText(node.value) == null && node.value.includes("\n");
 }
 /**
-* Check whether a JSX child node is **any** whitespace‑only text.
+* Check whether a JSX child node is any whitespace-only text
 *
-* This is a looser variant of {@link isWhitespace} — it matches every
+* This is a looser variant of {@link isWhitespace}; it matches every
 * `JSXText` node whose raw content is empty after trimming, regardless of
 * whether it contains a newline.
-*
-* @param node - A JSX child node.
-* @returns `true` when the node is a whitespace‑only `JSXText`.
+* @param node A JSX child node
+* @returns `true` when the node is a whitespace-only `JSXText`
 */
 function isWhitespaceText(node) {
 	if (node.type !== AST_NODE_TYPES.JSXText) return false;
 	return node.raw.trim() === "";
 }
 /**
-* Check whether a JSX child node is an **empty string expression** (`{""}`).
+* Check whether a JSX child node is an empty string expression (`{""}`)
 *
 * React's reconciler and SSR renderer explicitly skip empty strings,
 * producing no DOM node (see `ReactChildFiber.js` and `ReactFizzConfigDOM.js`).
 * Such expressions are therefore treated as non-rendered children, in the same
 * way as whitespace padding.
-*
-* @param node - A JSX child node.
-* @returns `true` when the node is a `{""}` expression container.
-*
-* @example
-* ```ts
-* import { isEmptyStringExpression } from "@eslint-react/jsx";
-*
-* // <div>{""}</div> -> the expression container is an empty string expression
-* const meaningful = element.children.filter(
-*   (child) => !isEmptyStringExpression(child),
-* );
-* ```
+* @param node A JSX child node
+* @returns `true` when the node is a `{""}` expression container
 */
 function isEmptyStringExpression(node) {
 	if (node.type !== AST_NODE_TYPES.JSXExpressionContainer) return false;
@@ -401,7 +297,7 @@ function isEmptyStringExpression(node) {
 //#endregion
 //#region src/get-children.ts
 /**
-* Get the **meaningful** children of a JSX element or fragment.
+* Get the meaningful children of a JSX element or fragment
 *
 * Mirrors Babel's `buildChildren` helper:
 * 1. Iterate over `element.children`.
@@ -409,23 +305,8 @@ function isEmptyStringExpression(node) {
 * 3. Skip `JSXExpressionContainer` nodes whose expression is empty.
 * 4. Skip `JSXEmptyExpression` nodes.
 * 5. Collect everything else.
-*
-* @param element - A `JSXElement` or `JSXFragment` node.
-* @returns An array of children nodes that contribute to rendered output.
-*
-* @example
-* ```ts
-* import { getChildren } from "@eslint-react/jsx";
-*
-* // <div>
-* //   <span />
-* // </div>
-* //
-* // Raw children: [JSXText("\n  "), JSXElement(<span />), JSXText("\n")]
-* // getChildren:  [JSXElement(<span />)]
-*
-* const meaningful = getChildren(node);
-* ```
+* @param element A `JSXElement` or `JSXFragment` node
+* @returns An array of children nodes that contribute to rendered output
 */
 function getChildren(element) {
 	const elements = [];
@@ -450,34 +331,34 @@ function getChildren(element) {
 //#endregion
 //#region src/get-element-type.ts
 /**
-* Get the string representation of a JSX element's type.
-*
-* - `<div>`              -> `"div"`
-* - `<Foo.Bar>`          -> `"Foo.Bar"`
-* - `<React.Fragment>`   -> `"React.Fragment"`
-* - `<></>`              -> `""`
-*
-* @param node - A `JSXElement` or `JSXFragment` node.
-* @returns The fully-qualified element type string.
+* Get the string representation of a JSX element's type
+*
+* - `<div>` -> `"div"`
+* - `<Foo.Bar>` -> `"Foo.Bar"`
+* - `<React.Fragment>` -> `"React.Fragment"`
+* - `<></>` -> `""`
+* @param node A `JSXElement` or `JSXFragment` node
+* @returns The fully-qualified element type string
 */
 function getElementFullType(node) {
 	if (node.type === AST_NODE_TYPES.JSXFragment) return "";
 	function getQualifiedName(node) {
-		if (node.type === AST_NODE_TYPES.JSXIdentifier) return node.name;
-		if (node.type === AST_NODE_TYPES.JSXNamespacedName) return node.namespace.name + ":" + node.name.name;
-		return getQualifiedName(node.object) + "." + getQualifiedName(node.property);
+		switch (node.type) {
+			case AST_NODE_TYPES.JSXIdentifier: return node.name;
+			case AST_NODE_TYPES.JSXNamespacedName: return node.namespace.name + ":" + node.name.name;
+			default: return getQualifiedName(node.object) + "." + getQualifiedName(node.property);
+		}
 	}
 	return getQualifiedName(node.openingElement.name);
 }
 /**
-* Get the **self name** (last dot-separated segment) of a JSX element type.
+* Get the self name (last dot-separated segment) of a JSX element type
 *
-* - `<Foo.Bar.Baz>`  -> `"Baz"`
-* - `<div>`           -> `"div"`
-* - `<></>`           -> `""`
-*
-* @param node - A `JSXElement` or `JSXFragment` node.
-* @returns The last segment of the element type, or `""` for fragments.
+* - `<Foo.Bar.Baz>` -> `"Baz"`
+* - `<div>` -> `"div"`
+* - `<></>` -> `""`
+* @param node A `JSXElement` or `JSXFragment` node
+* @returns The last segment of the element type, or `""` for fragments
 */
 function getElementSelfType(node) {
 	return getElementFullType(node).split(".").at(-1) ?? "";
@@ -486,27 +367,16 @@ function getElementSelfType(node) {
 //#endregion
 //#region src/has-any-attribute.ts
 /**
-* Check whether a JSX element carries **at least one** of the given attributes.
+* Check whether a JSX element carries at least one of the given attributes
 *
 * This is a batch variant of {@link hasAttribute} for the common pattern of
-* short-circuiting on multiple prop names:
-*
-* ```ts
-* // before
-* if (hasAttribute(ctx, el, "key")) return;
-* if (hasAttribute(ctx, el, "ref")) return;
-*
-* // after
-* if (hasAnyAttribute(ctx, el, ["key", "ref"])) return;
-* ```
+* short-circuiting on multiple prop names.
 *
 * Spread attributes are taken into account (see {@link findAttribute}).
-*
-* @param context - The ESLint rule context (needed for variable resolution in
-*                  spread attributes).
-* @param element - The `JSXElement` node to inspect.
-* @param names   - The attribute names to look for.
-* @returns `true` when **at least one** of the attributes is present.
+* @param context The ESLint rule context (needed for variable resolution in spread attributes)
+* @param element The `JSXElement` node to inspect
+* @param names The attribute names to look for
+* @returns `true` when at least one of the attributes is present
 */
 function hasAnyAttribute(context, element, names) {
 	return names.some((name) => findAttribute(context, element, name) != null);
@@ -515,28 +385,17 @@ function hasAnyAttribute(context, element, names) {
 //#endregion
 //#region src/has-attribute.ts
 /**
-* Check whether a JSX element carries a given attribute (prop).
+* Check whether a JSX element carries a given attribute (prop)
 *
 * This is a thin convenience wrapper around {@link findAttribute} for the
 * common case where you only need a boolean answer.
 *
 * Spread attributes are taken into account: `<Comp {...{ disabled: true }} />`
 * will report `true` for `"disabled"`.
-*
-* @param context - The ESLint rule context (needed for variable resolution in
-*                  spread attributes).
-* @param element - The `JSXElement` node to inspect.
-* @param name    - The attribute name to look for (e.g. `"className"`).
-* @returns `true` when the attribute is present on the element.
-*
-* @example
-* ```ts
-* import { hasAttribute } from "@eslint-react/jsx";
-*
-* if (hasAttribute(context, node, "key")) {
-*   // element has a `key` prop
-* }
-* ```
+* @param context The ESLint rule context (needed for variable resolution in spread attributes)
+* @param element The `JSXElement` node to inspect
+* @param name The attribute name to look for (ex: "className")
+* @returns `true` when the attribute is present on the element
 */
 function hasAttribute(context, element, name) {
 	return findAttribute(context, element, name) != null;
@@ -545,12 +404,11 @@ function hasAttribute(context, element, name) {
 //#endregion
 //#region src/has-children.ts
 /**
-* Check whether a JSX element (or fragment) has **meaningful** children —
-* that is, at least one child that is not purely whitespace text or an empty
-* string expression.
+* Check whether a JSX element (or fragment) has meaningful children, that is,
+* at least one child that is not purely whitespace text or an empty string expression
 *
 * A `JSXText` child whose `raw` content is empty after trimming is considered
-* non-meaningful because it is typically a code-formatting artefact
+* non-meaningful because it is typically a code-formatting artifact
 * (indentation between tags). While React's client renderer preserves these
 * nodes as text nodes, they rarely represent intentionally rendered content.
 *
@@ -558,32 +416,14 @@ function hasAttribute(context, element, name) {
 * non-meaningful because React's reconciler and SSR renderer explicitly skip
 * empty strings, producing no DOM node.
 *
-* Unlike {@link getChildren} — which only filters whitespace that contains a
-* newline — this check treats **any** whitespace-only text as non-meaningful
-* (see {@link isWhitespaceText}). As a result `hasChildren(node)` is **not**
+* Unlike {@link getChildren} (which only filters whitespace that contains a
+* newline) this check treats any whitespace-only text as non-meaningful
+* (see {@link isWhitespaceText}). As a result `hasChildren(node)` is not
 * always equal to `getChildren(node).length > 0`: they differ for
 * whitespace-only children that have no newline, such as `<div> </div>` or
 * `<div>\t\t</div>`. Choose the API that matches your rule's intent.
-*
-* @param element - A `JSXElement` or `JSXFragment` node.
-* @returns `true` when the element has at least one meaningful child.
-*
-* @example
-* ```ts
-* import { hasChildren } from "@eslint-react/jsx";
-*
-* // <div>hello</div>           -> true
-* // <div>  {expr}  </div>      -> true
-* // <div>   </div>             -> false  (whitespace-only)
-* // <div>                      -> false  (whitespace-only, with newlines)
-* // </div>
-* // <div></div>                -> false  (no children at all)
-* // <div>{""}</div>            -> false  (empty string expression)
-*
-* if (hasChildren(node)) {
-*   // element renders visible content
-* }
-* ```
+* @param element A `JSXElement` or `JSXFragment` node
+* @returns `true` when the element has at least one meaningful child
 */
 function hasChildren(element) {
 	if (element.children.length === 0) return false;
@@ -593,28 +433,16 @@ function hasChildren(element) {
 //#endregion
 //#region src/has-every-attribute.ts
 /**
-* Check whether a JSX element carries **all** of the given attributes (props).
+* Check whether a JSX element carries all of the given attributes (props)
 *
 * This is a batch variant of {@link hasAttribute} for the common pattern
 * where a rule needs to verify that a set of required props are all present.
 *
 * Spread attributes are taken into account (see {@link findAttribute}).
-*
-* @param context  - The ESLint rule context (needed for variable resolution in
-*                   spread attributes).
-* @param element  - The `JSXElement` node to inspect.
-* @param names    - The attribute names to look for.
-* @returns `true` when **every** name in `names` is present on the element.
-*
-* @example
-* ```ts
-* import { hasEveryAttribute } from "@eslint-react/jsx";
-*
-* // Ensure both `alt` and `src` are provided on an <img>
-* if (hasEveryAttribute(context, node, ["alt", "src"])) {
-*   // element has both props
-* }
-* ```
+* @param context The ESLint rule context (needed for variable resolution in spread attributes)
+* @param element The `JSXElement` node to inspect
+* @param names The attribute names to look for
+* @returns `true` when every name in `names` is present on the element
 */
 function hasEveryAttribute(context, element, names) {
 	return names.every((name) => findAttribute(context, element, name) != null);
@@ -624,74 +452,44 @@ function hasEveryAttribute(context, element, names) {
 //#region src/is-element.ts
 /**
 * Check whether a node is a `JSXElement` (or `JSXFragment`) and optionally
-* matches a given test.
+* matches a given test
 *
 * Modelled after
 * [`hast-util-is-element`](https://github.com/syntax-tree/hast-util-is-element):
 * the `test` parameter controls what counts as a match.
 *
-* When called **without** a test, the function acts as a simple type-guard
+* When called without a test, the function acts as a simple type-guard
 * for `JSXElement | JSXFragment`.
-*
-* @param node - The AST node to test.
-* @param test - Optional test to match the element type against.
-* @returns `true` when the node is a matching JSX element.
-*
-* @example
-* ```ts
-* import { isElement } from "@eslint-react/jsx";
-*
-* // Type-guard only — any JSX element or fragment
-* if (isElement(node)) { … }
-*
-* // Match a single tag name
-* if (isElement(node, "iframe")) { … }
-*
-* // Match one of several tag names
-* if (isElement(node, ["button", "input", "select"])) { … }
-*
-* // Custom predicate
-* if (isElement(node, (type) => type.endsWith(".Provider"))) { … }
-* ```
+* @param node The AST node to test
+* @param test Optional test to match the element type against
+* @returns `true` when the node is a matching JSX element
 */
 function isElement(node, test) {
 	if (node == null) return false;
 	if (node.type !== AST_NODE_TYPES.JSXElement && node.type !== AST_NODE_TYPES.JSXFragment) return false;
 	if (test == null) return true;
 	const elementType = getElementFullType(node);
-	if (typeof test === "string") return elementType === test;
-	if (typeof test === "function") return test(elementType, node);
-	return test.includes(elementType);
+	switch (typeof test) {
+		case "string": return elementType === test;
+		case "function": return test(elementType, node);
+		default: return test.includes(elementType);
+	}
 }
 
 //#endregion
 //#region src/is-fragment-element.ts
 /**
-* Check whether a node is a React **Fragment** element.
+* Check whether a node is a React Fragment element
 *
-* Recognises both the shorthand `<>…</>` syntax (`JSXFragment`) and the
+* Recognizes both the shorthand `<>...</>` syntax (`JSXFragment`) and the
 * explicit `<Fragment>` / `<React.Fragment>` form (`JSXElement`).
 *
-* The comparison is performed against the **self name** (last dot‑separated
-* segment) of both the node and the configured factory, so
-* `<React.Fragment>` matches `"React.Fragment"` and `<Fragment>` matches
-* `"Fragment"`.
-*
-* @param node                - The AST node to test.
-* @param jsxFragmentFactory  - The configured fragment factory string
-*                              (e.g. `"React.Fragment"`).  Defaults to
-*                              `"React.Fragment"`.
-* @returns `true` when the node represents a React Fragment.
-*
-* @example
-* ```ts
-* // Using the default factory
-* if (isFragmentElement(node)) { … }
-*
-* // With a custom factory from jsxConfig
-* const config = getJsxConfig(context);
-* if (isFragmentElement(node, config.jsxFragmentFactory)) { … }
-* ```
+* The comparison is performed against the self name (last dot-separated
+* segment) of both the node and the configured factory, so `<React.Fragment>`
+* matches `"React.Fragment"` and `<Fragment>` matches `"Fragment"`.
+* @param node The AST node to test
+* @param jsxFragmentFactory The configured fragment factory string (ex: "React.Fragment")
+* @returns `true` when the node represents a React Fragment
 */
 function isFragmentElement(node, jsxFragmentFactory = "React.Fragment") {
 	if (node.type === AST_NODE_TYPES.JSXFragment) return true;
@@ -703,23 +501,13 @@ function isFragmentElement(node, jsxFragmentFactory = "React.Fragment") {
 //#endregion
 //#region src/is-host-element.ts
 /**
-* Check whether a node is a **host** (intrinsic / DOM) element.
+* Check whether a node is a host (intrinsic / DOM) element
 *
 * A host element is a `JSXElement` whose tag name is a plain `JSXIdentifier`
-* starting with a lowercase letter – the same heuristic React uses to
+* starting with a lowercase letter, the same heuristic React uses to
 * distinguish `<div>` from `<MyComponent>`.
-*
-* @param node - The AST node to test.
-* @returns `true` when the node is a `JSXElement` with a lowercase tag name.
-*
-* @example
-* ```ts
-* // <div className="box" />  -> true
-* // <span />                 -> true
-* // <MyComponent />          -> false
-* // <Foo.Bar />              -> false
-* isHostElement(node);
-* ```
+* @param node The AST node to test
+* @returns `true` when the node is a `JSXElement` with a lowercase tag name
 */
 function isHostElement(node) {
 	return node.type === AST_NODE_TYPES.JSXElement && node.openingElement.name.type === AST_NODE_TYPES.JSXIdentifier && /^[a-z]/u.test(node.openingElement.name.name);
@@ -727,6 +515,9 @@ function isHostElement(node) {
 
 //#endregion
 //#region src/jsx-detection-hint.ts
+/**
+* Hints for JSX detection
+*/
 const JsxDetectionHint = {
 	None: 0n,
 	DoNotIncludeJsxWithNullValue: 1n << 0n,
@@ -742,9 +533,9 @@ const JsxDetectionHint = {
 	RequireBothBranchesOfConditionalExpressionToBeJsx: 1n << 10n
 };
 /**
-* Default JSX detection configuration.
+* Default JSX detection hint
 *
-* Skips number, bigint, boolean, string, and undefined literals –
+* Skips number, bigint, boolean, string, and undefined literals,
 * the value types that are commonly returned alongside JSX in React
 * components but are not themselves renderable elements.
 */