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

package/assets/docs/use-a-theme.doc.mjs

@@ -25,13 +25,13 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'Wire the generated module once',
-          code: "import {Theme} from '@astryxdesign/core';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n  return (\n    <Theme theme={themes[defaultThemeSlug]}>\n      <YourApp />\n    </Theme>\n  );\n}",
+          code: "import {Theme} from '@astryxdesign/core/theme';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n  return (\n    <Theme theme={themes[defaultThemeSlug]}>\n      <YourApp />\n    </Theme>\n  );\n}",
         },
         {
           type: 'code',
           lang: 'tsx',
           label: 'Switch among added themes',
-          code: "import {useState} from 'react';\nimport {Theme} from '@astryxdesign/core';\nimport {themes, type ThemeSlug} from './astryx-themes';\n\nconst [slug, setSlug] = useState<ThemeSlug>('neutral');\nconst app = <Theme theme={themes[slug]}><YourApp /></Theme>;",
+          code: "import {useState} from 'react';\nimport {Theme} from '@astryxdesign/core/theme';\nimport {themes, type ThemeSlug} from './astryx-themes';\n\nconst [slug, setSlug] = useState<ThemeSlug>('neutral');\nconst app = <Theme theme={themes[slug]}><YourApp /></Theme>;",
         },
         {
           type: 'prose',

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'],
+};

package/assets/templates/blocks/components/DrawerHeader/DrawerHeaderShowcase.tsx

@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Static header content: title, subtitle, a no-op close handler, and a divider
+ * @output The DrawerHeader row at the top of a square-cornered, drawer-width panel, visible without opening an overlay
+ * @position DrawerHeader's docsite showcase. Drawer has no inline mode
+ *   like Dialog's isInline, so a plain panel stands in for the drawer; in an
+ *   app, compose DrawerHeader in a Layout header slot inside a Drawer.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {DrawerHeader} from '@astryxdesign/core/Drawer';
+import {
+  Layout,
+  LayoutContent,
+  overlayPaddingReset,
+} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {
+  borderVars,
+  colorVars,
+  spacingVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+
+const styles = stylex.create({
+  // A card-like panel with square corners, matching the drawer's own corners.
+  panel: {
+    width: 360,
+    maxWidth: '100%',
+    boxSizing: 'border-box',
+    backgroundColor: colorVars['--color-background-card'],
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
+    borderColor: colorVars['--color-border'],
+    borderRadius: 0,
+  },
+  body: {
+    padding: spacingVars['--spacing-4'],
+    backgroundColor: colorVars['--color-background-muted'],
+    borderRadius: 0,
+  },
+});
+
+export default function DrawerHeaderShowcase() {
+  return (
+    // Like the Drawer root, the panel is a padding boundary, so the Layout
+    // regions inset by their own --spacing-4 default: the drawer's inset.
+    <div {...stylex.props(styles.panel, overlayPaddingReset.reset)}>
+      <Layout
+        height="auto"
+        header={
+          <DrawerHeader
+            title="Host details"
+            subtitle="web-prod-04"
+            onOpenChange={() => {}}
+            hasDivider
+          />
+        }
+        content={
+          <LayoutContent>
+            <div {...stylex.props(styles.body)}>
+              <Text type="body" color="secondary">
+                Drawer body content goes here.
+              </Text>
+            </div>
+          </LayoutContent>
+        }
+      />
+    </div>
+  );
+}

package/assets/templates/blocks/components/DrawerHeader/DrawerHeaderSubtitleEndContent.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: 'With subtitle and end content',
+  displayName: 'With subtitle and end content',
+  description:
+    'Add a subtitle under the title and put a status, such as a Badge, in endContent. The close button stays at the end of the row.',
+  exampleFor: 'DrawerHeader',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: [
+    'Drawer',
+    'DrawerHeader',
+    'Badge',
+    'Button',
+    'Layout',
+    'LayoutContent',
+    'Text',
+  ],
+};

package/assets/templates/blocks/components/DrawerHeader/DrawerHeaderSubtitleEndContent.tsx

@@ -0,0 +1,49 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Controlled open state for a modal Drawer
+ * @output A DrawerHeader with a subtitle, a status badge in its end slot, and a close button
+ * @position Copyable DrawerHeader example
+ */
+
+import {useState} from 'react';
+import {Drawer, DrawerHeader} from '@astryxdesign/core/Drawer';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Button} from '@astryxdesign/core/Button';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function DrawerHeaderSubtitleEndContent() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Button label="Open host details" onClick={() => setIsOpen(true)} />
+      <Drawer
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="web-prod-04"
+        width={360}>
+        <Layout
+          header={
+            <DrawerHeader
+              title="web-prod-04"
+              subtitle="us-east-1"
+              endContent={<Badge label="Healthy" variant="success" />}
+              onOpenChange={setIsOpen}
+            />
+          }
+          content={
+            <LayoutContent>
+              <Text type="body">
+                All 6 instances are passing readiness checks.
+              </Text>
+            </LayoutContent>
+          }
+        />
+      </Drawer>
+    </>
+  );
+}

package/assets/templates/blocks/components/DrawerHeader/DrawerHeaderWithCloseButton.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: 'With close button',
+  displayName: 'With close button',
+  description:
+    'Pass onOpenChange to render a close button that calls it with false. Drawer renders no close button of its own, so this is the usual visible way to close.',
+  exampleFor: 'DrawerHeader',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: [
+    'Drawer',
+    'DrawerHeader',
+    'Button',
+    'Layout',
+    'LayoutContent',
+    'Text',
+  ],
+};