@epilot/zenith-react 0.2.0-next.3 → 0.2.0-next.5

package/README.md

@@ -39,6 +39,14 @@ Application styles that need a design token import a named binding from
 `@epilot/zenith-react/tokens`. Do not add the token CSS as a second stylesheet,
 and do not write generated `--zenith-<hash>-*` names by hand.
 
+Drag-and-drop reordering for `List` is a separate entry, so apps that render a plain
+`List` do not bundle dnd-kit:
+
+```tsx
+import { ListItem } from "@epilot/zenith-react"
+import { SortableList } from "@epilot/zenith-react/list/sortable"
+```
+
 Zenith ships no `.css` files, and its `exports` map has no stylesheet entry:
 there is nothing to import. Porting from Volt, drop its `style.css`,
 `preflight.css` and `font.css` imports and add no replacement — the token CSS
@@ -124,6 +132,23 @@ Replace `https://main.d8s2wyuq7fsgk.amplifyapp.com` with your custom domain if
 configured. All queries and tools are strictly read-only and require no
 credentials.
 
+## Agents
+
+A Zenith skill teaches a coding agent to use the MCP above. It has `compose`,
+`review`, `tokens`, `migrate` and `setup` modes. In Claude Code, one plugin
+install adds the skill and the MCP connection:
+
+```sh
+claude plugin marketplace add https://gitlab.com/e-pilot/product/frontend/zenith.git
+claude plugin install zenith@zenith
+```
+
+Then run `/zenith:compose <screen>` or `/zenith:review`. For Codex, Cursor,
+Copilot and OpenCode, install the skill with
+`npx skills add https://gitlab.com/e-pilot/product/frontend/zenith --skill zenith`
+and add the MCP endpoint to the agent's configuration. The "Coding agents"
+page in the documentation's setup section has the steps for each agent.
+
 ## Which version you get
 
 `npm install @epilot/zenith-react` resolves the `latest` dist-tag, which points
@@ -138,10 +163,21 @@ npm install @epilot/zenith-react@next
 These are opt-in twice over — you name the tag, and a range like `^0.1.0` never
 resolves a prerelease. Pin an exact version if you adopt one.
 
+## Upgrading to 0.2.0
+
+0.2.0 moves every family from Radix to Base UI and serves the primitives from
+the runtime. The "Upgrade to 0.2.0" page in the documentation's setup section
+has the steps in order: the host serves the new runtime first (with `react` and
+`react-dom` external), bump the packages, run the `radix-to-base-ui` codemod
+(its output comes through your Prettier), run the migration sweep, add the test
+setup, check the attribute renames, and keep the two rules for pages that still
+mix Volt 1.x and Zenith.
+
 ## Reference
 
 The package is ESM-only and tree-shakeable. Resolved literal token values are in
-`@epilot/zenith-react/tokens.json`, and an optional Jest helper in
+`@epilot/zenith-react/tokens.json`. For tests, `@epilot/zenith-react/testing/setup.cjs`
+(a `PointerEvent` for jsdom 26 and older, Vitest and Jest) and an optional Jest helper in
 `@epilot/zenith-react/testing/jest-preset.cjs`.
 
 Component reference, guidelines and examples are on the documentation site — the

package/codemods/README.md

