refactor: reorganize JSX utilities and improve naming consistency

Rel1cx · Rel1cx · commit a77696f21f63 · 2025-04-07T11:55:37.000+08:00
diff --git a/.pkgs/configs/package.json b/.pkgs/configs/package.json
@@ -22,7 +22,7 @@
     "@eslint/js": "^9.24.0",
     "@stylistic/eslint-plugin": "^4.2.0",
     "eslint-plugin-de-morgan": "^1.2.1",
-    "eslint-plugin-function": "^0.0.12",
+    "eslint-plugin-function": "^0.0.13",
     "eslint-plugin-jsdoc": "^50.6.9",
     "eslint-plugin-perfectionist": "^4.11.0",
     "eslint-plugin-regexp": "^2.7.0",
diff --git a/package.json b/package.json
@@ -87,7 +87,7 @@
     "tsup": "^8.4.0",
     "tsx": "^4.19.3",
     "type-fest": "^4.39.1",
-    "typedoc": "^0.28.1",
+    "typedoc": "^0.28.2",
     "typedoc-plugin-markdown": "^4.6.1",
     "typedoc-plugin-mdn-links": "^5.0.1",
     "typescript": "^5.8.3",
diff --git a/packages/plugins/eslint-plugin-react-x/src/rules/no-useless-fragment.spec.ts b/packages/plugins/eslint-plugin-react-x/src/rules/no-useless-fragment.spec.ts
@@ -35,7 +35,7 @@ ruleTester.run(RULE_NAME, rule, {
         {
           type: T.JSXFragment,
           messageId: "uselessFragment",
-          data: { reason: "placed inside a built-in component" },
+          data: { reason: "placed inside a host component" },
         },
         {
           type: T.JSXFragment,
@@ -68,7 +68,7 @@ ruleTester.run(RULE_NAME, rule, {
         {
           type: T.JSXFragment,
           messageId: "uselessFragment",
-          data: { reason: "placed inside a built-in component" },
+          data: { reason: "placed inside a host component" },
         },
       ],
       output: "<p>{meow}</p>",
@@ -160,7 +160,7 @@ ruleTester.run(RULE_NAME, rule, {
         {
           type: T.JSXFragment,
           messageId: "uselessFragment",
-          data: { reason: "placed inside a built-in component" },
+          data: { reason: "placed inside a host component" },
         },
         {
           type: T.JSXFragment,
@@ -176,7 +176,7 @@ ruleTester.run(RULE_NAME, rule, {
         {
           type: T.JSXFragment,
           messageId: "uselessFragment",
-          data: { reason: "placed inside a built-in component" },
+          data: { reason: "placed inside a host component" },
         },
       ],
       output: '<div>{"a"}{"b"}</div>',
@@ -192,7 +192,7 @@ ruleTester.run(RULE_NAME, rule, {
         {
           type: T.JSXFragment,
           messageId: "uselessFragment",
-          data: { reason: "placed inside a built-in component" },
+          data: { reason: "placed inside a host component" },
         },
       ],
       output: `
@@ -208,7 +208,7 @@ ruleTester.run(RULE_NAME, rule, {
         {
           type: T.JSXElement,
           messageId: "uselessFragment",
-          data: { reason: "placed inside a built-in component" },
+          data: { reason: "placed inside a host component" },
         },
       ],
       output: '<div>{"a"}{"b"}</div>',
@@ -227,13 +227,13 @@ ruleTester.run(RULE_NAME, rule, {
         {
           type: T.JSXFragment,
           messageId: "uselessFragment",
-          data: { reason: "placed inside a built-in component" },
+          data: { reason: "placed inside a host component" },
           line: 3,
         },
         {
           type: T.JSXFragment,
           messageId: "uselessFragment",
-          data: { reason: "placed inside a built-in component" },
+          data: { reason: "placed inside a host component" },
           line: 7,
         },
       ],
@@ -250,7 +250,7 @@ ruleTester.run(RULE_NAME, rule, {
         {
           type: T.JSXFragment,
           messageId: "uselessFragment",
-          data: { reason: "placed inside a built-in component" },
+          data: { reason: "placed inside a host component" },
         },
       ],
       output: '<div>a {""}{""} a</div>',
@@ -267,7 +267,7 @@ ruleTester.run(RULE_NAME, rule, {
         {
           type: T.JSXElement,
           messageId: "uselessFragment",
-          data: { reason: "placed inside a built-in component" },
+          data: { reason: "placed inside a host component" },
           line: 4,
         },
         {
diff --git a/packages/plugins/eslint-plugin-react-x/src/rules/no-useless-fragment.ts b/packages/plugins/eslint-plugin-react-x/src/rules/no-useless-fragment.ts
@@ -57,7 +57,7 @@ export function create(context: RuleContext<MessageID, Options>, [option]: Optio
   const { allowExpressions = true } = option;
   return {
     JSXElement(node) {
-      if (!JSX.isJsxFragmentElement(node)) return;
+      if (!JSX.isFragmentElement(node)) return;
       checkNode(context, node, allowExpressions);
     },
     JSXFragment(node) {
@@ -103,16 +103,16 @@ function checkNode(
 ) {
   const initialScope = context.sourceCode.getScope(node);
   // return if the fragment is keyed (e.g. <Fragment key={key}>)
-  if (JSX.isJsxKeyedElement(node, initialScope)) {
+  if (JSX.isKeyedElement(node, initialScope)) {
     return;
   }
-  // report if the fragment is placed inside a built-in component (e.g. <div><></></div>)
-  if (JSX.isJsxBuiltInElement(node.parent)) {
+  // report if the fragment is placed inside a host component (e.g. <div><></></div>)
+  if (JSX.isHostElement(node.parent)) {
     context.report({
       messageId: "uselessFragment",
       node,
       data: {
-        reason: "placed inside a built-in component",
+        reason: "placed inside a host component",
       },
       fix: getFix(context, node),
     });
@@ -204,7 +204,7 @@ function getFix(context: RuleContext, node: TSESTree.JSXElement | TSESTree.JSXFr
 function canFix(node: TSESTree.JSXElement | TSESTree.JSXFragment) {
   if (node.parent.type === T.JSXElement || node.parent.type === T.JSXFragment) {
     // Not safe to fix `<Eeee><>foo</></Eeee>` because `Eeee` might require its children be a ReactElement.
-    return !JSX.isJsxUserDefinedElement(node.parent);
+    return JSX.isHostElement(node.parent);
   }
   // Not safe to fix fragments without a jsx parent.
   // const a = <></>
diff --git a/packages/plugins/eslint-plugin-react-x/src/rules/prefer-shorthand-fragment.ts b/packages/plugins/eslint-plugin-react-x/src/rules/prefer-shorthand-fragment.ts
@@ -35,7 +35,7 @@ export default createRule<[], MessageID>({
 export function create(context: RuleContext<MessageID, []>): RuleListener {
   return {
     JSXElement(node: TSESTree.JSXElement) {
-      if (!JSX.isJsxFragmentElement(node)) return;
+      if (!JSX.isFragmentElement(node)) return;
       const hasAttributes = node.openingElement.attributes.length > 0;
       if (hasAttributes) {
         return;
diff --git a/packages/shared/src/schemas.ts b/packages/shared/src/schemas.ts
@@ -10,7 +10,7 @@ export const CustomComponentPropSchema = object({
    */
   name: string(),
   /**
-   * The name of the prop in the built-in component.
+   * The name of the prop in the host component.
    * @example
    * "href"
    */
@@ -44,13 +44,13 @@ export const CustomComponentSchema = object({
    */
   name: string(),
   /**
-   * The name of the built-in component that the user-defined component represents.
+   * The name of the host component that the user-defined component represents.
    * @example
    * "a"
    */
   as: optional(string()),
   /**
-   * Attributes mapping between the user-defined component and the built-in component.
+   * Attributes mapping between the user-defined component and the host component.
    * @example
    * `Link` component has a `to` attribute that represents the `href` attribute in the built-in `a` element with a default value of `"/"`.
    */
diff --git a/packages/utilities/jsx/src/attribute/attribute-name.ts b/packages/utilities/jsx/src/attribute/attribute-name.ts
@@ -1,6 +1,6 @@
 import type { TSESTree } from "@typescript-eslint/utils";
 
-import { toString } from "./to-string";
+import { toString } from "../to-string";
 
 /**
  * Get the stringified name of a JSX attribute
diff --git a/packages/utilities/jsx/src/attribute/attribute-value.ts b/packages/utilities/jsx/src/attribute/attribute-value.ts
diff --git a/packages/utilities/jsx/src/attribute/attribute.ts b/packages/utilities/jsx/src/attribute/attribute.ts
@@ -4,7 +4,7 @@ import type { TSESTree } from "@typescript-eslint/utils";
 import * as VAR from "@eslint-react/var";
 import { AST_NODE_TYPES as T } from "@typescript-eslint/types";
 
-import { getAttributeName } from "./get-attribute-name";
+import { getAttributeName } from "./attribute-name";
 
 /**
  * Get the JSX attribute node with the given name
diff --git a/packages/utilities/jsx/src/attribute/hierarchy.ts b/packages/utilities/jsx/src/attribute/hierarchy.ts
diff --git a/packages/utilities/jsx/src/attribute/index.ts b/packages/utilities/jsx/src/attribute/index.ts
@@ -0,0 +1,4 @@
+export * from "./attribute";
+export * from "./attribute-name";
+export * from "./attribute-value";
+export * from "./hierarchy";
diff --git a/packages/utilities/jsx/src/element/element-type.ts b/packages/utilities/jsx/src/element/element-type.ts
@@ -1,12 +1,11 @@
 import type { TSESTree } from "@typescript-eslint/types";
 import { AST_NODE_TYPES as T } from "@typescript-eslint/types";
-
-import { toString } from "./to-string";
+import { toString } from "../to-string";
 
 /**
- * Get the stringified name of a JSX element
+ * Get the stringified type of a JSX element
  * @param node The JSX element node
- * @returns The name of the element
+ * @returns The type of the element
  */
 export function getElementType(node: TSESTree.JSXElement | TSESTree.JSXFragment) {
   if (node.type === T.JSXFragment) {
diff --git a/packages/utilities/jsx/src/element/index.ts b/packages/utilities/jsx/src/element/index.ts
@@ -0,0 +1,2 @@
+export * from "./element-type";
+export * from "./is";
diff --git a/packages/utilities/jsx/src/element/is.ts b/packages/utilities/jsx/src/element/is.ts
@@ -0,0 +1,34 @@
+import type { _ } from "@eslint-react/eff";
+import type { Scope } from "@typescript-eslint/scope-manager";
+import type { TSESTree } from "@typescript-eslint/types";
+import { AST_NODE_TYPES as T } from "@typescript-eslint/types";
+import { hasAttribute } from "../has-attribute";
+import { getElementType } from "./element-type";
+
+export function isHostElement(node: TSESTree.Node) {
+  return node.type === T.JSXElement
+    && node.openingElement.name.type === T.JSXIdentifier
+    && /^[a-z]/u.test(node.openingElement.name.name);
+}
+
+export function isKeyedElement(node: TSESTree.Node, initialScope?: Scope) {
+  return node.type === T.JSXElement
+    && hasAttribute("key", node.openingElement.attributes, initialScope);
+}
+
+function isFragmentElement(node: TSESTree.Node | null | _, allowJSXFragment?: false): node is TSESTree.JSXElement;
+function isFragmentElement(
+  node: TSESTree.Node | null | _,
+  allowJSXFragment?: true,
+): node is TSESTree.JSXElement | TSESTree.JSXFragment;
+function isFragmentElement(
+  node: TSESTree.Node | null | _,
+  allowJSXFragment = false,
+): node is TSESTree.JSXElement | TSESTree.JSXFragment {
+  if (node == null) return false;
+  if (node.type !== T.JSXElement && node.type !== T.JSXFragment) return false;
+  if (node.type === T.JSXFragment) return allowJSXFragment;
+  return getElementType(node).split(".").at(-1) === "Fragment";
+}
+
+export { isFragmentElement };
diff --git a/packages/utilities/jsx/src/has-attribute.ts b/packages/utilities/jsx/src/has-attribute.ts
@@ -1,7 +1,6 @@
 import type { Scope } from "@typescript-eslint/scope-manager";
 import type { TSESTree } from "@typescript-eslint/types";
-
-import { getAttribute } from "./get-attribute";
+import { getAttribute } from "./attribute";
 
 export function hasAttribute(
   name: string,
diff --git a/packages/utilities/jsx/src/index.ts b/packages/utilities/jsx/src/index.ts
@@ -1,12 +1,6 @@
-export * from "./find-parent-attribute";
-export * from "./get-attribute";
-export * from "./get-attribute-name";
-export * from "./get-attribute-value";
-export * from "./get-element-type";
+export * from "./attribute";
+export * from "./element";
 export * from "./has-attribute";
-export * from "./is-jsx";
-export * from "./is-jsx-element";
-export * from "./is-jsx-fragment";
-export * from "./is-jsx-text";
+export * from "./jsx-detection";
 export * from "./jsx-detection-hint";
 export * from "./to-string";
diff --git a/packages/utilities/jsx/src/is-jsx-element.ts b/packages/utilities/jsx/src/is-jsx-element.ts
diff --git a/packages/utilities/jsx/src/is-jsx-fragment.ts b/packages/utilities/jsx/src/is-jsx-fragment.ts
diff --git a/packages/utilities/jsx/src/is-jsx-text.ts b/packages/utilities/jsx/src/is-jsx-text.ts
diff --git a/packages/utilities/jsx/src/jsx-detection.ts b/packages/utilities/jsx/src/jsx-detection.ts
@@ -7,6 +7,16 @@ import * as VAR from "@eslint-react/var";
 import { AST_NODE_TYPES as T } from "@typescript-eslint/types";
 import { DEFAULT_JSX_DETECTION_HINT, JSXDetectionHint } from "./jsx-detection-hint";
 
+/**
+ * Check if a node is a `JSXText` or a `Literal` node
+ * @param node The AST node to check
+ * @returns `true` if the node is a `JSXText` or a `Literal` node
+ */
+export function isJsxText(node: TSESTree.Node | null | _): node is TSESTree.JSXText | TSESTree.Literal {
+  if (node == null) return false;
+  return node.type === T.JSXText || node.type === T.Literal;
+}
+
 /**
  * Heuristic decision to determine if a node is a JSX-like node.
  * @param code The sourceCode object
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
