@astryxdesign/cli 0.7.2-canary.db3a2e7 → 0.7.2-canary.e2909cf

package/assets/codemods/transforms/next/migrate-list-edge-compensation-to-edge.mjs

@@ -0,0 +1,198 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate List edgeCompensation to edge
+ *
+ * `edgeCompensation="inline"` on an imported `List` becomes `edge="outset"`,
+ * the value it already resolves to. List resolves
+ * `edge ?? (edgeCompensation === 'inline' ? 'outset' : 'padded')`, so `edge`
+ * wins only when it has a value. The deprecated prop is removed beside an
+ * `edge` string that no later spread can override; beside a computed `edge`,
+ * which may be undefined at runtime, it gets a TODO instead.
+ *
+ * Built on the shared `transformProp` helper, so it does not follow
+ * variables, helpers, wrappers, or types. Where a List writes
+ * `edgeCompensation` but the codemod cannot prove the result, it keeps the
+ * old prop and leaves a TODO instead of guessing: on a dynamic value, and
+ * wherever the List also spreads props. A spread before the old prop may
+ * carry an `edge` that wins today and that a new `edge` would override; one
+ * after it may override either prop. A spread onto a List that never writes
+ * `edgeCompensation` is not evidence of use, so it stays unchanged
+ * (`spec:AST-040` FR1): the deprecated prop keeps working through it, and
+ * its `@deprecated` type reports a typed use where the props are written.
+ * Comments are the codemod's only report channel (`api.report` is a stub),
+ * and each is added once, so a second run changes nothing.
+ */
+
+import {transformProp} from '../../transform-prop.mjs';
+
+export const meta = {
+  title: 'Migrate List edgeCompensation to edge',
+  description:
+    'Renames `edgeCompensation="inline"` to `edge="outset"` on List, and ' +
+    'drops `edgeCompensation` beside an `edge` string. Keeps the old prop ' +
+    'with a TODO where `edge` is computed or a later spread may override ' +
+    'it, on a dynamic value, and where the List also spreads props; the ' +
+    'deprecated prop still works there.',
+};
+
+const OLD_NAME = 'edgeCompensation';
+const NEW_NAME = 'edge';
+const CORE_IMPORT_RE = /^@(astryxdesign|xds)\/core(?:\/|$)/;
+
+const COMPONENT_PROPS = new Map([['List', new Set([OLD_NAME])]]);
+
+const DYNAMIC_COMMENT =
+  ' TODO(astryx upgrade): edgeCompensation is deprecated. Replace ' +
+  'edgeCompensation="inline" with edge="outset" by hand; this value is ' +
+  'computed. ';
+const BOTH_SET_COMMENT =
+  ' TODO(astryx upgrade): edgeCompensation is deprecated. edge is also set ' +
+  'here, but it may be undefined, and then edgeCompensation still applies. ' +
+  'Make edge default to "outset" where edgeCompensation is "inline", then ' +
+  'remove edgeCompensation. ';
+const SPREAD_COMMENT =
+  ' TODO(astryx upgrade): edgeCompensation is deprecated, but this List ' +
+  'also spreads props that may set edge, so it was left unchanged. Replace ' +
+  'edgeCompensation="inline" with edge="outset" by hand, after checking ' +
+  'which edge the spread passes. ';
+
+const TYPE_WRAPPERS = new Set([
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSTypeAssertion',
+  'TSNonNullExpression',
+  'TypeCastExpression',
+  'ParenthesizedExpression',
+]);
+
+/** @param {any} node */
+function unwrap(node) {
+  let current = node;
+  while (current && TYPE_WRAPPERS.has(current.type)) {
+    current = current.expression;
+  }
+  return current;
+}
+
+/** @param {any} node */
+function isStringLiteral(node) {
+  const value = unwrap(node);
+  return (
+    value != null &&
+    (value.type === 'StringLiteral' || value.type === 'Literal') &&
+    typeof value.value === 'string'
+  );
+}
+
+/**
+ * The value of a JSX attribute: the string of `edge="flush"`, or the
+ * expression inside `edge={...}`.
+ * @param {any} attribute
+ */
+function attributeValue(attribute) {
+  return attribute.value?.type === 'JSXExpressionContainer'
+    ? attribute.value.expression
+    : attribute.value;
+}
+
+/** @param {any} node */
+function isInlineLiteral(node) {
+  const value = unwrap(node);
+  return (
+    value != null &&
+    (value.type === 'StringLiteral' || value.type === 'Literal') &&
+    value.value === 'inline'
+  );
+}
+
+/**
+ * Attach a comment to a node once, so re-running the codemod adds nothing.
+ * @param {any} j @param {any} node @param {string} text
+ */
+function addComment(j, node, text) {
+  node.comments ??= [];
+  if (node.comments.some((/** @type {any} */ c) => c.value === text)) {
+    return false;
+  }
+  node.comments.push(j.commentBlock(text, true, false));
+  return true;
+}
+
+/** @param {any} attributes */
+function firstSpread(attributes) {
+  return attributes.find(
+    (/** @type {any} */ attribute) => attribute.type === 'JSXSpreadAttribute',
+  );
+}
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  transformProp(
+    root,
+    j,
+    {
+      matchesImport: source => CORE_IMPORT_RE.test(source),
+      components: COMPONENT_PROPS,
+    },
+    propPath => {
+      const opening = propPath.parent?.node;
+      const attributes = opening?.attributes ?? [];
+      const prop = propPath.node;
+      const edgeIndex = attributes.findIndex(
+        (/** @type {any} */ attribute) =>
+          attribute.type === 'JSXAttribute' &&
+          attribute.name?.name === NEW_NAME,
+      );
+      if (edgeIndex !== -1) {
+        // `edge` wins only when it has a value. A string that no later
+        // spread can override always does, so the old prop is inert and
+        // removing it changes nothing. A computed `edge` may be undefined,
+        // and then the old prop still decides.
+        const isProven =
+          isStringLiteral(attributeValue(attributes[edgeIndex])) &&
+          !attributes
+            .slice(edgeIndex + 1)
+            .some(
+              (/** @type {any} */ attribute) =>
+                attribute.type === 'JSXSpreadAttribute',
+            );
+        if (isProven) {
+          opening.attributes = attributes.filter(
+            (/** @type {any} */ attribute) => attribute !== prop,
+          );
+          hasChanges = true;
+        } else {
+          hasChanges = addComment(j, prop, BOTH_SET_COMMENT) || hasChanges;
+        }
+        return;
+      }
+      // With a spread on the element the rename cannot be proven: a spread
+      // before the old prop may carry an `edge` that wins today and that a
+      // new `edge` would override, and one after it may override either
+      // prop. The old prop keeps working, so it stays, with a TODO.
+      if (firstSpread(attributes)) {
+        hasChanges = addComment(j, prop, SPREAD_COMMENT) || hasChanges;
+        return;
+      }
+      if (isInlineLiteral(attributeValue(prop))) {
+        prop.name.name = NEW_NAME;
+        prop.value = j.stringLiteral('outset');
+        hasChanges = true;
+      } else {
+        hasChanges = addComment(j, prop, DYNAMIC_COMMENT) || hasChanges;
+      }
+    },
+  );
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/assets/docs/working-with-ai.doc.mjs

