npm - @astryxdesign/cli - Versions diffs - 0.4.2 → 0.4.3-canary.00bed29 - Mend

@astryxdesign/cli 0.4.2 → 0.4.3-canary.00bed29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (69) hide show

package/api/theme/theme.type.mjs CHANGED Viewed

@@ -10,6 +10,7 @@
  * ------------------------------------------------------------------
  * xds --json theme build <file>             -> theme.build
  * xds --json theme build <file> --check     -> theme.build.check
+ * xds --json theme build <a> <b> …          -> theme.build.batch
  * xds --json theme list                     -> theme.list
  * xds --json theme add <slug>               -> theme.add
  * xds --json theme template                 -> theme.template
@@ -22,7 +23,10 @@
  * xds --json theme build <file>
  * @typedef {object} ThemeBuildResponse
  * @property {'theme.build'} type
- * @property {{name: string, tokenCount: number, componentCount: number, sizeKB: number, outputs: {css: string, js: string, dts: string, variantsDts?: string}, warnings: string[]}} data
+ * `warnings` are defects the theme author should fix. `notices` are advisories
+ * about a correct theme — most of them cannot be fixed in a theme file at all,
+ * so folding them into `warnings` makes a clean build look dirty.
+ * @property {{name: string, tokenCount: number, componentCount: number, sizeKB: number, outputs: {css: string, js: string, dts: string, variantsDts?: string}, warnings: string[], notices: string[]}} data
  */
 /**
@@ -32,6 +36,16 @@
  * @property {{name: string, upToDate: boolean, stale: Array<{path: string, reason: 'missing' | 'outdated'}>, checked: string[]}} data
  */
