@astryxdesign/cli 0.4.5-canary.ffd05c4 → 0.4.6-canary.cea9ecd

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

@@ -346,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.
   //
@@ -413,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;
 }

package/assets/docs/cli-integrations.doc.mjs

@@ -16,7 +16,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'An integration is an npm package that contributes components, templates, and/or upgrade codemods to a consumer\'s design-system workflow. Consumers install the package and add it to their `astryx.config`; from then on the integration\'s contributions show up alongside core\'s in the same CLI commands.',
+          text: 'An integration is an npm package that contributes components, templates, doc topics, and/or upgrade codemods to a consumer\'s design-system workflow. Consumers install the package and add it to their `astryx.config`; from then on the integration\'s contributions show up alongside core\'s in the same CLI commands.',
         },
         {
           type: 'prose',
@@ -48,12 +48,12 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'To register your package as an integration, add an `astryx.integration.{ts,mjs,js}` file as a sibling of your `package.json`. It tells the CLI where to find your components, templates, and codemods. Identity (name, version) comes from your `package.json`, not this file.',
+          text: 'To register your package as an integration, add an `astryx.integration.{ts,mjs,js}` file as a sibling of your `package.json`. It tells the CLI where to find your components, templates, doc topics, and codemods. Identity (name, version) comes from your `package.json`, not this file.',
         },
         {
           type: 'code',
           lang: 'typescript',
-          code: "// astryx.integration.ts\nexport default {\n  components: './components',\n  templates: './templates',\n  codemods: './codemods',\n  issuesUrl: 'https://github.com/acme/widgets/issues',\n};",
+          code: "// astryx.integration.ts\nexport default {\n  components: './components',\n  templates: './templates',\n  codemods: './codemods',\n  docs: './docs',\n  issuesUrl: 'https://github.com/acme/widgets/issues',\n};",
         },
         {
           type: 'prose',
@@ -109,6 +109,44 @@ export const docs = {
         },
       ],
     },
+    {
+      title: 'Docs',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: "Point the integration file's `docs` field at a directory of reference docs and every `{topic}.doc.{ts,mjs,js}` under it becomes a topic the CLI serves — `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object stamped `type: 'generic'`, the same shape core's own topics use.",
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          code: "// docs/deploying.doc.ts\nexport default {\n  type: 'generic',\n  name: 'deploying',\n  title: 'Deploying',\n  description: 'Ship an app built with Acme widgets.',\n  category: 'guide',\n  sections: [\n    {title: 'Overview', content: [{type: 'prose', text: '...'}]},\n  ],\n};",
+        },
+        {
+          type: 'prose',
+          text: "A topic can also speak about one that already exists. `replaces: 'x'` takes over topic x — core's, or another integration's — so a package whose consumers install it differently can serve its own Getting Started instead of the built-in one. Give the replacement a different `name` and the old name keeps resolving to it, so a link or an agent that learned the old topic still lands in the right place.",
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          code: "export default {\n  type: 'generic',\n  name: 'getting-started',\n  replaces: 'getting-started',\n  title: 'Getting started',\n  description: 'Install Acme widgets and use your first component.',\n  sections: [/* ... */],\n};",
+        },
+        {
+          type: 'prose',
+          text: "`extends: 'x'` merges onto a topic instead of owning it: a section whose title matches one in the base replaces that section, and a section the base does not have is appended. Reach for it to correct or add to a topic you do not want to fork — a fork of someone else's guide stops receiving their fixes the day you write it.",
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'A topic name is a CLI argument and a docsite path, so it may hold only letters, digits, `_` and `-`.',
+            "A name that collides with an existing topic and declares neither `replaces` nor `extends` is an error, not a silent override — the CLI will not guess which one you meant.",
+            '`replaces` and `extends` are exclusive: a topic either takes another\'s place or merges onto it.',
+            'Two integrations replacing one topic is a warning, and the one configured later in `astryx.config` wins.',
+          ],
+        },
+      ],
+    },
     {
       title: 'Codemods',
       category: 'guide',

package/assets/docs/theme.doc.mjs

@@ -152,7 +152,7 @@ function App() {
         },
         {
           type: 'prose',
-          text: 'For an annotated map of the whole surface — every defineTheme field, the token families, and the component override syntax, each with the CLI command that prints its reference — run `astryx theme template`. It writes `theme.template.ts` into your project to read and copy from (`astryx init --features theme` writes it as part of project setup).',
+          text: 'For an annotated map of the whole surface (every defineTheme field, the token families, and the component override syntax, each with the CLI command that prints its reference), run `astryx theme template`. It writes `theme.template.ts` into your project to read and copy from (`astryx init --features theme` writes it as part of project setup).',
         },
       ],
     },
