@astryxdesign/cli 0.7.2-canary.c9f2659 → 0.7.2-canary.cbb7fa3

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/tree/add-a-component.doc.mjs

@@ -71,5 +71,15 @@ Declare component root ./components in astryx.integration.mjs.
         },
       ],
     },
+    {
+      id: 'document-an-existing-component',
+      title: 'Document a component you already have',
+      content: [
+        {
+          type: 'prose',
+          text: "To document a component your package already has, write its doc beside the source file and name the doc after that file, such as `acme-gallery.doc.mjs` beside `acme-gallery.tsx`. Set `name` to the export apps import, such as `name: 'AcmeGallery'`, and keep both files inside the components root that `astryx.integration.mjs` declares. The file does not have to be named after the component; {@link generic:component-imports} shows how apps then find it.",
+        },
+      ],
+    },
   ],
 };

package/assets/docs/tree/checks.doc.mjs

@@ -105,7 +105,7 @@ export const docs = {
             'It runs `npm pack` the way `npm publish` would, including your `prepack` script.',
             'It checks that every contribution file is in the `.tgz` file. A root missing from `files` fails with `Add "templates" to "files" in package.json.`',
             'It lists the components, templates, themes, docs, and codemods the temporary app sees, and compares them with your source.',
-            "It resolves each component's `import`, and each template's public import, the way Node does, and checks that the module exports the component, or a default export for a template.",
+            "It resolves each component's `import`, and each template's public import, the way Node does, and checks that the module exports the component under the name its doc documents, or a default export for a template. A type-only export does not count.",
             'For each theme, it rebuilds the source, compares the built module and production CSS with the authored outputs, and proves the module, CSS, and optional font CSS exports resolve from the packed package.',
             'It fails a package that needs an `@astryxdesign/cli` peer and lacks it: `>=0.6.6` for a template that sets `keywords`, and `>=0.6.4` for a template that sets `replaces`, a docs section, a placed guide, a doc section with an `id`, or a theme.',
           ],

package/assets/docs/tree/component-family.doc.mjs

@@ -95,7 +95,11 @@ export default {
         },
         {
           type: 'prose',
-          text: 'The public module named by `import` must export every component or hook named by a full entry.',
+          text: "The public module named by `import` must export every component or hook named by a full entry. Apps then list, search and open each component in the family by its own name. A full entry the module does not export is not listed, and `integration verify` does not report it: check the family with `astryx component --list`. When `import` names output your pack lifecycle builds (such as `dist`), the members are listed once that output exists, and `integration verify` compares them as they are listed after the pack builds it.",
+        },
+        {
+          type: 'prose',
+          text: "A member's source is the `.tsx` file in the family doc's folder, or below it, that declares it: the one the family's own file or the module `import` names reaches, else the one in that folder that declares the name, as when `import` names built output. A member that only a bundle or a file outside that folder declares is still listed, with no source for `--source` or `swizzle`. A member is not listed when a doc's file or a Core name your package replaces already has its name. A member that shares a name with Core opens with `--package`.",
         },
       ],
     },

package/assets/docs/tree/component-imports.doc.mjs

@@ -35,6 +35,14 @@ export const docs = {
           type: 'prose',
           text: 'Add writes the entry only when package.json already has an `exports` map, so start every package with `"exports": {}`.',
         },
+        {
+          type: 'prose',
+          text: 'A file does not have to be named after its component. When `Slides.tsx` exports `AcmeCarousel` and nothing named `Slides`, keep the doc beside it as `Slides.doc.mjs` and set its `name` to `AcmeCarousel`: apps list, search and open the component by that name, and `integration verify` checks that its import exports `AcmeCarousel`. A file that exports its own name keeps that name. A package that names its files in kebab case works the same way: `acme-gallery.doc.mjs` beside `acme-gallery.tsx` sets `name: \'AcmeGallery\'`.',
+        },
+        {
+          type: 'prose',
+          text: "The file name still opens the doc. A name that Core or another doc's file already has stays theirs, and so does a Core name your package replaces: with `Badge.doc.mjs` naming `AcmeBadge`, `astryx component Badge` opens Core's `Badge`, and `--package` with your package name reaches yours.",
+        },
       ],
     },
     {

package/assets/docs/tree/single-component.doc.mjs

@@ -56,7 +56,7 @@ export default {
           style: 'unordered',
           items: [
             'Keep `props` on the top-level doc. Private implementation helpers do not need entries.',
-            'Keep the doc beside the source and change both in the same pull request.',
+            'Name the doc after the source file beside it, such as `AcmeCarousel.doc.mjs` beside `AcmeCarousel.tsx`, and change both in the same pull request.',
             'If the module later exposes several related public exports, adapt this doc with {@link generic:component-family}.',
           ],
         },

package/assets/docs/tree/troubleshooting.doc.mjs

@@ -67,7 +67,7 @@ export const docs = {
           rows: [
             [
               '`component_export_missing`: `Component "AcmeCarousel" advertises import "@acme/astryx-widgets/components/AcmeCarousel", but that packed module does not export "AcmeCarousel".`',
-              "package.json has no `exports` map, or the module does not export the name. Keep `export function AcmeCarousel`, and add the entry: `npm pkg set 'exports[./components/AcmeCarousel]=./components/AcmeCarousel.tsx'`.",
+              "package.json has no `exports` map, or the module does not export the name. Keep `export function AcmeCarousel`, and add the entry: `npm pkg set 'exports[./components/AcmeCarousel]=./components/AcmeCarousel.tsx'`. When the quoted name is a file name, such as `acme-carousel`, set the doc's `name` to the component the file exports. A type-only export does not count.",
             ],
             [
               '`template_export_missing`: `Template "acme-dashboard" public import "@acme/astryx-widgets/templates/acme-dashboard" does not have a default export.`',
@@ -125,6 +125,14 @@ export const docs = {
           type: 'table',
           headers: ['Symptom', 'Fix'],
           rows: [
+            [
+              '`Error: No component named "AcmeCarousel"` for a component your package documents.',
+              "Its doc still names its file. Set `name` to the export, such as `name: 'AcmeCarousel'` in `acme-carousel.doc.mjs`. A family member is listed only when the module its family doc imports exports it ({@link generic:component-family}).",
+            ],
+            [
+              '`npx astryx component Dialog` opens Core\'s `Dialog`, not yours.',
+              "A name that Core, a legacy docs package, or another package's file already has stays theirs. Run `npx astryx component Dialog --package @acme/astryx-widgets`, or give your component a name of its own.",
+            ],
             [
               '`Error: Template "dashboard" is ambiguous — narrow it with --type and/or --package.`',
               "Your template id matches a Core id. Rename it, such as `acme-dashboard`, or set `replaces: 'dashboard'` to take its place. `npx astryx doctor integration templates` warns about this before you publish.",

package/assets/docs/tree/versioning.doc.mjs

@@ -140,6 +140,7 @@ export const docs = {
             'Published 0.6.3 and earlier reject a template that sets `replaces` or `keywords`, drop that template, and hide every doc topic your package ships. Published 0.6.4 and 0.6.5 still drop a template that sets `keywords`.',
             'A stable CLI before 0.6.4 cannot read a docs section, a section `id`, or a theme folder that `integration add theme` writes. It can then hide every doc topic your package ships.',
             'Stable 0.6.3 still loads your components, but 0.6.0 cannot read the component docs that `integration add component` writes: `component AcmeCarousel` fails there.',
+            'An app on an older CLI lists a component whose doc names another export of its file under the file name, and lists no family members, so `component AcmeCarousel` fails there.',
           ],
         },
         {

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