@astryxdesign/cli 0.7.2-canary.f16dc9f → 0.7.2-canary.fe2c655

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

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

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Controlled open state for a modal Drawer
+ * @output A Drawer whose DrawerHeader renders a close button because it receives onOpenChange
+ * @position Copyable DrawerHeader 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 DrawerHeaderWithCloseButton() {
+  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">
+                Passing onOpenChange renders the close button, which calls it
+                with false.
+              </Text>
+            </LayoutContent>
+          }
+        />
+      </Drawer>
+    </>
+  );
+}

package/assets/templates/pages/detail-page/page.tsx

@@ -600,9 +600,9 @@ export default function DetailPage2Template() {
         }
         end={!isNarrow && showSidePanel ? <RightPanel /> : undefined}
       />
-      {/* Mobile: the side panel content opens as a full-screen dialog. (A
-          side drawer/sheet would be more idiomatic, but Astryx has no Drawer
-          component yet — #2575 — so we use the fullscreen Dialog variant.) */}
+      {/* Mobile: the side-panel content uses the full viewport so order details
+          are not squeezed beside narrow page chrome. Drawer remains available
+          for side-overlay flows that intentionally preserve page context. */}
       <Dialog
         variant="fullscreen"
         isOpen={isNarrow && isPanelDialogOpen}

package/assets/templates/pages/table-inbox/page.tsx

@@ -1652,8 +1652,8 @@ const COMPOSER_TOOLS: {
 /**
  * The compose sheet.
  *
- * **`BottomSheet hasScrim={false}`, which is the only non-modal surface in
- * core.** With the scrim off the sheet opens with `show()` rather than
+ * **`BottomSheet hasScrim={false}` keeps this bottom-edge composer non-modal.**
+ * With the scrim off the sheet opens with `show()` rather than
  * `showModal()`, so it never enters the top layer, never makes the page inert
  * and never locks body scroll: the inbox behind it stays live. That matters
  * more here than anywhere else in this template, because writing a message is
@@ -1661,12 +1661,14 @@ const COMPOSER_TOOLS: {
  * actually said, copy an order number out of a thread. A modal composer
  * answers that with "close me first".
  *
- * The trade is position, and it is worth naming. A sheet rises from the bottom
- * edge, centred: its positioner is `inset-inline: 0` with
- * `justify-content: center`, and there is no anchor, side or width prop. So
- * this cannot be docked to the inline-end corner the way a `Dialog` can be.
- * `Dialog` takes a static `position` and would put the window in that corner —
- * but `Dialog` is always modal, so buying the corner costs the live inbox.
+ * The trade is bottom-edge geometry, and it is worth naming. A non-modal
+ * `Drawer` keeps page context live from an inline edge, but it is a full-height
+ * side panel; this composer intentionally rises from the bottom. A sheet's
+ * positioner is `inset-inline: 0` with `justify-content: center`, and there is
+ * no anchor, side or width prop. So this cannot be docked to the inline-end
+ * corner the way a `Dialog` can be. `Dialog` takes a static `position` and would
+ * put the window in that corner — but `Dialog` is always modal, so buying the
+ * corner costs the live inbox.
  * `ChatComposerDrawer` is a false friend: despite the name it is an in-flow
  * disclosure tray for a ChatComposer's attachments, with no positioning of its
  * own.

package/authoring/doctypes/base/type.ts

@@ -383,6 +383,12 @@ export interface ComponentPropDoc {
    *  ```
    */
   slotElements?: ComponentSlotElement[];
+  /** Lifecycle marker for a prop outside the stable compatibility promise
+   *  (spec:AST-017 FR21). Set `'experimental'` on a stable component's
+   *  optional `experimental` prop object, and say in `description` that its
+   *  contents may change or be removed in a patch release. Omit for stable
+   *  props. */
+  stability?: 'experimental';
 }
 
 /**

package/authoring/doctypes/component/component.doc.mjs

@@ -56,7 +56,7 @@ export const doc = {
       name: 'replaces',
       type: 'string',
       description:
-        "Integration components only: the exact `name` of the Core ComponentDoc this component takes over for unqualified lookup, so every app that loads the integration gets it from component detail, component lists, search, `swizzle <Name>`, and issue routing; `swizzle --list` keeps listing Core names. The Core original stays reachable with `--package @astryxdesign/core`. It takes effect only when the package's peer range starts at the release that applies it, `\"@astryxdesign/cli\": \">=0.6.7\"` or later; without such a range the component keeps its own name and `doctor integration components` warns. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.",
+        'Integration components only: the exact `name` of the Core ComponentDoc this component takes over for unqualified lookup, so every app that loads the integration gets it from component detail, component lists, search, `swizzle <Name>`, and issue routing; `swizzle --list` keeps listing Core names. The Core original stays reachable with `--package @astryxdesign/core`. It takes effect only when the package\'s peer range starts at the release that applies it, `"@astryxdesign/cli": ">=0.6.7"` or later; without such a range the component keeps its own name and `doctor integration components` warns. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.',
     },
     {
       name: 'keywords',
@@ -181,7 +181,7 @@ export const doc = {
       name: 'props',
       type: 'ComponentPropDoc[]',
       description:
-        'SingleComponentDoc variant (required there): all public props for the one primary component. Each prop is {name, type, description, default?, required?, slotElements?}. Skip styling props like xstyle/className/style. Also present on SubComponentDoc.',
+        'SingleComponentDoc variant (required there): all public props for the one primary component. Each prop is {name, type, description, default?, required?, slotElements?, stability?}. Skip styling props like xstyle/className/style. Also present on SubComponentDoc.',
     },
     {
       name: 'components',

package/clients/cli/lib/component-format.mjs

@@ -68,8 +68,12 @@ function formatPropsTable(props) {
   for (const p of props) {
     const def = p.default ? `\`${mdCell(p.default)}\`` : '-';
     const req = p.required ? ' **(required)**' : '';
+    // The text projection of the prop doc's `stability` field: an
+    // experimental prop is outside the stable compatibility promise.
+    const stability =
+      p.stability === 'experimental' ? ' **(experimental)**' : '';
     lines.push(
-      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
+      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req}${stability} |`,
     );
   }
   return lines.join('\n');