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

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

@@ -0,0 +1,231 @@
+/**
+ * Tooltip → Tooltip + TooltipTrigger asChild + TooltipContent.
+ *
+ * - The one child becomes the trigger; `title` becomes the content.
+ * - `placement` → `side` + `align`. MUI's default is bottom and Radix's is top, so `side` is
+ *   always written.
+ * - `enterDelay` → `delayDuration`; `open` stays on the root. Props MUI forwarded to the child
+ *   (`className`, `data-*`, `aria-*`) go on the trigger, which merges them into the child.
+ * - `arrow`, `interactive` and base-elements' `mode` are theming or Radix's default: dropped.
+ *   Other MUI-only props are dropped and reported.
+ * - Radix throws without a TooltipProvider above the tooltip, so the first tooltip of a file
+ *   carries a one-time reminder. A tooltip around anything but exactly one child stays on
+ *   base-elements.
+ */
+import type {
+  ASTPath,
+  JSXAttribute,
+  JSXElement,
+  JSXSpreadAttribute,
+} from "jscodeshift"
+import type { MigrateContext } from "../lib/types"
+import {
+  contentChildren,
+  element,
+  printAttrs,
+  setChildren,
+  takeAttrs,
+  printAttr,
+  reportValueUses,
+} from "./shared"
+
+export const handles = ["Tooltip", "TooltipProps"] as const
+
+const SILENT = ["arrow", "interactive", "mode", "title", "placement"]
+const REPORTED = [
+  "onOpen",
+  "onClose",
+  "leaveDelay",
+  "enterNextDelay",
+  "enterTouchDelay",
+  "leaveTouchDelay",
+  "disableHoverListener",
+  "disableFocusListener",
+  "disableTouchListener",
+  "PopperProps",
+  "PopperComponent",
+  "TransitionComponent",
+  "TransitionProps",
+  "classes",
+]
+
+export function migrate(ctx: MigrateContext): void {
+  const tooltips = ctx.elements("Tooltip").paths()
+  const convertible = tooltips.filter((p) => oneChild(p.node))
+  const stays = tooltips.filter((p) => !oneChild(p.node))
+  for (const path of stays)
+    ctx.todo(
+      path,
+      "Tooltip",
+      "stays on base-elements: Zenith's TooltipTrigger needs exactly one child element; wrap the children in one"
+    )
+  let root = ctx.names.Tooltip ?? "Tooltip"
+  const valueUsed = reportValueUses(
+    ctx,
+    "Tooltip",
+    "rebuild it as Tooltip > TooltipTrigger asChild + TooltipContent"
+  )
+  if (valueUsed && !stays.length) {
+    ctx.keep("Tooltip")
+    if (convertible.length) root = ctx.ensureZenith("Tooltip")
+  } else if (stays.length) {
+    ctx.keep(
+      "Tooltip",
+      "still used where a Tooltip stayed: see the TODOs on those elements"
+    )
+    if (convertible.length) root = ctx.ensureZenith("Tooltip")
+  } else ctx.move("Tooltip")
+  ctx.move("TooltipProps")
+
+  convertible.forEach((path, index) =>
+    migrateTooltip(ctx, path, root, index === 0)
+  )
+}
+
+function oneChild(el: JSXElement): boolean {
+  const children = contentChildren(el).filter(
+    (c) =>
+      !(
+        c.type === "JSXExpressionContainer" &&
+        c.expression.type === "JSXEmptyExpression"
+      )
+  )
+  return (
+    children.length === 1 &&
+    (children[0].type === "JSXElement" ||
+      children[0].type === "JSXExpressionContainer")
+  )
+}
+
+function migrateTooltip(
+  ctx: MigrateContext,
+  path: ASTPath<JSXElement>,
+  root: string,
+  first: boolean
+): void {
+  const { j, jsx } = ctx
+  const el = path.node
+  const reported: string[] = []
+  const content: JSXAttribute[] = []
+
+  const placement = jsx.attr(el, "placement")
+  const value = placement ? jsx.literal(placement) : "bottom"
+  if (typeof value === "string") {
+    const [side, align] = value.split("-")
+    content.push(j.jsxAttribute(j.jsxIdentifier("side"), jsx.str(side)))
+    if (align)
+      content.push(j.jsxAttribute(j.jsxIdentifier("align"), jsx.str(align)))
+  } else
+    reported.push(
+      `dropped ${printAttr(ctx, placement!)} (TooltipContent side: top | right | bottom | left, align: start | center | end)`
+    )
+  const title = jsx.attr(el, "title")
+
+  jsx.renameAttr(el, "enterDelay", "delayDuration")
+  const id = jsx.removeAttr(el, "id")
+  if (id) content.push(id)
+
+  const dropped = takeAttrs(ctx, el, REPORTED)
+  if (dropped.length)
+    reported.push(
+      `dropped ${printAttrs(ctx, dropped)} (Tooltip onOpenChange(open) replaces onOpen/onClose; delays live on TooltipProvider)`
+    )
+  takeAttrs(ctx, el, SILENT)
+
+  // What MUI spread onto the child goes on the trigger, which merges it into the child.
+  const trigger: (JSXAttribute | JSXSpreadAttribute)[] = [
+    j.jsxAttribute(j.jsxIdentifier("asChild")),
+  ]
+  const rootAttrs: JSXAttribute[] = []
+  for (const a of el.openingElement.attributes ?? []) {
+    if (a.type === "JSXSpreadAttribute") trigger.push(a)
+    else if (["open", "delayDuration", "key"].includes(jsx.attrName(a)))
+      rootAttrs.push(a)
+    else trigger.push(a)
+  }
+  el.openingElement.attributes = rootAttrs
+
+  const child = contentChildren(el).find(
+    (c) =>
+      !(
+        c.type === "JSXExpressionContainer" &&
+        c.expression.type === "JSXEmptyExpression"
+      )
+  )!
+  // An icon button's tooltip text is its only label: base-elements left it unnamed.
+  const iconButtons = [
+    ctx.names.IconButton,
+    ctx.names.ElevatedIconButton,
+  ].filter(Boolean)
+  if (
+    title &&
+    child.type === "JSXElement" &&
+    iconButtons.includes(jsx.tagName(child) ?? "") &&
+    !["aria-label", "aria-labelledby", "title"].some((n) => jsx.attr(child, n))
+  )
+    child.openingElement.attributes = [
+      ...(child.openingElement.attributes ?? []),
+      j.jsxAttribute(j.jsxIdentifier("aria-label"), title.value),
+    ]
+  const triggerEl = element(j, ctx.ensureZenith("TooltipTrigger"), trigger, [
+    j.jsxText("\n"),
+    child,
+    j.jsxText("\n"),
+  ])
+  const contentEl = element(
+    j,
+    ctx.ensureZenith("TooltipContent"),
+    content,
+    title ? [jsx.childFromValue(title)] : []
+  )
+  jsx.rename(el, root)
+  setChildren(j, el, [
+    j.jsxText("\n"),
+    triggerEl,
+    j.jsxText("\n"),
+    contentEl,
+    j.jsxText("\n"),
+  ])
+  if (!title) reported.push("no title: put the tooltip text in TooltipContent")
+  else if (canBeEmpty(title))
+    reported.push(
+      `${printAttr(ctx, title)} can be empty: MUI hid the tooltip then, Radix shows an empty bubble; render the Tooltip only when there is text`
+    )
+  if (first)
+    reported.push(
+      "Zenith's Tooltip throws without a TooltipProvider above it: add one once at the app root if there is none"
+    )
+  if (reported.length) ctx.todo(path, "Tooltip", reported.join("; "))
+}
+
+/** Whether `title` can evaluate to nothing: `""`, a ternary or `&&` with an empty side. */
+function canBeEmpty(a: JSXAttribute): boolean {
+  const v = a.value
+  if (v?.type === "StringLiteral" || v?.type === "Literal")
+    return String((v as { value: unknown }).value) === ""
+  if (v?.type !== "JSXExpressionContainer") return false
+  const empty = (e: { type: string; [k: string]: unknown }): boolean => {
+    switch (e.type) {
+      case "StringLiteral":
+        return e.value === ""
+      case "TemplateLiteral":
+        return (
+          (e.expressions as unknown[]).length === 0 &&
+          (e.quasis as { value: { cooked: string } }[])[0]?.value.cooked === ""
+        )
+      case "NullLiteral":
+        return true
+      case "BooleanLiteral":
+        return e.value === false
+      case "Identifier":
+        return e.name === "undefined"
+      case "ConditionalExpression":
+        return empty(e.consequent as never) || empty(e.alternate as never)
+      case "LogicalExpression":
+        return e.operator === "&&" || empty(e.right as never)
+      default:
+        return false
+    }
+  }
+  return empty(v.expression as never)
+}

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