@@ -44,7 +44,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'By default this creates `AGENTS.md` (the tool-agnostic standard most agents read). To target a specific tool\'s file instead:',
+          text: "By default this creates `AGENTS.md` (the tool-agnostic standard most agents read). To target a specific tool's file instead:",
         },
         {
           type: 'code',
@@ -182,21 +182,60 @@ astryx docs principles --dense`,
         },
         {
           type: 'prose',
-          text: 'Add the server to your MCP config file. This works with any MCP-compatible tool: Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), Windsurf (.windsurf/mcp.json), Cline, and others.',
+          text: 'Add the server to your MCP config file. The entry is a remote HTTP server, and the exact shape differs per client, so use the snippet for the tool you run. An entry with an unrecognized transport is skipped with a warning rather than an error, which reads as a server that connects but exposes no tools.',
         },
         {
           type: 'code',
           lang: 'json',
-          label: 'MCP config (same for all tools)',
+          label: 'Claude Code (.mcp.json)',
           code: `{
   "mcpServers": {
     "astryx": {
-      "type": "url",
+      "type": "http",
       "url": "https://astryx.atmeta.com/mcp"
     }
   }
 }`,
         },
+        {
+          type: 'prose',
+          text: 'Claude Code can also write that entry from the terminal:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: `claude mcp add --transport http astryx https://astryx.atmeta.com/mcp`,
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          label: 'Cline (cline_mcp_settings.json) - type is streamableHttp',
+          code: `{
+  "mcpServers": {
+    "astryx": {
+      "type": "streamableHttp",
+      "url": "https://astryx.atmeta.com/mcp"
+    }
+  }
+}`,
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          label:
+            'Cursor (.cursor/mcp.json) - remote servers take no type field',
+          code: `{
+  "mcpServers": {
+    "astryx": {
+      "url": "https://astryx.atmeta.com/mcp"
+    }
+  }
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'Claude Desktop is the exception: claude_desktop_config.json holds local stdio servers, so a remote server is added through Settings, then Connectors, then Add custom connector, pasting the URL above.',
+        },
         {
           type: 'prose',
           text: 'Once connected, your AI tool can search for components by natural language (e.g. "dropdown menu", "success message") and retrieve full documentation without any manual CLI invocation. The server uses the same keyword index from component docs, so search quality improves automatically as component documentation is updated.',

package/assets/templates/blocks/components/Drawer/DrawerForm.doc.mjs

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  name: 'Edit form with footer actions',
+  displayName: 'Edit form with footer actions',
+  description:
+    'Compose a Layout with DrawerHeader, the fields in LayoutContent, and Cancel and Save in a pinned LayoutFooter. purpose="form" keeps Escape but ignores scrim clicks, so a stray click outside does not discard edits.',
+  exampleFor: 'Drawer',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: [
+    'Drawer',
+    'DrawerHeader',
+    'Button',
+    'Layout',
+    'LayoutContent',
+    'LayoutFooter',
+    'HStack',
+    'VStack',
+    'TextInput',
+  ],
+};

package/assets/templates/blocks/components/Drawer/DrawerForm.tsx

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Controlled open state and two editable fields
+ * @output A form drawer with a header, scrolling fields, and pinned footer
+ *   actions; purpose="form" keeps Escape but ignores scrim clicks
+ * @position Copyable Drawer example
+ */
+
+import {useState} from 'react';
+import {Drawer, DrawerHeader} from '@astryxdesign/core/Drawer';
+import {Button} from '@astryxdesign/core/Button';
+import {Layout, LayoutContent, LayoutFooter} from '@astryxdesign/core/Layout';
+import {HStack, VStack} from '@astryxdesign/core/Stack';
+import {TextInput} from '@astryxdesign/core/TextInput';
+
+export default function DrawerForm() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [name, setName] = useState('web-prod-04');
+  const [owner, setOwner] = useState('Platform team');
+
+  return (
+    <>
+      <Button label="Edit host" onClick={() => setIsOpen(true)} />
+      <Drawer
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="Edit host"
+        purpose="form">
+        <Layout
+          header={<DrawerHeader title="Edit host" onOpenChange={setIsOpen} />}
+          content={
+            <LayoutContent>
+              <VStack gap={4}>
+                <TextInput label="Name" value={name} onChange={setName} />
+                <TextInput label="Owner" value={owner} onChange={setOwner} />
+              </VStack>
+            </LayoutContent>
+          }
+          footer={
+            <LayoutFooter>
+              <HStack gap={2} hAlign="end">
+                <Button
+                  label="Cancel"
+                  variant="secondary"
+                  onClick={() => setIsOpen(false)}
+                />
+                <Button
+                  label="Save"
+                  variant="primary"
+                  onClick={() => setIsOpen(false)}
+                />
+              </HStack>
+            </LayoutFooter>
+          }
+        />
+      </Drawer>
+    </>
+  );
+}

package/assets/templates/blocks/components/Drawer/DrawerScrim.doc.mjs

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  name: 'Modal or non-modal (hasScrim)',
+  displayName: 'Modal or non-modal (hasScrim)',
+  description:
+    'The default modal drawer dims the page, traps focus, and closes on a scrim click. With hasScrim={false}, the drawer has no scrim or focus trap and leaves the page interactive.',
+  exampleFor: 'Drawer',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: [
+    'Drawer',
+    'Button',
+    'Layout',
+    'LayoutContent',
+    'HStack',
+    'DrawerHeader',
+    'Text',
+  ],
+};

package/assets/templates/blocks/components/Drawer/DrawerScrim.tsx

@@ -0,0 +1,68 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Separate controlled states for modal and non-modal drawers
+ * @output A comparison of hasScrim's two presentations
+ * @position Copyable Drawer example
+ */
+
+import {useState} from 'react';
+import {Drawer, DrawerHeader} from '@astryxdesign/core/Drawer';
+import {Button} from '@astryxdesign/core/Button';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
+import {HStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function DrawerScrim() {
+  const [openModal, setOpenModal] = useState(false);
+  const [openPanel, setOpenPanel] = useState(false);
+
+  return (
+    <>
+      <HStack gap={2}>
+        <Button label="Open modal drawer" onClick={() => setOpenModal(true)} />
+        <Button
+          label="Open non-modal drawer"
+          onClick={() => setOpenPanel(true)}
+        />
+      </HStack>
+      <Drawer
+        isOpen={openModal}
+        onOpenChange={setOpenModal}
+        label="Edit details">
+        <Layout
+          header={
+            <DrawerHeader title="Edit details" onOpenChange={setOpenModal} />
+          }
+          content={
+            <LayoutContent>
+              <Text type="body">
+                The scrim blocks the page behind this modal drawer.
+              </Text>
+            </LayoutContent>
+          }
+        />
+      </Drawer>
+      <Drawer
+        isOpen={openPanel}
+        onOpenChange={setOpenPanel}
+        label="Inspector"
+        hasScrim={false}>
+        <Layout
+          header={
+            <DrawerHeader title="Inspector" onOpenChange={setOpenPanel} />
+          }
+          content={
+            <LayoutContent>
+              <Text type="body">
+                The page behind this non-modal drawer stays interactive.
+              </Text>
+            </LayoutContent>
+          }
+        />
+      </Drawer>
+    </>
+  );
+}

package/assets/templates/blocks/components/Drawer/DrawerShowcase.doc.mjs

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  name: 'Basic',
+  displayName: 'Basic',
+  description:
+    'Open a modal drawer from a single trigger. The scrim dims the page; Escape, a scrim click, or the header close button closes it, and focus returns to the trigger.',
+  exampleFor: 'Drawer',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: [
+    'Drawer',
+    'Button',
+    'Layout',
+    'LayoutContent',
+    'DrawerHeader',
+    'Text',
+  ],
+};

package/assets/templates/blocks/components/Drawer/DrawerShowcase.tsx

@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Controlled open state for a modal Drawer
+ * @output A single-trigger drawer with a scrim and a DrawerHeader close button
+ * @position Drawer's docsite showcase and copyable CLI block
+ */
+
+import {useState} from 'react';
+import {Drawer, DrawerHeader} from '@astryxdesign/core/Drawer';
+import {Button} from '@astryxdesign/core/Button';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function DrawerShowcase() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Button label="Open drawer" onClick={() => setIsOpen(true)} />
+      <Drawer
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="Details"
+        width={360}>
+        <Layout
+          header={<DrawerHeader title="Details" onOpenChange={setIsOpen} />}
+          content={
+            <LayoutContent>
+              <Text type="body">
+                Close with Escape, the scrim, or the close button.
+              </Text>
+            </LayoutContent>
+          }
+        />
+      </Drawer>
+    </>
+  );
+}

package/assets/templates/blocks/components/Drawer/DrawerStart.doc.mjs

@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  name: 'Slide in from the start edge',
+  displayName: 'Slide in from the start edge',
+  description:
+    'Set side="start" to open from the inline start edge: left in LTR and right in RTL. The default end edge follows the inspector convention.',
+  exampleFor: 'Drawer',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: [
+    'Drawer',
+    'Button',
+    'Layout',
+    'LayoutContent',
+    'DrawerHeader',
+    'Text',
+  ],
+};

package/assets/templates/blocks/components/Drawer/DrawerStart.tsx

@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Controlled open state and the logical start edge
+ * @output A Drawer that opens from the start side of the viewport
+ * @position Copyable Drawer example
+ */
+
+import {useState} from 'react';
+import {Drawer, DrawerHeader} from '@astryxdesign/core/Drawer';
+import {Button} from '@astryxdesign/core/Button';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function DrawerStart() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Button label="Open start drawer" onClick={() => setIsOpen(true)} />
+      <Drawer
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="Navigation"
+        side="start">
+        <Layout
+          header={<DrawerHeader title="Navigation" onOpenChange={setIsOpen} />}
+          content={
+            <LayoutContent>
+              <Text type="body">
+                The start edge follows the page's writing direction.
+              </Text>
+            </LayoutContent>
+          }
+        />
+      </Drawer>
+    </>
+  );
+}

package/assets/templates/blocks/components/Drawer/DrawerWidths.doc.mjs

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  name: 'Width budget: pixels or any CSS length',
+  displayName: 'Width budget: pixels or any CSS length',
+  description:
+    'Compare a numeric pixel width with rem and percentage lengths. The width budget also caps the drawer on mobile.',
+  exampleFor: 'Drawer',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: [
+    'Drawer',
+    'Button',
+    'Layout',
+    'LayoutContent',
+    'HStack',
+    'DrawerHeader',
+    'Text',
+  ],
+};

package/assets/templates/blocks/components/Drawer/DrawerWidths.tsx

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input A pixel, rem, or percentage width and controlled open state
+ * @output A Drawer demonstrating the selected width budget
+ * @position Copyable Drawer example
+ */
+
+import {useState} from 'react';
+import {Drawer, DrawerHeader} from '@astryxdesign/core/Drawer';
+import {Button} from '@astryxdesign/core/Button';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
+import {HStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function DrawerWidths() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [width, setWidth] = useState<number | string>(320);
+
+  function openAtWidth(value: number | string) {
+    setWidth(value);
+    setIsOpen(true);
+  }
+
+  return (
+    <>
+      <HStack gap={2}>
+        <Button label="320px" onClick={() => openAtWidth(320)} />
+        <Button label="32rem" onClick={() => openAtWidth('32rem')} />
+        <Button label="50%" onClick={() => openAtWidth('50%')} />
+      </HStack>
+      <Drawer
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="Width budget"
+        width={width}>
+        <Layout
+          header={
+            <DrawerHeader title="Width budget" onOpenChange={setIsOpen} />
+          }
+          content={
+            <LayoutContent>
+              <Text type="body">
+                Width: {typeof width === 'number' ? `${width}px` : width}
+              </Text>
+            </LayoutContent>
+          }
+        />
+      </Drawer>
+    </>
+  );
+}

package/assets/templates/blocks/components/DrawerHeader/DrawerHeaderShowcase.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  name: 'DrawerHeader',
+  displayName: 'Drawer Header',
+  description:
+    'DrawerHeader provides a structured header for drawers with slots for title, subtitle, close button, and optional start or end content.',
+  exampleFor: 'DrawerHeader',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['DrawerHeader', 'Layout', 'LayoutContent', 'Text'],
+};