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

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

@@ -0,0 +1,910 @@
+/**
+ * Helpers shared by the structural base-elements rules: build parts, move props between
+ * elements, and rewrite MUI's `(event, value)` handlers into the value-only callbacks Zenith's
+ * primitives take. Not a rule: the registry does not list it.
+ */
+import type {
+  ASTNode,
+  ASTPath,
+  JSCodeshift,
+  JSXAttribute,
+  JSXElement,
+  JSXSpreadAttribute,
+} from "jscodeshift"
+import { detectQuote } from "../lib/source"
+import type { MigrateContext } from "../lib/types"
+
+export type Child = NonNullable<JSXElement["children"]>[number]
+type Expression = Parameters<JSCodeshift["expressionStatement"]>[0]
+type Fn = {
+  type: string
+  params: { type: string; name?: string; typeAnnotation?: unknown }[]
+  body: ASTNode
+}
+
+/** Source text of a node as it prints now (its original text when unchanged). */
+export function source(j: JSCodeshift, node: ASTNode): string {
+  return j(node as never).toSource()
+}
+
+/**
+ * Parses `code` into an expression that prints as written: recast reuses the text of parsed
+ * nodes, where it would lay out a built `{ width: "100%" }` over three lines.
+ */
+export function parseExpression(j: JSCodeshift, code: string): Expression {
+  const declarator = j(`const value = ${code}`)
+    .find(j.VariableDeclarator)
+    .paths()[0]
+  return declarator.node.init as Expression
+}
+
+/** A string literal in the file's own quote style, for expressions (JSX attributes use `"`). */
+export function stringIn(ctx: MigrateContext, value: string) {
+  return ctx.jsx.str(
+    value,
+    detectQuote(ctx.file.source) === "single" ? "'" : '"'
+  )
+}
+
+/**
+ * A JSX element that was an expression root (`return (<X />)`) keeps recast's `parenthesized`
+ * mark; among JSX children those parentheses would print as text.
+ */
+function unparenthesize(children: Child[]): Child[] {
+  for (const child of children) {
+    const extra = (child as { extra?: { parenthesized?: boolean } }).extra
+    if (extra?.parenthesized) extra.parenthesized = false
+  }
+  return children
+}
+
+/** `<tag {...attrs}>{children}</tag>`, self-closing when there are no children. */
+export function element(
+  j: JSCodeshift,
+  tag: string,
+  attrs: (JSXAttribute | JSXSpreadAttribute)[] = [],
+  children: Child[] = []
+): JSXElement {
+  const name = j.jsxIdentifier(tag)
+  if (children.length === 0)
+    return j.jsxElement(j.jsxOpeningElement(name, attrs, true), null, [])
+  return j.jsxElement(
+    j.jsxOpeningElement(name, attrs),
+    j.jsxClosingElement(j.jsxIdentifier(tag)),
+    unparenthesize(normalizeChildren(j, children))
+  )
+}
+
+/**
+ * Re-splits text children so recast keeps them when it reprints the element: it trims every
+ * text child, which would drop the space in `<b>x</b> world`. A line break becomes its own
+ * `"\n"` text (recast indents it) and a significant edge space becomes `{" "}`.
+ */
+export function normalizeChildren(j: JSCodeshift, children: Child[]): Child[] {
+  const out: Child[] = []
+  const lineBreak = () => {
+    const prev = out[out.length - 1]
+    if (!(prev?.type === "JSXText" && prev.value === "\n"))
+      out.push(j.jsxText("\n"))
+  }
+  const space = () => out.push(j.jsxExpressionContainer(j.stringLiteral(" ")))
+  for (const child of children) {
+    if (child.type !== "JSXText") {
+      out.push(child)
+      continue
+    }
+    if (!/\S/.test(child.value)) {
+      if (child.value.includes("\n")) lineBreak()
+      else out.push(child)
+      continue
+    }
+    const [, lead, body, trail] = child.value.match(/^(\s*)([\s\S]*?)(\s*)$/)!
+    if (lead.includes("\n")) lineBreak()
+    else if (lead) space()
+    out.push(j.jsxText(body))
+    if (trail.includes("\n")) lineBreak()
+    else if (trail) space()
+  }
+  return out
+}
+
+/** Whether the children span lines (any text child holds a line break). */
+export function isMultiline(children: Child[] | undefined): boolean {
+  return (children ?? []).some(
+    (c) => c.type === "JSXText" && c.value.includes("\n")
+  )
+}
+
+/**
+ * Sets the element's children, opening it up when it was self-closing. When the new array is
+ * as long as the parsed one, recast patches it slot by slot and loses the indentation of the
+ * new line breaks; an empty text child (it prints as nothing) makes it reprint the element.
+ */
+export function setChildren(
+  j: JSCodeshift,
+  el: JSXElement,
+  children: Child[]
+): void {
+  const parsed = (el as { original?: JSXElement | null }).original
+  if (children.length && parsed?.children?.length === children.length)
+    children = [...children, j.jsxText("")]
+  el.children = children
+  if (children.length === 0) {
+    el.openingElement.selfClosing = true
+    el.closingElement = null
+    return
+  }
+  el.openingElement.selfClosing = false
+  if (!el.closingElement)
+    el.closingElement = j.jsxClosingElement(el.openingElement.name)
+}
+
+/** `[child]`, or `["\n", child, "\n"]` when the surrounding children spanned lines. */
+export function onlyChild(
+  j: JSCodeshift,
+  child: Child,
+  multiline: boolean
+): Child[] {
+  return multiline ? [j.jsxText("\n"), child, j.jsxText("\n")] : [child]
+}
+
+/** Moves `el`'s children into a new `<tag {...attrs}>`, which becomes `el`'s only child. */
+export function nestChildren(
+  j: JSCodeshift,
+  el: JSXElement,
+  tag: string,
+  attrs: (JSXAttribute | JSXSpreadAttribute)[] = []
+): JSXElement {
+  const multiline = isMultiline(el.children)
+  const inner = element(j, tag, attrs, el.children ?? [])
+  setChildren(j, el, onlyChild(j, inner, multiline))
+  return inner
+}
+
+/** Adds `child` first or last, on its own line when the element's children span lines. */
+export function insertChild(
+  j: JSCodeshift,
+  el: JSXElement,
+  child: Child,
+  at: "start" | "end"
+): void {
+  const multiline = isMultiline(el.children)
+  const children = normalizeChildren(j, el.children ?? [])
+  const nl = () => j.jsxText("\n")
+  if (children.length === 0) setChildren(j, el, [child])
+  else if (!multiline)
+    setChildren(
+      j,
+      el,
+      at === "start" ? [child, ...children] : [...children, child]
+    )
+  else if (at === "start") setChildren(j, el, [nl(), child, ...children])
+  else setChildren(j, el, [...children, child, nl()])
+}
+
+/** Maps a string literal, or a conditional whose branches are string literals, through `map`. */
+export function mapStringExpression(
+  j: JSCodeshift,
+  expression: Expression | undefined,
+  map: (value: string) => string | undefined,
+  literal: (value: string) => Expression = (value) => j.stringLiteral(value)
+): Expression | undefined {
+  if (!expression) return undefined
+  if (
+    expression.type === "StringLiteral" ||
+    (expression.type === "Literal" &&
+      typeof (expression as { value: unknown }).value === "string")
+  ) {
+    const next = map(String((expression as { value: unknown }).value))
+    return next === undefined ? undefined : literal(next)
+  }
+  if (expression.type === "ConditionalExpression") {
+    const consequent = mapStringExpression(
+      j,
+      expression.consequent,
+      map,
+      literal
+    )
+    const alternate = mapStringExpression(j, expression.alternate, map, literal)
+    if (!consequent || !alternate) return undefined
+    return j.conditionalExpression(
+      expression.test,
+      consequent as never,
+      alternate as never
+    )
+  }
+  return undefined
+}
+
+/**
+ * `jsx.mapAttrValue` (literals and ternaries of literals) with a Zenith default and a rename: a
+ * value mapping to `fallback` drops the attribute (`undefined` in a ternary), and a mapped
+ * attribute takes the name `rename`, replacing one of that name. Returns `false`, leaving the
+ * attribute as it was, when the value is dynamic or unmapped (the caller reports it); `true`
+ * when mapped or absent.
+ */
+export function mapAttr(
+  ctx: MigrateContext,
+  el: JSXElement,
+  name: string,
+  map: Readonly<Record<string, string>>,
+  { rename = name, fallback }: { rename?: string; fallback?: string } = {}
+): boolean {
+  const table: Record<string, string | null> = {}
+  for (const [key, value] of Object.entries(map))
+    table[key] = value === fallback ? null : value
+  const result = ctx.jsx.mapAttrValue(el, name, table)
+  if (result === "dynamic" || result === "unknown") return false
+  if (result === "mapped" && rename !== name && ctx.jsx.attr(el, name)) {
+    ctx.jsx.removeAttr(el, rename)
+    ctx.jsx.renameAttr(el, name, rename)
+  }
+  return true
+}
+
+/**
+ * MUI's ButtonBase renders `type="button"` unless told otherwise; a Zenith Button renders a
+ * bare `<button>`, which submits its form. Adds `type="button"` to an element that renders a
+ * native button and has no `type`, ahead of any spread so a spread `type` still wins.
+ */
+export function defaultButtonType(ctx: MigrateContext, el: JSXElement): void {
+  if (ctx.jsx.attr(el, "type") || ctx.jsx.attr(el, "asChild")) return
+  el.openingElement.attributes = [
+    ctx.j.jsxAttribute(ctx.j.jsxIdentifier("type"), ctx.jsx.str("button")),
+    ...(el.openingElement.attributes ?? []),
+  ]
+}
+
+/** Children that are not whitespace-only text. */
+export function contentChildren(el: JSXElement): Child[] {
+  return (el.children ?? []).filter(
+    (c) => !(c.type === "JSXText" && !c.value.trim())
+  )
+}
+
+/** Removes the named attributes and returns those present, in source order. */
+export function takeAttrs(
+  ctx: MigrateContext,
+  el: JSXElement,
+  names: readonly string[]
+): JSXAttribute[] {
+  const taken = ctx.jsx
+    .attrs(el)
+    .filter((a) => names.includes(ctx.jsx.attrName(a)))
+  for (const a of taken) ctx.jsx.removeAttr(el, ctx.jsx.attrName(a))
+  return taken
+}
+
+/** Removes every attribute not in `keep` (spreads stay) and returns the removed ones. */
+export function takeAttrsExcept(
+  ctx: MigrateContext,
+  el: JSXElement,
+  keep: (name: string) => boolean
+): JSXAttribute[] {
+  const names = ctx.jsx
+    .attrs(el)
+    .map((a) => ctx.jsx.attrName(a))
+    .filter((n) => !keep(n))
+  return takeAttrs(ctx, el, names)
+}
+
+/**
+ * One attribute as printed source, for a TODO message, which is one report line: a multi-line
+ * value is collapsed onto one line, a very long one prints as `name={…}`.
+ */
+export function printAttr(ctx: MigrateContext, a: JSXAttribute): string {
+  // One line, so the report stays one line per TODO; long values abbreviate (the diff has them).
+  const printed = ctx.jsx.print(a).replace(/\s*\n\s*/g, " ")
+  if (printed.length <= 160) return printed
+  return `${ctx.jsx.attrName(a)}={…}`
+}
+
+/** `a={b} c="d"`: attributes as printed source, for a TODO message. */
+export function printAttrs(
+  ctx: MigrateContext,
+  attrs: readonly JSXAttribute[]
+): string {
+  return attrs.map((a) => printAttr(ctx, a)).join(" ")
+}
+
+/** The expression inside `name={…}`, or `undefined` for a string or bare attribute. */
+export function attrExpression(
+  a: JSXAttribute | undefined
+): Expression | undefined {
+  const v = a?.value
+  if (v?.type !== "JSXExpressionContainer") return undefined
+  if (v.expression.type === "JSXEmptyExpression") return undefined
+  return v.expression as Expression
+}
+
+/** The value of an attribute as an expression: `"x"` → `"x"`, `{e}` → `e`, bare → `true`. */
+export function attrValue(j: JSCodeshift, a: JSXAttribute): Expression {
+  const v = a.value
+  if (v == null) return j.booleanLiteral(true)
+  if (v.type === "JSXExpressionContainer")
+    return v.expression as unknown as Expression
+  if (v.type === "StringLiteral" || v.type === "Literal")
+    return j.stringLiteral(String(v.value))
+  return v as unknown as Expression
+}
+
+/** A copy of `a` under a new name (the value node is shared, the attribute is not). */
+export function renamedAttr(
+  j: JSCodeshift,
+  a: JSXAttribute,
+  name: string
+): JSXAttribute {
+  return j.jsxAttribute(j.jsxIdentifier(name), a.value)
+}
+
+/** Whether an attribute is `name`, `name={true}` (a literal `true`). */
+export function isTrue(ctx: MigrateContext, a: JSXAttribute | undefined) {
+  return ctx.jsx.literal(a) === true
+}
+
+/** The nearest JSX element ancestor whose tag is `tag`. */
+export function closestElement(
+  path: ASTPath,
+  tag: string
+): ASTPath<JSXElement> | undefined {
+  let current = path.parent as ASTPath | null
+  while (current) {
+    const node = current.node as JSXElement
+    if (
+      node.type === "JSXElement" &&
+      node.openingElement.name.type === "JSXIdentifier" &&
+      node.openingElement.name.name === tag
+    )
+      return current as ASTPath<JSXElement>
+    current = current.parent
+  }
+  return undefined
+}
+
+/** Whether `path` sits among JSX children, where an element may be replaced by `{expr}`. */
+export function inJsxChildren(path: ASTPath): boolean {
+  const parent = path.parent?.node as { type?: string } | undefined
+  return parent?.type === "JSXElement" || parent?.type === "JSXFragment"
+}
+
+/** `cond && <el />`, as a JSX child `{…}` or as a plain expression elsewhere. */
+export function renderWhen(
+  j: JSCodeshift,
+  path: ASTPath<JSXElement>,
+  condition: Expression,
+  el: JSXElement
+): void {
+  const expression = j.logicalExpression("&&", condition as never, el)
+  path.replace(
+    inJsxChildren(path) ? j.jsxExpressionContainer(expression) : expression
+  )
+}
+
+/** The names an expression references or declares, to pick a fresh parameter name. */
+function namesIn(j: JSCodeshift, node: ASTNode): Set<string> {
+  const names = new Set<string>()
+  j(node as never)
+    .find(j.Identifier)
+    .forEach((p) => {
+      const parent = p.parent?.node
+      const property =
+        (parent?.type === "MemberExpression" ||
+          parent?.type === "OptionalMemberExpression") &&
+        parent.property === p.node &&
+        !parent.computed
+      if (!property) names.add(p.node.name)
+    })
+  return names
+}
+
+export function freshName(
+  j: JSCodeshift,
+  node: ASTNode,
+  preferred: string
+): string {
+  const taken = namesIn(j, node)
+  if (!taken.has(preferred)) return preferred
+  const next = `next${preferred[0].toUpperCase()}${preferred.slice(1)}`
+  if (!taken.has(next)) return next
+  let i = 2
+  while (taken.has(`${preferred}${i}`)) i += 1
+  return `${preferred}${i}`
+}
+
+function isFunction(node: ASTNode | undefined): node is ASTNode & Fn {
+  return (
+    !!node &&
+    (node.type === "ArrowFunctionExpression" ||
+      node.type === "FunctionExpression")
+  )
+}
+
+/** Identifier paths in `fn`'s body that reference the binding `name` (keys excluded). */
+function references(
+  j: JSCodeshift,
+  fn: Fn,
+  name: string
+): ASTPath<ASTNode & { name: string }>[] {
+  return j(fn.body as never)
+    .find(j.Identifier, { name })
+    .filter((p) => {
+      const parent = p.parent.node
+      if (
+        (parent.type === "MemberExpression" ||
+          parent.type === "OptionalMemberExpression") &&
+        parent.property === p.node &&
+        !parent.computed
+      )
+        return false
+      if (
+        (parent.type === "ObjectProperty" || parent.type === "Property") &&
+        parent.key === p.node &&
+        !parent.computed &&
+        !parent.shorthand
+      )
+        return false
+      return true
+    })
+    .paths() as never
+}
+
+/** `event.target.<prop>` / `event.currentTarget.<prop>` around a reference path, if it is one. */
+function targetRead(path: ASTPath, prop: string): ASTPath | undefined {
+  const inner = path.parent
+  const n = inner?.node
+  if (
+    !n ||
+    n.type !== "MemberExpression" ||
+    n.object !== path.node ||
+    n.computed ||
+    n.property.type !== "Identifier" ||
+    (n.property.name !== "target" && n.property.name !== "currentTarget")
+  )
+    return undefined
+  const outer = inner.parent
+  const m = outer?.node
+  if (
+    !m ||
+    m.type !== "MemberExpression" ||
+    m.object !== n ||
+    m.computed ||
+    m.property.type !== "Identifier" ||
+    m.property.name !== prop
+  )
+    return undefined
+  return outer
+}
+
+export type ValueHandlerOptions = {
+  /** What MUI's handler read from the event: `event.target.<prop>` becomes the value. */
+  targetProp?: string
+  /** Preferred name for the value parameter when the handler had none. */
+  valueName: string
+  /** Wraps every read of the value (`checked` → `checked === true` for a tri-state checkbox). */
+  mapValue?: (value: Expression) => Expression
+}
+
+/**
+ * Rewrites MUI's `(event, value) => …` into `(value) => …`, for an inline arrow or function
+ * whose event parameter is unused or read only as `event.target.<targetProp>`. Returns the
+ * rewritten function, or `undefined` for any other shape (a handler reference, a used event):
+ * the caller reports a TODO.
+ */
+export function valueHandler(
+  j: JSCodeshift,
+  expression: Expression | undefined,
+  options: ValueHandlerOptions
+): Expression | undefined {
+  // `((_, v: T) => …) as never` only quietened MUI's handler type: unwrap the cast.
+  while (
+    expression &&
+    (expression.type === "TSAsExpression" ||
+      expression.type === "TSSatisfiesExpression" ||
+      expression.type === "TSNonNullExpression")
+  )
+    expression = expression.expression as Expression
+  if (!isFunction(expression as ASTNode)) return undefined
+  const fn = expression as unknown as Fn
+  const [event, value, ...rest] = fn.params
+  if (rest.length) return undefined
+  if (event && event.type !== "Identifier") return undefined
+  if (value && value.type !== "Identifier") return undefined
+
+  const eventReads: ASTPath[] = []
+  if (event) {
+    for (const ref of references(j, fn, event.name!)) {
+      const read = options.targetProp
+        ? targetRead(ref, options.targetProp)
+        : undefined
+      if (!read) return undefined
+      eventReads.push(read)
+    }
+  }
+
+  const valueName = value
+    ? value.name!
+    : freshName(j, fn.body, options.valueName)
+  // A narrower annotation than the primitive passes (`v: "a" | "b"`) becomes a cast at each
+  // read, since the parameter itself must accept what Zenith passes.
+  const annotation = (
+    value?.typeAnnotation as { typeAnnotation?: ASTNode } | undefined
+  )?.typeAnnotation
+  const cast =
+    annotation &&
+    !["TSStringKeyword", "TSBooleanKeyword", "TSAnyKeyword"].includes(
+      annotation.type
+    )
+      ? source(j, annotation)
+      : undefined
+  const valueRef = (): Expression =>
+    cast
+      ? parseExpression(j, `${valueName} as ${cast}`)
+      : j.identifier(valueName)
+  const mapped = () =>
+    options.mapValue ? options.mapValue(valueRef()) : valueRef()
+
+  if (value && (options.mapValue || cast))
+    for (const ref of references(j, fn, valueName)) ref.replace(mapped())
+  for (const read of eventReads) read.replace(mapped())
+
+  // Rebuilt from source text so the parameter keeps its parentheses and the body its layout.
+  const params = event || value ? valueName : ""
+  const body = source(j, fn.body)
+  return parseExpression(
+    j,
+    fn.type === "ArrowFunctionExpression"
+      ? `(${params}) => ${body}`
+      : `function (${params}) ${body}`
+  )
+}
+
+/**
+ * `onClose={fn}` → `(open) => { if (!open) fn() }`: MUI's close callback as a Radix
+ * `onOpenChange`. Inline functions must take no parameters (their body moves under the
+ * `if`); a reference is called with no arguments, so a handler that needs MUI's
+ * `(event, reason)` fails the typecheck instead of silently changing. `undefined` for other
+ * shapes.
+ */
+export function closeAsOpenChange(
+  j: JSCodeshift,
+  expression: Expression | undefined
+): Expression | undefined {
+  if (!expression) return undefined
+  const open = freshName(j, expression as ASTNode, "open")
+  if (isFunction(expression as ASTNode)) {
+    const fn = expression as unknown as Fn
+    if (fn.params.length) return undefined
+    const body = source(j, fn.body)
+    return parseExpression(
+      j,
+      fn.body.type === "BlockStatement"
+        ? `(${open}) => {\n  if (!${open}) ${body.replace(/\n/g, "\n  ")}\n}`
+        : `(${open}) => { if (!${open}) ${body} }`
+    )
+  }
+  if (
+    expression.type === "Identifier" ||
+    expression.type === "MemberExpression"
+  )
+    return parseExpression(
+      j,
+      `(${open}) => { if (!${open}) ${source(j, expression)}() }`
+    )
+  return undefined
+}
+
+/**
+ * Replaces `path`'s element with `<tag {...attrs}>…before, element, …after</tag>` and returns the
+ * path of the (original) element inside it, whose source line a TODO can still report.
+ */
+export function wrapElement(
+  j: JSCodeshift,
+  path: ASTPath<JSXElement>,
+  tag: string,
+  attrs: JSXAttribute[],
+  before: Child[],
+  after: Child[]
+): ASTPath<JSXElement> {
+  const node = path.node
+  const wrapper = element(j, tag, attrs, [...before, node, ...after])
+  const [wrapperPath] = path.replace(wrapper) as ASTPath<JSXElement>[]
+  return wrapperPath.get("children", wrapper.children!.indexOf(node))
+}
+
+export type CheckedControlOptions = {
+  /** Radix Checkbox passes `boolean | "indeterminate"`: reads of the value become `=== true`. */
+  tristate: boolean
+  /** MUI `size` → Zenith `size`; `undefined` drops the prop silently. */
+  sizes?: Record<string, string>
+  fallbackSize?: string
+}
+
+/**
+ * Switch / Checkbox: `onChange(event, checked)` → `onCheckedChange(checked)` for inline handlers
+ * that read only the second parameter or `event.target.checked`; base-elements' `label` and
+ * `labelPlacement` → a wrapping Zenith `<Label>`. Everything else is reported.
+ */
+export function migrateCheckedControl(
+  ctx: MigrateContext,
+  path: ASTPath<JSXElement>,
+  component: string,
+  options: CheckedControlOptions
+): void {
+  const { j, jsx } = ctx
+  const el = path.node
+  const reported: string[] = []
+
+  const onChange = jsx.attr(el, "onChange")
+  if (onChange) {
+    const handler = valueHandler(j, attrExpression(onChange), {
+      targetProp: "checked",
+      valueName: "checked",
+      mapValue: options.tristate
+        ? (value) =>
+            j.binaryExpression("===", value as never, j.booleanLiteral(true))
+        : undefined,
+    })
+    if (handler) {
+      onChange.name = j.jsxIdentifier("onCheckedChange")
+      onChange.value = j.jsxExpressionContainer(handler as never)
+    } else {
+      jsx.removeAttr(el, "onChange")
+      reported.push(
+        `dropped ${printAttr(ctx, onChange)} (onCheckedChange(checked) passes only the new state${options.tristate ? ', true | false | "indeterminate"' : ""}; call your handler with it)`
+      )
+    }
+  }
+
+  if (options.tristate) {
+    const indeterminate = jsx.removeAttr(el, "indeterminate")
+    const checked = jsx.attr(el, "checked")
+    if (indeterminate && jsx.literal(indeterminate) !== false) {
+      const value = stringIn(ctx, "indeterminate")
+      if (isTrue(ctx, indeterminate))
+        jsx.setAttr(el, "checked", "indeterminate")
+      else
+        jsx.setAttr(
+          el,
+          "checked",
+          j.conditionalExpression(
+            attrValue(j, indeterminate) as never,
+            value as never,
+            (checked ? attrValue(j, checked) : j.booleanLiteral(false)) as never
+          )
+        )
+    }
+  }
+
+  if (options.sizes) {
+    if (
+      !mapAttr(ctx, el, "size", options.sizes, {
+        fallback: options.fallbackSize,
+      })
+    )
+      reported.push(
+        `dropped ${printAttrs(ctx, takeAttrs(ctx, el, ["size"]))} (size: ${Object.values(options.sizes).join(" | ")})`
+      )
+  } else takeAttrs(ctx, el, ["size"])
+  takeAttrs(ctx, el, ["color", "disableRipple", "disableFocusRipple"])
+
+  const unsupported = takeAttrs(ctx, el, [
+    "inputProps",
+    "inputRef",
+    "edge",
+    "icon",
+    "checkedIcon",
+    "indeterminateIcon",
+    "classes",
+    "checkboxPlacement",
+  ])
+  if (unsupported.length)
+    reported.push(
+      `dropped ${printAttrs(ctx, unsupported)} (no Zenith equivalent)`
+    )
+
+  // Spread props ({...field}, {...register("x")}) carry an onChange that Radix's button root
+  // never fires; the checked state has to be wired by hand.
+  for (const spread of el.openingElement.attributes ?? [])
+    if (spread.type === "JSXSpreadAttribute")
+      reported.push(
+        `${source(j, spread)} reaches Radix's button root, which never fires onChange: pass checked and onCheckedChange explicitly (react-hook-form: a Controller)`
+      )
+
+  const label = jsx.removeAttr(el, "label")
+  const placement = jsx.removeAttr(el, "labelPlacement")
+  let todoPath = path
+  if (label) {
+    const where = placement ? jsx.literal(placement) : "end"
+    if (where !== "end" && where !== "start")
+      reported.push(
+        `dropped ${printAttr(ctx, placement!)} (the Label lays control and text out in a row; stack them yourself)`
+      )
+    const text = jsx.childFromValue(label)
+    const nl = () => j.jsxText("\n")
+    todoPath =
+      where === "start"
+        ? wrapElement(
+            j,
+            path,
+            ctx.ensureZenith("Label"),
+            [],
+            [nl(), text, nl()],
+            [nl()]
+          )
+        : wrapElement(
+            j,
+            path,
+            ctx.ensureZenith("Label"),
+            [],
+            [nl()],
+            [nl(), text, nl()]
+          )
+  }
+  if (reported.length) ctx.todo(todoPath, component, reported.join("; "))
+}
+
+/**
+ * A close callback as a no-argument one (Callout `onDismiss`, Accordion `onValueChange` reads):
+ * a reference as is (the typecheck catches a handler that needs the event), an inline function
+ * whose parameters are unused without them. `undefined` when a parameter is read.
+ */
+export function withoutParams(
+  j: JSCodeshift,
+  expression: Expression | undefined
+): Expression | undefined {
+  if (!expression) return undefined
+  if (
+    expression.type === "Identifier" ||
+    expression.type === "MemberExpression"
+  )
+    return expression
+  if (!isFunction(expression as ASTNode)) return undefined
+  const fn = expression as unknown as Fn
+  if (!fn.params.length) return expression
+  for (const param of fn.params) {
+    if (param.type !== "Identifier") return undefined
+    if (references(j, fn, param.name!).length) return undefined
+  }
+  const body = source(j, fn.body)
+  return parseExpression(
+    j,
+    fn.type === "ArrowFunctionExpression"
+      ? `() => ${body}`
+      : `function () ${body}`
+  )
+}
+
+/** MUI Alert severity → Callout variant. */
+export const SEVERITY: Record<string, string> = {
+  success: "success",
+  info: "info",
+  warning: "warning",
+  error: "destructive",
+}
+
+export type CalloutParts = {
+  title?: JSXAttribute
+  /** Children of CalloutDescription. */
+  description: Child[]
+  /** `onClose` → `dismissible onDismiss`. */
+  onClose?: JSXAttribute
+  /** `action` → a trailing CalloutAction. */
+  action?: JSXAttribute
+}
+
+/**
+ * Fills a Callout element in place: title and description parts, a dismiss handler and an
+ * action. Returns what it could not carry over, for the caller's TODO.
+ */
+export function fillCallout(
+  ctx: MigrateContext,
+  el: JSXElement,
+  parts: CalloutParts
+): string[] {
+  const { j, jsx } = ctx
+  const reported: string[] = []
+  const children: Child[] = []
+  const nl = () => j.jsxText("\n")
+  if (parts.title)
+    children.push(
+      nl(),
+      element(
+        j,
+        ctx.ensureZenith("CalloutTitle"),
+        [],
+        [jsx.childFromValue(parts.title)]
+      )
+    )
+  const description = parts.description.filter(
+    (c) => !(c.type === "JSXText" && !c.value.trim())
+  )
+  if (description.length)
+    children.push(
+      nl(),
+      element(j, ctx.ensureZenith("CalloutDescription"), [], parts.description)
+    )
+  if (parts.action)
+    children.push(
+      nl(),
+      element(
+        j,
+        ctx.ensureZenith("CalloutAction"),
+        [],
+        [jsx.childFromValue(parts.action)]
+      )
+    )
+  if (children.length) children.push(nl())
+  setChildren(j, el, children)
+
+  if (parts.onClose) {
+    const handler = withoutParams(j, attrExpression(parts.onClose))
+    if (handler) {
+      jsx.setAttr(el, "dismissible", null)
+      jsx.setAttr(el, "onDismiss", handler)
+    } else
+      reported.push(
+        `dropped ${printAttr(ctx, parts.onClose)} (Callout dismissible + onDismiss() takes no event)`
+      )
+  }
+  return reported
+}
+
+/**
+ * Reports each use of legacy `name` as a value (`styled(X)`, `component={X}`) on its statement,
+ * in the wording of the runner's `moveElements` plus `fix`, for a rule that keeps the name
+ * itself (a family that stays, a body that stays MUI's). Returns the number of uses.
+ */
+export function reportValueUses(
+  ctx: MigrateContext,
+  name: string,
+  fix: string
+): number {
+  if (!ctx.names[name]) return 0
+  const { j } = ctx
+  const uses = ctx.valueUses(name)
+  uses.forEach((path) => {
+    let statement = (j(path).closest(j.Statement).paths()[0] ?? path) as ASTPath
+    if (
+      /^Export(Named|Default)Declaration$/.test(
+        String(statement.parent?.node.type ?? "")
+      )
+    )
+      statement = statement.parent
+    ctx.todo(
+      statement,
+      name,
+      `${source(j, path.parent.node)}: ${name} is used as a value here, so it stays on ${ctx.source}; ${fix}`
+    )
+  })
+  return uses.size()
+}
+
+/** The runner's `moveElements`, then `each` on every element it moved. */
+export function moveElements(
+  ctx: MigrateContext,
+  name: string,
+  target: string,
+  each: (path: ASTPath<JSXElement>) => void
+): void {
+  const paths = ctx.elements(name).paths()
+  ctx.moveElements(name, target)
+  paths.forEach(each)
+}
+
+/**
+ * For a family whose Zenith parts need the Zenith root's context (Dialog, Tabs, Accordion,
+ * ToggleButtonGroup): when any member is used as a value (`styled(TabContext)`), nothing in the
+ * family is migrated, since a Zenith part inside a base-elements root breaks at runtime. The
+ * uses are reported with `fix` and every name stays silently; `true` when the family stays.
+ */
+export function familyStays(
+  ctx: MigrateContext,
+  names: readonly string[],
+  fix: string
+): boolean {
+  const used = names.filter((n) => ctx.names[n] && ctx.valueUses(n).size() > 0)
+  if (!used.length) return false
+  for (const n of used) reportValueUses(ctx, n, fix)
+  for (const n of names) ctx.keep(n)
+  return true
+}