+/**
+ * xds --json theme build <a> <b> … — several themes in one invocation. Each
+ * result carries the file as it was passed and the receipt a single-file build
+ * would have returned (null when that theme produced no CSS). One file still
+ * returns the bare theme.build / theme.build.check envelope.
+ * @typedef {object} ThemeBuildBatchResponse
+ * @property {'theme.build.batch'} type
+ * @property {{count: number, results: Array<{file: string, receipt: ThemeBuildResponse | ThemeBuildCheckResponse | null}>}} data
+ */
 /**
  * A single theme entry as surfaced by `theme list`.
  * @typedef {object} ThemeListEntry

package/assets/cdn.template.html ADDED Viewed

@@ -0,0 +1,124 @@
+<!-- Copyright (c) Meta Platforms, Inc. and affiliates. -->
+<!doctype html>
+<!--
+  Astryx from a CDN — no build step, no bundler, no install.
+  Open this file in a browser (double-click works) or serve it from anywhere.
+  Everything is pinned to the Astryx version you had installed when this was
+  written; nothing here resolves to "latest", because an unpinned CDN URL
+  silently changes under you.
+  React 19 removed its UMD builds, so there is no global-script path any more:
+  an import map plus `type="module"` is how you load Astryx without a bundler.
+  Two things worth doing next:
+    - `astryx theme template` writes an annotated theme you can point this page
+      at. Its `color` scale generates a whole ramp from one seed colour and
+      guarantees >= 4.5:1 for the text it generates against its surface.
+    - `astryx component <Name>` prints any component's real prop surface.
+-->
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <!--
+      The theme names a font family; it never loads one. Without this link the
+      whole page silently falls back to the next family in the stack, which is
+      not the design you chose. `neutral` asks for Figtree — swap this for
+      whatever your theme names, or self-host with @font-face.
+    -->
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      rel="stylesheet"
+      href="https://fonts.googleapis.com/css2?family=Figtree:wght@400;500;600;700&display=swap" />
+    <!-- reset.css and astryx.css are the component styles; theme.css is the
+         theme. Note /dist/theme.css — the package root has no theme.css. -->
+    <link
+      rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/@astryxdesign/core@__ASTRYX_VERSION__/src/reset.css" />
+    <link
+      rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/@astryxdesign/core@__ASTRYX_VERSION__/dist/astryx.css" />
+    <link
+      rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/@astryxdesign/theme-neutral@__ASTRYX_VERSION__/dist/theme.css" />
+    <!--
+      react/jsx-runtime is not decoration: the published bundle imports it, and
+      leaving it out fails the page with "Failed to resolve module specifier".
+      ?external=react,react-dom makes esm.sh reuse the React above instead of
+      bundling its own. Two React copies means every hook throws
+      "Cannot read properties of null (reading 'useState')".
+      htm is optional — delete it and the `h` binding below if you would rather
+      call createElement directly. It costs ~1KB and buys JSX-shaped markup,
+      which is worth it as soon as the tree is more than a few levels deep.
+    -->
+    <script type="importmap">
+      {
+        "imports": {
+          "react": "https://esm.sh/react@19.2.0",
+          "react/jsx-runtime": "https://esm.sh/react@19.2.0/jsx-runtime",
+          "react-dom": "https://esm.sh/react-dom@19.2.0",
+          "react-dom/client": "https://esm.sh/react-dom@19.2.0/client",
+          "htm": "https://esm.sh/htm@3.1.1",
+          "@astryxdesign/core": "https://esm.sh/@astryxdesign/core@__ASTRYX_VERSION__?external=react,react-dom",
+          "@astryxdesign/theme-neutral": "https://esm.sh/@astryxdesign/theme-neutral@__ASTRYX_VERSION__?external=react,react-dom"
+        }
+      }
+    </script>
+    <!-- Nothing in the stylesheets sets a document font: the theme styles
+         prose elements and each component styles itself, and Button is
+         `font: inherit` by design. Without this line its label falls back to
+         the browser default (Times). -->
+    <style>
+      body {
+        font-family: var(--font-family-body);
+      }
+      /* Modules load over the network, so the page is empty for a moment.
+         Say so, rather than showing a blank screen that reads as broken. */
+      #root:empty::after {
+        content: 'Loading…';
+        display: block;
+        padding: 2rem;
+        color: var(--color-text-secondary);
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module">
+      import * as React from 'react';
+      import {createRoot} from 'react-dom/client';
+      import htm from 'htm';
+      import {Theme, Card, Stack, Heading, Text, Button} from '@astryxdesign/core';
+      import {neutralTheme} from '@astryxdesign/theme-neutral';
+      // Nothing is compiling this file, so there is no JSX. htm gives the same
+      // shape from a tagged template; `React.createElement` directly is the
+      // dependency-free alternative.
+      const h = htm.bind(React.createElement);
+      // Passing the theme OBJECT is what makes `mode` work: 'system' follows
+      // the OS, and light/dark switch at runtime. The `data-astryx-theme`
+      // attribute alone only scopes the stylesheet — it cannot switch modes.
+      createRoot(document.getElementById('root')).render(h`
+        <${Theme} theme=${neutralTheme} mode="system">
+          <${Stack} padding=${6} align="start">
+            <${Card} maxWidth=${480} elevation="low">
+              <${Stack} gap=${3} align="start">
+                <${Heading} level=${1}>Hello from a CDN</${Heading}>
+                <${Text}>No bundler, no install, no build step.</${Text}>
+                <!-- Button's text comes from \`label\`, which is required — it is
+                     the accessible name. Children are optional and only change
+                     the visible text; the accessible name stays \`label\`. -->
+                <${Button} variant="primary" label="Try me" />
+              </${Stack}>
+            </${Card}>
+          </${Stack}>
+        </${Theme}>
+      `);
+    </script>
+  </body>
+</html>

package/assets/docs/theme.doc.dense.mjs CHANGED Viewed

