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

package/README.md

@@ -163,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

@@ -8,6 +8,12 @@ once on code that imports `@epilot/zenith-react`:
 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                                                                      |
@@ -24,7 +30,12 @@ What it rewrites:
 
 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 DropdownMenu item whose `onSelect` calls
+`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.
 
@@ -38,8 +49,10 @@ Rules for a transform:
   `/* 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). Cover, per
-  family: the plain case, aliased imports, an inline handler, a handler reference, and one
+  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
@@ -50,7 +63,8 @@ Rules for a transform:
 
 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):
+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/

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/from-base-elements.ts

@@ -10,11 +10,17 @@
 import type { API, FileInfo, Options } from "jscodeshift"
 import { rules } from "./base-elements"
 import { runMigration } from "./lib/run-migration"
+import { formatOutput } from "../format"
 
 export const parser = "tsx"
 
 export const SOURCE = "@epilot/base-elements"
 
-export default function transform(file: FileInfo, api: API, options: Options) {
-  return runMigration({ file, api, options, source: SOURCE, rules })
+export default async function transform(
+  file: FileInfo,
+  api: API,
+  options: Options
+): Promise<string | undefined> {
+  const output = runMigration({ file, api, options, source: SOURCE, rules })
+  return output === undefined ? undefined : formatOutput(output, file.path)
 }

package/codemods/migrate/from-volt.ts

@@ -10,11 +10,17 @@
 import type { API, FileInfo, Options } from "jscodeshift"
 import { runMigration } from "./lib/run-migration"
 import { rules } from "./volt"
+import { formatOutput } from "../format"
 
 export const parser = "tsx"
 
 export const SOURCE = "@epilot/volt-ui-react"
 
-export default function transform(file: FileInfo, api: API, options: Options) {
-  return runMigration({ file, api, options, source: SOURCE, rules })
+export default async function transform(
+  file: FileInfo,
+  api: API,
+  options: Options
+): Promise<string | undefined> {
+  const output = runMigration({ file, api, options, source: SOURCE, rules })
+  return output === undefined ? undefined : formatOutput(output, file.path)
 }

package/codemods/radix-to-base-ui.ts

@@ -22,6 +22,8 @@
  * placement props, `value=""` for no selection) stays as it is: the wrappers still take them and
  * translate them for Base UI.
  */
