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

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

@@ -0,0 +1,55 @@
+/**
+ * Registry of base-elements rules. One module per component; every module exports `handles` and
+ * `migrate` (see `../lib/types.ts`). Order does not matter: each legacy name has exactly one
+ * owner, and the runner rejects duplicates.
+ */
+import type { MigrationRule } from "../lib/types"
+import * as accordion from "./accordion"
+import * as alert from "./alert"
+import * as avatar from "./avatar"
+import * as button from "./button"
+import * as checkbox from "./checkbox"
+import * as chip from "./chip"
+import * as chip360 from "./chip360"
+import * as circularProgress from "./circular-progress"
+import * as dialog from "./dialog"
+import * as iconButton from "./icon-button"
+import * as divider from "./divider"
+import * as feedbackMessage from "./feedback-message"
+import * as notification from "./notification"
+import * as paper from "./paper"
+import * as select from "./select"
+import * as skeleton from "./skeleton"
+import * as switchControl from "./switch"
+import * as tabs from "./tabs"
+import * as textField from "./text-field"
+import * as toggleButton from "./toggle-button"
+import * as tooltip from "./tooltip"
+import * as typography from "./typography"
+import * as unsupported from "./unsupported"
+
+export const rules: readonly MigrationRule[] = [
+  circularProgress,
+  divider,
+  skeleton,
+  avatar,
+  paper,
+  chip,
+  chip360,
+  unsupported,
+  button,
+  dialog,
+  textField,
+  typography,
+  tooltip,
+  switchControl,
+  checkbox,
+  tabs,
+  iconButton,
+  select,
+  alert,
+  notification,
+  feedbackMessage,
+  accordion,
+  toggleButton,
+]

package/codemods/migrate/base-elements/mui-props.ts

@@ -0,0 +1,29 @@
+/**
+ * MUI v4 props that every base-elements component accepts and no Zenith component does. A rule
+ * drops them from a moved element and reports each with its replacement.
+ */
+import type { ASTPath, JSXElement } from "jscodeshift"
+import type { MigrateContext } from "../lib/types"
+
+export const MUI_PROP_HINTS: Record<string, string> = {
+  classes: "style the slot with makeZenithStyles and pass className",
+  component:
+    "the element renders its own tag; wrap it, or use asChild where the part offers it",
+  innerRef: "use ref (every Zenith component forwards it)",
+}
+
+/** Drops `names` (default: the MUI set) from the element, one TODO per prop found. */
+export function dropWithHint(
+  ctx: MigrateContext,
+  path: ASTPath<JSXElement>,
+  component: string,
+  hints: Record<string, string> = MUI_PROP_HINTS
+): void {
+  for (const [name, hint] of Object.entries(hints)) {
+    const attr = ctx.jsx.attr(path.node, name)
+    if (!attr) continue
+    const printed = ctx.jsx.print(attr)
+    ctx.jsx.removeAttr(path.node, name)
+    ctx.todo(path, component, `dropped ${printed}: ${hint}`)
+  }
+}

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

