@astryxdesign/cli 0.4.4 → 0.4.5-canary.013e728

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @xds/cli
 
+# 0.4.5
+
+---
+
 # 0.4.4
 
 #### New Components
@@ -16,6 +20,7 @@
   Three more lessons came out of building a real app on it. The page now `<link>`s the theme's webfont from Google Fonts, because the theme _names_ Figtree and never loads it, so every viewer silently got the fallback stack (#5015 again). It imports the theme OBJECT and wraps in `<Theme theme={neutralTheme} mode="system">`, so light and dark follow the OS — the `data-astryx-theme` attribute alone scopes the stylesheet but cannot switch modes. And `#root:empty` carries a "Loading…" state, because ESM-from-CDN has real latency and a blank page reads as broken. Markup is `htm`, with a comment saying it is optional and `createElement` is the dependency-free alternative.
 
   A recipe that is only read is a recipe that is only assumed to work, so CI renders it: `.github/scripts/cdn-template-smoke-test.mjs` scaffolds the page with the real CLI and opens it in headless Chromium, failing on any console error, page error or failed request, and on a page that loads without rendering.
+
 - `astryx theme build` takes any number of theme files — `astryx theme build themes/*.ts` compiles them all in one process, so an app with several themes no longer hand-rolls a loop that re-enters the CLI once per theme. Outputs are byte-identical to the serial invocations; the run stops at the first failure and names the theme that failed. The CLI's Node floor (>=22.13) is now declared in `engines`, so a package manager can enforce it at install instead of the build failing later (#5121).
 - `defineTheme`: `color.accent` accepts a `[light, dark]` tuple (#2279)
   `ColorScaleConfig.accent` now takes either a single hex or a `[light, dark]` tuple, matching `TokenValue`. With a tuple, `expandColorScale` derives the light half of every generated `light-dark()` pair from the light seed's palettes and the dark half from the dark seed's, so each scheme gets a consistent derived palette (muted, on-accent, neutrals) instead of the `tokens['--color-accent']` workaround that skips scale generation. Single-string configs are unchanged, token for token. Also documents the precedence between `color` and `tokens` for accent-derived values: `tokens` entries win token by token, the `var(--color-accent)` reference tokens follow a `--color-accent` override at runtime, and the baked `--color-on-accent` stays derived from the `color.accent` seed.

package/api/component/_adapter.d.mts

@@ -12,6 +12,7 @@
  * @property {any[]} [components]
  * @property {{description?: string}} [usage]
  * @property {any} [theming]
+ * @property {string} [import] set when the doc states its own import specifier
  */
 /**
  * Options object for `loadDocs`, matching its declared parameter shape (used
@@ -29,6 +30,12 @@
  * @property {string|undefined} issuesUrl
  * @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration|null} integration
  */
+/**
+ * What ownership shaping needs from an owner. The core and legacy-external
+ * paths synthesize a bare `{package, sourcePath}` rather than resolving a full
+ * {@link ComponentOwner}, so everything past those two is optional here.
+ * @typedef {Partial<ComponentOwner> & {package: string, sourcePath: string|null}} OwnershipSubject
+ */
 /**
  * A back-compat external package discovered via `pkg.astryx.docs`.
  * @typedef {{name: string, category: string, docsDir: string}} ExternalPackageRef
@@ -152,15 +159,12 @@ export function extractProps(docs: LoadedComponentDoc): any[];
  * swizzleable source file exists for the owner). Existing doc fields (name,
  * usage, props, …) are preserved.
  * @param {LoadedComponentDoc} docs
- * @param {{package: string, sourcePath: string|null}} owner
+ * @param {OwnershipSubject} owner
  * @param {string} componentName
  * @param {string} coreDir
  * @returns {import('./component.type.mjs').ComponentDetailResponse['data']}
  */
-export function withOwnership(docs: LoadedComponentDoc, owner: {
-    package: string;
-    sourcePath: string | null;
-}, componentName: string, coreDir: string): import("./component.type.mjs").ComponentDetailResponse["data"];
+export function withOwnership(docs: LoadedComponentDoc, owner: OwnershipSubject, componentName: string, coreDir: string): import("./component.type.mjs").ComponentDetailResponse["data"];
 /**
  * When the caller asked for "Code" but the resolved doc is for "CodeBlock"
  * (parent), scope the response to just the matching sub-component. Returns the
@@ -193,6 +197,10 @@ export type LoadedComponentDoc = {
         description?: string;
     } | undefined;
     theming?: any;
+    /**
+     * set when the doc states its own import specifier
+     */
+    import?: string | undefined;
 };
 /**
  * Options object for `loadDocs`, matching its declared parameter shape (used
@@ -215,6 +223,15 @@ export type ComponentOwner = {
     issuesUrl: string | undefined;
     integration: import("../../foundation/integrations/integrations.mjs").LoadedIntegration | null;
 };
+/**
+ * What ownership shaping needs from an owner. The core and legacy-external
+ * paths synthesize a bare `{package, sourcePath}` rather than resolving a full
+ * {@link ComponentOwner}, so everything past those two is optional here.
+ */
+export type OwnershipSubject = Partial<ComponentOwner> & {
+    package: string;
+    sourcePath: string | null;
+};
 /**
  * A back-compat external package discovered via `pkg.astryx.docs`.
  */