@@ -0,0 +1,182 @@
+# Consumer codemods
+
+`radix-to-base-ui.ts` moves consumer code across the Base UI port (DECISIONS.md D12: only overlay
+dismissal interceptors left the surface). It is one transform for every family; consumers run it
+once on code that imports `@epilot/zenith-react`:
+
+```sh
+bunx jscodeshift@17.3.0 --parser=tsx -t node_modules/@epilot/zenith-react/codemods/radix-to-base-ui.ts src/
+```
+
+Every transform here prints each file it rewrites through your project's Prettier (resolved
+next to the file, with the config that applies to it), so the result passes your format check as
+it is; `.prettierignore` is not consulted. Without Prettier in the project the output keeps
+recast's formatting, the run says so once on stderr, and you run your formatter on the changed
+files.
+
+What it rewrites:
+
+| Content part             | Root whose `onOpenChange` takes the handlers | Props moved                                                                      |
+| ------------------------ | -------------------------------------------- | -------------------------------------------------------------------------------- |
+| `DialogContent`          | `Dialog`                                     | `onEscapeKeyDown`, `onPointerDownOutside`, `onInteractOutside`, `onFocusOutside` |
+| `AlertDialogContent`     | `AlertDialog`                                | `onEscapeKeyDown`, `onFocusOutside`                                              |
+| `DrawerContent`          | `Drawer`                                     | all four                                                                         |
+| `PopoverContent`         | `Popover`                                    | all four                                                                         |
+| `FieldComboboxContent`   | `FieldCombobox`                              | all four                                                                         |
+| `DropdownMenuContent`    | `DropdownMenu`                               | all four                                                                         |
+| `DropdownMenuSubContent` | `DropdownMenuSub`                            | all four                                                                         |
+| `SelectContent`          | `Select`                                     | `onEscapeKeyDown`, `onPointerDownOutside`                                        |
+| `TooltipContent`         | `Tooltip`                                    | `onEscapeKeyDown`, `onPointerDownOutside`                                        |
+
+Each handler becomes a check on Base UI's `eventDetails.reason` (`escape-key`, `outside-press`,
+`focus-out`), and one that calls `preventDefault()` keeps the overlay open through
+`eventDetails.cancel()`, as it did under Radix. A handler is called with the event only when it
+takes one: an inline function by its parameters, a reference by its declaration (a `const` or
+`function`, `useCallback`, a type annotation, a destructured prop whose type is written in the
+file, or one of those behind a relative import), so `const close = () => …` becomes `close?.()`
+and typechecks. A reference the file cannot explain (a package import, a member expression, a
+conditional) gets the event. A DropdownMenu item whose `onSelect` calls
+`preventDefault()` to keep the menu open is reported: the menu closes regardless under Base UI. Props
+a wrapper can still translate, such as `forceMount`, stay on the surface and need no rule.
+
+Each port added its own `<family>-base-ui.ts`; the Radix teardown (#97) folded them into this one
+before any release shipped them, with every family's fixtures.
+
+Rules for a transform:
+
+- Only touch named imports from `@epilot/zenith-react` (aliases resolved); leave Volt imports alone.
+- Each rule is a local, syntactic rewrite with no hand edits afterwards. Anything else gets a
+  `/* TODO(zenith-base-ui): … */` comment and an `api.report` line, so the run's output is the
+  list of places a human has to look.
+- Fixtures: `__testfixtures__/radix-to-base-ui-<family>-<case>.input.tsx` and `.output.tsx`, the
+  output being exactly what `--dry --print` emits (no report lines, no absolute paths), formatted
+  by the repository's own Prettier config as the transform prints it. Cover, per
+  family: the plain case, aliased imports, an inline handler, a handler reference, a
+  zero-parameter reference (a `const`, a `function` and an import from `handlers.ts`), and one
+  unsupported shape that gets the TODO.
+- `./run-fixtures.sh radix-to-base-ui` diffs every fixture of the transform. `fixtures.test.ts`
+  also reruns the transform over each expected output and requires a no-op, and typechecks the
+  outputs against the public types; the `-unsupported` fixtures keep the prop the transform cannot
+  rewrite and are the only outputs not typechecked.
+
+## Migrating to Zenith
+
+Two entry transforms in `migrate/` move consumer code onto `@epilot/zenith-react` from the
+predecessor libraries. Run one, work the report, then run `radix-to-base-ui.ts` (it is not
+chained: the predecessor APIs are the Radix-era ones). Both print through your project's
+Prettier, as above:
+
+```sh
+bunx jscodeshift@17.3.0 --parser=tsx -t node_modules/@epilot/zenith-react/codemods/migrate/from-volt.ts src/
+bunx jscodeshift@17.3.0 --parser=tsx -t node_modules/@epilot/zenith-react/codemods/migrate/from-base-elements.ts src/
+```
+
+The run's output is the TODO list. Every place a human has to look is one line,
+` REP <file> <line> <Component>: <fix>`, and the same text sits in the code as a
+`TODO(zenith-migrate): <Component>: <fix>` comment. The fix is concrete ("dropped `value={p}`:
+Spinner is indeterminate…"), so the reader needs no mapping document; look a component up only
+when its line says so. `rg 'TODO\(zenith-migrate\)'` lists what is left.
+
+### What each transform does
+
+`from-volt` (Volt 1.7): every name Zenith kept (279, the whole barrel minus the list below)
+moves onto the Zenith import unchanged; the `style.css`, `preflight.css` and `font.css` imports
+are deleted; `ColumnFiltersState`, `ColumnOrderState`, `ColumnPinningState`, `FilterFn` and
+`PaginationState` come from `@tanstack/react-table`; `cn`, `CloseIcon`, the `*Variants` helpers
+and `useClientPagination` stay on the Volt import with the replacement in their TODO
+(`mergeClasses` + `makeZenithStyles`; `calculatePagination`/`clampPage`). Then run the
+`radix-to-base-ui` transform: the Volt API is Radix-era.
+
+`from-base-elements` (3.10, MUI v4): syntactic renames with prop maps for `CircularProgress` →
+`Spinner`, `Divider` → `Separator`, `Skeleton`, `Avatar`/`AvatarGroup`, `Paper` → `Surface`,
+`Chip`/`Chip360` → `Pill`, structural rewrites for the button, form, dialog, typography,
+navigation and feedback families (the table below), and a one-line hint for everything else
+(`unsupported.ts`: Grid, Box, the spacing components, Icon, theme and `makeStyles`, MUI's count
+Badge, masked fields, LinearProgress, Drawer360, react-beautiful-dnd, transitions, and the
+same-name-different-API families such as Table and List). MUI theming props (`color="primary"`
+on a spinner, `classes`) are dropped and, where they change behaviour, reported. A legacy
+binding that is also used as a value (`styled(Paper)`, `component={Paper}`) stays on the legacy
+import with one TODO per use; only its JSX elements move. Re-exports, `import()`, `require` and
+`jest.mock`/`vi.mock` of the legacy package are reported, never rewritten.
+
+Dry run first and read the report (`--dry` writes nothing; add `--print` to see the output).
+Line numbers in the report are the input file's; after a write run, find each place by its
+`TODO(zenith-migrate)` comment instead. The `tsx` parser rejects the `<T>x` cast in `.ts`
+files: rewrite those as `x as T` before running.
+
+```sh
+bunx jscodeshift@17.3.0 --parser=tsx --extensions=tsx,ts,jsx,js --dry \
+  -t node_modules/@epilot/zenith-react/codemods/migrate/from-base-elements.ts src/ | grep ' REP '
+```
+
+### base-elements structural rules
+
+One module per family in `migrate/base-elements/` (shared helpers in `shared.ts`). Simple
+shapes are rewritten onto the Zenith parts; anything else still compiles and gets a TODO.
+
+| base-elements                                                                  | Zenith                                                                                                     | Rewritten                                                                                                                                                                                                                                                            | Reported                                                                                                              |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `Button`                                                                       | `Button`                                                                                                   | variant × color (contained → primary, outlined → secondary, text → tertiary or ghost), size, `startIcon`/`endIcon` as children, `href`/`component` → `asChild`, `fullWidth` → `width: 100%`, `type="button"` when MUI rendered a native button                       | a dynamic variant or size, MUI-only props                                                                             |
+| `IconButton`, `ElevatedIconButton`, `TooltipIconButton`                        | `Button size="icon…"`                                                                                      | small → `icon-xs`, medium → `icon`, large → `icon-lg`; ghost, primary or secondary; TooltipIconButton → Tooltip parts with its title as `aria-label`                                                                                                                 | no accessible name, `edge`                                                                                            |
+| `Dialog`, `DialogTitle`, `DialogContent`, `DialogActions`, `DialogContentText` | `Dialog` > `DialogContent` (the panel) > `DialogHeader`/`DialogTitle`, `DialogFooter`, `DialogDescription` | `onClose` → `onOpenChange`, `maxWidth` → panel `size` (nearest with `fullWidth`, else at most `lg`), `disableBackdropClick`/`disableEscapeKeyDown` → `preventDefault()` handlers, `showCloseButton={false}`; MUI's `DialogContent` is the body and becomes a `<div>` | the body's scrolling, an `onClose` that reads `(event, reason)`, ids Radix owns, `aria-labelledby` pointing elsewhere |
+| `TextField`                                                                    | `Field` + `FieldLabel` + `FieldInput`/`FieldTextarea` + `FieldDescription`/`FieldError`                    | input props, `inputProps`, `inputRef`, `multiline`/`rows`, `error` + `helperText`, `InputProps` adornments → `FieldInputGroup` + `FieldGroupAddon`                                                                                                                   | a label without an `id` to tie it to, `select`, a dynamic `multiline`, `margin`                                       |
+| `Typography`, `H1`–`H6`, `DisplayText`, `LargeText`, `BodyText`, `SmallText`   | `Text`                                                                                                     | variant by the epilot theme's sizes (h1–h4 → title3 … caption → body1), `textSecondary` → helper2/helper1, `gutterBottom`/`noWrap`/`align`/`customColor` → inline style                                                                                              | a lost heading level, block → inline next to siblings, colours Text has no variant for                                |
+| `Tooltip`                                                                      | `Tooltip` > `TooltipTrigger asChild` + `TooltipContent`                                                    | `placement` → `side`/`align` (MUI's bottom default written out), `enterDelay` → `delayDuration`                                                                                                                                                                      | the TooltipProvider Radix needs (once per file), a title that can be empty, MUI timing props                          |
+| `Switch`, `Checkbox`                                                           | `Switch`, `Checkbox`                                                                                       | `onChange(event, checked)` → `onCheckedChange(checked)`, `indeterminate` → `checked="indeterminate"`, `label` → a wrapping `Label`                                                                                                                                   | handler references, spread props (`{...field}`)                                                                       |
+| `TabContext`, `Tabs`, `TabList`, `PrimaryTabs`, `Tab`, `TabPanel`              | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`                                                           | the list's `onChange` → the root's `onValueChange`, `label` → children                                                                                                                                                                                               | numeric or missing tab values                                                                                         |
+| `Select` + `MenuItem`                                                          | `Select` > `SelectTrigger` > `SelectValue`, `SelectContent` > `SelectItem`                                 | static or `.map` items, `event.target.value` handlers, `placeholder`, `label` → `Field` + `FieldLabel`                                                                                                                                                               | other children, empty or null values, `renderValue`, `multiple`, a `MenuItem` outside a Select                        |
+| `Alert`, `Notification` (and Info/Error/Success), `FeedbackMessage`            | `Callout` + `CalloutTitle`/`CalloutDescription`/`CalloutAction`                                            | `severity`/`stateVariant` → `variant`, `onClose` → `dismissible onDismiss`, `visible` → a render condition                                                                                                                                                           | a dynamic severity, the feedback icon action                                                                          |
+| `Accordion`, `AccordionSummary`, `AccordionDetails`                            | `Accordion type="single" collapsible` > `AccordionItem` > `AccordionTrigger` + `AccordionContent`          | `defaultExpanded`/`expanded`/`onChange` → `defaultValue`/`value`/`onValueChange`                                                                                                                                                                                     | `AccordionActions`, handler references                                                                                |
+| `ToggleButtonGroup`, `ToggleButton`                                            | `SegmentedControl` (exclusive) or `ToggleGroup type="multiple"`                                            | `onChange` → `onValueChange`                                                                                                                                                                                                                                         | a dynamic `exclusive`, a `ToggleButton` on its own                                                                    |
+
+An inline MUI handler `(event, value) => …` becomes `(value) => …` when it reads only the value
+or `event.target.<prop>`; a handler reference keeps MUI's signature, so it is dropped and
+reported. Where Zenith's parts need Zenith's root (Dialog, Tabs, Accordion, ToggleButtonGroup),
+a family member used as a value (`styled(Dialog)`) keeps the whole family on base-elements: a
+Zenith part inside an MUI root breaks at runtime.
+
+### Rule contract
+
+One module per legacy component, listed in its source's registry (`migrate/volt/index.ts`,
+`migrate/base-elements/index.ts`). The contract is `migrate/lib/types.ts`:
+
+```ts
+export const handles = ["CircularProgress", "CircularProgressProps"] as const
+export function migrate(ctx: MigrateContext) {
+  ctx.move("CircularProgress", "Spinner") // onto the Zenith import; un-aliased bindings are renamed
+  ctx.move("CircularProgressProps", "SpinnerProps")
+  ctx.elements("CircularProgress").forEach((path) => {
+    ctx.jsx.removeAttr(path.node, "color")
+    const value = ctx.jsx.attr(path.node, "value")
+    if (value) {
+      ctx.jsx.removeAttr(path.node, "value")
+      ctx.todo(
+        path,
+        "CircularProgress",
+        `dropped ${ctx.jsx.print(value)}: Spinner is indeterminate`
+      )
+    }
+  })
+}
+```
+
+- `ctx.move(name, target?)` puts the legacy export on the Zenith import (merged into an existing
+  one); `ctx.keep(name, fix)` leaves it on the legacy import with one TODO at the import. A name
+  the rule neither moves nor keeps is kept with a generic TODO. A rule never edits imports itself.
+- `ctx.todo(path, component, fix)` adds the comment (a `{/* */}` sibling inside JSX children)
+  and the report line. `ctx.ensureZenith(name)` imports a Zenith export for a per-element rewrite
+  (`ctx.jsx.rename(el, ctx.ensureZenith("Spinner"))`) when only some elements can move.
+- `ctx.jsx` has the prop helpers: `attr`, `literal`, `removeAttr`, `renameAttr`, `setAttr`,
+  `mapAttrValue`, `wrapChildren`, `wrap`, `rename`, `styleObject`, `print`.
+- A moved element must compile against Zenith's types: drop what has no equivalent and name it
+  in the TODO, or keep the whole name on the legacy import. Theming-only props (`color="primary"`)
+  are dropped silently; anything that changes behaviour or layout is reported.
+- A rule that owns a bare module specifier (a stylesheet import) lists it in `handlesModules`.
+- Fixtures: `__testfixtures__/from-<source>-<component>-<case>.{input,output}.tsx`, with `plain`,
+  `aliased`, `partial` (names left on the legacy import) and one `todo` shape. `fixtures.test.ts`
+  runs every transform on its fixtures, asserts one report per TODO and a no-op rerun, and
+  typechecks the outputs against Zenith's public types (`tsconfig.fixtures.json`, with
+  `legacy-modules.d.ts` stubbing the predecessors) the way a consumer ends up with them: a
+  `from-*` output is first run through the `radix-to-base-ui` transform, since its Zenith
+  API is the Radix-era one. `./run-fixtures.sh <transform>` is the
+  per-transform CLI over the same test.

package/codemods/format.ts

@@ -0,0 +1,86 @@
+/**
+ * Prints a transform's output the way the project's formatter would, so the written file passes
+ * the project's Prettier check (#114). Prettier is resolved from the file's own location, so it is
+ * the project's copy under npm, bun and pnpm alike, and runs with the config that applies to the
+ * file. A project without Prettier gets recast's output as it is and one note on stderr to run
+ * its formatter on the changed files.
+ */
+import { createRequire } from "node:module"
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path"
+
+type Prettier = {
+  resolveConfig: (
+    file: string,
+    options?: { editorconfig?: boolean }
+  ) => Promise<Record<string, unknown> | null>
+  format: (
+    source: string,
+    options?: Record<string, unknown>
+  ) => Promise<string> | string
+}
+
+const loaded = new Map<string, Promise<Prettier | undefined>>()
+let noted = false
+
+export async function formatOutput(
+  output: string,
+  filePath: string
+): Promise<string> {
+  const file = resolve(filePath)
+  const prettier = await loadPrettier(file)
+  if (!prettier) {
+    if (!noted) {
+      noted = true
+      process.stderr.write(
+        `zenith codemods: no Prettier found from ${dirname(file)}; run your formatter on the changed files\n`
+      )
+    }
+    return output
+  }
+  try {
+    const config =
+      (await prettier.resolveConfig(file, { editorconfig: true })) ?? {}
+    return await prettier.format(output, { ...config, filepath: file })
+  } catch (error) {
+    process.stderr.write(
+      `zenith codemods: Prettier could not format ${file}: ${String(error)}\n`
+    )
+    return output
+  }
+}
+
+/** One resolution per directory: the same Prettier serves every file beside it. */
+function loadPrettier(file: string): Promise<Prettier | undefined> {
+  const dir = dirname(file)
+  let pending = loaded.get(dir)
+  if (!pending) {
+    pending = resolvePrettier(file)
+    loaded.set(dir, pending)
+  }
+  return pending
+}
+
+async function resolvePrettier(file: string): Promise<Prettier | undefined> {
+  try {
+    const id = createRequire(file).resolve("prettier")
+    if (!installedAbove(id, file)) return undefined
+    const loadedModule = (await import(id)) as { default?: Prettier } & Prettier
+    const prettier = loadedModule.default ?? loadedModule
+    return typeof prettier.format === "function" ? prettier : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Only the project's own copy formats: one in a `node_modules` above the file. Bun resolves a
+ * missing package from its global cache, which would format a project that never uses Prettier
+ * with Prettier's defaults.
+ */
+function installedAbove(resolved: string, file: string): boolean {
+  const index = resolved.indexOf(`${sep}node_modules${sep}`)
+  if (index < 0) return false
+  const project = resolved.slice(0, index)
+  const below = relative(project, file)
+  return below !== "" && !below.startsWith("..") && !isAbsolute(below)
+}

package/codemods/migrate/base-elements/accordion.ts

@@ -0,0 +1,132 @@
+/**
+ * Accordion / AccordionSummary / AccordionDetails → Accordion / AccordionItem /
+ * AccordionTrigger / AccordionContent.
+ *
+ * An MUI Accordion is one collapsible item; Zenith's Accordion is the group. Each MUI Accordion
+ * becomes `<Accordion type="single" collapsible>` around one `<AccordionItem value="item">`:
+ *
+ * - `defaultExpanded` → `defaultValue="item"`; `expanded={open}` → `value={open ? "item" : ""}`;
+ *   `onChange={(event, expanded) => …}` → `onValueChange={(expanded) => …}` with each read of
+ *   `expanded` as `expanded === "item"`. `disabled` goes to the item.
+ * - `expandIcon` is dropped (the trigger draws its own chevron), as are MUI's paper and
+ *   transition props. AccordionActions has no part: it stays, reported.
+ */
+import type { ASTPath, JSXElement } from "jscodeshift"
+import type { MigrateContext } from "../lib/types"
+import {
+  attrExpression,
+  attrValue,
+  isTrue,
+  nestChildren,
+  printAttr,
+  renamedAttr,
+  stringIn,
+  takeAttrs,
+  valueHandler,
+  familyStays,
+} from "./shared"
+
+export const handles = [
+  "Accordion",
+  "AccordionProps",
+  "AccordionSummary",
+  "AccordionSummaryProps",
+  "AccordionDetails",
+  "AccordionDetailsProps",
+  "AccordionActions",
+  "AccordionActionsProps",
+] as const
+
+const ITEM = "item"
+const SILENT = [
+  "TransitionComponent",
+  "TransitionProps",
+  "square",
+  "elevation",
+  "variant",
+  "classes",
+]
+
+export function migrate(ctx: MigrateContext): void {
+  if (
+    familyStays(
+      ctx,
+      ["Accordion", "AccordionSummary", "AccordionDetails", "AccordionActions"],
+      'migrate this accordion by hand: Accordion type="single" collapsible > AccordionItem > AccordionTrigger + AccordionContent'
+    )
+  )
+    return
+  ctx.move("Accordion")
+  ctx.move("AccordionProps")
+  ctx.move("AccordionSummary", "AccordionTrigger")
+  ctx.move("AccordionSummaryProps", "AccordionTriggerProps")
+  ctx.move("AccordionDetails", "AccordionContent")
+  ctx.move("AccordionDetailsProps", "AccordionContentProps")
+  const actions = "no part for actions: put them at the end of AccordionContent"
+  ctx.keep("AccordionActions", actions)
+  ctx.keep("AccordionActionsProps", actions)
+
+  ctx.elements("Accordion").forEach((path) => migrateAccordion(ctx, path))
+  ctx.elements("AccordionSummary").forEach((path) => {
+    takeAttrs(ctx, path.node, [
+      "expandIcon",
+      "IconButtonProps",
+      "aria-controls",
+      "id",
+    ])
+  })
+}
+
+function migrateAccordion(
+  ctx: MigrateContext,
+  path: ASTPath<JSXElement>
+): void {
+  const { j, jsx } = ctx
+  const el = path.node
+  const reported: string[] = []
+  const item = () => stringIn(ctx, ITEM)
+
+  const expanded = jsx.removeAttr(el, "expanded")
+  const defaultExpanded = jsx.removeAttr(el, "defaultExpanded")
+  const onChange = jsx.removeAttr(el, "onChange")
+  const disabled = jsx.removeAttr(el, "disabled")
+  takeAttrs(ctx, el, SILENT)
+
+  const openWhen = (a: NonNullable<typeof expanded>) =>
+    isTrue(ctx, a)
+      ? ITEM
+      : j.conditionalExpression(
+          attrValue(j, a) as never,
+          item() as never,
+          stringIn(ctx, "") as never
+        )
+  const attrs = [
+    j.jsxAttribute(j.jsxIdentifier("type"), jsx.str("single")),
+    j.jsxAttribute(j.jsxIdentifier("collapsible")),
+  ]
+  el.openingElement.attributes = [
+    ...attrs,
+    ...(el.openingElement.attributes ?? []),
+  ]
+  if (expanded) jsx.setAttr(el, "value", openWhen(expanded))
+  else if (defaultExpanded && jsx.literal(defaultExpanded) !== false)
+    jsx.setAttr(el, "defaultValue", openWhen(defaultExpanded))
+
+  if (onChange) {
+    const handler = valueHandler(j, attrExpression(onChange), {
+      valueName: "value",
+      mapValue: (value) =>
+        j.binaryExpression("===", value as never, item() as never),
+    })
+    if (handler) jsx.setAttr(el, "onValueChange", handler)
+    else
+      reported.push(
+        `dropped ${printAttr(ctx, onChange)} (onValueChange(value) passes "item" when it opens and "" when it closes)`
+      )
+  }
+
+  const itemAttrs = [j.jsxAttribute(j.jsxIdentifier("value"), jsx.str(ITEM))]
+  if (disabled) itemAttrs.push(renamedAttr(j, disabled, "disabled"))
+  nestChildren(j, el, ctx.ensureZenith("AccordionItem"), itemAttrs)
+  if (reported.length) ctx.todo(path, "Accordion", reported.join("; "))
+}

package/codemods/migrate/base-elements/alert.ts

@@ -0,0 +1,81 @@
+/**
+ * Alert → Callout.
+ *
+ * - `severity` → `variant` (error → destructive); MUI's default is success, Callout's info, so an
+ *   absent severity is written as `variant="success"`.
+ * - Children → `CalloutDescription`; `action` → a trailing `CalloutAction`; `onClose` →
+ *   `dismissible onDismiss`.
+ * - `icon={false}` → `hideIcon`, another icon → `customIcon`.
+ * - MUI's `variant`, `color`, `elevation` and base-elements' `isSmall` are theming: dropped.
+ */
+import type { ASTPath, JSXElement } from "jscodeshift"
+import type { MigrateContext } from "../lib/types"
+import {
+  SEVERITY,
+  fillCallout,
+  mapAttr,
+  printAttr,
+  printAttrs,
+  renamedAttr,
+  takeAttrs,
+  moveElements,
+} from "./shared"
+
+export const handles = ["Alert", "AlertProps"] as const
+
+export function migrate(ctx: MigrateContext): void {
+  moveElements(ctx, "Alert", "Callout", (path) => migrateAlert(ctx, path))
+  ctx.move("AlertProps", "CalloutProps")
+}
+
+function migrateAlert(ctx: MigrateContext, path: ASTPath<JSXElement>): void {
+  const { j, jsx } = ctx
+  const el = path.node
+  const reported: string[] = []
+
+  if (!jsx.attr(el, "severity")) jsx.setAttr(el, "variant", "success")
+  else if (
+    !mapAttr(ctx, el, "severity", SEVERITY, {
+      rename: "variant",
+      fallback: "info",
+    })
+  )
+    reported.push(
+      `dropped ${printAttr(ctx, takeAttrs(ctx, el, ["severity"])[0])} (variant: success | info | warning | destructive)`
+    )
+
+  const icon = jsx.removeAttr(el, "icon")
+  if (icon && jsx.literal(icon) === false) jsx.setAttr(el, "hideIcon", null)
+  else if (icon)
+    el.openingElement.attributes = [
+      ...(el.openingElement.attributes ?? []),
+      renamedAttr(j, icon, "customIcon"),
+    ]
+  takeAttrs(ctx, el, ["color", "isSmall", "elevation", "square"])
+  const variant = jsx.attr(el, "variant")
+  if (
+    variant &&
+    !["success", "info", "warning", "destructive"].includes(
+      String(jsx.literal(variant))
+    )
+  )
+    takeAttrs(ctx, el, ["variant"])
+  const unsupported = takeAttrs(ctx, el, [
+    "iconMapping",
+    "closeText",
+    "classes",
+  ])
+  if (unsupported.length)
+    reported.push(
+      `dropped ${printAttrs(ctx, unsupported)} (no Callout equivalent)`
+    )
+
+  reported.push(
+    ...fillCallout(ctx, el, {
+      description: el.children ?? [],
+      onClose: jsx.removeAttr(el, "onClose"),
+      action: jsx.removeAttr(el, "action"),
+    })
+  )
+  if (reported.length) ctx.todo(path, "Alert", reported.join("; "))
+}

package/codemods/migrate/base-elements/avatar.ts

@@ -0,0 +1,116 @@
+/**
+ * Avatar and AvatarGroup keep their names. MUI's initials are children; Zenith's are `initials`.
+ * Custom colours become the `color` family or a TODO; shapes other than round are reported.
+ */
+import type { MigrateContext } from "../lib/types"
+import { dropWithHint } from "./mui-props"
+
+export const handles = [
+  "Avatar",
+  "AvatarProps",
+  "AvatarGroup",
+  "AvatarGroupProps",
+] as const
+
+const COLORS =
+  "gray | blue | sky | cyan | teal | mint | green | lime | yellow | orange | bronze | red | pink | purple | indigo"
+
+export function migrate(ctx: MigrateContext): void {
+  const { jsx } = ctx
+  const avatars = ctx.elements("Avatar")
+  const groups = ctx.elements("AvatarGroup")
+  ctx.moveElements("Avatar")
+  ctx.moveElements("AvatarGroup")
+  ctx.move("AvatarProps")
+  ctx.move("AvatarGroupProps")
+
+  avatars.forEach((path) => {
+    const el = path.node
+    const children = (el.children ?? []).filter(
+      (c) => !(c.type === "JSXText" && c.value.trim() === "")
+    )
+    if (children.length === 1) {
+      const [child] = children
+      if (child.type === "JSXText") {
+        jsx.setAttr(el, "initials", child.value.trim())
+        jsx.setChildren(el, [])
+      } else if (
+        child.type === "JSXExpressionContainer" &&
+        child.expression.type !== "JSXEmptyExpression"
+      ) {
+        const literal =
+          child.expression.type === "StringLiteral"
+            ? child.expression.value
+            : undefined
+        jsx.setAttr(el, "initials", literal ?? (child.expression as never))
+        jsx.setChildren(el, [])
+      } else {
+        const printed = ctx.j(child as never).toSource()
+        jsx.setChildren(el, [])
+        ctx.todo(
+          path,
+          "Avatar",
+          `dropped child ${printed}: Avatar shows src= or initials= only; an icon avatar is a styled span`
+        )
+      }
+    } else if (children.length > 1) {
+      jsx.setChildren(el, [])
+      ctx.todo(
+        path,
+        "Avatar",
+        "dropped children: Avatar shows src= or initials= only (one text child becomes initials=)"
+      )
+    }
+
+    const variant = jsx.mapAttrValue(el, "variant", {
+      circle: null,
+      circular: null,
+    })
+    if (variant === "unknown" || variant === "dynamic") {
+      const printed = jsx.print(jsx.attr(el, "variant")!)
+      jsx.removeAttr(el, "variant")
+      ctx.todo(
+        path,
+        "Avatar",
+        `dropped ${printed}: Avatar is round; a square one is a styled span`
+      )
+    }
+
+    for (const name of ["backgroundColor", "borderColor"]) {
+      const attr = jsx.attr(el, name)
+      if (!attr) continue
+      jsx.removeAttr(el, name)
+      ctx.todo(
+        path,
+        "Avatar",
+        `dropped ${jsx.print(attr)}: pick color= (${COLORS}), or leave it unset to hash alt/initials`
+      )
+    }
+    for (const name of ["sizes", "srcSet", "imgProps"]) {
+      const attr = jsx.attr(el, name)
+      if (!attr) continue
+      jsx.removeAttr(el, name)
+      ctx.todo(
+        path,
+        "Avatar",
+        `dropped ${jsx.print(attr)}: Avatar takes src and alt only`
+      )
+    }
+    dropWithHint(ctx, path, "Avatar")
+  })
+
+  groups.forEach((path) => {
+    const el = path.node
+    jsx.removeAttr(el, "spacing")
+    const variant = jsx.attr(el, "variant")
+    if (variant) {
+      jsx.removeAttr(el, "variant")
+      ctx.todo(
+        path,
+        "AvatarGroup",
+        `dropped ${jsx.print(variant)}: avatars are round`
+      )
+    }
+    dropWithHint(ctx, path, "AvatarGroup")
+  })
+}