@astryxdesign/cli 0.1.3-canary.6d57c8d → 0.1.3-canary.70cd22e

package/docs/browser-support.doc.mjs

@@ -0,0 +1,200 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'browser-support',
+  title: 'Browser Support',
+  category: 'guide',
+  description:
+    'What browsers Astryx targets, which modern platform features it depends on, and how to support older browsers for your own audience.',
+
+  sections: [
+    {
+      title: 'Overview',
+      content: [
+        {
+          type: 'prose',
+          text: 'Astryx is built on modern web platform features — the Popover API, CSS anchor positioning, and CSS `light-dark()`. These let components stay small, accessible, and dependency-free, but they also set a floor on which browsers render everything correctly.',
+        },
+        {
+          type: 'prose',
+          text: 'A design system does not own its traffic — the products built on it do. Their audiences range from evergreen-Chrome-only internal tools to public sites with meaningful older-Safari share. So Astryx does not declare a single hard browser floor the way an app would. Instead it defines tiers that describe what works at each level, and hands the final decision to you. Pick the tier that matches your audience.',
+        },
+      ],
+    },
+    {
+      title: 'Support Tiers',
+      content: [
+        {
+          type: 'prose',
+          text: 'Astryx officially supports Tier 1 and Tier 2. Tier 3 is best-effort: components will not crash, but positioning and theming may degrade.',
+        },
+        {
+          type: 'table',
+          headers: ['Tier', 'Baseline', 'Representative versions', 'What your users experience'],
+          rows: [
+            [
+              'Tier 1 — Full fidelity',
+              'Current Baseline (2026)',
+              'Chrome 125+, Edge 125+, Safari 26+, Firefox 147+',
+              'Everything works, including CSS anchor positioning. This is the reference target.',
+            ],
+            [
+              'Tier 2 — Functional',
+              'Baseline − 2 years (2024)',
+              'Chrome 114+, Edge 114+, Safari 17+, Firefox 125+',
+              'Components open, dismiss, and are fully usable. Only anchor positioning is missing, so layered surfaces (tooltips, menus, popovers) may not be positioned next to their trigger.',
+            ],
+            [
+              'Tier 3 — Below Tier 2',
+              'Older than Baseline − 2',
+              'Anything older',
+              'Best-effort. The only guarantee is "does not crash." `light-dark()` is unavailable, so theme colors may fall back to defaults.',
+            ],
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Which Features Set the Floor',
+      content: [
+        {
+          type: 'prose',
+          text: 'Only three modern features carry a browser requirement. Everything else Astryx uses (`:has()`, `color-mix()`, container queries, the `<dialog>` element) has been widely available since 2023 or earlier and needs no special handling.',
+        },
+        {
+          type: 'table',
+          headers: ['Feature', 'Role in Astryx', 'Widely available'],
+          rows: [
+            [
+              'CSS Anchor Positioning',
+              'Positions layered surfaces relative to their trigger (tooltips, menus, popovers, dropdowns).',
+              'Baseline 2026 — the tightest requirement.',
+            ],
+            [
+              'Popover API',
+              'Opens, stacks, and light-dismisses layered surfaces via the top layer.',
+              'Baseline 2025.',
+            ],
+            [
+              'CSS light-dark()',
+              'Compiles every theme color tuple into a single value that responds to color scheme. Underpins the whole theming system.',
+              'Widely available since mid-2024.',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'The gap that matters is between Tier 1 and Tier 2: the Popover API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly — they just are not positioned. This is the one feature most consumers will need to reason about.',
+        },
+      ],
+    },
+    {
+      title: 'Which Components Are Affected',
+      content: [
+        {
+          type: 'prose',
+          text: 'The browser requirement is concentrated in the layered-surface components — anything that renders content in an overlay positioned against a trigger:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Tooltip',
+            'HoverCard',
+            'Popover',
+            'ContextMenu',
+            'Selector and MultiSelector (dropdown surfaces)',
+            'Tokenizer (suggestion menu)',
+            'Carousel (anchored controls)',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'If your product does not use any of these, it has no anchor-positioning requirement at all — it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Layout, typography, forms, buttons, cards, tables, and navigation all work down to Tier 2 with no special handling.',
+        },
+      ],
+    },
+    {
+      title: 'What Astryx Guarantees',
+      content: [
+        {
+          type: 'list',
+          style: 'do',
+          items: [
+            'Components never throw on missing platform APIs. Where a browser lacks the Popover API, layers fall back to plain visibility instead of crashing.',
+            'Tier 1 and Tier 2 are officially supported and tested.',
+            'Non-layered components render correctly down to Tier 2.',
+          ],
+        },
+        {
+          type: 'list',
+          style: 'dont',
+          items: [
+            'Astryx does not guarantee correct layer positioning below Tier 1 (anchor positioning). Closing that gap for a Tier 2 audience is a consumer choice — see below.',
+            'Astryx does not ship a `light-dark()` fallback, so theme colors are not guaranteed below Tier 2.',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Supporting Older Browsers',
+      content: [
+        {
+          type: 'prose',
+          text: 'If your audience includes Tier 2 browsers and you need correct layer positioning, you have three options, cheapest first. All of them are decisions you make for your audience — Astryx does not impose one.',
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'Polyfill anchor positioning. Load a CSS anchor positioning polyfill conditionally behind an `@supports` check so it costs nothing on Tier 1. This is the lowest-effort way to get correct positioning; note that polyfills may not cover every position-fallback feature.',
+            'Provide a JS positioning fallback. Detect missing support with `CSS.supports("anchor-name", "--x")` and position layers with a measurement-based library (e.g. a floating-element positioner) when it returns false. More code, full control.',
+            'Accept degraded positioning. Document for your users that on Tier 2 browsers, layered surfaces open correctly but may not sit next to their trigger. Cheapest, and often fine for internal tools on evergreen browsers.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Feature-detect at runtime rather than sniffing user agents:',
+        },
+        {
+          type: 'code',
+          lang: 'js',
+          label: 'Feature detection',
+          code: `// Popover API (Tier 2 and up)
+const hasPopover = typeof HTMLElement !== 'undefined'
+  && typeof HTMLElement.prototype.showPopover === 'function';
+
+// CSS anchor positioning (Tier 1)
+const hasAnchorPositioning = CSS.supports('anchor-name', '--x');
+
+// CSS light-dark() (Tier 2 and up)
+const hasLightDark = CSS.supports('color', 'light-dark(#000, #fff)');`,
+        },
+      ],
+    },
+    {
+      title: 'How These Tiers Move Over Time',
+      content: [
+        {
+          type: 'prose',
+          text: 'The tiers are rolling, not frozen to specific versions. They track the Web Baseline year:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Tier 1 tracks the current Baseline year.',
+            'Tier 2 tracks Baseline minus two years.',
+            'Tier 3 is everything older, and remains best-effort.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the Popover API and `light-dark()` still are — so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
+        },
+      ],
+    },
+  ],
+};

package/docs/layout.doc.mjs

@@ -92,7 +92,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Card is a widget container, not a list-item wrapper. The fastest way to make an app look like a generic AI prototype is to wrap every record in a Card with a Badge. Dense data — anything the user scans, filters, or selects — belongs in rows: Table for columnar data, List/Item for single-line records, edge-to-edge with dividers and 32–40px row height.',
+          text: 'Card is a widget container, not a list-item wrapper. The fastest way to make an app look like a generic AI prototype is to wrap every record in a Card with a Badge. Dense data (anything the user scans, filters, or selects) belongs in rows: Table for columnar data, List/Item for single-line records, edge-to-edge with dividers and 32–40px row height.',
         },
         {
           type: 'list',
@@ -111,7 +111,7 @@ export const docs = {
             'Wrapping each list item in a Card (card soup)',
             'Stacking full-width Cards as a substitute for page structure',
             'Nesting Cards inside Cards',
-            'Using Badge as decoration — reserve it for counts and enumerated states; use StatusDot or Token for status and metadata',
+            'Using Badge as decoration: reserve it for counts and enumerated states; use StatusDot or Token for status and metadata',
           ],
         },
       ],

package/docs/theme.doc.mjs

@@ -124,14 +124,14 @@ function App() {
           type: 'table',
           headers: ['Prop', 'Type', 'Default', 'Description'],
           rows: [
-            ['theme', 'DefinedTheme', '—', 'Theme object (required)'],
+            ['theme', 'DefinedTheme', '-', 'Theme object (required)'],
             [
               'mode',
               "'system' | 'light' | 'dark'",
               "'system'",
               'Color mode. system follows OS preference.',
             ],
-            ['children', 'ReactNode', '—', 'App content'],
+            ['children', 'ReactNode', '-', 'App content'],
           ],
         },
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.3-canary.6d57c8d",
+  "version": "0.1.3-canary.70cd22e",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -75,9 +75,9 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.3-canary.6d57c8d",
-    "@astryxdesign/lab": "0.1.3-canary.6d57c8d",
-    "@astryxdesign/theme-neutral": "0.1.3-canary.6d57c8d",
+    "@astryxdesign/core": "0.1.3-canary.70cd22e",
+    "@astryxdesign/lab": "0.1.3-canary.70cd22e",
+    "@astryxdesign/theme-neutral": "0.1.3-canary.70cd22e",
     "gpt-tokenizer": "^2.0.0"
   },
   "peerDependenciesMeta": {
@@ -92,9 +92,9 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.3-canary.6d57c8d",
-    "@astryxdesign/lab": "0.1.3-canary.6d57c8d",
-    "@astryxdesign/theme-neutral": "0.1.3-canary.6d57c8d",
+    "@astryxdesign/core": "0.1.3-canary.70cd22e",
+    "@astryxdesign/lab": "0.1.3-canary.70cd22e",
+    "@astryxdesign/theme-neutral": "0.1.3-canary.70cd22e",
     "gpt-tokenizer": "^2.0.0"
   },
   "scripts": {

package/src/lib/component-format.mjs

@@ -7,9 +7,20 @@
 import {discoverComponents, findComponentReadme, resolveImportPath} from './component-discovery.mjs';
 import {loadDocs} from './component-loader.mjs';
 
-/** Derive the theme component key from a theming target (strips 'xds-' prefix). */
+/**
+ * Derive the `defineTheme` component-override key from a theming target.
+ *
+ * Override keys are the component's stable class name with the `astryx-`
+ * namespace prefix stripped — `generateThemeRules` re-adds the prefix when it
+ * builds the `.astryx-*` selector. So `astryx-base-table` → key `base-table`
+ * (→ `.astryx-base-table`), and `astryx-button` → key `button`.
+ *
+ * Keep the `astryx-` literal in sync with packages/core/src/naming.ts
+ * (NAMESPACE / classPrefix), the same way build-theme.mjs mirrors it.
+ * <!-- SYNC: packages/core/src/naming.ts (namespace prefix source of truth) -->
+ */
 function targetKey(target) {
-  return target.className.replace(/^xds-/, '');
+  return target.className.replace(/^astryx-/, '');
 }
 
 function dataAttrForName(name) {

package/src/lib/component-format.test.mjs

@@ -51,3 +51,45 @@ describe('formatFull sub-component rendering', () => {
     expect(out).not.toContain('astryx component XDSButtonGroup');
   });
 });
+
+describe('formatFull theming override keys', () => {
+  // Regression guard: the `defineTheme` component-override key is the stable
+  // class name with the `astryx-` prefix stripped — `generateThemeRules`
+  // re-adds the prefix to build the `.astryx-*` selector. targetKey() used to
+  // strip a dead `xds-` prefix (from before the astryx rename), so the printed
+  // example advertised `astryx-*` keys. Those double-prefix to
+  // `.astryx-astryx-*` at runtime and silently match nothing. See issue #3458.
+  it('prints override keys without the astryx- prefix (single-word component)', () => {
+    const docs = {
+      name: 'Button',
+      description: 'A button.',
+      theming: {targets: [{className: 'astryx-button', visualProps: ['variant']}]},
+    };
+    const out = formatFull(docs);
+
+    expect(out).toContain("'button': {");
+    // The full DOM class must not appear as an override key.
+    expect(out).not.toContain("'astryx-button': {");
+  });
+
+  it('prints override keys without the astryx- prefix (compound Table classes)', () => {
+    const docs = {
+      name: 'Table',
+      description: 'A table.',
+      theming: {
+        targets: [
+          {className: 'astryx-base-table'},
+          {className: 'astryx-table-cell'},
+        ],
+      },
+    };
+    const out = formatFull(docs);
+
+    // Correct keys: class name minus the astryx- prefix.
+    expect(out).toContain("'base-table': {");
+    expect(out).toContain("'table-cell': {");
+    // The verbatim DOM class names must not be advertised as override keys.
+    expect(out).not.toContain("'astryx-base-table': {");
+    expect(out).not.toContain("'astryx-table-cell': {");
+  });
+});

package/templates/blocks/components/MetadataListItem/MetadataListItemBasic.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   name: 'MetadataListItem — Basic',
   displayName: 'MetadataListItem — Basic',
   description:
-    'Labeled key–value rows inside a MetadataList. Values accept any content, from plain text to components like Badge.',
+    'Labeled key-value rows inside a MetadataList. Values accept any content, from plain text to components like Badge.',
   isReady: true,
   aspectRatio: 16 / 9,
   componentsUsed: ['MetadataList', 'MetadataListItem', 'Badge'],

package/templates/blocks/components/Table/TableRowExpansionTable.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useTableRowExpansion',
+  name: 'useTableRowExpansion — Tree Table',
+  displayName: 'useTableRowExpansion — Tree Table',
+  description:
+    'A tree table using useTableRowExpansion with inherited columns. Child rows use the same columns as parents, indented by depth. Click the chevron or right-click to expand/collapse.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Table'],
+};

package/templates/blocks/components/Table/TableRowExpansionTable.tsx

@@ -0,0 +1,99 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {
+  Table,
+  useTableRowExpansion,
+  useTableRowExpansionState,
+  proportional,
+  pixel,
+} from '@astryxdesign/core/Table';
+
+interface FileNode extends Record<string, unknown> {
+  id: string;
+  name: string;
+  type: 'folder' | 'file';
+  size: string;
+  children?: FileNode[];
+}
+
+const fileTree: FileNode[] = [
+  {
+    id: 'src',
+    name: 'src',
+    type: 'folder',
+    size: '—',
+    children: [
+      {
+        id: 'src/components',
+        name: 'components',
+        type: 'folder',
+        size: '—',
+        children: [
+          {
+            id: 'src/components/Button.tsx',
+            name: 'Button.tsx',
+            type: 'file',
+            size: '4.2 KB',
+            children: [],
+          },
+          {
+            id: 'src/components/Table.tsx',
+            name: 'Table.tsx',
+            type: 'file',
+            size: '12.8 KB',
+            children: [],
+          },
+        ],
+      },
+      {
+        id: 'src/index.ts',
+        name: 'index.ts',
+        type: 'file',
+        size: '0.4 KB',
+        children: [],
+      },
+    ],
+  },
+  {
+    id: 'package.json',
+    name: 'package.json',
+    type: 'file',
+    size: '1.8 KB',
+    children: [],
+  },
+];
+
+const columns = [
+  {key: 'name', header: 'Name', width: proportional(2)},
+  {key: 'type', header: 'Type', width: pixel(80)},
+  {key: 'size', header: 'Size', width: pixel(90)},
+];
+
+export default function TableRowExpansionTable() {
+  const [expandedKeys, setExpandedKeys] = useState<Set<string>>(
+    new Set(['src']),
+  );
+
+  const {data, expansionConfig} = useTableRowExpansionState<FileNode>({
+    baseData: fileTree,
+    getChildren: item => item.children ?? [],
+    getRowKey: item => item.id,
+    expandedKeys,
+    setExpandedKeys,
+  });
+
+  const expansion = useTableRowExpansion(expansionConfig);
+
+  return (
+    <Table
+      data={data}
+      columns={columns}
+      idKey="id"
+      hasHover
+      plugins={{expansion}}
+    />
+  );
+}

package/templates/blocks/components/ToggleButtonGroup/ToggleButtonGroupVertical.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   name: 'ToggleButtonGroup — Vertical',
   displayName: 'ToggleButtonGroup — Vertical',
   description:
-    'A vertically stacked ToggleButtonGroup using the vertical orientation, shown with both single-select and multi-select behavior — ideal for sidebar-style option lists and vertical toolbars.',
+    'A vertically stacked ToggleButtonGroup using the vertical orientation, shown with both single-select and multi-select behavior, ideal for sidebar-style option lists and vertical toolbars.',
   isReady: true,
   aspectRatio: 3 / 4,
   componentsUsed: ['ToggleButton', 'ToggleButtonGroup', 'Layout', 'Text'],

package/templates/themes/stone/stoneTheme.ts

@@ -94,13 +94,13 @@ export const stoneTheme = defineTheme({
     // Core semantic — all neutrals H=291
     // Stone 900 T=16 C=1.4, Stone 500 T=55 C=4, Stone 300 T=86 C=1.6, Stone 100 T=96 C=1
     '--color-accent': ['#25252a', '#f3f3f5'], // light: Stone Neutral T15
-    '--color-accent-muted': ['#25252a14', '#f3f3f5'], // light: Stone Neutral T15 · 8%
+    '--color-accent-muted': ['#25252a14', '#f3f3f520'], // light: Stone Neutral T15 · 8% / dark: T96 · 12.5%
     '--color-neutral': ['#25252a0f', '#f3f3f51a'], // light: Stone Neutral T15 · 6% / dark: T96 · 10%
     '--color-background-surface': ['#ffffff', '#1b1b1f'], // dark: Stone Neutral T10
     '--color-background-body': ['#f3f3f5', '#111015'], // dark: Stone Neutral T5
     '--color-overlay': ['#25252a80', '#28282a'], // light: Stone Neutral T15 · 50%
-    '--color-overlay-hover': ['#25252a0d', '#f3f3f5'], // light: Stone Neutral T15 · 5%
-    '--color-overlay-pressed': ['#25252a1a', '#f3f3f5'], // light: Stone Neutral T15 · 10%
+    '--color-overlay-hover': ['#25252a0d', '#f3f3f50d'], // light: Stone Neutral T15 · 5% / dark: T96 · 5%
+    '--color-overlay-pressed': ['#25252a1a', '#f3f3f51a'], // light: Stone Neutral T15 · 10% / dark: T96 · 10%
     '--color-background-muted': ['#e2e2e8', '#3b3b3f'], // light: Stone Neutral T90
 
     // Text — H=291