package/api/component/_adapter.mjs

@@ -18,6 +18,8 @@
  * deduped, so each leaf stays a thin projection.
  */
 
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {findCoreDir, discoverExternalPackages} from '../../foundation/fs/paths.mjs';
 import {
@@ -48,6 +50,7 @@ export {CORE_PACKAGE};
  * @property {any[]} [components]
  * @property {{description?: string}} [usage]
  * @property {any} [theming]
+ * @property {string} [import] set when the doc states its own import specifier
  */
 
 /**
@@ -68,6 +71,13 @@ export {CORE_PACKAGE};
  * @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration|null} integration
  */
 
+/**
+ * What ownership shaping needs from an owner. The core and legacy-external
+ * paths synthesize a bare `{package, sourcePath}` rather than resolving a full
+ * {@link ComponentOwner}, so everything past those two is optional here.
+ * @typedef {Partial<ComponentOwner> & {package: string, sourcePath: string|null}} OwnershipSubject
+ */
+
 /**
  * A back-compat external package discovered via `pkg.astryx.docs`.
  * @typedef {{name: string, category: string, docsDir: string}} ExternalPackageRef
@@ -357,7 +367,7 @@ export function extractProps(docs) {
  * swizzleable source file exists for the owner). Existing doc fields (name,
  * usage, props, …) are preserved.
  * @param {LoadedComponentDoc} docs
- * @param {{package: string, sourcePath: string|null}} owner
+ * @param {OwnershipSubject} owner
  * @param {string} componentName
  * @param {string} coreDir
  * @returns {import('./component.type.mjs').ComponentDetailResponse['data']}
@@ -366,15 +376,53 @@ export function withOwnership(docs, owner, componentName, coreDir) {
   const importSpec =
     owner.package === CORE_PACKAGE
       ? resolveImportPath(coreDir, componentName)
-      : `${owner.package}/${componentName}`;
+      : resolveIntegrationImportPath(owner, componentName);
   return /** @type {any} */ ({
     ...docs,
     package: owner.package,
-    import: importSpec,
+    // A doc file may state its own specifier, e.g. when one entry point exports
+    // several components. Only fall back to a resolved one when it does not.
+    import: docs.import ?? importSpec,
     sourceAvailable: owner.sourcePath != null,
   });
 }
 