@@ -0,0 +1,98 @@
+/**
+ * Notification, InfoNotification, ErrorNotification, SuccessNotification → Callout.
+ *
+ * - `title` → `CalloutTitle`; `message` and the children → `CalloutDescription`.
+ * - `severity` → `variant` (error → destructive; Notification's default info is Callout's too).
+ *   The Info/Error/Success variants fix it and hide the icon, as they did.
+ * - `visible` (default false: the notification collapsed) → rendered when it is set,
+ *   `{visible && <Callout …>}`; an absent `visible` is reported, since MUI rendered nothing.
+ * - `onClose` → `dismissible onDismiss`.
+ */
+import type { ASTPath, JSXElement } from "jscodeshift"
+import type { MigrateContext } from "../lib/types"
+import {
+  SEVERITY,
+  attrValue,
+  fillCallout,
+  isTrue,
+  mapAttr,
+  printAttrs,
+  renderWhen,
+  takeAttrs,
+  moveElements,
+} from "./shared"
+
+const FIXED: Record<string, string | undefined> = {
+  Notification: undefined,
+  InfoNotification: "info",
+  ErrorNotification: "destructive",
+  SuccessNotification: "success",
+}
+
+export const handles = [...Object.keys(FIXED), "BaseNotificationProps"] as const
+
+export function migrate(ctx: MigrateContext): void {
+  for (const name of Object.keys(FIXED)) {
+    moveElements(ctx, name, "Callout", (path) =>
+      migrateNotification(ctx, path, name)
+    )
+  }
+  ctx.move("BaseNotificationProps", "CalloutProps")
+}
+
+function migrateNotification(
+  ctx: MigrateContext,
+  path: ASTPath<JSXElement>,
+  component: string
+): void {
+  const { j, jsx } = ctx
+  const el = path.node
+  const reported: string[] = []
+
+  const fixed = FIXED[component]
+  if (fixed) {
+    jsx.removeAttr(el, "severity")
+    if (fixed !== "info") jsx.setAttr(el, "variant", fixed)
+    jsx.setAttr(el, "hideIcon", null)
+  } else if (
+    !mapAttr(ctx, el, "severity", SEVERITY, {
+      rename: "variant",
+      fallback: "info",
+    })
+  )
+    reported.push(
+      `dropped ${printAttrs(ctx, takeAttrs(ctx, el, ["severity"]))} (variant: success | info | warning | destructive)`
+    )
+  takeAttrs(ctx, el, ["color", "elevation"])
+  const unsupported = takeAttrs(ctx, el, [
+    "icon",
+    "iconMapping",
+    "closeText",
+    "classes",
+  ])
+  if (unsupported.length)
+    reported.push(
+      `dropped ${printAttrs(ctx, unsupported)} (no Callout equivalent)`
+    )
+
+  const message = jsx.removeAttr(el, "message")
+  reported.push(
+    ...fillCallout(ctx, el, {
+      title: jsx.removeAttr(el, "title"),
+      description: [
+        ...(message ? [jsx.childFromValue(message)] : []),
+        ...(el.children ?? []),
+      ],
+      onClose: jsx.removeAttr(el, "onClose"),
+    })
+  )
+
+  const visible = jsx.removeAttr(el, "visible")
+  if (!visible)
+    reported.push(
+      `${component} without visible rendered nothing (it defaults to false): render the Callout only when it should show`
+    )
+  if (reported.length) ctx.todo(path, component, reported.join("; "))
+  if (visible && !isTrue(ctx, visible))
+    renderWhen(j, path, attrValue(j, visible), el)
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Paper → Surface. Surface is a role, not an elevation scale: `elevation={0}` and
+ * `variant="outlined"` are the flat `kind="section"`, anything raised is `kind="panel"`.
+ */
+import type { MigrateContext } from "../lib/types"
+import { dropWithHint } from "./mui-props"
+
+export const handles = ["Paper", "PaperProps"] as const
+
+export function migrate(ctx: MigrateContext): void {
+  const { jsx } = ctx
+  const elements = ctx.elements("Paper")
+  ctx.moveElements("Paper", "Surface")
+  ctx.move("PaperProps", "SurfaceProps")
+
+  elements.forEach((path) => {
+    const el = path.node
+    let kind = "panel"
+
+    // `variant` decides the kind when present (MUI ignores elevation for an outlined Paper): a
+    // literal or a ternary of literals becomes `kind`; anything else is reported.
+    let kindFromVariant = false
+    const variant = jsx.attr(el, "variant")
+    if (variant) {
+      const mapped = jsx.mapAttrValue(el, "variant", {
+        outlined: "section",
+        elevation: "panel",
+      })
+      if (mapped === "mapped") {
+        jsx.renameAttr(el, "variant", "kind")
+        kindFromVariant = true
+      } else {
+        const printed = jsx.print(variant)
+        jsx.removeAttr(el, "variant")
+        ctx.todo(
+          path,
+          "Paper",
+          `dropped ${printed}: Surface kind is "panel" (raised) or "section" (flat, MUI outlined); pick one`
+        )
+      }
+    }
+    const elevation = jsx.attr(el, "elevation")
+    if (elevation) {
+      const value = jsx.literal(elevation)
+      if (typeof value === "number") {
+        if (value === 0) kind = "section"
+      } else if (!kindFromVariant) {
+        ctx.todo(
+          path,
+          "Paper",
+          `dropped ${jsx.print(elevation)}: Surface kind is "panel" (raised) or "section" (flat); pick one`
+        )
+      }
+      jsx.removeAttr(el, "elevation")
+    }
+
+    const square = jsx.attr(el, "square")
+    if (square) {
+      jsx.removeAttr(el, "square")
+      ctx.todo(
+        path,
+        "Paper",
+        "dropped square: Surface uses the token radius; override borderRadius via makeZenithStyles"
+      )
+    }
+
+    if (!kindFromVariant) {
+      el.openingElement.attributes = [
+        ctx.j.jsxAttribute(ctx.j.jsxIdentifier("kind"), jsx.str(kind)),
+        ...(el.openingElement.attributes ?? []),
+      ]
+    }
+    dropWithHint(ctx, path, "Paper", {
+      classes: "style the Surface with makeZenithStyles and pass className",
+      component: "wrap that element with <Surface kind asChild>",
+    })
+  })
+}

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

@@ -0,0 +1,328 @@
+/**
+ * Select + MenuItem → Select / SelectTrigger / SelectValue / SelectContent / SelectItem.
+ *
+ * Converted when the children are static: MenuItem elements, or `{list.map(… => <MenuItem>)}`,
+ * each with a non-empty string value (Radix reserves "" for "no selection"). Anything else
+ * stays on base-elements with a TODO.
+ *
+ * - `value`, `defaultValue`, `name`, `disabled`, `required`, `open` stay on the root;
+ *   `onChange={(event) => f(event.target.value)}` → `onValueChange={(value) => f(value)}`.
+ * - `placeholder` → `<SelectValue placeholder>`; `id`, `className`, `style`, `data-*` and
+ *   `aria-*` go on the trigger, which MUI's select box was.
+ * - base-elements' `label` → a wrapping `Field` with a `FieldLabel` tied to the trigger's id.
+ * - `variant`, `size`, `fullWidth`, `customBackgroundColor` are theming: dropped. `renderValue`,
+ *   `MenuProps`, `multiple`, `displayEmpty`, `error` and the rest are dropped and reported.
+ * - A MenuItem outside a Select (a Menu's) stays on base-elements with a DropdownMenu hint.
+ */
+import type {
+  ASTPath,
+  JSXAttribute,
+  JSXElement,
+  JSXSpreadAttribute,
+} from "jscodeshift"
+import type { MigrateContext } from "../lib/types"
+import {
+  attrExpression,
+  contentChildren,
+  element,
+  printAttr,
+  printAttrs,
+  renamedAttr,
+  setChildren,
+  takeAttrs,
+  valueHandler,
+  wrapElement,
+  type Child,
+  reportValueUses,
+} from "./shared"
+
+export const handles = [
+  "Select",
+  "SelectProps",
+  "MenuItem",
+  "MenuItemProps",
+] as const
+
+const ROOT = [
+  "value",
+  "defaultValue",
+  "name",
+  "disabled",
+  "required",
+  "open",
+  "key",
+]
+const SILENT = [
+  "variant",
+  "size",
+  "fullWidth",
+  "customBackgroundColor",
+  "color",
+]
+const TRIGGER = (name: string) =>
+  name === "id" ||
+  name === "className" ||
+  name === "style" ||
+  name.startsWith("data-") ||
+  name.startsWith("aria-")
+
+export function migrate(ctx: MigrateContext): void {
+  const { jsx } = ctx
+  const itemTag = ctx.names.MenuItem
+  const converted = new Set<JSXElement>()
+  let keptSelect = false
+
+  const toConvert: ASTPath<JSXElement>[] = []
+  ctx.elements("Select").forEach((path) => {
+    const items = itemTag ? menuItems(ctx, path.node, itemTag) : undefined
+    const problem = items
+      ? itemProblem(ctx, items)
+      : "its children are not MenuItems"
+    if (problem) {
+      keptSelect = true
+      ctx.todo(
+        path,
+        "Select",
+        `stays on base-elements: ${problem}; rebuild it as Select + SelectTrigger + SelectValue + SelectContent + SelectItem`
+      )
+      return
+    }
+    for (const item of items!) converted.add(item)
+    toConvert.push(path)
+  })
+
+  let root = ctx.names.Select ?? "Select"
+  if (
+    reportValueUses(
+      ctx,
+      "Select",
+      "rebuild it as Select > SelectTrigger > SelectValue + SelectContent > SelectItem"
+    ) &&
+    !keptSelect
+  ) {
+    ctx.keep("Select")
+    ctx.keep("SelectProps")
+    if (toConvert.length) root = ctx.ensureZenith("Select")
+  } else if (keptSelect) {
+    ctx.keep(
+      "Select",
+      "still used where a Select stayed: see the TODOs on those elements"
+    )
+    ctx.keep(
+      "SelectProps",
+      "type it from Zenith's SelectProps once the Select moves"
+    )
+    if (toConvert.length) root = ctx.ensureZenith("Select")
+  } else {
+    ctx.move("Select")
+    ctx.move("SelectProps")
+  }
+  for (const path of toConvert) migrateSelect(ctx, path, root)
+
+  let keptItem = false
+  if (itemTag)
+    ctx.elements("MenuItem").forEach((path) => {
+      if (!converted.has(path.node)) {
+        keptItem = true
+        return
+      }
+      jsx.rename(path.node, ctx.ensureZenith("SelectItem"))
+      takeAttrs(ctx, path.node, [
+        "dense",
+        "disableGutters",
+        "button",
+        "selected",
+      ])
+      const unsupported = takeAttrs(ctx, path.node, [
+        "divider",
+        "ListItemClasses",
+        "classes",
+        "component",
+      ])
+      if (unsupported.length)
+        ctx.todo(
+          path,
+          "MenuItem",
+          `dropped ${printAttrs(ctx, unsupported)} (no SelectItem equivalent)`
+        )
+    })
+  if (
+    reportValueUses(
+      ctx,
+      "MenuItem",
+      "a select option becomes SelectItem; a menu entry DropdownMenuItem"
+    ) &&
+    !keptItem
+  )
+    ctx.keep("MenuItem")
+  else if (keptItem)
+    ctx.keep(
+      "MenuItem",
+      "still used outside a converted Select: a select option becomes SelectItem inside SelectContent; a menu entry becomes DropdownMenuItem inside DropdownMenuContent"
+    )
+  else ctx.drop("MenuItem")
+  ctx.keep(
+    "MenuItemProps",
+    "SelectItemProps for a select option, DropdownMenuItemProps for a menu entry"
+  )
+}
+
+/** The MenuItem elements a Select renders, or `undefined` when its children are anything else. */
+function menuItems(
+  ctx: MigrateContext,
+  select: JSXElement,
+  itemTag: string
+): JSXElement[] | undefined {
+  const { j, jsx } = ctx
+  const items: JSXElement[] = []
+  for (const child of contentChildren(select)) {
+    if (child.type === "JSXElement" && jsx.tagName(child) === itemTag) {
+      items.push(child)
+      continue
+    }
+    if (child.type === "JSXExpressionContainer") {
+      if (child.expression.type === "JSXEmptyExpression") continue
+      const call = child.expression
+      const isMap =
+        call.type === "CallExpression" &&
+        call.callee.type === "MemberExpression" &&
+        call.callee.property.type === "Identifier" &&
+        call.callee.property.name === "map"
+      const returned = j(child as never)
+        .find(j.JSXElement)
+        .filter((p) => jsx.tagName(p.node) === itemTag)
+        .nodes()
+      if (isMap && returned.length === 1) {
+        items.push(returned[0])
+        continue
+      }
+    }
+    return undefined
+  }
+  return items.length ? items : undefined
+}
+
+/** Why the items cannot become SelectItems, if they cannot. */
+function itemProblem(
+  ctx: MigrateContext,
+  items: JSXElement[]
+): string | undefined {
+  for (const item of items) {
+    const value = ctx.jsx.attr(item, "value")
+    if (!value) return "a MenuItem has no value"
+    const literal = ctx.jsx.literal(value)
+    if (literal === "")
+      return 'a MenuItem has value="" (Radix reserves it for "no selection"; use a sentinel such as "none")'
+    if (typeof literal === "number" || typeof literal === "boolean")
+      return `a MenuItem has ${printAttr(ctx, value)} (SelectItem values are strings)`
+    const expression = attrExpression(value)
+    if (
+      expression?.type === "NullLiteral" ||
+      (expression?.type === "Identifier" && expression.name === "undefined")
+    )
+      return `a MenuItem has ${printAttr(ctx, value)} (use a sentinel string such as "none" and map it)`
+  }
+  return undefined
+}
+
+function migrateSelect(
+  ctx: MigrateContext,
+  path: ASTPath<JSXElement>,
+  root: string
+): void {
+  const { j, jsx } = ctx
+  const el = path.node
+  const reported: string[] = []
+  jsx.rename(el, root)
+
+  const onChange = jsx.attr(el, "onChange")
+  if (onChange) {
+    const handler = valueHandler(j, attrExpression(onChange), {
+      targetProp: "value",
+      valueName: "value",
+    })
+    jsx.removeAttr(el, "onChange")
+    if (handler) jsx.setAttr(el, "onValueChange", handler)
+    else
+      reported.push(
+        `dropped ${printAttr(ctx, onChange)} (onValueChange(value) passes only the value: call your handler with it)`
+      )
+  }
+
+  const label = jsx.removeAttr(el, "label")
+  const placeholder = jsx.removeAttr(el, "placeholder")
+  takeAttrs(ctx, el, SILENT)
+  const rootAttrs: (JSXAttribute | JSXSpreadAttribute)[] = []
+  const trigger: (JSXAttribute | JSXSpreadAttribute)[] = []
+  const dropped: JSXAttribute[] = []
+  for (const a of el.openingElement.attributes ?? []) {
+    if (a.type === "JSXSpreadAttribute") {
+      rootAttrs.push(a)
+      reported.push(
+        "spread props are MUI SelectProps: keep value/onValueChange/name on Select, styling on SelectTrigger"
+      )
+      continue
+    }
+    const name = jsx.attrName(a)
+    if (ROOT.includes(name) || name === "onValueChange") rootAttrs.push(a)
+    else if (TRIGGER(name)) trigger.push(a)
+    else dropped.push(a)
+  }
+  if (dropped.length)
+    reported.push(
+      `dropped ${printAttrs(ctx, dropped)} (renderValue → SelectValue children; MenuProps → SelectContent props; multiple has no Select equivalent)`
+    )
+  el.openingElement.attributes = rootAttrs
+
+  const value = element(
+    j,
+    ctx.ensureZenith("SelectValue"),
+    placeholder ? [placeholder] : []
+  )
+  const triggerEl = element(j, ctx.ensureZenith("SelectTrigger"), trigger, [
+    j.jsxText("\n"),
+    value,
+    j.jsxText("\n"),
+  ])
+  const content = element(
+    j,
+    ctx.ensureZenith("SelectContent"),
+    [],
+    el.children ?? []
+  )
+  setChildren(j, el, [
+    j.jsxText("\n"),
+    triggerEl,
+    j.jsxText("\n"),
+    content,
+    j.jsxText("\n"),
+  ])
+
+  let todoPath = path
+  if (label) {
+    const id = trigger.find(
+      (a): a is JSXAttribute =>
+        a.type === "JSXAttribute" && jsx.attrName(a) === "id"
+    )
+    const labelEl = element(
+      j,
+      ctx.ensureZenith("FieldLabel"),
+      id ? [renamedAttr(j, id, "htmlFor")] : [],
+      [jsx.childFromValue(label)]
+    )
+    const nl = (): Child => j.jsxText("\n")
+    todoPath = wrapElement(
+      j,
+      path,
+      ctx.ensureZenith("Field"),
+      [],
+      [nl(), labelEl, nl()],
+      [nl()]
+    )
+    if (!id)
+      reported.push(
+        "FieldLabel is not tied to the trigger: give SelectTrigger an id and FieldLabel htmlFor"
+      )
+  }
+  if (reported.length) ctx.todo(todoPath, "Select", reported.join("; "))
+}