@astryxdesign/cli 0.4.7 → 0.5.0-canary.009bcb3

package/assets/codemods/transforms/v0.5.0/banner-collapsible-content.mjs

@@ -0,0 +1,171 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate Banner's `defaultIsExpanded` onto `collapsible`
+ *
+ * Banner's collapse axis used to be a single knob, `defaultIsExpanded`, with
+ * the disclosure itself inferred from the presence of `children`. There was no
+ * way to have content without a toggle, and no controlled mode. The axis now
+ * lives on one `boolean | CollapsibleConfig` prop, per the boolean-or-config
+ * convention:
+ *
+ *   <Banner>{children}</Banner>                     → collapsible, starts closed
+ *   <Banner collapsible={{defaultIsOpen: true}}>    → collapsible, starts open
+ *   <Banner collapsible={{isOpen, onOpenChange}}>   → controlled
+ *   <Banner collapsible={false}>                    → always visible, no toggle
+ *
+ * The default is unchanged, so a Banner that never mentioned the old prop needs
+ * no rewrite at all — this transform is a prop rename and nothing more:
+ *
+ *   defaultIsExpanded            → collapsible={{defaultIsOpen: true}}
+ *   defaultIsExpanded={true}     → collapsible={{defaultIsOpen: true}}
+ *   defaultIsExpanded={false}    → (removed — it is the default)
+ *   defaultIsExpanded={expr}     → collapsible={{defaultIsOpen: expr}}
+ *
+ * Only elements named `Banner` are touched, and only when the file imports that
+ * name from `@astryxdesign/core`: `defaultIsExpanded` is also a ChatToolCalls
+ * prop, which this migration must leave alone.
+ *
+ * Scope: JSX attributes only. `defaultIsExpanded` inside a props object (a
+ * Storybook `args`, a spread built up in a variable) is left alone rather than
+ * rewritten on a guess about which component the object is for — removing the
+ * prop from the type makes those sites a type error, which is loud enough to
+ * find them.
+ */
+
+export const meta = {
+  title: "Rename Banner's `defaultIsExpanded` to the `collapsible` config",
+  description:
+    "Banner's collapse axis is now a single `collapsible?: boolean | " +
+    'CollapsibleConfig` prop. Rewrites `defaultIsExpanded` to the equivalent ' +
+    'config (`{defaultIsOpen: true}`), and drops ' +
+    '`defaultIsExpanded={false}`, which is the default. Banners that never ' +
+    'set the prop are untouched — the default is unchanged. Pass ' +
+    '`collapsible={false}` for content that is always visible.',
+  pr: '#5255',
+};
+
+const OLD_PROP = 'defaultIsExpanded';
+const NEW_PROP = 'collapsible';
+const COMPONENT = 'Banner';
+
+/**
+ * Does this file use the core `Banner`?
+ *
+ * `defaultIsExpanded` is a ChatToolCalls prop too, and a local component may
+ * well be called Banner, so an unqualified element-name match is not enough.
+ *
+ * @param {any} j
+ * @param {any} root
+ * @returns {boolean}
+ */
+function importsCoreBanner(j, root) {
+  let found = false;
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    const source = path.node.source?.value;
+    if (typeof source !== 'string' || !source.startsWith('@astryxdesign/core')) {
+      return;
+    }
+    for (const spec of path.node.specifiers ?? []) {
+      if (
+        (spec.type === 'ImportSpecifier' && spec.imported?.name === COMPONENT) ||
+        (spec.local?.name === COMPONENT &&
+          (spec.type === 'ImportDefaultSpecifier' ||
+            spec.type === 'ImportSpecifier'))
+      ) {
+        found = true;
+      }
+    }
+  });
+  return found;
+}
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  // Cheap bail-out: nothing to rename without the old prop.
+  if (!file.source.includes(OLD_PROP)) {
+    return undefined;
+  }
+
+  const j = api.jscodeshift;
+  const root = j(file.source);
+
+  if (!importsCoreBanner(j, root)) {
+    return undefined;
+  }
+
+  let hasChanges = false;
+
+  /** `collapsible={{defaultIsOpen: <expr>}}` */
+  const collapsibleWithDefault = (/** @type {any} */ expression) =>
+    j.jsxAttribute(
+      j.jsxIdentifier(NEW_PROP),
+      j.jsxExpressionContainer(
+        j.objectExpression([
+          j.objectProperty(j.identifier('defaultIsOpen'), expression),
+        ]),
+      ),
+    );
+
+  root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
+    const name = path.node.name;
+    if (name?.type !== 'JSXIdentifier' || name.name !== COMPONENT) {
+      return;
+    }
+
+    const attrs = path.node.attributes ?? [];
+    const oldIndex = attrs.findIndex(
+      (/** @type {any} */ a) =>
+        a.type === 'JSXAttribute' && a.name?.name === OLD_PROP,
+    );
+    if (oldIndex === -1) {
+      return;
+    }
+
+    // Already migrated by hand, or a spread that may carry either prop:
+    // in both cases a rewrite would be guesswork.
+    const hasNewProp = attrs.some(
+      (/** @type {any} */ a) =>
+        a.type === 'JSXAttribute' && a.name?.name === NEW_PROP,
+    );
+    const hasSpread = attrs.some(
+      (/** @type {any} */ a) => a.type === 'JSXSpreadAttribute',
+    );
+    if (hasNewProp || hasSpread) {
+      return;
+    }
+
+    const value = attrs[oldIndex].value;
+
+    if (value == null) {
+      // Bare `defaultIsExpanded` — starts open.
+      attrs[oldIndex] = collapsibleWithDefault(j.booleanLiteral(true));
+    } else if (value.type === 'JSXExpressionContainer') {
+      const expression = value.expression;
+      const isBooleanLiteral =
+        expression.type === 'BooleanLiteral' ||
+        (expression.type === 'Literal' && typeof expression.value === 'boolean');
+      if (isBooleanLiteral && expression.value === false) {
+        // Starting closed is the default now, so the prop simply goes.
+        attrs.splice(oldIndex, 1);
+      } else if (isBooleanLiteral) {
+        attrs[oldIndex] = collapsibleWithDefault(j.booleanLiteral(true));
+      } else {
+        // A dynamic default stays dynamic.
+        attrs[oldIndex] = collapsibleWithDefault(expression);
+      }
+    } else {
+      // `defaultIsExpanded="something"` is not valid for a boolean prop;
+      // leave it for a human rather than inventing a meaning.
+      return;
+    }
+
+    hasChanges = true;
+  });
+
+  return hasChanges ? root.toSource({quote: 'single'}) : undefined;
+}