+/**
+ * Resolve the specifier an integration component is imported from, against the
+ * owning package's `exports` map.
+ *
+ * A component lives in a directory that need not share its name — several
+ * components can be exported from one entry point — so the specifier has to
+ * come from the directory the doc file sits in, checked against `exports`,
+ * rather than from the component name. Falls back to the package root when the
+ * directory is not an exported subpath, matching what a consumer would have to
+ * write by hand.
+ *
+ * @param {OwnershipSubject} owner
+ * @param {string} componentName
+ * @returns {string}
+ */
+function resolveIntegrationImportPath(owner, componentName) {
+  const packageDir = owner.integration?.__packageDir;
+  const directory = owner.docPath
+    ? path.basename(path.dirname(owner.docPath))
+    : componentName;
+  if (!packageDir) {
+    return owner.package;
+  }
+  try {
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(packageDir, 'package.json'), 'utf-8'),
+    );
+    if (manifest.exports?.[`./${directory}`]) {
+      return `${owner.package}/${directory}`;
+    }
+  } catch {
+    // An unreadable or malformed manifest is not worth failing a lookup over.
+  }
+  return owner.package;
+}
+
 /**
  * When the caller asked for "Code" but the resolved doc is for "CodeBlock"
  * (parent), scope the response to just the matching sub-component. Returns the

package/assets/codemods/transforms/v0.1.0/__tests__/drop-xds-prefix-imports.test.mjs

@@ -212,4 +212,249 @@ describe('drop-xds-prefix-imports', () => {
     const output = await applyTransform(input);
     expect(output).toBe(input);
   });
+
+  it('aliases a component wrapper collision in place (XDS -> Astryx), leaving the local fn untouched', async () => {
+    const input = [
+      `import {XDSLinkProvider} from '@xds/core/Link';`,
+      `export default function LinkProvider({children}) {`,
+      `  return <XDSLinkProvider component={NextLink}>{children}</XDSLinkProvider>;`,
+      `}`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    // Import aliased in place, local wrapper + its name untouched.
+    expect(output).toContain('import {LinkProvider as AstryxLinkProvider}');
+    expect(output).toContain('function LinkProvider({children})');
+    // JSX rewritten to the alias -> no self-recursion.
+    expect(output).toContain('<AstryxLinkProvider component={NextLink}>');
+    expect(output).not.toContain('XDSLinkProvider');
+    // No duplicate bare LinkProvider import.
+    expect(output).not.toMatch(/import \{LinkProvider\}/);
+  });
+
+  it('aliases a hook collision as use<Astryx>Name (not <Astryx>use)', async () => {
+    const input = [
+      `import {useXDSToast} from '@xds/core';`,
+      `function useToast() {`,
+      `  return useXDSToast();`,
+      `}`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    expect(output).toContain('import {useToast as useAstryxToast}');
+    expect(output).toContain('function useToast()');
+    expect(output).toContain('return useAstryxToast();');
+    expect(output).not.toContain('useXDSToast');
+    // Must not produce the malformed `Astryxuse...` form.
+    expect(output).not.toContain('AstryxuseToast');
+  });
+
+  it('aliases on collision with a local default import binding', async () => {
+    const input = [
+      `import Link from 'next/link';`,
+      `import {XDSLink} from '@xds/core';`,
+      `export const a = <XDSLink href="/" />;`,
+      `export const b = <Link href="/" />;`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    expect(output).toContain('import {Link as AstryxLink}');
+    expect(output).toContain(`import Link from 'next/link';`);
+    expect(output).toContain('<AstryxLink href="/" />');
+    expect(output).toContain('<Link href="/" />');
+    expect(output).not.toContain('XDSLink');
+  });
+
+  it('aliases on collision with a local type alias', async () => {
+    const input = [
+      `import type {XDSTab} from '@xds/core';`,
+      `type Tab = {id: string};`,
+      `const active: XDSTab = null as any;`,
+      `const local: Tab = {id: '1'};`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    expect(output).toContain('Tab as AstryxTab');
+    expect(output).toContain('type Tab = {id: string};');
+    expect(output).toContain('const active: AstryxTab');
+    expect(output).toContain('const local: Tab');
+    expect(output).not.toContain('XDSTab');
+  });
+
+  it('aliases on collision with a local interface', async () => {
+    const input = [
+      `import type {XDSTheme} from '@xds/core';`,
+      `interface Theme {}`,
+      `const t: XDSTheme = null as any;`,
+      `const local: Theme = {};`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    expect(output).toContain('Theme as AstryxTheme');
+    expect(output).toContain('interface Theme {}');
+    expect(output).toContain('const t: AstryxTheme');
+    expect(output).not.toContain('XDSTheme');
+  });
+
+  it('still bare-renames when there is NO colliding local binding', async () => {
+    const input = [
+      `import {XDSButton} from '@xds/core';`,
+      `export const App = () => <XDSButton label="Hi" />;`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    // No local `Button` binding -> existing blind bare-rename behavior kept.
+    expect(output).toContain(`import {Button} from '@xds/core';`);
+    expect(output).toContain('<Button label="Hi" />');
+    expect(output).not.toContain('AstryxButton');
+    expect(output).not.toContain('XDSButton');
+  });
+
+  describe('JSX whitespace preservation on element-name rename', () => {
+    it('preserves the space between text and a following {expression} inside return (...)', async () => {
+      const input = [
+        `import {XDSText} from '@xds/core';`,
+        `export function App({name}) {`,
+        `  return (`,
+        `    <XDSText>hello {name} world</XDSText>`,
+        `  );`,
+        `}`,
+      ].join('\n');
+      const output = await applyTransform(input);
+      // Element is renamed...
+      expect(output).toContain('<Text>');
+      expect(output).toContain('</Text>');
+      expect(output).not.toContain('XDSText');
+      // ...and the whitespace around the {expression} survives (the bug
+      // collapsed `{name} world` to `{name}world`).
+      expect(output).toContain('hello {name} world');
+      expect(output).not.toContain('{name}world');
+    });
+
+    it('preserves whitespace with multiple {expressions} adjacent to text', async () => {
+      const input = [
+        `import {XDSText} from '@xds/core';`,
+        `export function App({a, b}) {`,
+        `  return (`,
+        `    <XDSText>involving {a} in the {b} dataset</XDSText>`,
+        `  );`,
+        `}`,
+      ].join('\n');
+      const output = await applyTransform(input);
+      expect(output).toContain('involving {a} in the {b} dataset');
+      expect(output).toContain('<Text>');
+      expect(output).not.toContain('XDSText');
+    });
+
+    it('preserves whitespace across a multi-line JSX body', async () => {
+      const input = [
+        `import {XDSText} from '@xds/core';`,
+        `export function App({a, b}) {`,
+        `  return (`,
+        `    <XDSText>`,
+        `      involving {a} in the {b} dataset`,
+        `    </XDSText>`,
+        `  );`,
+        `}`,
+      ].join('\n');
+      const output = await applyTransform(input);
+      expect(output).toContain('involving {a} in the {b} dataset');
+      expect(output).toContain('<Text>');
+      expect(output).toContain('</Text>');
+      expect(output).not.toContain('XDSText');
+    });
+
+    it('renames both the opening and closing tag of the same element', async () => {
+      const input = [
+        `import {XDSCard} from '@xds/core';`,
+        `export const App = ({n}) => (<XDSCard>value {n} here</XDSCard>);`,
+      ].join('\n');
+      const output = await applyTransform(input);
+      expect(output).toContain('<Card>');
+      expect(output).toContain('</Card>');
+      expect(output).toContain('value {n} here');
+      expect(output).not.toContain('XDSCard');
+    });
+
+    it('preserves whitespace for multiple different elements in one return', async () => {
+      const input = [
+        `import {XDSCard, XDSText, XDSButton} from '@xds/core';`,
+        `export const App = ({n}) => (`,
+        `  <XDSCard>`,
+        `    <XDSText>hello {n} world</XDSText>`,
+        `    <XDSButton>click {n} here</XDSButton>`,
+        `  </XDSCard>`,
+        `);`,
+      ].join('\n');
+      const output = await applyTransform(input);
+      expect(output).toContain('import {Card, Text, Button}');
+      expect(output).toContain('<Card>');
+      expect(output).toContain('hello {n} world');
+      expect(output).toContain('click {n} here');
+      expect(output).not.toContain('XDS');
+    });
+
+    it('renames only the mapped segment of a member-expression tag name, preserving whitespace', async () => {
+      const input = [
+        `import {XDSMenu} from '@xds/core';`,
+        `export const App = ({x}) => (<XDSMenu.Item>pick {x} now</XDSMenu.Item>);`,
+      ].join('\n');
+      const output = await applyTransform(input);
+      // Only the mapped `XDSMenu` segment is renamed; `.Item` is preserved.
+      expect(output).toContain('<Menu.Item>');
+      expect(output).toContain('</Menu.Item>');
+      expect(output).toContain('pick {x} now');
+      expect(output).not.toContain('XDSMenu');
+    });
+
+    it('renames a self-closing element with attributes without altering the attributes', async () => {
+      const input = [
+        `import {XDSButton} from '@xds/core';`,
+        `export const App = () => <XDSButton label="x" onClick={fn} />;`,
+      ].join('\n');
+      const output = await applyTransform(input);
+      expect(output).toContain('<Button label="x" onClick={fn} />');
+      expect(output).not.toContain('XDSButton');
+    });
+
+    it('handles a JSX body with no whitespace to preserve', async () => {
+      const input = [
+        `import {XDSButton} from '@xds/core';`,
+        `export const App = ({label}) => <XDSButton>{label}</XDSButton>;`,
+      ].join('\n');
+      const output = await applyTransform(input);
+      expect(output).toContain('<Button>{label}</Button>');
+      expect(output).not.toContain('XDSButton');
+    });
+
+    it('preserves whitespace when the bare name is aliased on a collision', async () => {
+      const input = [
+        `import {XDSCodeBlock} from '@xds/core/CodeBlock';`,
+        `export function CodeBlock({code}) {`,
+        `  return (<XDSCodeBlock>run {code} now</XDSCodeBlock>);`,
+        `}`,
+      ].join('\n');
+      const output = await applyTransform(input);
+      expect(output).toContain('CodeBlock as AstryxCodeBlock');
+      expect(output).toContain('<AstryxCodeBlock>');
+      expect(output).toContain('</AstryxCodeBlock>');
+      expect(output).toContain('run {code} now');
+    });
+
+    it('keeps a custom local alias on the element tag and preserves whitespace', async () => {
+      const input = [
+        `import {XDSText as Txt} from '@xds/core';`,
+        `export const App = ({n}) => (<Txt>hello {n} world</Txt>);`,
+      ].join('\n');
+      const output = await applyTransform(input);
+      expect(output).toContain('Text as Txt');
+      expect(output).toContain('<Txt>hello {n} world</Txt>');
+      expect(output).not.toContain('XDSText');
+    });
+
+    it('is idempotent: a second pass over already-migrated output is a no-op', async () => {
+      const input = [
+        `import {XDSText} from '@xds/core';`,
+        `export const App = ({n}) => (<XDSText>a {n} b</XDSText>);`,
+      ].join('\n');
+      const once = await applyTransform(input);
+      const twice = await applyTransform(once);
+      expect(twice).toBe(once);
+      expect(once).toContain('a {n} b');
+    });
+  });
 });

package/assets/codemods/transforms/v0.1.0/drop-xds-prefix-imports.mjs

@@ -64,6 +64,22 @@ export const meta = {
 
 const XDS_CORE_SOURCE = /^@xds\/core(\/.*)?$/;
 
+/**
+ * Compute a collision alias for an XDS-prefixed identifier by replacing the
+ * `XDS` segment IN PLACE with `Astryx` (as opposed to prefixing the bare name).
+ * This keeps hook names well-formed:
+ *
+ *   XDSButton       -> AstryxButton
+ *   XDSLinkProvider -> AstryxLinkProvider
+ *   useXDSToast     -> useAstryxToast   (NOT AstryxuseToast)
+ *
+ * Only the first `XDS` occurrence is replaced, matching how `bareName` strips a
+ * single leading prefix.
+ */
+function aliasName(/** @type {any} */ name) {
+  return name.replace('XDS', 'Astryx');
+}
+
 /**
  * Compute the bare (unprefixed) name for an XDS-prefixed identifier.
  * Returns null if the name is not XDS-prefixed in a renameable way.
@@ -190,7 +206,12 @@ export default function transformer(file, api) {
     if (!node) return;
     if (
       (node.type === 'FunctionDeclaration' ||
-        node.type === 'ClassDeclaration') &&
+        node.type === 'ClassDeclaration' ||
+        // Type-only bindings share the module namespace for our purposes: a
+        // `type Tab`/`interface Theme` collides with an un-prefixed `XDSTab`/
+        // `XDSTheme` type import and would create a duplicate declaration.
+        node.type === 'TSTypeAliasDeclaration' ||
+        node.type === 'TSInterfaceDeclaration') &&
       node.id
     ) {
       existingBindings.add(node.id.name);
@@ -239,10 +260,13 @@ export default function transformer(file, api) {
       if (bare !== importedName && existingBindings.has(bare)) {
         // COLLISION: the bare name is already a top-level binding in this file
         // (e.g. a local `export function CodeBlock` alongside imported
-        // `XDSCodeBlock`). Un-prefixing directly would create a duplicate
-        // declaration, so alias the import to `Astryx<Name>` and rename the
+        // `XDSCodeBlock`, or a `type Tab` alongside `XDSTab`). Un-prefixing
+        // directly would create a duplicate declaration (TS2451), so alias the
+        // import by replacing `XDS` with `Astryx` in place and rename the
         // import's references to that alias, leaving the local binding intact.
-        const alias = `Astryx${bare}`;
+        // In-place replacement keeps hooks well-formed: `useXDSToast` becomes
+        // `useAstryxToast`, not `AstryxuseToast`.
+        const alias = aliasName(importedName);
         localRenames.set(importedName, alias);
         existingBindings.add(alias);
         hasChanges = true;
@@ -322,18 +346,27 @@ export default function transformer(file, api) {
     }
     // Don't double-rewrite the import specifier we already handled.
     if (parent.type === 'ImportSpecifier') return;
+    // JSX element tag names are handled by a source-string splice after
+    // `toSource()` (see renameJsxElementNamesInSource). Mutating them here
+    // would dirty the enclosing JSXElement and make recast collapse whitespace
+    // around adjacent `{expressions}`. Under the tsx parser a JSX tag-name
+    // JSXIdentifier is a subtype of Identifier, so it surfaces in this
+    // `find(j.Identifier)` pass and must be explicitly skipped.
+    if (isJsxElementNameIdentifier(path)) return;
     path.node.name = newName;
     hasChanges = true;
   });
 
-  // JSX element names: <XDSButton> -> <Button>
-  root.find(j.JSXIdentifier).forEach((/** @type {any} */ path) => {
-    const newName = localRenames.get(path.node.name);
-    if (newName) {
-      path.node.name = newName;
-      hasChanges = true;
-    }
-  });
+  // JSX element names (`<XDSButton>` -> `<Button>`) are intentionally NOT
+  // renamed via AST mutation here. Mutating a JSXIdentifier in place dirties the
+  // enclosing JSXElement; when that element is the argument of a parenthesized
+  // `return ( <JSX/> )` (i.e. every React component body), recast declines a
+  // surgical child reprint and generically re-prints the whole return argument.
+  // Its generic JSXElement printer drops significant whitespace from JSXText
+  // that sits next to a `{expression}` -- so `hello {name} world` collapses to
+  // `hello {name}world`. Instead we splice the element-name renames directly
+  // into the emitted source string (below), which never re-prints the subtree.
+  // See renameJsxElementNamesInSource for the mechanism.
 
   // 5. Rename TS type references in generic type-argument positions.
   //
