@astryxdesign/cli 0.4.7 → 0.5.0-canary.32a62fd

package/api/theme/targets/targets.mjs

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx theme targets` leaf — the whole themeable surface, enumerated.
+ *
+ * @input  a cwd (to resolve the project's `@astryxdesign/core`) and an optional
+ *         component/key filter
+ * @output the `theme.targets` envelope: one row per theming target
+ * @position api/theme/targets — projection over
+ *           foundation/discovery/theming-targets.mjs, the same component docs
+ *           `astryx component <Name>` prints its Theming table from.
+ */
+
+import * as path from 'node:path';
+import {findCoreDir} from '../../../foundation/fs/paths.mjs';
+import {collectThemingTargets} from '../../../foundation/discovery/theming-targets.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {AstryxError} from '../../error.mjs';
+
+/**
+ * Whether a target matches the caller's filter loosely: any target whose key,
+ * class, or component contains it — so `theme targets thumb` finds the switch
+ * thumb without knowing which component owns it.
+ * @param {import('../../../foundation/discovery/theming-targets.mjs').ThemingTarget} target
+ * @param {string} filter - already lowercased
+ * @returns {boolean}
+ */
+function matchesLoosely(target, filter) {
+  return (
+    target.key.toLowerCase().includes(filter) ||
+    target.className.toLowerCase().includes(filter) ||
+    target.component.toLowerCase().includes(filter)
+  );
+}
+
+/**
+ * List every component theming target — the `defineTheme` `components` keys,
+ * with the props and states each one accepts.
+ *
+ * A filter naming a component exactly wins over a substring search, so
+ * `theme targets Button` is Button's own set (what `astryx component Button`
+ * prints) rather than every key that happens to contain "button".
+ *
+ * @param {string} [filter] - component name, or a substring of a target key
+ * @param {{cwd?: string}} [ctx]
+ * @returns {Promise<import('../theme.type.mjs').ThemeTargetsResponse>}
+ */
+export async function themeTargets(filter, {cwd = process.cwd()} = {}) {
+  const coreDir = findCoreDir(cwd);
+  if (!coreDir) {
+    throw new AstryxError(
+      'Could not find @astryxdesign/core package',
+      undefined,
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
+  }
+
+  const all = await collectThemingTargets(path.join(coreDir, 'src'));
+  const needle = filter ? String(filter).toLowerCase() : null;
+  let targets = all;
+  if (needle) {
+    const named = all.filter(t => t.component.toLowerCase() === needle);
+    targets = named.length > 0 ? named : all.filter(t => matchesLoosely(t, needle));
+  }
+
+  if (needle && targets.length === 0) {
+    const near = [...new Set(all.map(t => t.component))]
+      .filter(name => name.toLowerCase().startsWith(needle.slice(0, 3)))
+      .sort()
+      .slice(0, 5)
+      .map(name => ({name, reason: 'has theming targets'}));
+    throw new AstryxError(
+      `No theming target matches "${filter}". Run \`theme targets\` with no filter for the whole list.`,
+      near.length > 0 ? near : undefined,
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+  }
+
+  return {
+    type: 'theme.targets',
+    data: {
+      filter: filter ?? null,
+      componentCount: new Set(targets.map(t => t.component)).size,
+      targets,
+    },
+  };
+}

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

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Direct-API tests for the `theme targets` leaf. Runs against the real
+ * core docs, so it doubles as a guard that the themeable surface stays
+ * readable and shaped as `theme.targets` promises.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {themeTargets} from './targets.mjs';
+
+describe('themeTargets (api/theme/targets)', () => {
+  it('returns a theme.targets envelope covering the whole surface', async () => {
+    const result = await themeTargets();
+    expect(result.type).toBe('theme.targets');
+    expect(result.data.filter).toBeNull();
+    expect(result.data.targets.length).toBeGreaterThan(100);
+    expect(result.data.componentCount).toBeGreaterThan(50);
+    for (const t of result.data.targets) {
+      expect(Object.keys(t).sort()).toEqual([
+        'className',
+        'component',
+        'key',
+        'props',
+        'states',
+      ]);
+    }
+  }, 60_000);
+
+  it('scopes to one component by name', async () => {
+    const {data} = await themeTargets('Switch');
+    expect(data.filter).toBe('Switch');
+    expect(data.componentCount).toBe(1);
+    expect(data.targets.map(t => t.key)).toEqual([
+      'switch',
+      'switch-field',
+      'switch-label',
+      'switch-thumb',
+    ]);
+  }, 60_000);
+
+  // Half the system's keys contain "button" (chat-send-button, toggle-button,
+  // …). A component name has to mean the component, or `theme targets Button`
+  // answers a different question than `component Button` and the two views
+  // look like they disagree.
+  it('prefers an exact component name over a substring match', async () => {
+    const {data} = await themeTargets('Button');
+    expect(data.targets.map(t => t.key)).toEqual(['button']);
+  }, 60_000);
+
+  // This command answers "which theme slot paints the switch thumb?" — a
+  // question you can only ask by the part, not the component, until you
+  // already know which component owns it.
+  it('searches keys by substring, across components', async () => {
+    const {data} = await themeTargets('thumb');
+    expect(data.componentCount).toBeGreaterThan(1);
+    expect(data.targets.map(t => t.key)).toContain('switch-thumb');
+    for (const t of data.targets) expect(t.key).toContain('thumb');
+  }, 60_000);
+
+  it('rejects a filter that matches nothing, with components to try', async () => {
+    await expect(themeTargets('nosuchthing')).rejects.toMatchObject({
+      code: 'ERR_UNKNOWN_COMPONENT',
+    });
+  }, 60_000);
+});