@@ -261,7 +261,7 @@ const brandTheme = defineTheme({
         },
         {
           type: 'prose',
-          text: 'Inheritance is resolved when the theme is defined, so an extended theme is flat: `astryx theme build` emits one self-contained stylesheet holding everything the child inherited, and the base theme\'s CSS does not need to be loaded next to it. A base that is not a theme — most often an import that missed — is a build error rather than a theme that silently inherits nothing.',
+          text: 'Inheritance is resolved when the theme is defined, so an extended theme is flat: `astryx theme build` emits one self-contained stylesheet holding everything the child inherited, and the base theme\'s CSS does not need to be loaded next to it. A base that is not a theme (most often an import that missed) is a build error rather than a theme that silently inherits nothing.',
         },
       ],
     },
@@ -425,7 +425,7 @@ import './themes/ocean.css';
         },
         {
           type: 'prose',
-          text: 'The build also warns when the theme names font families it does not load (webfonts like Fraunces) and prints the `<link>`/`@font-face` to add — the built CSS only sets font-family, so loading the font files stays the app\'s job. See `astryx docs typography` for the full recipe.',
+          text: 'The build also warns when the theme names font families it does not load (webfonts like Fraunces) and prints the `<link>`/`@font-face` to add. The built CSS only sets font-family, so loading the font files stays the app\'s job. See `astryx docs typography` for the full recipe.',
         },
       ],
     },

package/assets/templates/blocks/components/AvatarGroup/AvatarGroupInteractive.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'AvatarGroup',
+  name: 'AvatarGroup — Interactive',
+  displayName: 'Avatar Group — Interactive',
+  description:
+    'A facepile whose avatars link to profiles, with an overflow indicator that opens the full member list. The whole group is one Tab stop; arrow keys move between the avatars and the overflow button.',
+  isReady: true,
+  isShowcase: false,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['AvatarGroup', 'Avatar', 'Layout', 'Text'],
+};

package/assets/templates/blocks/components/AvatarGroup/AvatarGroupInteractive.tsx