@@ -389,5 +422,98 @@ export default function transformer(file, api) {
   };
   renameTypeReferences(root.get().node);
 
-  return hasChanges ? root.toSource() : undefined;
+  if (!hasChanges) return undefined;
+
+  // Emit the AST-based renames, then splice the JSX element-name renames onto
+  // the emitted string (see the note in the JSX section above for why element
+  // names cannot be renamed through the AST without collapsing whitespace).
+  const emitted = root.toSource();
+  return renameJsxElementNamesInSource(j, emitted, localRenames);
+}
+
+/**
+ * Rename JSX element tag names (`<XDSButton>` / `</XDSButton>`) by splicing the
+ * new names directly into the already-emitted source, so recast never re-prints
+ * the surrounding JSX subtree (which would strip whitespace next to
+ * `{expressions}`).
+ *
+ * Spans are computed by re-parsing `source` itself, so the offsets are always
+ * valid against the string we splice into -- no dependency on the original
+ * pre-transform offsets. Splices are applied right-to-left (descending start
+ * offset) so earlier offsets stay valid as we go.
+ *
+ * Only the identifier that IS the element's tag name is renamed:
+ * - `<Foo attr />`            -> the `Foo` opening-name only (not `attr`)
+ * - `<Ns.Foo />` / `<Foo.Bar>`-> the specific member-expression identifier that
+ *   maps in `renames`; the other part of the member name is preserved
+ *
+ * @param {any} j jscodeshift instance (already bound to the tsx parser)
+ * @param {string} source emitted source to rewrite
+ * @param {Map<string, string>} renames localName -> newLocalName
+ * @returns {string}
+ */
+function renameJsxElementNamesInSource(j, source, renames) {
+  if (renames.size === 0) return source;
+
+  const root = j(source);
+
+  /** @type {Array<{start: number, end: number, name: string}>} */
+  const edits = [];
+
+  root.find(j.JSXIdentifier).forEach((/** @type {any} */ path) => {
+    const node = path.node;
+    const newName = renames.get(node.name);
+    if (!newName || newName === node.name) return;
+
+    // The identifier must BE an element tag name -- the `.name` of a
+    // JSXOpeningElement/JSXClosingElement, or the matching part of a
+    // JSXMemberExpression tag name. Attribute names, attribute values, and the
+    // non-matching half of a member-expression name must be left alone.
+    if (!isJsxElementNameIdentifier(path)) return;
+
+    if (typeof node.start !== 'number' || typeof node.end !== 'number') return;
+    edits.push({start: node.start, end: node.end, name: newName});
+  });
+
+  if (edits.length === 0) return source;
+
+  edits.sort((a, b) => b.start - a.start);
+
+  let out = source;
+  for (const {start, end, name} of edits) {
+    out = out.slice(0, start) + name + out.slice(end);
+  }
+  return out;
+}
+
+/**
+ * Is this JSXIdentifier path the tag name of its element (opening or closing),
+ * as opposed to an attribute name or a namespace/member-expression segment we
+ * should not rename? For member-expression tag names (`<Foo.Bar>`) we accept
+ * the identifier regardless of which segment it is -- the caller only reaches
+ * here for identifiers whose name is in the rename map, and each renamed
+ * identifier maps independently, so `<Foo.Bar>` renames only the segment(s)
+ * that actually map.
+ *
+ * @param {any} path jscodeshift path to a JSXIdentifier
+ * @returns {boolean}
+ */
+function isJsxElementNameIdentifier(path) {
+  const parent = path.parent && path.parent.node;
+  if (!parent) return false;
+
+  if (
+    parent.type === 'JSXOpeningElement' ||
+    parent.type === 'JSXClosingElement'
+  ) {
+    return parent.name === path.node;
+  }
+
+  // `<Foo.Bar>` / `<A.B.C>`: the tag name is a JSXMemberExpression whose
+  // segments are JSXIdentifiers. Rename the specific matching segment only.
+  if (parent.type === 'JSXMemberExpression') {
+    return parent.object === path.node || parent.property === path.node;
+  }
+
+  return false;
 }