+import { existsSync, readFileSync, statSync } from "node:fs"
+import { dirname, resolve } from "node:path"
 import type {
   API,
   ArrowFunctionExpression,
@@ -39,6 +41,12 @@ import type {
   Options,
   VariableDeclaration,
 } from "jscodeshift"
+import { formatOutput } from "./format"
+
+type J = API["jscodeshift"]
+type Scope = ASTPath["scope"]
+/** Where a reference is looked up: the file's AST, its path (imports resolve against it) and depth. */
+type Lookup = { j: J; root: Collection; path: string; depth: number }
 
 const ZENITH = "@epilot/zenith-react"
 
@@ -98,7 +106,11 @@ const TODO = "TODO(zenith-base-ui)"
 
 export const parser = "tsx"
 
-export default function transform(file: FileInfo, api: API, options: Options) {
+export default async function transform(
+  file: FileInfo,
+  api: API,
+  options: Options
+): Promise<string | undefined> {
   const j = api.jscodeshift
   const root = j(file.source)
   const local = zenithLocalNames(j, root)
@@ -225,8 +237,16 @@ export default function transform(file: FileInfo, api: API, options: Options) {
           const test = comparisons.reduce((a, b) =>
             j.logicalExpression("||", a, b)
           )
+          const withEvent = handlerTakesEvent(
+            { j, root, path: file.path, depth: 0 },
+            contentPath.scope,
+            value
+          )
           checks.push(
-            j.ifStatement(test, j.expressionStatement(callHandler(j, value)))
+            j.ifStatement(
+              test,
+              j.expressionStatement(callHandler(j, value, withEvent))
+            )
           )
           removeAttr(contentPath.node, h.node)
         }
@@ -336,7 +356,10 @@ export default function transform(file: FileInfo, api: API, options: Options) {
   if (todos.length) changed = true
 
   return changed
-    ? root.toSource({ quote: options.quote ?? "single" })
+    ? formatOutput(
+        root.toSource({ quote: options.quote ?? "single" }),
+        file.path
+      )
     : undefined
 }
 
@@ -375,15 +398,280 @@ function eventField(j: API["jscodeshift"], field: string) {
   )
 }
 
-function callHandler(j: API["jscodeshift"], handler: never) {
-  const event = j.memberExpression(
-    j.identifier("eventDetails"),
-    j.identifier("event")
-  )
-  const h = handler as { type: string; params?: unknown[] }
+function callHandler(j: J, handler: never, withEvent: boolean) {
+  const h = handler as { type: string }
+  const args = withEvent
+    ? [j.memberExpression(j.identifier("eventDetails"), j.identifier("event"))]
+    : []
   // An inline function is always defined; a reference may be undefined (a conditional handler).
-  // An inline function that ignores the event is called without it, so the output typechecks.
   return h.type === "ArrowFunctionExpression" || h.type === "FunctionExpression"
-    ? j.callExpression(handler, h.params?.length ? [event] : [])
-    : j.optionalCallExpression(handler, [event], true)
+    ? j.callExpression(handler, args)
+    : j.optionalCallExpression(handler, args, true)
+}
+
+/**
+ * Whether the handler is called with the event. A function that takes no parameter is called
+ * without it, so the output typechecks (TS2554): an inline function by its own parameters, a
+ * reference by the declaration it resolves to, in this file or in a relative import (a `const`
+ * or `function` declaration, `useCallback`, a type annotation, a destructured prop whose type is
+ * written in the file). A reference the file cannot explain (a package import, a member
+ * expression, a conditional) gets the event: an extra argument is harmless at runtime, and
+ * TypeScript reports the rare zero-parameter case.
+ */
+function handlerTakesEvent(
+  lookup: Lookup,
+  scope: Scope,
+  handler: { type: string; params?: unknown[]; name?: string }
+): boolean {
+  if (
+    handler.type === "ArrowFunctionExpression" ||
+    handler.type === "FunctionExpression"
+  )
+    return (handler.params?.length ?? 0) > 0
+  if (handler.type !== "Identifier" || !handler.name) return true
+  const arity = referenceArity(lookup, scope, handler.name)
+  return arity === undefined || arity > 0
+}
+
+const MAX_DEPTH = 8
+
+/** The number of parameters `name` is declared with, or undefined when the file does not say. */
+function referenceArity(
+  lookup: Lookup,
+  scope: Scope,
+  name: string
+): number | undefined {
+  if (lookup.depth > MAX_DEPTH) return undefined
+  const declaring = scope?.lookup(name)
+  const [binding] = declaring?.getBindings()[name] ?? []
+  return binding ? bindingArity(lookup, binding) : undefined
+}
+
+function bindingArity(lookup: Lookup, binding: ASTPath): number | undefined {
+  const { j } = lookup
+  const id = binding.node
+  const parent = binding.parent?.node
+  // `const close: () => void = …`, a parameter `close: () => void`
+  if (j.Identifier.check(id) && id.typeAnnotation) {
+    const arity = typeArity(lookup, id.typeAnnotation.typeAnnotation)
+    if (arity !== undefined) return arity
+  }
+  if (j.VariableDeclarator.check(parent) && binding.name === "id")
+    return parent.init
+      ? expressionArity(lookup, binding.parent.scope, parent.init)
+      : undefined
+  if (j.FunctionDeclaration.check(parent) && binding.name === "id")
+    return parent.params.length
+  if (
+    j.ImportSpecifier.check(parent) ||
+    j.ImportDefaultSpecifier.check(parent)
+  ) {
+    const declaration = binding.parent.parent?.node
+    if (!j.ImportDeclaration.check(declaration)) return undefined
+    const imported = j.ImportSpecifier.check(parent)
+      ? String(parent.imported.name)
+      : "default"
+    return importedArity(lookup, String(declaration.source.value), imported)
+  }
+  // `({ onClose }: { onClose: () => void }) => …`: the destructured prop's type
+  if (
+    (j.ObjectProperty.check(parent) || j.Property.check(parent)) &&
+    binding.name === "value"
+  ) {
+    const pattern = binding.parent.parent?.node
+    const key = parent.key
+    const keyName = j.Identifier.check(key)
+      ? key.name
+      : j.StringLiteral.check(key)
+        ? key.value
+        : undefined
+    if (
+      !j.ObjectPattern.check(pattern) ||
+      !pattern.typeAnnotation ||
+      keyName === undefined
+    )
+      return undefined
+    const members = typeMembers(lookup, pattern.typeAnnotation.typeAnnotation)
+    for (const member of members ?? []) {
+      const memberKey = (member as { key?: unknown }).key
+      const memberName = j.Identifier.check(memberKey)
+        ? memberKey.name
+        : j.StringLiteral.check(memberKey)
+          ? memberKey.value
+          : undefined
+      if (memberName !== keyName) continue
+      if (j.TSMethodSignature.check(member)) return member.parameters.length
+      if (j.TSPropertySignature.check(member))
+        return member.typeAnnotation
+          ? typeArity(lookup, member.typeAnnotation.typeAnnotation)
+          : undefined
+      return undefined
+    }
+  }
+  return undefined
+}
+
+function expressionArity(
+  lookup: Lookup,
+  scope: Scope,
+  expression: unknown
+): number | undefined {
+  const { j } = lookup
+  if (
+    j.ArrowFunctionExpression.check(expression) ||
+    j.FunctionExpression.check(expression)
+  )
+    return expression.params.length
+  if (j.Identifier.check(expression))
+    return referenceArity(
+      { ...lookup, depth: lookup.depth + 1 },
+      scope,
+      expression.name
+    )
+  if (j.TSAsExpression.check(expression))
+    return (
+      typeArity(lookup, expression.typeAnnotation) ??
+      expressionArity(lookup, scope, expression.expression)
+    )
+  if (j.TSNonNullExpression.check(expression))
+    return expressionArity(lookup, scope, expression.expression)
+  // `useCallback(() => …, [])`: the callback's own parameters
+  if (j.CallExpression.check(expression)) {
+    const { callee } = expression
+    const hook = j.Identifier.check(callee)
+      ? callee.name
+      : j.MemberExpression.check(callee) && j.Identifier.check(callee.property)
+        ? callee.property.name
+        : undefined
+    return hook === "useCallback"
+      ? expressionArity(lookup, scope, expression.arguments[0])
+      : undefined
+  }
+  return undefined
+}
+
+/** The parameter count of a function type, through unions with undefined and aliases in the file. */
+function typeArity(lookup: Lookup, type: unknown): number | undefined {
+  const { j, root } = lookup
+  if (j.TSFunctionType.check(type)) return type.parameters.length
+  if (j.TSParenthesizedType.check(type))
+    return typeArity(lookup, type.typeAnnotation)
+  if (j.TSUnionType.check(type)) {
+    const arities = type.types
+      .filter(
+        (t) => !j.TSUndefinedKeyword.check(t) && !j.TSNullKeyword.check(t)
+      )
+      .map((t) => typeArity(lookup, t))
+    return arities.length && arities.every((a) => a !== undefined)
+      ? Math.max(...(arities as number[]))
+      : undefined
+  }
+  if (
+    j.TSTypeReference.check(type) &&
+    j.Identifier.check(type.typeName) &&
+    !type.typeParameters &&
+    lookup.depth <= MAX_DEPTH
+  ) {
+    const alias = root
+      .find(j.TSTypeAliasDeclaration, { id: { name: type.typeName.name } })
+      .nodes()[0]
+    return alias
+      ? typeArity({ ...lookup, depth: lookup.depth + 1 }, alias.typeAnnotation)
+      : undefined
+  }
+  return undefined
+}
+
+/** The members of an object type written in the file: a literal, an alias, an interface, an intersection. */
+function typeMembers(lookup: Lookup, type: unknown): unknown[] | undefined {
+  const { j, root } = lookup
+  if (j.TSTypeLiteral.check(type)) return type.members
+  if (j.TSParenthesizedType.check(type))
+    return typeMembers(lookup, type.typeAnnotation)
+  // A member found in one part of an intersection is one of the property's overloads.
+  if (j.TSIntersectionType.check(type))
+    return type.types.flatMap((t) => typeMembers(lookup, t) ?? [])
+  if (
+    j.TSTypeReference.check(type) &&
+    j.Identifier.check(type.typeName) &&
+    !type.typeParameters &&
+    lookup.depth <= MAX_DEPTH
+  ) {
+    const name = type.typeName.name
+    const deeper = { ...lookup, depth: lookup.depth + 1 }
+    const alias = root
+      .find(j.TSTypeAliasDeclaration, { id: { name } })
+      .nodes()[0]
+    if (alias) return typeMembers(deeper, alias.typeAnnotation)
+    // An interface's own members; one inherited through `extends` stays unknown.
+    const iface = root
+      .find(j.TSInterfaceDeclaration, { id: { name } })
+      .nodes()[0]
+    return iface?.body.body
+  }
+  return undefined
+}
+
+const MODULE_SUFFIXES = [
+  "",
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  "/index.ts",
+  "/index.tsx",
+  "/index.js",
+]
+
+/** The arity of `imported` from a relative module, read from disk; a package import stays unknown. */
+function importedArity(
+  lookup: Lookup,
+  source: string,
+  imported: string
+): number | undefined {
+  if (!source.startsWith(".") || lookup.depth > MAX_DEPTH) return undefined
+  const base = resolve(dirname(lookup.path), source)
+  const file = MODULE_SUFFIXES.map((suffix) => base + suffix).find(
+    (candidate) => existsSync(candidate) && statSync(candidate).isFile()
+  )
+  if (!file) return undefined
+  const { j } = lookup
+  let root: Collection
+  try {
+    root = j(readFileSync(file, "utf8"))
+  } catch {
+    return undefined
+  }
+  const other: Lookup = { j, root, path: file, depth: lookup.depth + 1 }
+  const program = root.find(j.Program).paths()[0]
+  const local = (name: string) => referenceArity(other, program.scope, name)
+
+  if (imported === "default") {
+    const declaration = root
+      .find(j.ExportDefaultDeclaration)
+      .nodes()[0]?.declaration
+    if (j.Identifier.check(declaration)) return local(declaration.name)
+    if (j.FunctionDeclaration.check(declaration))
+      return declaration.params.length
+    return expressionArity(other, program.scope, declaration)
+  }
+  for (const node of root.find(j.ExportNamedDeclaration).nodes()) {
+    for (const specifier of node.specifiers ?? []) {
+      if (!j.ExportSpecifier.check(specifier)) continue
+      if (String(specifier.exported.name) !== imported) continue
+      const localName = String(specifier.local?.name ?? specifier.exported.name)
+      return node.source
+        ? importedArity(other, String(node.source.value), localName)
+        : local(localName)
+    }
+  }
+  // `export const close = …` and `export function close() {}` are program-scope bindings.
+  const own = local(imported)
+  if (own !== undefined) return own
+  for (const node of root.find(j.ExportAllDeclaration).nodes()) {
+    const through = importedArity(other, String(node.source.value), imported)
+    if (through !== undefined) return through
+  }
+  return undefined
 }