package/api/theme/theme.d.mts

@@ -3,6 +3,7 @@
 
 export { themeAdd } from "./add/add.mjs";
 export { themeTemplate } from "./template/template.mjs";
+export { themeTargets } from "./targets/targets.mjs";
 export { themeList } from "./list/list.mjs";
 export { listThemes } from "./_adapter.mjs";
 export { themeBuild, importSpecifier } from "./build/build.mjs";

package/api/theme/theme.mjs

@@ -1,7 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `theme` command barrel — re-exports the build/add/list leaves so the CLI
+ * @file `theme` command barrel — re-exports the build/add/list/template/targets
+ * leaves so the CLI
  * (cli/commands/build-theme.mjs) and scripted callers import from one place.
  * Each leaf is also importable directly (e.g. api/theme/add/add.mjs). `theme`
  * has real subcommands, so there is no flag-dispatch here — the CLI calls the
@@ -11,5 +12,6 @@
 export {themeBuild, importSpecifier} from './build/build.mjs';
 export {themeAdd} from './add/add.mjs';
 export {themeTemplate} from './template/template.mjs';
+export {themeTargets} from './targets/targets.mjs';
 export {themeList} from './list/list.mjs';
 export {listThemes} from './_adapter.mjs';

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

@@ -101,3 +101,26 @@ export type ThemeTemplateResponse = {
         reason: "exists" | null;
     };
 };
+/**
+ * One themeable target: the `defineTheme` `components` key, the class it
+ * renders as, the component whose doc declares it, and the props and states
+ * that are legal override keys under it.
+ */
+export type ThemeTargetEntry = {
+    key: string;
+    className: string;
+    component: string;
+    props: string[];
+    states: string[];
+};
+/**
+ * xds --json theme targets [filter]
+ */
+export type ThemeTargetsResponse = {
+    type: "theme.targets";
+    data: {
+        filter: string | null;
+        componentCount: number;
+        targets: ThemeTargetEntry[];
+    };
+};

package/api/theme/theme.type.mjs

@@ -14,9 +14,10 @@
  * xds --json theme list                     -> theme.list
  * xds --json theme add <slug>               -> theme.add
  * xds --json theme template                 -> theme.template
+ * xds --json theme targets [filter]         -> theme.targets
  * (file not found / parse error)            -> CLIError
  *
- * @position api — colocated typedefs for api/theme/{theme,build,add,list,template,_adapter}
+ * @position api — colocated typedefs for api/theme/{theme,build,add,list,template,targets,_adapter}
  */
 
 /**
@@ -78,6 +79,25 @@
  * @property {{path: string, written: boolean, reason: 'exists' | null}} data
  */
 
