@astryxdesign/cli 0.4.2 → 0.4.3-canary.d9189c9

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

@@ -5,6 +5,11 @@
  * xds --json theme build <file>
  */
 export type ThemeBuildResponse = {
+    /**
+     * `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.
+     */
     type: "theme.build";
     data: {
         name: string;
@@ -18,6 +23,7 @@ export type ThemeBuildResponse = {
             variantsDts?: string;
         };
         warnings: string[];
+        notices: string[];
     };
 };
 /**

package/api/theme/theme.type.mjs

@@ -22,7 +22,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
  */
 
 /**

package/assets/docs/theme.doc.mjs

@@ -253,10 +253,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/templates/blocks/components/ComplexSelector/ComplexSelectorDeadlinePicker.doc.mjs

@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'ComplexSelector',
+  name: 'ComplexSelector — Deadline Picker',
+  displayName: 'Complex Selector — Deadline Picker',
+  description:
+    'A multi-step deadline field: pick a preset like Today or Next week, or switch to a custom date and time before applying. The popup stays open until the user commits, so the content owns the Apply action.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: [
+    'ComplexSelector',
+    'RadioList',
+    'DateInput',
+    'TimeInput',
+    'Button',
+  ],
+};

package/assets/templates/blocks/components/ComplexSelector/ComplexSelectorDeadlinePicker.tsx

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {ComplexSelector} from '@astryxdesign/core/ComplexSelector';
+import {RadioList, RadioListItem} from '@astryxdesign/core/RadioList';
+import {DateInput} from '@astryxdesign/core/DateInput';
+import {TimeInput} from '@astryxdesign/core/TimeInput';
+import {Button} from '@astryxdesign/core/Button';
+import {VStack} from '@astryxdesign/core/Layout';
+
+type ISODate =
+  `${number}${number}${number}${number}-${number}${number}-${number}${number}`;
+type ISOTime = string & {readonly __brand: 'ISOTimeString'};
+
+interface Deadline {
+  preset: 'today' | 'next-week' | 'custom';
+  date: ISODate;
+  time: ISOTime;
+}
+
+const presetLabels: Record<Deadline['preset'], string> = {
+  today: 'Today',
+  'next-week': 'Next week',
+  custom: 'Custom date',
+};
+
+function formatDeadline(value: Deadline) {
+  if (value.preset === 'custom') {
+    return `${value.date} at ${value.time}`;
+  }
+  return presetLabels[value.preset];
+}
+
+export default function ComplexSelectorDeadlinePicker() {
+  const [value, setValue] = useState<Deadline>({
+    preset: 'today',
+    date: '2026-04-06' as ISODate,
+    time: '17:00' as ISOTime,
+  });
+
+  return (
+    <ComplexSelector<Deadline>
+      label="Deadline"
+      description="Choose a preset or set a custom date and time."
+      value={value}
+      onChange={setValue}
+      triggerLabel={formatDeadline(value)}
+      style={{width: 320}}>
+      {(selectedValue, onChange, close) => {
+        const set = (patch: Partial<Deadline>) =>
+          onChange({...selectedValue, ...patch});
+
+        return (
+          <VStack gap={4} style={{width: 320}}>
+            <RadioList
+              label="When is it due?"
+              value={selectedValue.preset}
+              onChange={preset => set({preset: preset as Deadline['preset']})}>
+              <RadioListItem label="Today" value="today" />
+              <RadioListItem label="Next week" value="next-week" />
+              <RadioListItem label="Custom date" value="custom" />
+            </RadioList>
+
+            {selectedValue.preset === 'custom' && (
+              <VStack gap={3}>
+                <DateInput
+                  label="Date"
+                  value={selectedValue.date}
+                  onChange={date => date && set({date})}
+                />
+                <TimeInput
+                  label="Time"
+                  value={selectedValue.time}
+                  onChange={time => time && set({time})}
+                />
+              </VStack>
+            )}
+
+            <Button label="Apply" variant="primary" onClick={close} />
+          </VStack>
+        );
+      }}
+    </ComplexSelector>
+  );
+}

package/assets/templates/blocks/components/ComplexSelector/ComplexSelectorShowcase.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'ComplexSelector',
+  name: 'ComplexSelector',
+  displayName: 'Complex Selector',
+  description:
+    'A two-axis picker: choose a fruit and a ripeness level from one control. ComplexSelector owns the trigger, popover, and focus restore while the custom grid owns its keyboard semantics.',
+  isReady: true,
+  aspectRatio: 1,
+  isShowcase: true,
+  componentsUsed: ['ComplexSelector', 'Text'],
+};

package/assets/templates/blocks/components/ComplexSelector/ComplexSelectorShowcase.tsx

@@ -0,0 +1,199 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useEffect, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {ComplexSelector} from '@astryxdesign/core/ComplexSelector';
+import {Text} from '@astryxdesign/core/Text';
+import {useGridFocus} from '@astryxdesign/core/hooks';
+import {
+  borderVars,
+  colorVars,
+  radiusVars,
+  spacingVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+
+type Fruit = 'Apple' | 'Pear' | 'Peach' | 'Plum';
+type Ripeness = 'Crisp' | 'Tender' | 'Juicy' | 'Peak';
+
+interface FruitValue {
+  fruit: Fruit;
+  ripeness: Ripeness;
+}
+
+const fruits: Array<{id: Fruit; emoji: string; description: string}> = [
+  {id: 'Apple', emoji: '🍎', description: 'Bright and balanced'},
+  {id: 'Pear', emoji: '🍐', description: 'Soft floral sweetness'},
+  {id: 'Peach', emoji: '🍑', description: 'Round summer flavor'},
+  {id: 'Plum', emoji: '🟣', description: 'Jammy and tart'},
+];
+
+const ripenessLevels: Array<{
+  id: Ripeness;
+  shortLabel: string;
+  description: string;
+}> = [
+  {id: 'Crisp', shortLabel: 'C', description: 'Snappy bite'},
+  {id: 'Tender', shortLabel: 'T', description: 'Easy bite'},
+  {id: 'Juicy', shortLabel: 'J', description: 'Full juice'},
+  {id: 'Peak', shortLabel: 'P', description: 'Most intense'},
+];
+
+const GRID_CELL_SELECTOR = '[role="gridcell"]';
+
+const styles = stylex.create({
+  grid: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: spacingVars['--spacing-1'],
+    minWidth: 280,
+  },
+  row: {
+    display: 'grid',
+    gridTemplateColumns: 'minmax(150px, 1fr) repeat(4, 44px)',
+    alignItems: 'center',
+    columnGap: spacingVars['--spacing-1'],
+  },
+  rowHeader: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-2'],
+    textAlign: 'start',
+    minWidth: 0,
+  },
+  emoji: {
+    fontSize: 18,
+    flexShrink: 0,
+  },
+  fruitText: {
+    display: 'flex',
+    flexDirection: 'column',
+    minWidth: 0,
+  },
+  cell: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    height: 36,
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
+    borderColor: colorVars['--color-border'],
+    borderRadius: radiusVars['--radius-container'],
+    backgroundColor: colorVars['--color-background-card'],
+    color: colorVars['--color-text-secondary'],
+    fontFamily: 'inherit',
+    cursor: 'pointer',
+    ':hover': {
+      '@media (hover: hover)': {
+        borderColor: colorVars['--color-border-emphasized'],
+        color: colorVars['--color-text-primary'],
+      },
+    },
+  },
+  cellSelected: {
+    borderColor: colorVars['--color-accent'],
+    backgroundColor: colorVars['--color-accent'],
+    color: colorVars['--color-on-accent'],
+  },
+});
+
+function FruitRipenessGrid({
+  value,
+  onChange,
+}: {
+  value: FruitValue;
+  onChange: (value: FruitValue) => void;
+}) {
+  const {gridRef, handleKeyDown, handleFocus, focusCell} =
+    useGridFocus<HTMLDivElement>({
+      columns: ripenessLevels.length,
+      cellSelector: GRID_CELL_SELECTOR,
+      hasRovingTabIndex: true,
+    });
+
+  useEffect(() => {
+    const rowIndex = fruits.findIndex(f => f.id === value.fruit);
+    const columnIndex = ripenessLevels.findIndex(l => l.id === value.ripeness);
+    requestAnimationFrame(() => {
+      focusCell(
+        rowIndex >= 0 && columnIndex >= 0
+          ? rowIndex * ripenessLevels.length + columnIndex
+          : 0,
+      );
+    });
+  }, [focusCell, value]);
+
+  return (
+    <div
+      ref={gridRef}
+      role="grid"
+      aria-label="Fruit ripeness choices"
+      onKeyDown={handleKeyDown}
+      onFocus={handleFocus}
+      {...stylex.props(styles.grid)}>
+      {fruits.map(fruit => (
+        <div key={fruit.id} role="row" {...stylex.props(styles.row)}>
+          <div role="rowheader" {...stylex.props(styles.rowHeader)}>
+            <span aria-hidden="true" {...stylex.props(styles.emoji)}>
+              {fruit.emoji}
+            </span>
+            <span {...stylex.props(styles.fruitText)}>
+              <Text type="body">{fruit.id}</Text>
+              <Text type="supporting" color="secondary">
+                {fruit.description}
+              </Text>
+            </span>
+          </div>
+          {ripenessLevels.map(level => {
+            const isSelected =
+              value.fruit === fruit.id && value.ripeness === level.id;
+            return (
+              <button
+                key={`${fruit.id}-${level.id}`}
+                type="button"
+                role="gridcell"
+                aria-label={`${fruit.id}, ${level.id}: ${level.description}`}
+                aria-selected={isSelected || undefined}
+                tabIndex={isSelected ? 0 : -1}
+                onClick={() => onChange({fruit: fruit.id, ripeness: level.id})}
+                {...stylex.props(
+                  styles.cell,
+                  isSelected && styles.cellSelected,
+                )}>
+                {level.shortLabel}
+              </button>
+            );
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export default function ComplexSelectorShowcase() {
+  const [value, setValue] = useState<FruitValue>({
+    fruit: 'Apple',
+    ripeness: 'Juicy',
+  });
+
+  return (
+    <ComplexSelector<FruitValue>
+      label="Fruit blend"
+      description="Choose a fruit and ripeness in one control. Arrow keys move across the grid."
+      value={value}
+      onChange={setValue}
+      triggerLabel={`${value.fruit} · ${value.ripeness}`}
+      style={{width: 280}}>
+      {(selectedValue, onChange, close) => (
+        <FruitRipenessGrid
+          value={selectedValue}
+          onChange={nextValue => {
+            onChange(nextValue);
+            close();
+          }}
+        />
+      )}
+    </ComplexSelector>
+  );
+}

package/assets/templates/blocks/components/ComplexSelector/ComplexSelectorTreeSearch.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'ComplexSelector',
+  name: 'ComplexSelector — Tree Search',
+  displayName: 'Complex Selector — Tree Search',
+  description:
+    'A destination picker that combines a search field with a TreeList hierarchy. TreeList owns tree keyboard navigation; ComplexSelector owns the trigger, popover, and focus restore. Selecting a folder closes the popup.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['ComplexSelector', 'TextInput', 'TreeList'],
+};

package/assets/templates/blocks/components/ComplexSelector/ComplexSelectorTreeSearch.tsx

@@ -0,0 +1,188 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useMemo, useState} from 'react';
+import {ComplexSelector} from '@astryxdesign/core/ComplexSelector';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {TreeList, type TreeListItemData} from '@astryxdesign/core/TreeList';
+import {Text} from '@astryxdesign/core/Text';
+import {VStack} from '@astryxdesign/core/Layout';
+
+interface DestinationNode {
+  id: string;
+  label: string;
+  path: string;
+  children?: DestinationNode[];
+}
+
+interface Destination {
+  id: string;
+  label: string;
+  path: string;
+}
+
+const destinationTree: DestinationNode[] = [
+  {
+    id: 'workspace',
+    label: 'Workspace',
+    path: '/Workspace',
+    children: [
+      {
+        id: 'research',
+        label: 'Research',
+        path: '/Workspace/Research',
+        children: [
+          {
+            id: 'field-notes',
+            label: 'Field notes',
+            path: '/Workspace/Research/Field notes',
+          },
+          {
+            id: 'interviews',
+            label: 'Interviews',
+            path: '/Workspace/Research/Interviews',
+          },
+        ],
+      },
+      {
+        id: 'roadmap',
+        label: 'Roadmap',
+        path: '/Workspace/Roadmap',
+      },
+    ],
+  },
+  {
+    id: 'teams',
+    label: 'Teams',
+    path: '/Teams',
+    children: [
+      {
+        id: 'design-systems',
+        label: 'Design systems',
+        path: '/Teams/Design systems',
+        children: [
+          {
+            id: 'accessibility',
+            label: 'Accessibility',
+            path: '/Teams/Design systems/Accessibility',
+          },
+        ],
+      },
+    ],
+  },
+];
+
+function matches(node: DestinationNode, query: string): boolean {
+  if (node.label.toLowerCase().includes(query)) {
+    return true;
+  }
+  return (node.children ?? []).some(child => matches(child, query));
+}
+
+function filterTree(
+  nodes: DestinationNode[],
+  query: string,
+): DestinationNode[] {
+  if (!query) {
+    return nodes;
+  }
+  return nodes
+    .filter(node => matches(node, query))
+    .map(node => ({
+      ...node,
+      children: node.children ? filterTree(node.children, query) : undefined,
+    }));
+}
+
+function toItems(
+  nodes: DestinationNode[],
+  selectedId: string,
+  onSelect: (value: Destination) => void,
+): TreeListItemData[] {
+  return nodes.map(node => {
+    const hasChildren = (node.children ?? []).length > 0;
+    return {
+      id: node.id,
+      label: node.label,
+      isSelected: node.id === selectedId,
+      isExpanded: true,
+      onClick: hasChildren
+        ? undefined
+        : () => onSelect({id: node.id, label: node.label, path: node.path}),
+      children: hasChildren
+        ? toItems(node.children ?? [], selectedId, onSelect)
+        : undefined,
+    };
+  });
+}
+
+function DestinationSearch({
+  value,
+  onChange,
+  close,
+}: {
+  value: Destination;
+  onChange: (value: Destination) => void;
+  close: () => void;
+}) {
+  const [query, setQuery] = useState('');
+  const items = useMemo(
+    () =>
+      toItems(
+        filterTree(destinationTree, query.toLowerCase()),
+        value.id,
+        next => {
+          onChange(next);
+          close();
+        },
+      ),
+    [query, value.id, onChange, close],
+  );
+
+  return (
+    <VStack gap={3} style={{width: 360}}>
+      <TextInput
+        label="Search destinations"
+        isLabelHidden
+        value={query}
+        onChange={setQuery}
+        hasClear
+        placeholder="Search folders or teams"
+      />
+      {items.length > 0 ? (
+        <TreeList items={items} density="compact" />
+      ) : (
+        <Text type="supporting" color="secondary">
+          No matching destinations.
+        </Text>
+      )}
+    </VStack>
+  );
+}
+
+export default function ComplexSelectorTreeSearch() {
+  const [value, setValue] = useState<Destination>({
+    id: 'accessibility',
+    label: 'Accessibility',
+    path: '/Teams/Design systems/Accessibility',
+  });
+
+  return (
+    <ComplexSelector<Destination>
+      label="Destination"
+      description="Search and browse nested folders."
+      value={value}
+      onChange={setValue}
+      triggerLabel={value.path}
+      style={{width: 360}}>
+      {(selectedValue, onChange, close) => (
+        <DestinationSearch
+          value={selectedValue}
+          onChange={onChange}
+          close={close}
+        />
+      )}
+    </ComplexSelector>
+  );
+}

package/assets/templates/themes/neutral/neutralTheme.ts

@@ -528,15 +528,17 @@ export const neutralTheme = defineTheme({
     //          to a deep tinted bg + light text rather than locking the
     //          light-mode pastel.
     //
-    // The inner-header *-muted token is forced transparent so the outer
-    // tinted background shows through cleanly.
+    // The inner-header *-muted token carries the tinted background for every
+    // status, info included. A theme override that sets a plain CSS property
+    // instead lands in @layer astryx-theme, which StyleX's @layer priority4
+    // outranks, so `backgroundColor` here would silently do nothing and the
+    // info banner would paint no background at all.
     //
     // Status overrides reference --color-text-{hue} so text/icon colors
     // stay in sync with the palette anchors automatically.
     banner: {
       'status:info': {
-        backgroundColor: 'var(--color-background-blue)',
-        '--color-accent-muted': 'transparent',
+        '--color-accent-muted': 'var(--color-background-blue)',
         '--color-text-primary': 'var(--color-text-blue)',
         '--color-text-secondary': 'var(--color-text-blue)',
         '--color-accent': 'var(--color-text-blue)',

package/clients/cli/commands/build-theme.font-warning.test.mjs

@@ -75,13 +75,16 @@ describe('theme build font-loading warning', () => {
     expect(result.stdout).toContain('@font-face');
     expect(result.stdout).toContain('font-display: swap');
     expect(result.stdout).toContain('astryx docs typography');
-    // The one-line summaries follow the CLI's stream contract: warnings on
-    // stderr, like the override-validation warnings in the same build.
-    expect(result.stderr).toContain('Font "Space Grotesk"');
-    expect(result.stderr).toContain('Font "JetBrains Mono"');
+    // The one-line summaries follow the CLI's stream contract. These are
+    // NOTICES about a correct theme, not warnings, so they go to stdout with
+    // the rest of the build's progress — stderr stays for the defects an
+    // author has to fix.
+    expect(result.stdout).toContain('note: Font "Space Grotesk"');
+    expect(result.stdout).toContain('note: Font "JetBrains Mono"');
+    expect(result.stderr).not.toContain('Font "');
   });
 
-  it('keeps --json stdout one valid envelope: warnings inside, snippet suppressed', async () => {
+  it('keeps --json stdout one valid envelope: notices inside, snippet suppressed', async () => {
     const project = path.join(tmpDir, 'project');
     const themeFile = writeTheme(
       project,
@@ -100,7 +103,7 @@ describe('theme build font-loading warning', () => {
     // contract, not just substring presence.
     const envelope = JSON.parse(result.stdout);
     expect(envelope.type).toBe('theme.build');
-    expect(envelope.data.warnings).toEqual(
+    expect(envelope.data.notices).toEqual(
       expect.arrayContaining([expect.stringContaining('Font "Space Grotesk"')]),
     );
     expect(result.stdout).not.toContain('fonts.googleapis.com');