@astryxdesign/cli 0.4.4 → 0.4.5-canary.1fdecb1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @xds/cli
 
+# 0.4.5
+
+---
+
 # 0.4.4
 
 #### New Components
@@ -16,6 +20,7 @@
   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.

package/assets/codemods/transforms/v0.1.0/__tests__/drop-xds-prefix-imports.test.mjs

@@ -212,4 +212,95 @@ describe('drop-xds-prefix-imports', () => {
     const output = await applyTransform(input);
     expect(output).toBe(input);
   });
+
+  it('aliases a component wrapper collision in place (XDS -> Astryx), leaving the local fn untouched', async () => {
+    const input = [
+      `import {XDSLinkProvider} from '@xds/core/Link';`,
+      `export default function LinkProvider({children}) {`,
+      `  return <XDSLinkProvider component={NextLink}>{children}</XDSLinkProvider>;`,
+      `}`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    // Import aliased in place, local wrapper + its name untouched.
+    expect(output).toContain('import {LinkProvider as AstryxLinkProvider}');
+    expect(output).toContain('function LinkProvider({children})');
+    // JSX rewritten to the alias -> no self-recursion.
+    expect(output).toContain('<AstryxLinkProvider component={NextLink}>');
+    expect(output).not.toContain('XDSLinkProvider');
+    // No duplicate bare LinkProvider import.
+    expect(output).not.toMatch(/import \{LinkProvider\}/);
+  });
+
+  it('aliases a hook collision as use<Astryx>Name (not <Astryx>use)', async () => {
+    const input = [
+      `import {useXDSToast} from '@xds/core';`,
+      `function useToast() {`,
+      `  return useXDSToast();`,
+      `}`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    expect(output).toContain('import {useToast as useAstryxToast}');
+    expect(output).toContain('function useToast()');
+    expect(output).toContain('return useAstryxToast();');
+    expect(output).not.toContain('useXDSToast');
+    // Must not produce the malformed `Astryxuse...` form.
+    expect(output).not.toContain('AstryxuseToast');
+  });
+
+  it('aliases on collision with a local default import binding', async () => {
+    const input = [
+      `import Link from 'next/link';`,
+      `import {XDSLink} from '@xds/core';`,
+      `export const a = <XDSLink href="/" />;`,
+      `export const b = <Link href="/" />;`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    expect(output).toContain('import {Link as AstryxLink}');
+    expect(output).toContain(`import Link from 'next/link';`);
+    expect(output).toContain('<AstryxLink href="/" />');
+    expect(output).toContain('<Link href="/" />');
+    expect(output).not.toContain('XDSLink');
+  });
+
+  it('aliases on collision with a local type alias', async () => {
+    const input = [
+      `import type {XDSTab} from '@xds/core';`,
+      `type Tab = {id: string};`,
+      `const active: XDSTab = null as any;`,
+      `const local: Tab = {id: '1'};`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    expect(output).toContain('Tab as AstryxTab');
+    expect(output).toContain('type Tab = {id: string};');
+    expect(output).toContain('const active: AstryxTab');
+    expect(output).toContain('const local: Tab');
+    expect(output).not.toContain('XDSTab');
+  });
+
+  it('aliases on collision with a local interface', async () => {
+    const input = [
+      `import type {XDSTheme} from '@xds/core';`,
+      `interface Theme {}`,
+      `const t: XDSTheme = null as any;`,
+      `const local: Theme = {};`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    expect(output).toContain('Theme as AstryxTheme');
+    expect(output).toContain('interface Theme {}');
+    expect(output).toContain('const t: AstryxTheme');
+    expect(output).not.toContain('XDSTheme');
+  });
+
+  it('still bare-renames when there is NO colliding local binding', async () => {
+    const input = [
+      `import {XDSButton} from '@xds/core';`,
+      `export const App = () => <XDSButton label="Hi" />;`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    // No local `Button` binding -> existing blind bare-rename behavior kept.
+    expect(output).toContain(`import {Button} from '@xds/core';`);
+    expect(output).toContain('<Button label="Hi" />');
+    expect(output).not.toContain('AstryxButton');
+    expect(output).not.toContain('XDSButton');
+  });
 });

package/assets/codemods/transforms/v0.1.0/drop-xds-prefix-imports.mjs

@@ -64,6 +64,22 @@ export const meta = {
 
 const XDS_CORE_SOURCE = /^@xds\/core(\/.*)?$/;
 
+/**
+ * Compute a collision alias for an XDS-prefixed identifier by replacing the
+ * `XDS` segment IN PLACE with `Astryx` (as opposed to prefixing the bare name).
+ * This keeps hook names well-formed:
+ *
+ *   XDSButton       -> AstryxButton
+ *   XDSLinkProvider -> AstryxLinkProvider
+ *   useXDSToast     -> useAstryxToast   (NOT AstryxuseToast)
+ *
+ * Only the first `XDS` occurrence is replaced, matching how `bareName` strips a
+ * single leading prefix.
+ */
+function aliasName(/** @type {any} */ name) {
+  return name.replace('XDS', 'Astryx');
+}
+
 /**
  * Compute the bare (unprefixed) name for an XDS-prefixed identifier.
  * Returns null if the name is not XDS-prefixed in a renameable way.
@@ -190,7 +206,12 @@ export default function transformer(file, api) {
     if (!node) return;
     if (
       (node.type === 'FunctionDeclaration' ||
-        node.type === 'ClassDeclaration') &&
+        node.type === 'ClassDeclaration' ||
+        // Type-only bindings share the module namespace for our purposes: a
+        // `type Tab`/`interface Theme` collides with an un-prefixed `XDSTab`/
+        // `XDSTheme` type import and would create a duplicate declaration.
+        node.type === 'TSTypeAliasDeclaration' ||
+        node.type === 'TSInterfaceDeclaration') &&
       node.id
     ) {
       existingBindings.add(node.id.name);
@@ -239,10 +260,13 @@ export default function transformer(file, api) {
       if (bare !== importedName && existingBindings.has(bare)) {
         // COLLISION: the bare name is already a top-level binding in this file
         // (e.g. a local `export function CodeBlock` alongside imported
-        // `XDSCodeBlock`). Un-prefixing directly would create a duplicate
-        // declaration, so alias the import to `Astryx<Name>` and rename the
+        // `XDSCodeBlock`, or a `type Tab` alongside `XDSTab`). Un-prefixing
+        // directly would create a duplicate declaration (TS2451), so alias the
+        // import by replacing `XDS` with `Astryx` in place and rename the
         // import's references to that alias, leaving the local binding intact.
-        const alias = `Astryx${bare}`;
+        // In-place replacement keeps hooks well-formed: `useXDSToast` becomes
+        // `useAstryxToast`, not `AstryxuseToast`.
+        const alias = aliasName(importedName);
         localRenames.set(importedName, alias);
         existingBindings.add(alias);
         hasChanges = true;

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

@@ -4,91 +4,336 @@
 
 export const docsDense = {
   description:
-    'frame-first app layout: shell choice, region budgets, cards vs rows',
+    'outside-in app layout: scaffold -> structure -> spacing -> breakpoints.',
   sections: [
     {
-      section: 'Frame First',
-      title: 'Frame First',
+      section: 'Overview',
+      title: 'Overview',
       content: [
         {
           type: 'prose',
-          text: 'decide frame before content. content-first (Card-wrapped sections in a scroll column) = prototype look.',
+          text: 'build outside-in. settle the shell + region budgets before any content, then work inward. content-first drifts into a padded column of cards, each section inventing its own container.',
         },
         {
           type: 'list',
           items: [
-            'pick frame: AppShell (nav apps) | Layout+LayoutPanel+LayoutContent (multi-pane tools) | plain column (docs/forms)',
-            'budget regions in px first: side nav 240-280, rail 64-72, inspector 340-420, facet rail 220-260',
-            'container policy per region: dense data = rows; dashboards/galleries = card grids',
-            'write responsive contract up front',
+            'scaffold: pick shell, budget regions, choose nav',
+            'structure: rank content per region, pick the weakest container that groups it',
+            'spacing: hold one content line per region, then tune gaps + density',
+            'breakpoints: decide what each region does as width changes',
           ],
         },
-        null,
+        {
+          type: 'prose',
+          text: 'decides layout, not component APIs. npx astryx build "<idea>" = closest template for your app type. npx astryx component <Name> = props.',
+        },
       ],
     },
     {
-      section: 'App Archetypes',
-      title: 'App Archetypes',
+      section: 'Scaffold',
+      title: 'Scaffold',
       content: [
+        // Shell
+        null,
         {
           type: 'prose',
-          text: 'container choice tracks archetype, not preference.',
+          text: 'pick the shell + budget its regions before any content exists. structural widths are the one place raw px belongs; everything inside uses the scale.',
+        },
+        {
+          type: 'list',
+          items: [
+            'pick frame: AppShell (nav apps) | Layout + LayoutPanel in a start/end slot (multi-pane tools) | plain column (docs/forms)',
+            'give every fixed region a width budget, so none negotiates for space at render time',
+            'read content to set fill vs capped: tables/charts/boards fill; prose/forms/lists cap via Layout contentWidth',
+            'set container policy (rows or card grid) before writing content',
+          ],
+        },
+        null,
+        {
+          type: 'prose',
+          text: 'verify: every region has a width budget + fill-or-capped + a container policy written down before any content.',
+        },
+        // Navigation
+        null,
+        {
+          type: 'prose',
+          text: 'nav left open? default SideNav: it absorbs destinations you have not planned yet. app type + destination count are guiding indicators, not determining rules.',
+        },
+        {
+          type: 'list',
+          items: [
+            'SideNav (default): need grouping, customizable, items carry secondary actions, or must collapse. trackers, consoles, settings usually start here',
+            'TopNav: shallow nav you expect to stay shallow, context must stay visible, or control/filter-heavy page; + TabList for a 2nd level. media libraries often sit over grid content',
+            'both: a genuine suite. TopNav = ecosystem concerns (context switcher, global search), SideNav = product nav',
+            'neither: messaging/feeds use a column frame of rail, nav, stream, panel',
+          ],
         },
         null,
         {
           type: 'prose',
-          text: 'start from matching template (astryx template --list), study with --skeleton.',
+          text: 'verify: you can state the reason in one sentence, and it still holds if the nav doubles. npx astryx build "<idea>" names the closest template, --skeleton shows the pairing wired up.',
+        },
+        // Best practices
+        null,
+        {
+          type: 'list',
+          items: [
+            'decide frame + region width budgets + fill-or-capped before content',
+            'state the reason for the nav choice, or inherit template pairing',
+            'raw px for structural widths; interior = tokens',
+          ],
+        },
+        {
+          type: 'list',
+          items: [
+            'build content-first, Card-wrapping each section',
+            'stretch prose/forms/lists across a wide region instead of capping with contentWidth',
+            'SideNav when the nav is really filters/controls, or must hold wide elements like breadcrumbs',
+            'TopNav when top-slot ownership is unclear, or hierarchy is deep or still growing',
+            'both bars when the ecosystem layer is thin',
+            'break template nav pairing without a reason',
+          ],
         },
       ],
     },
     {
-      section: 'Cards vs Rows',
-      title: 'Cards vs Rows',
+      section: 'Structure',
+      title: 'Structure',
       content: [
+        // Type hierarchy
+        null,
+        {
+          type: 'prose',
+          text: 'one lead per region, then rank with weight+color, not size. two text colors only: primary + secondary, nothing dimmer. body copy needs no props.',
+        },
+        {
+          type: 'list',
+          items: [
+            'body (default): plain Text, no type/color/size prop',
+            'lead: Heading at the level matching page depth, or body Text at a heavier weight',
+            'support: step to secondary color, not to a smaller size',
+            'meta: the supporting type, or StatusDot/Token instead of prose',
+          ],
+        },
+        null,
+        {
+          type: 'prose',
+          text: 'squint test: read lead, then support, then groups, in order. everything at once = raise contrast (weight/color), not borders and not smaller text.',
+        },
+        // Containers
+        null,
+        {
+          type: 'prose',
+          text: 'weakest container that reads as a group, escalate only when it fails. weakest to strongest:',
+        },
+        {
+          type: 'list',
+          items: [
+            'spacing/gap: related items inside one group. the default rhythm',
+            'Divider: peers in a dense list/toolbar, or fencing a header from a scrollable body',
+            'Section: default page-structure unit, related content under a heading. no border',
+            'Card: self-contained widget (KPI tile, chart, gallery entry) or hard boundary',
+          ],
+        },
+        null,
+        {
+          type: 'prose',
+          text: 'test: records -> rows (Table columnar, List single-line); self-contained widget or hard boundary -> Card; everything else -> Section.',
+        },
+        // Headers and footers
+        null,
+        {
+          type: 'prose',
+          text: 'a region can pin a header/footer while its body scrolls. both are Layout slots, and padding set once on Layout reaches all three, so header/body/footer share one content line.',
+        },
+        {
+          type: 'list',
+          items: [
+            'LayoutHeader in the header slot: region title + its primary action',
+            'Toolbar instead of LayoutHeader when the header carries interactive controls',
+            'LayoutFooter in the footer slot: actions that commit the work + must stay reachable',
+            'defaultHasDividers on Layout fences both at once, rather than hasDivider per slot',
+          ],
+        },
+        null,
+        {
+          type: 'prose',
+          text: 'verify: scroll the body. header + footer stay put, dividers run full-bleed, all three still share one left content line.',
+        },
+        // Side panels
+        null,
+        {
+          type: 'prose',
+          text: 'master-detail: select a row -> fixed-width side panel, no navigation away.',
+        },
+        {
+          type: 'list',
+          items: [
+            'LayoutPanel in the start or end slot of Layout, holding a fixed width budget',
+            'hasDivider fences it from content; isScrollable so long detail scrolls on its own',
+            'user-adjustable width: useResizable() + ResizeHandle on the panel inner edge. after the panel in a start slot, before it in an end slot w/ isReversed',
+            'the handle then owns the divider, so the panel sets hasDivider={false}',
+            'EmptyState when nothing is selected, so the region never collapses',
+          ],
+        },
+        null,
         {
           type: 'prose',
-          text: 'Card = widget container, NOT list-item wrapper. dense/scannable/selectable data = rows: Table (columnar) or List/Item (single-line), edge-to-edge, 32-40px rows, dividers.',
+          text: 'verify: at narrow widths the panel yields width instead of squeezing content (see Breakpoints), and only one element between the regions draws a border.',
         },
+        // Best practices
+        null,
         {
           type: 'list',
           items: [
-            'Table+plugins: hosts, deployments, monitors, users',
-            'List/Item rows: issues, files, conversations',
-            'Card: KPI tiles, chart panels, gallery entries, settings groups',
-            'EmptyState for zero-match',
+            'one lead per region; rank via weight+color; one primary action',
+            'leave body copy at its defaults; demote via weight+color, not size',
+            'default Section; weakest container that reads as a group',
+            'collections = rows (Table/List), edge-to-edge with dividers',
+            'side panel on select; it yields width at narrow sizes',
           ],
         },
         {
           type: 'list',
           items: [
-            'no Card-wrapped list items (card soup)',
-            'no stacked full-width Cards as page structure',
-            'no Cards in Cards',
-            'no decorative Badge: counts/enums only; StatusDot/Token for status',
+            'grey + shrink body copy, so a whole region reads as metadata',
+            'the disabled color for content; it fails contrast, it is for disabled controls',
+            'card soup: each record in its own Card',
+            'cards-in-cards, or full-width Cards as page structure',
+            'a header/footer rebuilt inside the body, where it scrolls away with the rows',
+            'flexbox soup instead of Grid/Layout/Section/FormLayout',
+            'two competing primary actions in one region',
+            'Badge as decoration; use StatusDot/Token for status',
           ],
         },
       ],
     },
     {
-      section: 'Panels and Inspectors',
-      title: 'Panels and Inspectors',
+      section: 'Spacing',
+      title: 'Spacing',
       content: [
+        // Alignment
+        null,
+        {
+          type: 'prose',
+          text: 'container owns padding + child gaps; children zero margins; interior spacing = token. one content line per region, hold the line not the padding: container_inset = content_line - component_intrinsic_inset.',
+        },
+        {
+          type: 'list',
+          items: [
+            'Text/Heading carry no inset -> container takes the full padding',
+            'List/Tab/Menu/nav items carry a small inset -> container gives up padding, component owns the line',
+            'Table cells carry a larger inset -> container gives up padding, cell owns the line',
+          ],
+        },
+        null,
         {
           type: 'prose',
-          text: 'master-detail: row select opens fixed-width inspector (LayoutPanel end slot + width budget + resizable/useResizable). overlay content <=1024px, do not compress.',
+          text: 'verify: draw one vertical line down the left. every label touches it; only hover/selected backgrounds cross it.',
         },
+        // Rhythm
         null,
+        {
+          type: 'prose',
+          text: 'grouping = contrast between tight and generous gaps, not one repeated value. same step everywhere = proximity does no work.',
+        },
+        {
+          type: 'list',
+          items: [
+            'tight gaps bind: the smallest steps, inside an item or field',
+            'generous gaps separate: several steps up, between sections',
+            'reach for the in-between steps to tune cadence, not the same two values everywhere',
+          ],
+        },
+        null,
+        {
+          type: 'prose',
+          text: 'verify: borders removed, you can still name the groups from spacing alone. cannot = intervals too uniform. form fields excepted: FormLayout owns their spacing.',
+        },
+        // Density and size
+        null,
+        {
+          type: 'prose',
+          text: 'density by use frequency; every control in a row shares one size so heights share a baseline.',
+        },
+        {
+          type: 'list',
+          items: [
+            'compact: high-volume, fast scan (logs, monitors, large datasets)',
+            'balanced: most Table/List surfaces',
+            'spacious: low-frequency or high-stakes rows (settings, short selection list)',
+          ],
+        },
+        null,
+        {
+          type: 'prose',
+          text: 'verify: one size per row, paired with the density of the region it sits in.',
+        },
+        // Best practices
+        null,
+        {
+          type: 'list',
+          items: [
+            'container owns padding; children zero margins',
+            'one content line: text on line, hover bleeds to edge',
+            'one padding token across region header/body/footer',
+            'contrast tight vs generous gaps',
+            'one control size per row; density by use frequency',
+          ],
+        },
+        {
+          type: 'list',
+          items: [
+            'double padding (component past its heading); keep one inset owner',
+            'raw px for interior spacing; tokens only',
+            'one repeated gap everywhere',
+            'mixed control sizes in one row',
+          ],
+        },
       ],
     },
     {
-      section: 'Responsive Contract',
-      title: 'Responsive Contract',
+      section: 'Breakpoints',
+      title: 'Breakpoints',
       content: [
+        // Responsive contract
+        null,
         {
           type: 'prose',
-          text: 'declare breakpoint behavior as comment at frame root: which regions collapse/overlay/drop at which widths.',
+          text: 'lock what each region does as width changes; pair each contract line with the prop/hook that enforces it.',
+        },
+        {
+          type: 'list',
+          items: [
+            'divide: how many regions survive at each width',
+            'reveal: which regions earn their width only when there is room, opening on demand below that',
+            'resize: content flexes, fixed regions hold their budgets, text capped by contentWidth so line length holds',
+            'swap: nav -> MobileNav at the AppShell mobileNav breakpoint; side panel -> Dialog/BottomSheet via useMediaQuery',
+          ],
         },
         null,
+        {
+          type: 'prose',
+          text: 'verify: every contract line names a mechanism, so the comment cannot drift from the behavior.',
+        },
+        // Best practices
+        null,
+        {
+          type: 'list',
+          items: [
+            'write the contract down for every region before calling the layout done',
+            'decide per region: revealed, resized, or swapped at each width',
+            'drop a region rather than let it fight for width it lacks',
+          ],
+        },
+        {
+          type: 'list',
+          items: [
+            '3 regions at a width where none has usable space',
+            'shrink every region uniformly instead of swapping/dropping one',
+            'a CSS breakpoint the contract comment never mentions',
+          ],
+        },
       ],
     },
   ],