@@ -9,7 +9,7 @@ export const docsDense = {
     { section: 'Available Themes', title: 'Themes', content: [null, null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },
     { section: 'Theme Props', title: 'Props', content: [null] },
     { section: 'Creating a Custom Theme', title: 'Custom Theme', content: [{ type: 'prose', text: '`theme list` + `theme add <slug>` to start from a shipped theme, or defineTheme from scratch. only override tokens that differ.' }, null, { type: 'prose', text: '`astryx theme template` writes theme.template.ts: every defineTheme field + token families + override syntax, annotated, with the CLI command that prints each reference.' }] },
-    { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent hex via HCT.' }, null, null] },
+    { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent via HCT; accent = hex or [light, dark] tuple (per-scheme palettes). tokens overrides win token-by-token; --color-on-accent stays baked from color.accent, so prefer a tuple accent over overriding --color-accent.' }, null, null] },
     { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-focus-offset etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `astryx component <Name>` for details.' }, null, null, null, null] },
     { section: 'Custom Variants', title: 'Custom Variants', content: [{ type: 'prose', text: 'any unknown prop:value in components becomes a new variant. astryx theme build generates TS augmentations. works on any extensible prop axis (variant, status, etc).' }, null, null, null, null] },
     { section: 'Building Themes for Production', title: 'Build for Production', content: [{ type: 'prose', text: 'astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },

package/assets/docs/theme.doc.mjs CHANGED Viewed

@@ -162,7 +162,7 @@ function App() {
       content: [
         {
           type: 'prose',
-          text: 'defineTheme creates a theme from token overrides and optional scale configs. Scale configs generate tokens from parameters. Explicit token overrides always take precedence over scale-generated values.',
+          text: 'defineTheme creates a theme from token overrides and optional scale configs. Scale configs generate tokens from parameters. Explicit token overrides always take precedence over scale-generated values, token by token. One caveat for the accent: overriding --color-accent in tokens re-points the reference tokens (--color-accent-muted, --color-text-accent, --color-icon-accent) but NOT --color-on-accent, which stays baked from the color.accent seed. To give each scheme its own accent with a consistent derived palette, pass a [light, dark] tuple to color.accent instead of overriding the token.',
         },
         {
           type: 'code',
@@ -172,7 +172,8 @@ function App() {
 const myTheme = defineTheme({
   name: 'my-theme',
-  color: { accent: '#7B61FF', neutralStyle: 'cool' },
+  // accent: single hex, or [light, dark] tuple to seed each scheme separately
+  color: { accent: ['#7B61FF', '#9B85FF'], neutralStyle: 'cool' },
   typography: {
     scale: { base: 14, ratio: 1.2 },
     body: { family: 'Inter', fallbacks: '-apple-system, sans-serif' },
@@ -181,7 +182,7 @@ const myTheme = defineTheme({
   motion: { fast: 175, medium: 410, ratio: 0.75 },
   tokens: {
     // Explicit overrides take precedence over scale-generated values
-    '--color-accent': ['#7B61FF', '#9B85FF'],
+    '--color-background-body': ['#FFFFFF', '#0A0A0A'],
   },
   components: {
     button: { 'variant:primary': { color: 'white' } },
@@ -195,7 +196,7 @@ const myTheme = defineTheme({
             [
               'color',
               '--color-accent, --color-background-*, --color-text-*, --color-border, etc.',
-              'accent? (hex; omit for neutral-only), neutralStyle? (warm|cool|neutral), contrast? (standard|high)',
+              'accent? (hex or [light, dark] tuple; omit for neutral-only), neutralStyle? (warm|cool|neutral), contrast? (standard|high)',
             ],
             [
               'typography.scale',
@@ -253,10 +254,15 @@ const brandTheme = defineTheme({
             ['tokens', 'Base tokens are copied first, then child tokens override on top.'],
             ['components', 'Deep-merged: child component rules override matching keys from the base.'],
             ['icons', 'Shallow-merged: child icons override matching names from the base.'],
-            ['fonts', 'Base fonts included first, then child fonts appended.'],
+            ['indicators', 'Shallow-merged: child indicators override matching names from the base.'],
+            ['onDark, onLight', "Deep-merged per surface: the base's resolved surface first, then the child's overrides."],
             ['typography, motion, radius, color', 'Child config replaces base entirely (these are scale inputs, not additive).'],
           ],
         },
+        {
+          type: 'prose',
+          text: 'Inheritance is resolved when the theme is defined, so an extended theme is flat: `astryx theme build` emits one self-contained stylesheet holding everything the child inherited, and the base theme\'s CSS does not need to be loaded next to it. A base that is not a theme — most often an import that missed — is a build error rather than a theme that silently inherits nothing.',
+        },
       ],
     },
     {

package/assets/docs/theme.doc.zh.mjs CHANGED Viewed

@@ -9,7 +9,7 @@ export const docsZh = {
     { section: 'Available Themes', title: '可用主题', content: [null, null, { type: 'prose', text: '已发布主题：neutral（推荐起点）、butter、chocolate、gothic（仅暗色）、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版（运行时注入）。@astryxdesign/theme-{name}/built = 优化版（配合 theme.css）。' }] },
     { section: 'Theme Props', title: 'Theme 属性', content: [null] },
     { section: 'Creating a Custom Theme', title: '创建自定义主题', content: [{ type: 'prose', text: '用 `theme list` + `theme add <slug>` 从内置主题开始，或用 defineTheme 从零编写。只覆盖与默认值不同的令牌。' }, null, { type: 'prose', text: '`astryx theme template` 会写入 theme.template.ts：带注释的完整参考，涵盖每个 defineTheme 字段、令牌族和覆盖语法，并标明打印各自参考的 CLI 命令。' }] },
-    { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置（typography、radius、motion）+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },
+    { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置（color、typography、radius、motion）+ 显式令牌覆盖 + 组件覆盖。color 通过 HCT 从 accent 派生完整调色板；accent 接受单个十六进制值或 [light, dark] 元组（每个模式使用各自的种子色）。tokens 覆盖按令牌逐个生效；--color-on-accent 始终由 color.accent 计算得出，因此优先使用元组 accent 而不是覆盖 --color-accent。' }, null, null] },
     { section: 'Building Themes for Production', title: '生产构建', content: [{ type: 'prose', text: 'astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js（__built:true）+ .d.ts。' }, null, null, null, null] },
     { section: 'Runtime vs Built Themes', title: '运行时 vs 构建', content: [{ type: 'prose', text: '运行时：useInsertionEffect 在客户端注入样式。构建：静态 CSS 在首次渲染时就存在。SSR 应用请使用 /built + theme.css。' }, null, null, null] },
     { section: 'Light/Dark Mode', title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。Theme 上 mode='system'（默认）跟随系统偏好。" }, null, null] },

package/assets/templates/blocks/components/BottomSheet/BottomSheetHeights.doc.mjs ADDED Viewed

@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'BottomSheet',
+  name: 'Bottom Sheet — Height variants',
+  displayName: 'Bottom Sheet — Height variants',
+  description:
+    'Compares hug, capped, and tall starting heights for different amounts of content.',
+  isReady: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: [
+    'BottomSheet',
+    'Button',
+    'Divider',
+    'Heading',
+    'Stack',
+    'Text',
+  ],
+};

package/assets/templates/blocks/components/BottomSheet/BottomSheetHeights.tsx ADDED Viewed

@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+'use client';
+import {useState} from 'react';
+import {
+  BottomSheet,
+  type BottomSheetHeight,
+} from '@astryxdesign/core/BottomSheet';
+import {Button} from '@astryxdesign/core/Button';
+import {Divider} from '@astryxdesign/core/Divider';
+import {Heading} from '@astryxdesign/core/Heading';
+import {HStack, VStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+const descriptions: Record<BottomSheetHeight, string> = {
+  hug: 'Hug fits short, bounded content.',
+  capped: 'Capped starts at a comfortable mid-height for lists and filters.',
+  tall: 'Tall reserves most of the viewport for long or changing content.',
+};
+export default function BottomSheetHeights() {
+  const [height, setHeight] = useState<BottomSheetHeight | null>(null);
+  return (
+    <>
+      <HStack gap={2} wrap="wrap">
+        <Button label="Open hug" onClick={() => setHeight('hug')} />
+        <Button label="Open capped" onClick={() => setHeight('capped')} />
+        <Button label="Open tall" onClick={() => setHeight('tall')} />
+      </HStack>
+      <BottomSheet
+        isOpen={height != null}
+        onOpenChange={isOpen => !isOpen && setHeight(null)}
+        label={`${height ?? 'Hug'} height`}
+        height={height ?? 'hug'}>
+        <VStack gap={4} style={{padding: 'var(--spacing-4)'}}>
+          <Heading level={3}>{height ?? 'Hug'} height</Heading>
+          <Divider />
+          <Text type="body">{descriptions[height ?? 'hug']}</Text>
+          <Button label="Close" onClick={() => setHeight(null)} />
+        </VStack>
+      </BottomSheet>
+    </>
+  );
+}

package/assets/templates/blocks/components/BottomSheet/BottomSheetMobileKeyboard.doc.mjs ADDED Viewed

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'BottomSheet',
+  name: 'Bottom Sheet — Mobile keyboard',
+  displayName: 'Bottom Sheet — Mobile keyboard',
+  description:
+    'Uses a tall, scrollable form that keeps focused controls visible above the mobile keyboard.',
+  isReady: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: [
+    'BottomSheet',
+    'Button',
+    'Divider',
+    'Heading',
+    'Stack',
+    'Text',
+    'TextArea',
+    'TextInput',
+  ],
+};

package/assets/templates/blocks/components/BottomSheet/BottomSheetMobileKeyboard.tsx ADDED Viewed

@@ -0,0 +1,100 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+'use client';
+import {useState} from 'react';
+import {BottomSheet} from '@astryxdesign/core/BottomSheet';
+import {Button} from '@astryxdesign/core/Button';
+import {Divider} from '@astryxdesign/core/Divider';
+import {Heading} from '@astryxdesign/core/Heading';
+import {VStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+import {TextArea} from '@astryxdesign/core/TextArea';
+import {TextInput} from '@astryxdesign/core/TextInput';
+interface ProfileFormValues {
+  name: string;
+  email: string;
+  company: string;
+  role: string;
+  bio: string;
+  notes: string;
+}
+const initialValues: ProfileFormValues = {
+  name: '',
+  email: '',
+  company: '',
+  role: '',
+  bio: '',
+  notes: '',
+};
+export default function BottomSheetMobileKeyboard() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [values, setValues] = useState(initialValues);
+  const update =
+    (field: keyof ProfileFormValues) =>
+    (value: string): void =>
+      setValues(current => ({...current, [field]: value}));
+  return (
+    <>
+      <Button label="Edit profile" onClick={() => setIsOpen(true)} />
+      <BottomSheet
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="Edit profile"
+        height="tall">
+        <form
+          onSubmit={event => {
+            event.preventDefault();
+            setIsOpen(false);
+          }}>
+          <VStack gap={4} style={{padding: 'var(--spacing-4)'}}>
+            <Heading level={3}>Edit profile</Heading>
+            <Divider />
+            <Text type="supporting" color="secondary">
+              Focus fields throughout the form to see them remain visible above
+              the mobile keyboard.
+            </Text>
+            <TextInput
+              label="Name"
+              value={values.name}
+              onChange={update('name')}
+            />
+            <TextInput
+              label="Email"
+              type="email"
+              value={values.email}
+              onChange={update('email')}
+            />
+            <TextInput
+              label="Company"
+              value={values.company}
+              onChange={update('company')}
+            />
+            <TextInput
+              label="Role"
+              value={values.role}
+              onChange={update('role')}
+            />
+            <TextArea
+              label="Bio"
+              rows={5}
+              value={values.bio}
+              onChange={update('bio')}
+            />
+            <TextArea
+              label="Notes"
+              rows={5}
+              value={values.notes}
+              onChange={update('notes')}
+            />
+            <Button label="Save profile" type="submit" />
+          </VStack>
+        </form>
+      </BottomSheet>
+    </>
+  );
+}

package/assets/templates/blocks/components/BottomSheet/BottomSheetNoScrim.doc.mjs ADDED Viewed

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'BottomSheet',
+  name: 'Bottom Sheet — No scrim',
+  displayName: 'Bottom Sheet — No scrim',
+  description:
+    'Keeps the page visible and interactive behind a non-modal bottom sheet.',
+  isReady: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: [
+    'BottomSheet',
+    'Button',
+    'Divider',
+    'Heading',
+    'Section',
+    'Stack',
+    'Text',
+  ],
+};

package/assets/templates/blocks/components/BottomSheet/BottomSheetNoScrim.tsx ADDED Viewed

@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+'use client';
+import {useState} from 'react';
+import {BottomSheet} from '@astryxdesign/core/BottomSheet';
+import {Button} from '@astryxdesign/core/Button';
+import {Divider} from '@astryxdesign/core/Divider';
+import {Heading} from '@astryxdesign/core/Heading';
+import {Section} from '@astryxdesign/core/Section';
+import {VStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+export default function BottomSheetNoScrim() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [backgroundClicks, setBackgroundClicks] = useState(0);
+  return (
+    <Section padding={4}>
+      <VStack gap={3}>
+        <Heading level={3}>Nearby places</Heading>
+        <Text type="body">Background interactions: {backgroundClicks}</Text>
+        <Button
+          label="Interact with page"
+          variant="secondary"
+          onClick={() => setBackgroundClicks(count => count + 1)}
+        />
+        <Button label="Show place details" onClick={() => setIsOpen(true)} />
+      </VStack>
+      <BottomSheet
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="Place details"
+        height="hug"
+        hasScrim={false}>
+        <VStack gap={4} style={{padding: 'var(--spacing-4)'}}>
+          <Heading level={3}>Central Park</Heading>
+          <Divider />
+          <Text type="body">
+            The page remains visible and interactive behind this sheet.
+          </Text>
+          <Button label="Close details" onClick={() => setIsOpen(false)} />
+        </VStack>
+      </BottomSheet>
+    </Section>
+  );
+}

package/assets/templates/blocks/components/BottomSheet/BottomSheetShowcase.doc.mjs ADDED Viewed

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'BottomSheet',
+  name: 'Bottom Sheet',
+  displayName: 'Bottom Sheet',
+  description: 'A mobile filter surface that rises from the bottom edge.',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: [
+    'BottomSheet',
+    'Button',
+    'CheckboxInput',
+    'Divider',
+    'Heading',
+    'Section',
+    'Stack',
+  ],
+};

package/assets/templates/blocks/components/BottomSheet/BottomSheetShowcase.tsx ADDED Viewed

@@ -0,0 +1,51 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+'use client';
+import {useState} from 'react';
+import {BottomSheet} from '@astryxdesign/core/BottomSheet';
+import {Button} from '@astryxdesign/core/Button';
+import {CheckboxInput} from '@astryxdesign/core/CheckboxInput';
+import {Divider} from '@astryxdesign/core/Divider';
+import {Heading} from '@astryxdesign/core/Heading';
+import {Section} from '@astryxdesign/core/Section';
+import {VStack} from '@astryxdesign/core/Stack';
+export default function BottomSheetShowcase() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [inStock, setInStock] = useState(false);
+  const [onSale, setOnSale] = useState(false);
+  const [freeShipping, setFreeShipping] = useState(false);
+  return (
+    <>
+      <Button label="Open sheet" onClick={() => setIsOpen(true)} />
+      <BottomSheet isOpen={isOpen} onOpenChange={setIsOpen} label="Filters">
+        <Section padding={4}>
+          <VStack gap={4}>
+            <Heading level={3}>Filters</Heading>
+            <Divider />
+            <VStack gap={2}>
+              <CheckboxInput
+                label="In stock"
+                value={inStock}
+                onChange={setInStock}
+              />
+              <CheckboxInput
+                label="On sale"
+                value={onSale}
+                onChange={setOnSale}
+              />
+              <CheckboxInput
+                label="Free shipping"
+                value={freeShipping}
+                onChange={setFreeShipping}
+              />
+            </VStack>
+            <Button label="Apply" onClick={() => setIsOpen(false)} />
+          </VStack>
+        </Section>
+      </BottomSheet>
+    </>
+  );
+}

package/assets/templates/blocks/components/BottomSheet/BottomSheetSwitcherShowcase.doc.mjs ADDED Viewed

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'BottomSheetSwitcher',
+  name: 'Bottom Sheet Switcher',
+  displayName: 'Bottom Sheet Switcher',
+  description:
+    'A three-step flow that transitions between content-hugging sheets of different heights inside one shared dialog.',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: [
+    'BottomSheet',
+    'BottomSheetSwitcher',
+    'Button',
+    'CheckboxInput',
+    'Divider',
+    'Heading',
+    'RadioList',
+    'Section',
+    'Stack',
+    'Text',
+  ],
+};