@astryxdesign/cli 0.4.3-canary.fd13115 → 0.4.4-canary.0f4d45f

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @xds/cli
 
+# 0.4.4
+
+#### New Components
+
+- Promote `BottomSheet` and `BottomSheetSwitcher` from the canary-only Lab package to Core. The stable package now includes their existing native-dialog, drag-detent, transition, and mobile-keyboard behavior, plus Core documentation and examples (#5080).
+
+#### New Features
+
+- `astryx template --cdn` writes a working no-build-step CDN starter page (#5068).
+  A CDN starter is a template, so it joins the template family beside `--skeleton` rather than claiming a top-level command. It is a flag and not the positional `astryx template cdn` because the positional resolves against everything `discoverAll()` finds, where a `cdn` id would shadow a discovered template. `cdn.template.html` loads Astryx from jsDelivr and esm.sh with no bundler, no install and no build step, with every CDN URL pinned to the Astryx version you have installed — an unpinned CDN URL resolves to whatever is latest and is cached hard, so a page written today breaks tomorrow without being edited. An existing file is never clobbered; `--overwrite` replaces it, and `--json` returns the receipt.
+
+  The annotations are the things that are load-bearing and silent when missing: `?external=react,react-dom` (without it esm.sh bundles a second React and every hook throws `Cannot read properties of null (reading 'useState')`), `react/jsx-runtime` in the import map (the published bundle imports it; omitting it fails the page with `Failed to resolve module specifier`), and a `font-family` on `body` (nothing in the stylesheets sets a document font, so `Button` — which is `font: inherit` — otherwise renders its label in the browser's default serif).
+
+  Three more lessons came out of building a real app on it. The page now `<link>`s the theme's webfont from Google Fonts, because the theme _names_ Figtree and never loads it, so every viewer silently got the fallback stack (#5015 again). It imports the theme OBJECT and wraps in `<Theme theme={neutralTheme} mode="system">`, so light and dark follow the OS — the `data-astryx-theme` attribute alone scopes the stylesheet but cannot switch modes. And `#root:empty` carries a "Loading…" state, because ESM-from-CDN has real latency and a blank page reads as broken. Markup is `htm`, with a comment saying it is optional and `createElement` is the dependency-free alternative.
+
+  A recipe that is only read is a recipe that is only assumed to work, so CI renders it: `.github/scripts/cdn-template-smoke-test.mjs` scaffolds the page with the real CLI and opens it in headless Chromium, failing on any console error, page error or failed request, and on a page that loads without rendering.
+- `astryx theme build` takes any number of theme files — `astryx theme build themes/*.ts` compiles them all in one process, so an app with several themes no longer hand-rolls a loop that re-enters the CLI once per theme. Outputs are byte-identical to the serial invocations; the run stops at the first failure and names the theme that failed. The CLI's Node floor (>=22.13) is now declared in `engines`, so a package manager can enforce it at install instead of the build failing later (#5121).
+- `defineTheme`: `color.accent` accepts a `[light, dark]` tuple (#2279)
+  `ColorScaleConfig.accent` now takes either a single hex or a `[light, dark]` tuple, matching `TokenValue`. With a tuple, `expandColorScale` derives the light half of every generated `light-dark()` pair from the light seed's palettes and the dark half from the dark seed's, so each scheme gets a consistent derived palette (muted, on-accent, neutrals) instead of the `tokens['--color-accent']` workaround that skips scale generation. Single-string configs are unchanged, token for token. Also documents the precedence between `color` and `tokens` for accent-derived values: `tokens` entries win token by token, the `var(--color-accent)` reference tokens follow a `--color-accent` override at runtime, and the baked `--color-on-accent` stays derived from the `color.accent` seed.
+
+#### Fixes
+
+- Bottom Sheet showcase block: the filter checkboxes are interactive again (#5157).
+  `CheckboxInput` is fully controlled — `value` is required and the input only moves when the owner updates it. The showcase passed a literal `value={false}` with no `onChange`, so the three filters ("In stock", "On sale", "Free shipping") rendered but could never be toggled: on the docs site the first thing a reader tries in a Bottom Sheet does nothing, and anyone copying the block inherits three dead controls. Each filter now has its own `useState` and `onChange`, matching the checkbox wiring already used in the Bottom Sheet Switcher showcase.
+- An integration whose manifest fails to load is no longer silent. A manifest that throws on import — the common case being one still calling a `create*` authoring factory, removed in 0.3.0 — contributes nothing, and the CLI treated that as if the package had never been configured: `astryx discover` answered `No integrations configured.` while `astryx.config.mjs` plainly configured one, and no command said a word. The only way to find out was to already suspect it and run `validate-integration` by name. Meta's internal `@nest/xds-meta` sat invisible to CLI discovery for a week that way, and the app team's conclusion was that the components did not exist (#5119).
+  The load error now counts as an integration issue, so the existing one-line stderr nudge fires on `component`, `template` and `upgrade`, and `discover` — the command whose whole job is listing integrations — nudges too, as does `search`. `discover` also stops reporting `configured: false` for a project that configured an integration that failed to load; the empty state now distinguishes "you configured nothing" from "what you configured contributed nothing", which is the distinction `meta.configured` was introduced to carry.
+
+  Nothing becomes fatal: the warning is best-effort, stderr-only, suppressed under `--json`, and never changes an exit code. Broken contributions are still skipped exactly as before.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @cixzhang
+- @imdreamrunner
+- @jiunshinn
+
+---
+
 # 0.4.3
 
 #### Fixes
@@ -8,6 +47,7 @@
   The `theme.build` receipt now separates the two: `warnings` are defects the author should fix, `notices` are advisories about a correct theme. The font advisory moves to `notices` and to stdout with the rest of the build's progress; stderr stays for defects. The template guard is back to `warnings` being empty, and no longer needs to know which fonts the template names.
 
   Programmatic callers reading `data.warnings` for font advisories should read `data.notices`; the message text is unchanged.
+
 - `extends` now reaches the CSS. A theme that extended another built a stylesheet holding only the declarations it stated itself: the base's tokens, component overrides and surface rules were all absent, and because each theme is `@scope`d to its own `data-astryx-theme` value, loading the base's stylesheet alongside could not fill the gap either. Every consumer of an inheritance chain silently got stock geometry, elevation and type with a new palette painted over it (#5067). Nothing warned; the loss only showed up by diffing two generated stylesheets token by token.
   The cause was `theme build` shadowing its own inputs. It writes `<name>.js` next to `<name>.ts`, and the loader resolved a plain `./<name>` specifier to that generated artifact before the source — so the second build of a family read the artifact, which carries no `components` and exports `<name>Theme` rather than whatever the source exports. A named import that missed became `extends: undefined`, and `defineTheme` treated an absent base as no base at all. The loader now resolves source extensions first, which is also the resolution the author's TypeScript sees, so the CSS a build emits matches the theme that type-checked.
 

package/README.md

@@ -415,6 +415,7 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `hook.detail.params`        | Just one hook's parameters table (HookParamDoc[]).                                                                                                                                                                                                  |
 | `theme.build`               | A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.                                                                   |
 | `theme.build.check`         | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing.                                                                                |
+| `theme.build.batch`         | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS.                                   |
 | `theme.list`                | Every bundled theme as a ThemeListEntry[]: each with slug, displayName, description, and a maintained flag.                                                                                                                                         |
 | `theme.add`                 | A scaffold receipt: resolved slug, displayName, maintained flag, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.                                                                                          |
 | `theme.template`            | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not — `exists` when a file was already there, which is a success.                                                       |

package/api/discover/_adapter.d.mts

@@ -6,9 +6,11 @@
  *
  * External packages come from configured integrations that declare a components
  * root; each becomes a scannable package keyed by its docsDir. `configured`
- * reports whether ANY integration declared a components root — it lets an empty
- * result distinguish "nothing configured" (`false`) from "configured but
- * nothing discovered" (`true`), which the list leaf surfaces as `meta`.
+ * reports whether the project configured ANY integration — including one whose
+ * manifest failed to load, which contributes nothing but is emphatically not
+ * "nothing configured". It lets an empty result distinguish "nothing
+ * configured" (`false`) from "configured but nothing discovered" (`true`),
+ * which the list leaf surfaces as `meta`.
  *
  * @returns {Promise<{packages: ScannedPackage[], configured: boolean}>}
  */

package/api/discover/_adapter.mjs

@@ -62,9 +62,11 @@ function validateDocs(docs) {
  *
  * External packages come from configured integrations that declare a components
  * root; each becomes a scannable package keyed by its docsDir. `configured`
- * reports whether ANY integration declared a components root — it lets an empty
- * result distinguish "nothing configured" (`false`) from "configured but
- * nothing discovered" (`true`), which the list leaf surfaces as `meta`.
+ * reports whether the project configured ANY integration — including one whose
+ * manifest failed to load, which contributes nothing but is emphatically not
+ * "nothing configured". It lets an empty result distinguish "nothing
+ * configured" (`false`) from "configured but nothing discovered" (`true`),
+ * which the list leaf surfaces as `meta`.
  *
  * @returns {Promise<{packages: ScannedPackage[], configured: boolean}>}
  */
@@ -84,7 +86,7 @@ export async function discoverPackages() {
       docsDir: integration.components,
     }));
   if (explicitPackages.length === 0) {
-    return {packages: [], configured: false};
+    return {packages: [], configured: loadedIntegrations.length > 0};
   }
 
   const packages = scanAllPackages(

package/api/theme/theme.type.d.mts

@@ -41,6 +41,22 @@ export type ThemeBuildCheckResponse = {
         checked: string[];
     };
 };
+/**
+ * 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.
+ */
+export type ThemeBuildBatchResponse = {
+    type: "theme.build.batch";
+    data: {
+        count: number;
+        results: Array<{
+            file: string;
+            receipt: ThemeBuildResponse | ThemeBuildCheckResponse | null;
+        }>;
+    };
+};
 /**
  * A single theme entry as surfaced by `theme list`.
  */

package/api/theme/theme.type.mjs

@@ -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
@@ -35,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/templates/blocks/components/BottomSheet/BottomSheetHeights.doc.mjs

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

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