package/assets/codemods/transforms/v0.5.0/index.mjs

@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file next transform manifest
+ *
+ * Staged codemods for the next release. The Version Packages PR promotes
+ * this file into the resolved version folder.
+ */
+
+import bannerCollapsibleContent, {
+  meta as bannerCollapsibleContentMeta,
+} from './banner-collapsible-content.mjs';
+
+export default [
+  {
+    name: 'banner-collapsible-content',
+    transform: bannerCollapsibleContent,
+    meta: bannerCollapsibleContentMeta,
+  },
+];

package/assets/docs/README.md

@@ -0,0 +1,50 @@
+# /packages/cli/assets/docs
+
+Reference topics for people **building with** Astryx. Not docs about building Astryx itself.
+
+One `{topic}.doc.mjs` per topic, plus optional `{topic}.doc.dense.mjs` / `{topic}.doc.zh.mjs` prose overlays. `foundation/discovery/docs-discovery.mjs` picks up any `{topic}.doc.mjs` here with no registration; `api/docs/_adapter.mjs` merges the overlays.
+
+What you add reaches `astryx docs <topic>`, `astryx search`, the `--json` API, the agent-docs block and the doc site — and ships on npm.
+
+## Who you are writing for
+
+Someone building a product with Astryx. Their questions:
+
+- what a component is for, and when to reach for something else
+- the props, their defaults, and what each does to what they see
+- how to compose it, and the pattern to copy
+- what it costs — bundle size, the a11y obligations they inherit
+- how to theme it, and which targets are stable
+
+**The test for anything you add: does a caller act on it?** They are not reviewing a PR, promoting a component out of lab, or attaching evidence to a checklist.
+
+## Tells that you are writing for us instead
+
+- second person aimed at the wrong reader — "reviewers should…", "before promoting a component…", "attach evidence for…"
+- **rubric, readiness, gate, audit, checklist, sign-off, promotion, evidence** as things the reader must produce
+- a table of things to verify rather than things to use
+- anything about lab → core, which is our lifecycle, not theirs
+- Storybook, Playwright, CI or the Simulator named as tools the reader runs
+
+One subtlety: a statement about the **system's behavior** is caller-facing even when it sounds like process. "A component's theme targets are stable once published" tells a caller what they can rely on; "reviewers must check that theme targets are stable" is ours. Same fact, different reader — **rewrite it rather than move it**.
+
+## Where the rest goes
+
+The material is usually good; the finding is placement, not quality. It goes in the [wiki](https://github.com/facebook/astryx/wiki) — **as a section on the page that already covers it, not a new page.** The wiki is at nearly 60 pages, several of them overlapping, because every stray section got its own.
+
+| what you wrote                                      | where it goes                                                                                                                                                                                |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| how a component is graded — checks, scoring         | [Component-Audit-Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric)                                                                                                     |
+| lab → core promotion, what a component must satisfy | [Component-Lifecycle](https://github.com/facebook/astryx/wiki/Component-Lifecycle)                                                                                                           |
+| how to build a new component                        | [Component-Authoring-Guide](https://github.com/facebook/astryx/wiki/Component-Authoring-Guide), [Creating-New-Components](https://github.com/facebook/astryx/wiki/Creating-New-Components)   |
+| what a component must be hardened against           | [Component-Hardening-Protocol](https://github.com/facebook/astryx/wiki/Component-Hardening-Protocol), [Hardening-Audit-Guide](https://github.com/facebook/astryx/wiki/Hardening-Audit-Guide) |
+| a11y requirements as checks we run                  | [Accessibility-Checklist](https://github.com/facebook/astryx/wiki/Accessibility-Checklist)                                                                                                   |
+| how the system is put together                      | [System-Architecture](https://github.com/facebook/astryx/wiki/System-Architecture), [Theming-Infrastructure](https://github.com/facebook/astryx/wiki/Theming-Infrastructure)                 |
+| API naming and shape decisions                      | [API-Conventions](https://github.com/facebook/astryx/wiki/API-Conventions), [API-Arbitration](https://github.com/facebook/astryx/wiki/API-Arbitration)                                       |
+| contributor workflow, PR process                    | [Contributing](https://github.com/facebook/astryx/wiki/Contributing), [Contributing-with-AI-Assistants](https://github.com/facebook/astryx/wiki/Contributing-with-AI-Assistants)             |
+| release mechanics                                   | [Release-Process](https://github.com/facebook/astryx/wiki/Release-Process)                                                                                                                   |
+| what a nightly agent role does                      | the Night-Watch pages, from [Night-Watch-Overview](https://github.com/facebook/astryx/wiki/Night-Watch-Overview)                                                                             |
+
+**Fits no row?** It is still not caller-facing. Default it to [Contributing](https://github.com/facebook/astryx/wiki/Contributing), or `CONTRIBUTING.md` when it is a step someone follows with the repo cloned. Never default it back to this directory.
+
+Worked example: a responsive-and-interaction readiness rubric is grading criteria → **Component-Audit-Rubric**, or **Component-Lifecycle** if it is a promotion gate.

package/assets/docs/cli-integrations.doc.mjs

@@ -115,7 +115,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "Point the integration file's `docs` field at a directory of reference docs and every `{topic}.doc.{ts,mjs,js}` under it becomes a topic the CLI serves — `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object stamped `type: 'generic'`, the same shape core's own topics use.",
+          text: "Point the integration file's `docs` field at a directory of reference docs and every `{topic}.doc.{ts,mjs,js}` under it becomes a topic the CLI serves: `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object stamped `type: 'generic'`, the same shape core's own topics use.",
         },
         {
           type: 'code',
@@ -124,7 +124,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "A topic can also speak about one that already exists. `replaces: 'x'` takes over topic x — core's, or another integration's — so a package whose consumers install it differently can serve its own Getting Started instead of the built-in one. Give the replacement a different `name` and the old name keeps resolving to it, so a link or an agent that learned the old topic still lands in the right place.",
+          text: "A topic can also speak about one that already exists. `replaces: 'x'` takes over topic x (core's, or another integration's) so a package whose consumers install it differently can serve its own Getting Started instead of the built-in one. Give the replacement a different `name` and the old name keeps resolving to it, so a link or an agent that learned the old topic still lands in the right place.",
         },
         {
           type: 'code',
@@ -133,14 +133,14 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "`extends: 'x'` merges onto a topic instead of owning it: a section whose title matches one in the base replaces that section, and a section the base does not have is appended. Reach for it to correct or add to a topic you do not want to fork — a fork of someone else's guide stops receiving their fixes the day you write it.",
+          text: "`extends: 'x'` merges onto a topic instead of owning it: a section whose title matches one in the base replaces that section, and a section the base does not have is appended. Reach for it to correct or add to a topic you do not want to fork: a fork of someone else's guide stops receiving their fixes the day you write it.",
         },
         {
           type: 'list',
           style: 'unordered',
           items: [
             'A topic name is a CLI argument and a docsite path, so it may hold only letters, digits, `_` and `-`.',
-            "A name that collides with an existing topic and declares neither `replaces` nor `extends` is an error, not a silent override — the CLI will not guess which one you meant.",
+            "A name that collides with an existing topic and declares neither `replaces` nor `extends` is an error, not a silent override; the CLI will not guess which one you meant.",
             '`replaces` and `extends` are exclusive: a topic either takes another\'s place or merges onto it.',
             'Two integrations replacing one topic is a warning, and the one configured later in `astryx.config` wins.',
           ],

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

@@ -10,7 +10,7 @@ export const docsDense = {
     { 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 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: '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 theme targets [Name]` to enumerate every themeable key (--json for lint), `astryx component <Name>` for one component.' }, 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] },
     { section: 'Runtime vs Built Themes', title: 'Runtime vs Built', content: [{ type: 'prose', text: 'runtime: useInsertionEffect injects styles client-side. built: static CSS on first paint. USE /built + theme.css FOR SSR.' }, null, null, null] },

package/assets/docs/theme.doc.mjs

@@ -300,7 +300,7 @@ const brandTheme = defineTheme({
         },
         {
           type: 'prose',
-          text: 'Run `astryx component <Name>` to see a component\'s theming targets, public CSS variables, and which standard CSS properties are supported.',
+          text: 'Run `astryx theme targets` for every themeable key in the system (`astryx theme targets <Name>` to scope it, `--json` to lint a theme against it), and `astryx component <Name>` for one component\'s theming targets, public CSS variables, and which standard CSS properties are supported.',
         },
         {
           type: 'list',

package/assets/docs/typography.doc.mjs

@@ -51,7 +51,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Astryx never loads font files. defineTheme and the built CSS only set font-family — naming a webfont (Fraunces, JetBrains Mono, …) makes every browser look for it, and quietly fall back when the app has not loaded it. `astryx theme build` warns when a theme names families that are neither CSS generics nor common system fonts and prints the snippet to add; loading the font is always the app\'s job.',
+          text: 'Astryx never loads font files. defineTheme and the built CSS only set font-family: naming a webfont (Fraunces, JetBrains Mono, and so on) makes every browser look for it, and quietly fall back when the app has not loaded it. `astryx theme build` warns when a theme names families that are neither CSS generics nor common system fonts and prints the snippet to add; loading the font is always the app\'s job.',
         },
         {
           type: 'code',
@@ -77,7 +77,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "Always pair a webfont with a real fallback stack — metric-similar system fonts plus a generic — so text stays readable before the font loads and wherever it never does: defineTheme({typography: {heading: {family: 'Fraunces', fallbacks: 'Georgia, serif'}}}).",
+          text: "Always pair a webfont with a real fallback stack (metric-similar system fonts plus a generic) so text stays readable before the font loads and wherever it never does: defineTheme({typography: {heading: {family: 'Fraunces', fallbacks: 'Georgia, serif'}}}).",
         },
       ],
     },

package/assets/templates/blocks/components/Banner/BannerCollapsibleContent.doc.mjs

@@ -6,7 +6,7 @@ export const doc = {
   exampleFor: 'Banner',
   name: 'Banner — Collapsible',
   displayName: 'Banner — Collapsible',
-  description: 'Combine an action button, dismiss control, and expandable detail area in one banner. Use for complex notifications like config changes or deployment summaries.',
+  description: 'Combine an action button, dismiss control, and a collapsible detail area in one banner. Children sit behind the toggle by default; `collapsible={{defaultIsOpen: true}}` starts it open, and `collapsible={false}` drops the toggle entirely. Use for complex notifications like config changes or deployment summaries.',
   isReady: true,
   aspectRatio: 16 / 9,
   componentsUsed: ['Banner', 'Button', 'List', 'Layout', 'Text'],

package/assets/templates/blocks/components/Banner/BannerCollapsibleContent.tsx

@@ -16,7 +16,7 @@ export default function BannerCollapsibleContent() {
       description="Review the changes before they take effect."
       endContent={<Button label="Review" variant="secondary" size="sm" />}
       isDismissable
-      defaultIsExpanded>
+      collapsible={{defaultIsOpen: true}}>
       <Stack direction="vertical" gap={2}>
         <Text type="supporting" color="secondary">
           Changed settings:

package/assets/templates/blocks/components/DateInput/DateInputClearable.tsx

@@ -16,7 +16,11 @@ export default function DateInputClearable() {
   );
 
   return (
-    <Stack direction="vertical" gap={4} width="100%" style={{maxWidth: 400}}>
+    <Stack
+      direction="vertical"
+      gap={4}
+      width="100%"
+      style={{minWidth: 240, maxWidth: 400}}>
       <Text type="supporting" color="secondary">
         {value ? `Selected: ${value}` : 'No date selected'}
       </Text>

package/assets/templates/blocks/components/DateInput/DateInputDateRange.tsx

@@ -27,7 +27,11 @@ export default function DateInputDateRange() {
   const [value, setValue] = useState<DateString | undefined>(undefined);
 
   return (
-    <Stack direction="vertical" gap={4} width="100%" style={{maxWidth: 400}}>
+    <Stack
+      direction="vertical"
+      gap={4}
+      width="100%"
+      style={{minWidth: 240, maxWidth: 400}}>
       <Text type="supporting" color="secondary">
         {value ? `Booked: ${value}` : 'Pick a date in the available range'}
       </Text>
@@ -37,6 +41,7 @@ export default function DateInputDateRange() {
         max={max}
         description={description}
         placeholder="Select a booking date"
+        nativePicker="never"
         value={value}
         onChange={setValue}
       />

package/assets/templates/blocks/components/DateInput/DateInputFormats.tsx

@@ -16,7 +16,11 @@ export default function DateInputFormats() {
   );
 
   return (
-    <Stack direction="vertical" gap={4} width="100%" style={{maxWidth: 400}}>
+    <Stack
+      direction="vertical"
+      gap={4}
+      width="100%"
+      style={{minWidth: 240, maxWidth: 400}}>
       <Text type="supporting" color="secondary">
         The same committed date, displayed with different formats.
       </Text>

package/assets/templates/blocks/components/DateInput/DateInputShowcase.tsx

@@ -13,7 +13,10 @@ export default function DateInputShowcase() {
   const [date, setDate] = useState<DateString | undefined>(undefined);
 
   return (
-    <Stack direction="vertical" width="100%" style={{maxWidth: 400}}>
+    <Stack
+      direction="vertical"
+      width="100%"
+      style={{minWidth: 240, maxWidth: 400}}>
       <DateInput
         label="Start date"
         placeholder="Select a date"

package/assets/templates/blocks/components/DateInput/DateInputWithDescription.tsx

@@ -14,7 +14,11 @@ export default function DateInputWithDescription() {
   const [value, setValue] = useState<DateString | undefined>(undefined);
 
   return (
-    <Stack direction="vertical" gap={4} width="100%" style={{maxWidth: 400}}>
+    <Stack
+      direction="vertical"
+      gap={4}
+      width="100%"
+      style={{minWidth: 240, maxWidth: 400}}>
       <Text type="supporting" color="secondary">
         Helper text explains what the field expects
       </Text>

package/assets/templates/blocks/components/DateInput/DateInputWithValidation.tsx

@@ -21,7 +21,11 @@ export default function DateInputWithValidation() {
   );
 
   return (
-    <Stack direction="vertical" gap={4} width="100%" style={{maxWidth: 400}}>
+    <Stack
+      direction="vertical"
+      gap={4}
+      width="100%"
+      style={{minWidth: 240, maxWidth: 400}}>
       <DateInput
         label="Event date"
         value={errorVal}

package/assets/templates/blocks/components/Dialog/DialogAdaptivePresentation.doc.mjs

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Dialog',
+  alsoExampleFor: ['BottomSheet', 'useMediaQuery'],
+  name: 'Dialog — Adaptive presentation',
+  displayName: 'Dialog — Adaptive presentation',
+  description:
+    'Opt-in recipe for an AdaptiveDialog wrapper: Dialog remains the default everywhere, while touchPresentation="bottom-sheet" switches only at lg and below when pointer is coarse and hover is unavailable. Includes a deterministic presentation override for tests/unusual environments and notes that BottomSheet purpose controls swipe and scrim dismissal. Usage examples: touchPresentation="dialog" keeps Dialog, "fullscreen" chooses fullscreen Dialog, and "bottom-sheet" chooses BottomSheet only for the touch-oriented range. Keep presentation as the deterministic override. Do not use this by default for AlertDialog or destructive confirmations.',
+  isReady: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: [
+    'Dialog',
+    'DialogHeader',
+    'BottomSheet',
+    'Layout',
+    'Button',
+    'Text',
+    'TextInput',
+    'TextArea',
+    'useMediaQuery',
+  ],
+};

package/assets/templates/blocks/components/Dialog/DialogAdaptivePresentation.tsx

@@ -0,0 +1,167 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState, type ReactNode} from 'react';
+import {BottomSheet} from '@astryxdesign/core/BottomSheet';
+import {Button} from '@astryxdesign/core/Button';
+import {
+  Dialog,
+  DialogHeader,
+  type DialogPurpose,
+} from '@astryxdesign/core/Dialog';
+import {Heading} from '@astryxdesign/core/Heading';
+import {
+  HStack,
+  Layout,
+  LayoutContent,
+  LayoutFooter,
+  VStack,
+} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {TextArea} from '@astryxdesign/core/TextArea';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {useMediaQuery} from '@astryxdesign/core/hooks';
+
+const TOUCH_ORIENTED_LG_QUERY =
+  '(max-width: 1024px) and (pointer: coarse) and (hover: none)';
+
+type AdaptivePresentation = 'dialog' | 'fullscreen' | 'bottom-sheet';
+
+type AdaptiveDialogProps = {
+  isOpen: boolean;
+  onOpenChange: (isOpen: boolean) => void;
+  title: string;
+  children: ReactNode;
+  footer?: ReactNode;
+  purpose?: DialogPurpose;
+  width?: number | string;
+  maxHeight?: number | string;
+  touchPresentation?: AdaptivePresentation;
+  presentation?: AdaptivePresentation;
+  bottomSheetHeight?: 'hug' | 'capped' | 'tall' | number | string;
+};
+
+function AdaptiveDialog({
+  isOpen,
+  onOpenChange,
+  title,
+  children,
+  footer,
+  purpose = 'info',
+  width = 480,
+  maxHeight = '75dvh',
+  touchPresentation = 'dialog',
+  presentation,
+  bottomSheetHeight = 'capped',
+}: AdaptiveDialogProps) {
+  const isTouchOrientedLargeOrBelow = useMediaQuery(TOUCH_ORIENTED_LG_QUERY);
+  const resolvedPresentation =
+    presentation ??
+    (isTouchOrientedLargeOrBelow ? touchPresentation : 'dialog');
+
+  if (resolvedPresentation === 'bottom-sheet') {
+    return (
+      <BottomSheet
+        isOpen={isOpen}
+        onOpenChange={onOpenChange}
+        label={title}
+        purpose={purpose}
+        height={bottomSheetHeight}>
+        <VStack gap={4} style={{padding: 'var(--spacing-4)'}}>
+          <Heading level={3}>{title}</Heading>
+          {children}
+          {footer}
+        </VStack>
+      </BottomSheet>
+    );
+  }
+
+  const dialogContent = (
+    <Layout
+      header={<DialogHeader title={title} onOpenChange={onOpenChange} />}
+      content={<LayoutContent>{children}</LayoutContent>}
+      footer={footer ? <LayoutFooter>{footer}</LayoutFooter> : undefined}
+    />
+  );
+
+  return (
+    <Dialog
+      isOpen={isOpen}
+      onOpenChange={onOpenChange}
+      purpose={purpose}
+      width={width}
+      maxHeight={maxHeight}
+      variant={
+        resolvedPresentation === 'fullscreen' ? 'fullscreen' : 'standard'
+      }>
+      {dialogContent}
+    </Dialog>
+  );
+}
+
+export default function DialogAdaptivePresentation() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [name, setName] = useState('Ruby Cheung');
+  const [email, setEmail] = useState('ruby@example.com');
+  const [notes, setNotes] = useState('');
+
+  return (
+    <>
+      <Button label="Edit profile" onClick={() => setIsOpen(true)} />
+      {/*
+        touchPresentation examples:
+        - "dialog" keeps Dialog even in touch-oriented <=lg contexts.
+        - "fullscreen" uses fullscreen Dialog there.
+        - "bottom-sheet" uses BottomSheet there.
+        presentation="dialog" | "fullscreen" | "bottom-sheet" overrides
+        the media query for tests and unusual environments.
+      */}
+      <AdaptiveDialog
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        title="Edit profile"
+        purpose="form"
+        touchPresentation="bottom-sheet"
+        bottomSheetHeight="tall"
+        footer={
+          <HStack gap={2} hAlign="end" wrap="wrap">
+            <Button
+              label="Cancel"
+              variant="secondary"
+              onClick={() => setIsOpen(false)}
+            />
+            <Button
+              label="Save profile"
+              variant="primary"
+              onClick={() => setIsOpen(false)}
+            />
+          </HStack>
+        }>
+        <VStack gap={4}>
+          <Text type="supporting" color="secondary">
+            Dialog remains the default presentation. This example explicitly
+            opts into a Bottom Sheet only at lg and below when the device has a
+            coarse pointer and no hover. Pass the presentation prop to make
+            tests or unusual environments deterministic.
+          </Text>
+          <Text type="supporting" color="secondary">
+            In Bottom Sheet presentation, purpose="form" blocks scrim clicks and
+            swipe dismissal while preserving Escape. Use this opt-in only when
+            that contract is acceptable; keep AlertDialog/destructive
+            confirmations on Dialog unless a product deliberately chooses
+            otherwise.
+          </Text>
+          <TextInput label="Name" value={name} onChange={setName} />
+          <TextInput
+            label="Email"
+            type="email"
+            value={email}
+            onChange={setEmail}
+          />
+          <TextArea label="Notes" rows={6} value={notes} onChange={setNotes} />
+        </VStack>
+      </AdaptiveDialog>
+    </>
+  );
+}

package/assets/templates/blocks/components/Dialog/DialogScrollingContent.tsx

@@ -69,7 +69,7 @@ function Content({onClose}: {onClose: () => void}) {
 
 // Remove isInline for production — dialogs should be modal.
 export default function DialogScrollingContent() {
-  const dialog = useImperativeDialog({maxHeight: '50vh'});
+  const dialog = useImperativeDialog({maxHeight: '50dvh'});
 
   return (
     <>