@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+'use client';
+
+import {AvatarGroup, AvatarGroupOverflow} from '@astryxdesign/core/AvatarGroup';
+import {Avatar} from '@astryxdesign/core/Avatar';
+import {Stack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+const MEMBERS = [
+  {name: 'Alex Daniels', key: 'alex', href: '/team/alex'},
+  {name: 'Ann Smith', key: 'ann', href: '/team/ann'},
+  {name: 'Carol Davis', key: 'carol', href: '/team/carol'},
+];
+
+const TOTAL_MEMBERS = 18;
+
+export default function AvatarGroupInteractive() {
+  return (
+    <Stack direction="vertical" gap={8}>
+      <Stack direction="vertical" gap={3}>
+        <Text type="supporting" color="secondary">
+          Reviewers
+        </Text>
+        <AvatarGroup size="lg" aria-label="Reviewers">
+          {MEMBERS.map(m => (
+            <Avatar key={m.key} name={m.name} href={m.href} />
+          ))}
+          <AvatarGroupOverflow
+            count={TOTAL_MEMBERS - MEMBERS.length}
+            onClick={() => {}}
+          />
+        </AvatarGroup>
+      </Stack>
+      <Stack direction="vertical" gap={3}>
+        <Text type="supporting" color="secondary">
+          Compact, static
+        </Text>
+        <AvatarGroup size="sm" aria-label="Attendees">
+          {MEMBERS.map(m => (
+            <Avatar key={m.key} name={m.name} />
+          ))}
+          <AvatarGroupOverflow count={TOTAL_MEMBERS - MEMBERS.length} />
+        </AvatarGroup>
+      </Stack>
+    </Stack>
+  );
+}

package/assets/templates/blocks/components/AvatarGroup/AvatarGroupShowcase.doc.mjs

@@ -6,7 +6,7 @@ export const doc = {
   name: 'AvatarGroup',
   displayName: 'Avatar Group',
   description:
-    'Overlapping avatar rows with max limit and server-side overflow count. Shows team members in a compact facepile layout.',
+    'Overlapping avatar rows with a sliced visible set and a server-side overflow count. Shows team members in a compact facepile layout.',
   isReady: true,
   isShowcase: true,
   aspectRatio: 16 / 9,

package/assets/templates/blocks/components/Breadcrumbs/BreadcrumbsCustomSeparator.tsx

@@ -2,25 +2,38 @@
 
 'use client';
 
+import * as stylex from '@stylexjs/stylex';
 import {Breadcrumbs, BreadcrumbItem} from '@astryxdesign/core/Breadcrumbs';
 import {Stack} from '@astryxdesign/core/Layout';
 import {Text} from '@astryxdesign/core/Text';
+import {rtlStyles} from '@astryxdesign/core/utils';
 
+// Only a glyph the bidi algorithm does not already flip needs rtlStyles.mirror.
+// U+203A has Unicode Bidi_Mirrored=Yes, so the browser mirrors it under RTL on
+// its own and a second flip would point it back the wrong way; U+2192 has
+// Bidi_Mirrored=No and stays pointing left-to-right unless we mirror it.
 const SEPARATORS = [
-  {char: '›', label: 'Chevron'},
-  {char: '→', label: 'Arrow'},
-  {char: '·', label: 'Dot'},
+  {char: '›', label: 'Chevron', needsRtlMirror: false},
+  {char: '→', label: 'Arrow', needsRtlMirror: true},
+  {char: '·', label: 'Dot', needsRtlMirror: false},
 ];
 
 export default function BreadcrumbsCustomSeparator() {
   return (
     <Stack direction="vertical" gap={4}>
-      {SEPARATORS.map(({char, label}) => (
+      {SEPARATORS.map(({char, label, needsRtlMirror}) => (
         <Stack key={label} direction="vertical" gap={1}>
           <Text type="supporting" color="secondary">
             {label}
           </Text>
-          <Breadcrumbs separator={char}>
+          <Breadcrumbs
+            separator={
+              needsRtlMirror ? (
+                <span {...stylex.props(rtlStyles.mirror)}>{char}</span>
+              ) : (
+                char
+              )
+            }>
             <BreadcrumbItem href="/">Home</BreadcrumbItem>
             <BreadcrumbItem href="/docs">Docs</BreadcrumbItem>
             <BreadcrumbItem isCurrent>API Reference</BreadcrumbItem>

package/assets/templates/blocks/components/Selector/SelectorOptionDescriptions.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   name: 'Selector — Option descriptions',
   displayName: 'Selector — Option descriptions',
   description:
-    'Options carry a description, so the dropdown draws a two-line row. The closed trigger is sized by padding, so it is the size token for a one-line value and exactly one line taller for a two-line one — both on the 4px rhythm. An InputGroup pins the row, so the value folds back onto one line there.',
+    'Options carry a description, so the dropdown draws a two-line row. The closed trigger is sized by padding, so it is the size token for a one-line value and exactly one line taller for a two-line one; both on the 4px rhythm. An InputGroup pins the row, so the value folds back onto one line there.',
   isReady: true,
   aspectRatio: 16 / 9,
   componentsUsed: ['Selector', 'SelectorOption', 'InputGroup', 'Button', 'Stack'],