@astryxdesign/cli 0.4.7-canary.fe95cd5 → 0.5.0-canary.055e75f

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @xds/cli
 
+# 0.5.0
+
+#### Breaking Changes
+
+- Banner: the collapse axis moves onto one `collapsible` prop, and content can opt out of collapsing (#5255)
+  Banner inferred its disclosure from its content: any `children` got a chevron in the header and were hidden until it was pressed. There was no way to show content without a toggle — the case a banner most often wants, a list of the three fields that failed validation — and `defaultIsExpanded` was the only knob, with no controlled mode.
+
+  The whole axis is now one `boolean | CollapsibleConfig` prop, following the boolean-or-config convention `SideNav.collapsible` set, and backed by the shared `useCollapsible` hook rather than Banner's own state:
+
+  ```tsx
+  <Banner status="error" title="3 fields need attention">…</Banner>  // unchanged: collapsible, starts closed
+  <Banner collapsible={false}>…</Banner>                             // new: always visible, no toggle
+  <Banner collapsible={{defaultIsOpen: true}}>…</Banner>             // replaces defaultIsExpanded
+  <Banner collapsible={{isOpen, onOpenChange}}>…</Banner>            // new: controlled
+  ```
+
+  **The default is unchanged** — a banner that never mentioned `defaultIsExpanded` behaves exactly as it did. The breaking part is the prop itself: `defaultIsExpanded` is removed in favour of the config, which is a type error at every JSX call site that names it.
+
+  **Codemod:** `npx astryx upgrade --codemod banner-collapsible-content`
+
+  It rewrites `defaultIsExpanded` to `collapsible={{defaultIsOpen: true}}` and drops `defaultIsExpanded={false}`, which is now the default. Banners that never set the prop are left alone.
+
+  **One case the codemod and the compiler both miss: a spread.** `defaultIsExpanded` inside a props object is out of the transform's scope. A props object in a typed position still fails to compile — but an inferred one that is spread, `<Banner {...args} />`, does not, because TypeScript does not excess-property-check a spread. The prop then falls through to the DOM and the banner quietly starts collapsed. **Grep for `defaultIsExpanded` after running the codemod** and migrate any spread sites by hand.
+
+#### New Components
+
+- Promote `Stepper` and `Step` from the canary-only Lab package to Core. The stable package now ships their existing horizontal/vertical layouts, separated and on-track indicators, semantic status, density, and non-linear navigation, plus Core documentation and rendered examples. The default `aria-label` is now localized.
+  Advancing one step now animates the connector. Every connector the four layouts draw — the separated bars and the on-track segments alike — grows its accent fill out of the segment's leading edge instead of swapping a background color, so moving forward reads as progress travelling the track. That one gesture is the only thing that animates: going back, jumping forward by more than one step, and mounting mid-flow all apply at once, as does any change under `prefers-reduced-motion`. Retreats are deliberately instant — run in reverse the same transition ends on a shrinking stub of accent, and a remnant still on the track reads as unfinished where the identical curve growing forward reads as arrived — and multi-step jumps are instant because a jump is a navigation rather than a progression, so sweeping a front across the crossed segments only makes the user sit out a journey they asked to skip. Where one span is drawn by several segments (the on-track layouts split a span between two steps, three when a content slot sits between them) the segments take abutting slices of the span's time and run linearly, so the fill reads as one line growing at a constant speed rather than pieces lighting in turn.
+
+  Five visual fixes land with the promotion. Horizontal steps now divide the track evenly instead of sizing to their own labels, so every progress segment is the same width regardless of how long a step is named. Number indicators shrink from 20px to 16px to match the check, ring, and custom-icon indicators, so a step swapping its number for a check as it completes no longer nudges the label beside it. A step description now occupies a 16px box rather than a 24px one — it previously inherited the page's line box instead of applying its own leading, which opened an 8px gap under the label. A step's content slot now starts flush with the label above it at every density: the slot renders outside the density-padded label area, so it was hanging one pad short of it. And a vertical on-track step carrying content keeps its connector unbroken — the content renders below the row that draws the line, so the track used to split open around any step with content (#5201).
+
+#### New Features
+
+- AspectRatio: emit `ratio` as a class-level declaration instead of a hard inline style, so the ratio can be overridden responsively: StyleX consumers pass an `aspect-ratio` rule via `xstyle` (including under `@media`/`@container` conditions), and plain-CSS/Tailwind consumers override `aspect-ratio` from their own unlayered rules, which beat the `astryx-base` cascade layer regardless of specificity. The mixed-gallery template's hero now switches 3:1 to 3:2 when the grid stacks with a one-line override on a single element, replacing the duplicated hero markup the fixed inline ratio previously forced (#3883, closes #2798)
+- CLI: `astryx theme targets` lists every component theming target — the `defineTheme` key, the class it paints, and the props and states it accepts — for one component or the whole system, with `--json` for lint and audit scripts. `astryx theme --help` now points at component overrides instead of reading as a build-tool menu. The listing and `theme build`'s override validation share one enumeration of the component docs, so neither can drift from the components (#5115).
+
+#### Fixes
+
+- neutral theme: darken the light-mode error red from `#e33f4a` to `#c9303a` so the filled `Badge variant="error"` label clears WCAG 2.1 AA. White on `#e33f4a` is 4.14:1 and the badge label is 12px/weight 500, so the 4.5:1 normal-text threshold applies rather than the 3:1 large-text allowance; `#c9303a` gives 5.29:1 while holding the hue (OKLCH H 21.9 -> 22.8, C 0.200 -> 0.189). StatusDot and the ProgressBar `--color-error` rebinding move with it — both are documented as tracking the badge fill so the dot and its badge read as one status language. Dark mode is untouched (dark text on `#ff705d`, 6.60:1). Adds `scripts/check-badge-contrast.test.mjs`, which resolves every theme's badge label/fill pair through `light-dark()`, `var()` indirection and alpha compositing, and holds all of them to 4.5:1 (#4446).
+- Unified search and build now include components contributed by integrations, so a component registered through an integration is findable and buildable alongside the built-in set instead of silently missing from both (#5259).
+- Table - Grouped page template: wrap the rows in `TableBody`
+  The template rendered `<TableRow>` straight into `<Table>`, so the emitted DOM was `<table><tr>`. `<table>` cannot contain a row directly: the HTML parser inserts an implied `<tbody>` when it parses server-rendered markup and React does not when it renders on the client, so anyone who copied the template into an app as a server-rendered page inherited a hydration mismatch in their own app. Client-only the DOM is still invalid — nothing reparents the rows, so the table ends up with `<tr>` children and no `<tbody>` at all, and any CSS or query aimed at `tbody` silently misses.
+
+  The rows now sit in `<TableBody>`, the same element the data-driven `data={...}` path renders, so styling, dividers, and column widths are unchanged (#5278).
+
+#### Other Changes
+
+- Public component theming vars are enumerable, and guarded against being documented but unsettable
+  `collectThemingVars` joins `collectThemingTargets` as part of the one enumeration the theming surface is read from. Two guards ride on it: a documented public var no component reads compiles to a declaration that never applies, and a var the component writes inline outranks every cascade layer, so no theme can reach it. Both had shipped; neither is visible in the generated theme CSS the jsdom suites assert on (#5409).
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @AKnassa
+- @andrskr
+- @cixzhang
+- @ernestt
+- @freddymeta
+- @jiunshinn
+- @rubyycheung
+
+---
+
 # 0.4.7
 
 ---

package/api/search/search.mjs

@@ -34,10 +34,12 @@ import {pathToFileURL} from 'node:url';
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {
   discoverComponents,
+  discoverIntegrationComponents,
   findComponentReadme,
   resolveImportPath,
 } from '../../foundation/discovery/component-discovery.mjs';
 import {discoverHooks, findHookDoc} from '../../foundation/discovery/hook-discovery.mjs';
+import {loadIntegrationsSafely} from '../component/_adapter.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {discoverTemplates, extractComponents} from '../template/template.mjs';
 import {loadDocsCatalog, loadTopicDoc} from '../docs/_adapter.mjs';
@@ -350,12 +352,12 @@ async function loadModuleDoc(docPath, exportName = 'docs') {
 }
 
 /**
- * Build component candidates: name + keywords + usage/description from the
- * component's .doc.mjs.
+ * Build component candidates from core's own tree: name + keywords +
+ * usage/description from the component's .doc.mjs.
  * @param {string} coreDir
  * @returns {Promise<Candidate[]>}
  */
-async function gatherComponents(coreDir) {
+async function gatherCoreComponents(coreDir) {
   const grouped = discoverComponents(coreDir);
   const names = Object.values(grouped).flat();
   /** @type {Candidate[]} */
@@ -383,6 +385,50 @@ async function gatherComponents(coreDir) {
   return candidates;
 }
 
+/**
+ * Build component candidates contributed by the project's configured
+ * integrations (astryx.config's `integrations`): name + keywords +
+ * usage/description from each component's .doc.mjs, same as core. Without
+ * this, an integration component is invisible to `search`/`build` even
+ * though `component --list`/`component <Name>` already resolve it — the two
+ * discovery paths silently disagreed.
+ * @param {string} cwd
+ * @returns {Promise<Candidate[]>}
+ */
+async function gatherIntegrationComponents(cwd) {
+  const loadedIntegrations = await loadIntegrationsSafely(cwd);
+  /** @type {Candidate[]} */
+  const candidates = [];
+  for (const integration of loadedIntegrations) {
+    for (const rec of discoverIntegrationComponents(integration)) {
+      const doc = await loadModuleDoc(rec.docPath);
+      candidates.push({
+        domain: 'component',
+        name: rec.name,
+        keywords: doc && Array.isArray(doc.keywords) ? doc.keywords : [],
+        description: doc ? doc.usage?.description || doc.description || '' : '',
+        _import: rec.package,
+      });
+    }
+  }
+  return candidates;
+}
+
+/**
+ * Build component candidates: core's own tree plus every configured
+ * integration's components.
+ * @param {string} coreDir
+ * @param {string} cwd
+ * @returns {Promise<Candidate[]>}
+ */
+async function gatherComponents(coreDir, cwd) {
+  const [core, integrations] = await Promise.all([
+    gatherCoreComponents(coreDir),
+    gatherIntegrationComponents(cwd),
+  ]);
+  return [...core, ...integrations];
+}
+
 /**
  * Build hook candidates: name + keywords + usage/description from the hook's
  * .doc.mjs.
@@ -611,7 +657,7 @@ export async function search(query, options = {}) {
   /** @param {string} d */
   const wants = d => !type || type === d;
   const [components, hooks, docTopics, templates] = await Promise.all([
-    wants('component') ? gatherComponents(coreDir) : [],
+    wants('component') ? gatherComponents(coreDir, cwd) : [],
     wants('hook') ? gatherHooks(coreDir) : [],
     wants('doc') ? gatherDocs(cwd) : [],
     wants('template') ? gatherTemplates(cwd) : [],

package/api/search/search.test.mjs

@@ -10,9 +10,17 @@
  * `limit`, an empty query, and a bad `--type` all throw AstryxError with the
  * ERR_INVALID_ARGUMENT code, so a direct `@astryxdesign/cli/api` caller gets the
  * same contract as `astryx search` on the command line.
+ *
+ * The last describe block covers integration-contributed components, using the
+ * same temp-consumer harness as template-integration.test.mjs. Before this,
+ * `search`/`build` only ever scanned @astryxdesign/core — an integration's own
+ * components were invisible to both, even though `component --list` and
+ * `component <Name>` already resolved them. The two discovery paths silently
+ * disagreed.
  */
 
 import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {search, SEARCH_DOMAINS} from './search.mjs';
@@ -92,3 +100,66 @@ describe('search leaf — limit validation (API matches the CLI contract)', () =
     });
   }, SLOW);
 });
+
+describe('search leaf — integration components', () => {
+  /**
+   * A minimal consumer project: a stub `@astryxdesign/core` (so `findCoreDir`
+   * resolves without needing the real package) plus an installed
+   * `@acme/widgets` integration that contributes one component.
+   */
+  function makeConsumerWithIntegrationComponent() {
+    const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-search-it-'));
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({name: 'consumer'}));
+    fs.writeFileSync(
+      path.join(dir, 'astryx.config.mjs'),
+      `export default { integrations: ['@acme/widgets'] };\n`,
+    );
+
+    // Stub core: just needs to exist with an (empty) src/ so discoverComponents
+    // doesn't throw. Its own component list is irrelevant to this test.
+    const coreDir = path.join(dir, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(path.join(coreDir, 'src'), {recursive: true});
+
+    const widgetsDir = path.join(dir, 'node_modules', '@acme', 'widgets');
+    fs.mkdirSync(path.join(widgetsDir, 'components'), {recursive: true});
+    fs.writeFileSync(
+      path.join(widgetsDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(widgetsDir, 'astryx.integration.mjs'),
+      `export default { components: './components' };\n`,
+    );
+    fs.writeFileSync(
+      path.join(widgetsDir, 'components', 'FancyGizmo.doc.mjs'),
+      `export const docs = {
+        name: 'FancyGizmo',
+        keywords: ['gizmo', 'widget'],
+        usage: {description: 'A fancy gizmo widget.'},
+      };\n`,
+    );
+
+    return dir;
+  }
+
+  it('includes a component contributed by a configured integration', async () => {
+    const dir = makeConsumerWithIntegrationComponent();
+    try {
+      const r = await search('gizmo', {cwd: dir, type: 'component'});
+      expect(r.data.results.some(x => x.name === 'FancyGizmo')).toBe(true);
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  }, SLOW);
+
+  it('reports the contributing package as the import hint', async () => {
+    const dir = makeConsumerWithIntegrationComponent();
+    try {
+      const r = await search('FancyGizmo', {cwd: dir, type: 'component'});
+      const hit = r.data.results.find(x => x.name === 'FancyGizmo');
+      expect(hit?.import).toBe('@acme/widgets');
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  }, SLOW);
+});

package/api/theme/build/build.mjs

@@ -349,8 +349,8 @@ const _augmentationTargetCache = new Map();
  * Resolve a rendered theme class token (the key without `astryx-`) to candidate
  * public core subpaths and interface prefixes that may own its augmentable prop
  * maps. Some tokens are subtargets documented by a parent component
- * (`avatar-status-dot` augments `@astryxdesign/core/Avatar`), and some stable
- * class tokens intentionally omit word separators (`progressbar`, `statusdot`)
+ * (`avatar-status-dot` augments `@astryxdesign/core/Avatar`), and some
+ * deprecated tokens still omit word separators (`progressbar`, `statusdot`)
  * while the public API keeps `ProgressBar`/`StatusDot` casing. Component docs
  * are the source of truth for the target token → owning component relationship.
  *
@@ -428,8 +428,8 @@ async function resolveAugmentationTargetCandidates(componentName) {
 
       // Try the exact rendered token first for documented subtargets such as
       // avatar-status-dot → AvatarStatusDotVariantMap, then the owning public
-      // component name for unhyphenated public casings such as progressbar →
-      // ProgressBarVariantMap/statusdot → StatusDotVariantMap.
+      // component name for the deprecated unhyphenated tokens such as
+      // progressbar → ProgressBarVariantMap/statusdot → StatusDotVariantMap.
       addCandidate(moduleName, toPascalCase(componentName));
       addCandidate(moduleName, moduleName);
       if (Array.isArray(doc?.components)) {

package/api/theme/targets/targets.test.mjs

@@ -34,6 +34,7 @@ describe('themeTargets (api/theme/targets)', () => {
     expect(data.targets.map(t => t.key)).toEqual([
       'switch',
       'switch-field',
+      'switch-label',
       'switch-thumb',
     ]);
   }, 60_000);

package/api/theme/themeTargets.doc.mjs

@@ -18,9 +18,9 @@ export const doc = {
     'Enumerates the whole themeable surface: each `defineTheme` components key, the stable ' +
     'class it paints, the component that declares it, and the props and states that are legal ' +
     'override keys under it. Same source as the Theming table `astryx component <Name>` prints ' +
-    '— the component docs — so the list cannot drift from the components, and `theme build` ' +
+    '(the component docs), so the list cannot drift from the components, and `theme build` ' +
     'validates overrides against this exact set. A filter naming a component gives that ' +
-    'component\u2019s set; anything else is a substring search over the keys.',
+    'component\'s set; anything else is a substring search over the keys.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeTargets(filter?: string, ctx?: {cwd?: string}): Promise<ThemeTargetsResponse>',
@@ -35,7 +35,7 @@ export const doc = {
     {
       name: 'ctx.cwd',
       type: 'string',
-      description: 'Directory the project’s @astryxdesign/core is resolved from.',
+      description: 'Directory the project\'s @astryxdesign/core is resolved from.',
     },
   ],
   returns: [

package/assets/codemods/__tests__/registry.test.mjs

@@ -26,6 +26,7 @@ describe('registry', () => {
         '0.2.1',
         '0.3.0',
         '0.4.0',
+        '0.5.0',
       ]);
     });
   });

package/assets/codemods/registry.mjs

@@ -27,6 +27,7 @@ const registry = new Map([
   ['0.2.1', () => import('./transforms/v0.2.1/index.mjs')],
   ['0.3.0', () => import('./transforms/v0.3.0/index.mjs')],
   ['0.4.0', () => import('./transforms/v0.4.0/index.mjs')],
+  ['0.5.0', () => import('./transforms/v0.5.0/index.mjs')],
 ]);
 
 // Re-export from the shared utility so registry callers and other consumers

package/assets/codemods/transforms/v0.5.0/__tests__/next-codemods.test.mjs

@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Unit tests for the staged (next-release) codemods.
+ *
+ * Mirrors v0.4.0/__tests__/next-codemods.test.mjs, which covers the codemods
+ * after promotion. Keeping a copy here means a staged transform is tested from
+ * the day it is written rather than the day it is released.
+ */
+
+import {describe, expect, it} from 'vitest';
+import jscodeshift from 'jscodeshift';
+
+const j = jscodeshift.withParser('tsx');
+const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+
+async function apply(name, source) {
+  const {default: transform} = await import(`../${name}.mjs`);
+  return transform({source, path: 'test.tsx'}, api) ?? source;
+}
+
+const TRANSFORM = 'banner-collapsible-content';
+
+const IMPORT = "import {Banner} from '@astryxdesign/core/Banner';\n";
+
+describe('banner-collapsible-content', () => {
+  it('rewrites a bare defaultIsExpanded to a starts-open config', async () => {
+    const output = await apply(
+      TRANSFORM,
+      `${IMPORT}const el = <Banner status="info" title="T" defaultIsExpanded><p>d</p></Banner>;`,
+    );
+    expect(output).toContain('defaultIsOpen: true');
+    expect(output).not.toContain('defaultIsExpanded');
+  });
+
+  it('rewrites defaultIsExpanded={true} the same way', async () => {
+    const output = await apply(
+      TRANSFORM,
+      `${IMPORT}const el = <Banner status="info" title="T" defaultIsExpanded={true}><p>d</p></Banner>;`,
+    );
+    expect(output).toContain('defaultIsOpen: true');
+    expect(output).not.toContain('defaultIsExpanded');
+  });
+
+  it('drops defaultIsExpanded={false}, which is the default', async () => {
+    const output = await apply(
+      TRANSFORM,
+      `${IMPORT}const el = <Banner status="info" title="T" defaultIsExpanded={false}><p>d</p></Banner>;`,
+    );
+    expect(output).not.toContain('defaultIsExpanded');
+    // No config needed: starting collapsed is what a Banner does by default.
+    expect(output).not.toContain('collapsible');
+    // Untouched attributes keep their original text (recast only reprints
+    // what changed), so the element is exactly the base minus the prop.
+    expect(output).toContain('<Banner status="info" title="T">');
+  });
+
+  it('keeps a dynamic default dynamic', async () => {
+    const output = await apply(
+      TRANSFORM,
+      `${IMPORT}const el = <Banner status="info" title="T" defaultIsExpanded={isOpen}><p>d</p></Banner>;`,
+    );
+    expect(output).toContain('defaultIsOpen: isOpen');
+    expect(output).not.toContain('defaultIsExpanded');
+  });
+
+  it('leaves a banner that never set the prop alone', async () => {
+    // The default is unchanged, so this banner still behaves as it did. The
+    // migration must not touch it — that is the whole point of the shape.
+    const source = `${IMPORT}const el = <Banner status="error" title="T"><ul><li>a</li></ul></Banner>;`;
+    const output = await apply(TRANSFORM, source);
+    expect(output).toBe(source);
+  });
+
+  it('leaves a childless banner alone', async () => {
+    const source = `${IMPORT}const el = <Banner status="info" title="T" />;`;
+    const output = await apply(TRANSFORM, source);
+    expect(output).toBe(source);
+  });
+
+  it('leaves a banner that already uses collapsible alone', async () => {
+    const source = `${IMPORT}const el = <Banner status="info" title="T" collapsible={false} defaultIsExpanded><p>d</p></Banner>;`;
+    const output = await apply(TRANSFORM, source);
+    expect(output).toBe(source);
+  });
+
+  it('does not guess around a spread', async () => {
+    const source = `${IMPORT}const el = <Banner status="info" title="T" defaultIsExpanded {...rest}><p>d</p></Banner>;`;
+    const output = await apply(TRANSFORM, source);
+    expect(output).toBe(source);
+  });
+
+  it("leaves another component's defaultIsExpanded alone", async () => {
+    // ChatToolCalls has a prop of the same name that this migration must not
+    // touch.
+    const source = `import {ChatToolCalls} from '@astryxdesign/core/Chat';
+const el = <ChatToolCalls calls={calls} defaultIsExpanded />;`;
+    const output = await apply(TRANSFORM, source);
+    expect(output).toBe(source);
+  });
+
+  it('leaves a Banner that is not the core Banner alone', async () => {
+    const source = `import {Banner} from './ui/Banner';
+const el = <Banner status="info" title="T" defaultIsExpanded><p>d</p></Banner>;`;
+    const output = await apply(TRANSFORM, source);
+    expect(output).toBe(source);
+  });
+
+  it('leaves the prop inside a props object alone', async () => {
+    // Out of scope by design: which component the object feeds is a guess,
+    // and the removed prop makes those sites a type error anyway.
+    const source = `${IMPORT}const args = {status: 'info', title: 'T', defaultIsExpanded: true};
+const el = <Banner {...args} />;`;
+    const output = await apply(TRANSFORM, source);
+    expect(output).toBe(source);
+  });
+
+  it('migrates a Banner imported from the package root', async () => {
+    const output = await apply(
+      TRANSFORM,
+      `import {Banner, Button} from '@astryxdesign/core';
+const el = <Banner status="info" title="T" defaultIsExpanded><p>d</p></Banner>;`,
+    );
+    expect(output).toContain('defaultIsOpen: true');
+    expect(output).not.toContain('defaultIsExpanded');
+  });
+});

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

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

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

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

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

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

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

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