@@ -0,0 +1,247 @@
+/**
+ * Typography, H1–H6, DisplayText, LargeText, BodyText, SmallText → Text.
+ *
+ * Zenith's variants run opposite to HTML headings (title3 is the largest). By the epilot MUI
+ * theme's sizes: h1–h4 (96–32px) → title3 (30px), h5 → title2 (24px), h6 → title1 (20px),
+ * subtitle1 → heading2 (16px bold), subtitle2 → heading1 (14px bold), body1 (16px) and body2
+ * → body2 (14px, Text's default, omitted), caption/overline → body1 (12px).
+ * `color="textSecondary"` turns body2/body1 into helper2/helper1 (the gray ink). Text has no
+ * other colour variants, so error/primary/secondary (and textSecondary elsewhere) are reported
+ * with the token to set.
+ *
+ * Text renders an inline `<span>`. A heading (H1–H6, an h* variant or component) is reported
+ * so it can be wrapped in its `<hN>`; MUI's block element (`<p>`, `<h6>` for subtitles) is
+ * reported when the element shares its parent with other content. `customColor`,
+ * `gutterBottom`, `paragraph`, `noWrap`, `align` and `display="block"` become inline styles.
+ */
+import type { ASTPath, JSXElement } from "jscodeshift"
+import type { MigrateContext } from "../lib/types"
+import {
+  attrExpression,
+  contentChildren,
+  mapStringExpression,
+  parseExpression,
+  printAttrs,
+  source,
+  stringIn,
+  takeAttrs,
+  printAttr,
+  moveElements,
+} from "./shared"
+
+const COMPONENTS: Record<string, string> = {
+  Typography: "body1",
+  H1: "h1",
+  H2: "h2",
+  H3: "h3",
+  H4: "h4",
+  H5: "h5",
+  H6: "h6",
+  DisplayText: "h6",
+  LargeText: "body1",
+  BodyText: "body2",
+  SmallText: "caption",
+}
+
+export const handles = [...Object.keys(COMPONENTS), "TypographyProps"] as const
+
+const VARIANTS: Record<string, string> = {
+  h1: "title3",
+  h2: "title3",
+  h3: "title3",
+  h4: "title3",
+  h5: "title2",
+  h6: "title1",
+  subtitle1: "heading2",
+  subtitle2: "heading1",
+  body1: "body2",
+  body2: "body2",
+  caption: "body1",
+  overline: "body1",
+  button: "body2",
+}
+const SECONDARY: Record<string, string> = { body2: "helper2", body1: "helper1" }
+/** MUI colours that are Text's own ink anyway. */
+const INK = new Set(["initial", "inherit", "textPrimary"])
+/** The token for a colour Text has no variant for. */
+const COLOR_TOKENS: Record<string, string> = {
+  error: "tokens.errorA11",
+  primary: "tokens.accentA11",
+  secondary: "tokens.accentA11",
+  textSecondary: "tokens.grayA11",
+}
+/** MUI variants whose default element is an inline `<span>`, like Text's. */
+const INLINE = new Set(["caption", "overline", "button", "inherit", "srOnly"])
+
+export function migrate(ctx: MigrateContext): void {
+  for (const name of Object.keys(COMPONENTS)) {
+    moveElements(ctx, name, "Text", (path) => migrateText(ctx, path, name))
+  }
+  ctx.move("TypographyProps", "TextProps")
+}
+
+function migrateText(
+  ctx: MigrateContext,
+  path: ASTPath<JSXElement>,
+  component: string
+): void {
+  const { j, jsx } = ctx
+  const el = path.node
+  const reported: string[] = []
+  const style: [string, string][] = []
+
+  const variantAttr = jsx.removeAttr(el, "variant")
+  const muiVariant = variantAttr
+    ? jsx.literal(variantAttr)
+    : COMPONENTS[component]
+  const colorAttr = jsx.removeAttr(el, "color")
+  const color = jsx.literal(colorAttr)
+  let heading: string | undefined
+  if (typeof muiVariant === "string" && muiVariant in VARIANTS) {
+    let variant = VARIANTS[muiVariant]
+    if (color === "textSecondary" && SECONDARY[variant])
+      variant = SECONDARY[variant]
+    else if (colorAttr && !INK.has(String(color)))
+      reported.push(colorTodo(ctx, colorAttr))
+    if (variant !== "body2") jsx.setAttr(el, "variant", variant)
+    if (/^h[1-6]$/.test(muiVariant)) heading = muiVariant
+  } else {
+    const mapped = mapStringExpression(
+      j,
+      attrExpression(variantAttr),
+      (v) => VARIANTS[v],
+      (v) => stringIn(ctx, v) as never
+    )
+    if (mapped) jsx.setAttr(el, "variant", mapped)
+    else
+      reported.push(
+        `dropped ${printAttr(ctx, variantAttr!)} (h1–h4 → title3, h5 → title2, h6 → title1, subtitle1/2 → heading2/1, body1/2 → body2, caption → body1)`
+      )
+    if (colorAttr && !INK.has(String(color)))
+      reported.push(colorTodo(ctx, colorAttr))
+  }
+
+  let inline = typeof muiVariant === "string" && INLINE.has(muiVariant)
+  const componentAttr = jsx.removeAttr(el, "component")
+  if (componentAttr) {
+    // The element MUI rendered, which decides whether there is a heading to keep.
+    const tag = jsx.literal(componentAttr)
+    const isHeading = typeof tag === "string" && /^h[1-6]$/.test(tag)
+    heading = isHeading ? (tag as string) : undefined
+    inline = tag === "span"
+    if (tag !== "span" && !isHeading)
+      reported.push(
+        `dropped ${printAttr(ctx, componentAttr)} (Text always renders a <span>; wrap it in the element you need)`
+      )
+  }
+
+  const customColor = jsx.removeAttr(el, "customColor")
+  const quoted = (v: string) => source(j, stringIn(ctx, v))
+  if (customColor) {
+    const value = jsx.literal(customColor)
+    style.push([
+      "color",
+      typeof value === "string"
+        ? quoted(value)
+        : source(j, attrExpression(customColor) as never),
+    ])
+  }
+  let block = false
+  if (jsx.removeAttr(el, "gutterBottom"))
+    style.push(["marginBottom", quoted("0.35em")])
+  if (jsx.removeAttr(el, "paragraph")) {
+    style.push(["marginBottom", quoted("1rem")])
+    block = true
+  }
+  if (jsx.removeAttr(el, "noWrap")) {
+    style.push(
+      ["overflow", quoted("hidden")],
+      ["textOverflow", quoted("ellipsis")],
+      ["whiteSpace", quoted("nowrap")]
+    )
+    block = true
+  }
+  const align = jsx.removeAttr(el, "align")
+  const alignValue = jsx.literal(align)
+  if (typeof alignValue === "string" && alignValue !== "inherit") {
+    style.push(["textAlign", quoted(alignValue)])
+    block = true
+  } else if (align && alignValue !== "inherit")
+    reported.push(
+      `dropped ${printAttr(ctx, align)} (set textAlign in your styles)`
+    )
+  const display = jsx.removeAttr(el, "display")
+  if (jsx.literal(display) === "block") block = true
+  else if (display && jsx.literal(display) !== "initial")
+    reported.push(
+      `dropped ${printAttr(ctx, display)} (set display in your styles)`
+    )
+  if (block) style.unshift(["display", quoted("block")])
+  if (style.length) applyStyle(ctx, el, style, reported)
+
+  const unsupported = takeAttrs(ctx, el, ["classes", "variantMapping"])
+  if (unsupported.length)
+    reported.push(`dropped ${printAttrs(ctx, unsupported)} (MUI-only)`)
+
+  if (heading) {
+    const level = heading.slice(1)
+    reported.push(
+      `Text renders a <span>: wrap it in <${heading}> (or add role="heading" aria-level={${level}}) to keep the heading`
+    )
+  } else if (!block && !inline && sharesParent(path))
+    reported.push(
+      "Text is inline where MUI rendered a block: it now shares a line with its siblings; set display: block or lay the parent out as a column"
+    )
+  if (reported.length) ctx.todo(path, component, reported.join("; "))
+}
+
+/** Adds `key: value` entries (values are source text) to `style`, creating it when absent. */
+function applyStyle(
+  ctx: MigrateContext,
+  el: JSXElement,
+  entries: [string, string][],
+  reported: string[]
+): void {
+  const { j, jsx } = ctx
+  if (!jsx.attr(el, "style")) {
+    const body = entries.map(([k, v]) => `${k}: ${v}`).join(", ")
+    jsx.setAttr(el, "style", parseExpression(j, `{ ${body} }`))
+    return
+  }
+  const object = jsx.styleObject(el)
+  if (!object) {
+    reported.push(
+      `add ${entries.map(([k, v]) => `${k}: ${v}`).join(", ")} to its style`
+    )
+    return
+  }
+  for (const [k, v] of entries)
+    jsx.setObjectKey(object, k, parseExpression(j, v))
+}
+
+/** Whether the element sits among other content in a JSX parent (text or elements). */
+function sharesParent(path: ASTPath<JSXElement>): boolean {
+  const parent = path.parent?.node as JSXElement | undefined
+  if (
+    !parent ||
+    (parent.type !== "JSXElement" && parent.type !== "JSXFragment")
+  )
+    return false
+  return contentChildren(parent).some(
+    (c) =>
+      c !== path.node &&
+      !(
+        c.type === "JSXExpressionContainer" &&
+        c.expression.type === "JSXEmptyExpression"
+      )
+  )
+}
+
+function colorTodo(
+  ctx: MigrateContext,
+  color: NonNullable<ReturnType<MigrateContext["jsx"]["attr"]>>
+): string {
+  const value = ctx.jsx.literal(color)
+  const token = typeof value === "string" ? COLOR_TOKENS[value] : undefined
+  return `dropped ${printAttr(ctx, color)} (Text has no colour variant${token ? `: set color: ${token} in a makeZenithStyles class` : "; set the colour in a makeZenithStyles class with a tokens.* value"})`
+}