+/**
+ * One themeable target: the `defineTheme` `components` key, the class it
+ * renders as, the component whose doc declares it, and the props and states
+ * that are legal override keys under it.
+ * @typedef {object} ThemeTargetEntry
+ * @property {string} key
+ * @property {string} className
+ * @property {string} component
+ * @property {string[]} props
+ * @property {string[]} states
+ */
+
+/**
+ * xds --json theme targets [filter]
+ * @typedef {object} ThemeTargetsResponse
+ * @property {'theme.targets'} type
+ * @property {{filter: string | null, componentCount: number, targets: ThemeTargetEntry[]}} data
+ */
+
 // Make this a module so the @typedefs above are importable as types via
 // `import('./theme.type.mjs').ThemeBuildResponse` (and re-exportable from a .d.ts).
 export {};

package/api/theme/themeTargets.doc.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file FunctionDoc for `themeTargets()` / `astryx theme targets`. Colocated
+ * with the API function it documents; the response-shape source of truth stays
+ * in `theme.type.mjs`.
+ * @position packages/cli/api/theme — function documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;

package/api/theme/themeTargets.doc.mjs

@@ -0,0 +1,58 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FunctionDoc for `themeTargets()` / `astryx theme targets`. Colocated
+ * with the API function it documents; the response-shape source of truth stays
+ * in `theme.type.mjs`.
+ * @position packages/cli/api/theme — function documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc = {
+  type: 'function',
+  kind: 'api',
+  name: 'themeTargets',
+  displayName: 'themeTargets()',
+  summary: 'List every component theming target a theme can override.',
+  description:
+    '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` ' +
+    '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.',
+  importPath: '@astryxdesign/cli/api',
+  signature:
+    'themeTargets(filter?: string, ctx?: {cwd?: string}): Promise<ThemeTargetsResponse>',
+  keywords: ['theme', 'targets', 'defineTheme', 'components', 'override', 'class', 'states', 'audit'],
+  params: [
+    {
+      name: 'filter',
+      type: 'string',
+      description:
+        'A component name (exact, case-insensitive) or a substring of a target key. Omit for the whole surface.',
+    },
+    {
+      name: 'ctx.cwd',
+      type: 'string',
+      description: 'Directory the project’s @astryxdesign/core is resolved from.',
+    },
+  ],
+  returns: [
+    {
+      type: 'theme.targets',
+      description:
+        'The echoed filter, how many components are represented, and the targets: each {key, className, component, props, states}.',
+    },
+  ],
+  throws: [
+    {code: 'ERR_CORE_NOT_FOUND', when: '@astryxdesign/core cannot be resolved from cwd'},
+    {code: 'ERR_UNKNOWN_COMPONENT', when: 'a filter matches no target'},
+  ],
+  examples: [
+    {label: 'The whole themeable surface', code: 'await themeTargets();'},
+    {label: "One component's targets", code: "await themeTargets('Switch');"},
+  ],
+  command: 'theme targets',
+  related: ['themeBuild', 'themeTemplate', 'component'],
+};

package/api/theme/themeTemplate.doc.mjs

@@ -15,9 +15,9 @@ export const doc = {
   displayName: 'themeTemplate()',
   summary: 'Write the annotated theme template into a project.',
   description:
-    'Writes theme.template.ts: the annotated reference for the whole theme surface — every ' +
+    'Writes theme.template.ts: the annotated reference for the whole theme surface, covering every ' +
     'defineTheme field, the token families, the component override syntax, and how a theme is ' +
-    'consumed — with the CLI command that prints the authoritative reference for each section. ' +
+    'consumed, with the CLI command that prints the authoritative reference for each section. ' +
     'Read it, copy what you need into your own theme file, delete it. Where `theme add` starts ' +
     'you from a theme we ship, this starts you from a blank one. Refuses to overwrite without ' +
     '`overwrite`, so it is safe to re-run.',
@@ -48,7 +48,7 @@ export const doc = {
     {
       type: 'theme.template',
       description:
-        'Receipt: the path (relative to cwd), whether it was written, and the reason it was not — `exists` when a file was already there, which is a success, not a failure.',
+        'Receipt: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success, not a failure.',
     },
   ],
   throws: [{code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'}],

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