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

package/scripts/migration-diagnostics-core.mjs

@@ -29,6 +29,22 @@ export const RULES = [
     description:
       'A decorative (non-core) token family is used, with varying confidence that a correctly-scoped install call covers it (high confidence for no local evidence at all, down to low for an unresolved dynamic path). This rule NEVER reports severity "error": local absence of an install call does not prove a bootstrap/provider install does not exist elsewhere — this is single-source analysis with no cross-file tracing, so it cannot assert a definite defect, only flag what needs verification. Core families (accent/gray/error/warning/success/info) are excluded — they load by default. Requires an injected TypeScript module (see requiresTypeScript).',
   },
+  {
+    code: "radix-data-state-selector",
+    title: "Radix-era data-state selector or query",
+    defaultSeverity: "warning",
+    requiresTypeScript: false,
+    description:
+      "A `data-state` attribute selector, Tailwind `data-[state=…]` variant, JSX attribute or test query reads a state Radix set (`open`, `closed`, `checked`, `active`, `on`, …). The Base UI parts carry one attribute per state instead (`data-open`, `data-checked`, `data-active`, `data-pressed`, …), so the selector stops matching after the upgrade; the suggestion names the replacement per family (RADIX_RENAMES, the upgrade guide's table). A warning, not an error: Zenith's own List, Table and DataTable keep their `data-state` values, and a selector alone does not say which element it targets.",
+  },
+  {
+    code: "radix-css-variable",
+    title: "Radix-era --radix-* CSS variable",
+    defaultSeverity: "error",
+    requiresTypeScript: false,
+    description:
+      "A `--radix-*` custom property (`--radix-popover-content-transform-origin`, `--radix-select-trigger-width`, `--radix-accordion-content-height`, …) is read. Base UI publishes none of them; the positioner and panel variables have new names (`--transform-origin`, `--available-width`, `--anchor-width`, `--accordion-panel-height`, …), which the suggestion gives.",
+  },
 ]
 
 /** ts/tsx/js/jsx — the extensions `unestablished-palette-install` can parse. Exported so the
@@ -165,9 +181,277 @@ function textualFindings(identity, fileLabel, raw) {
     )
   }
 
+  findings.push(...radixFindings(identity, fileLabel, stripped, lineOf, colOf))
+  return findings
+}
+
+// ---------------------------------------------------------------------------
+// Rule 4 + 5: Radix-era state attributes and CSS variables (textual, comment-stripped)
+// ---------------------------------------------------------------------------
+
+/** The Zenith parts an overlay-style `data-state="open|closed"` became `data-open`/`data-closed` on. */
+const OPEN_CLOSED_PARTS = [
+  "Dialog",
+  "AlertDialog",
+  "Drawer",
+  "Popover",
+  "FieldCombobox",
+  "Tooltip",
+  "DropdownMenu content and sub content",
+  "Select content",
+  "Accordion item and panel",
+]
+const POPUP_TRIGGERS = [
+  "Dialog trigger",
+  "AlertDialog trigger",
+  "Drawer trigger",
+  "Popover trigger",
+  "Tooltip trigger",
+  "DropdownMenu trigger and sub trigger",
+  "Select trigger",
+]
+const CHECKED_PARTS = [
+  "Checkbox",
+  "Switch (root and thumb)",
+  "Radio",
+  "SegmentedControl",
+  "DropdownMenu checkbox and radio items",
+]
+
+/** The Radix primitive names Zenith's positioned families used in their `--radix-*` variables. */
+export const RADIX_VARIABLE_FAMILIES = [
+  { radix: "popover", zenith: "Popover, FieldCombobox" },
+  { radix: "dropdown-menu", zenith: "DropdownMenu" },
+  { radix: "select", zenith: "Select" },
+  { radix: "tooltip", zenith: "Tooltip" },
+]
+
+/**
+ * The attribute and CSS-variable renames of the Base UI port (DECISIONS.md D12), one row per
+ * Radix name and Base UI replacement. The rules below match on these, and
+ * `renderRadixRenamesMarkdown()` prints the upgrade guide's table from them, so the two cannot
+ * drift. Family names are Zenith's; `<family>` in a variable name stands for one of
+ * RADIX_VARIABLE_FAMILIES. A `baseUi` of null means the state has no attribute any more: it is
+ * the part without the other one (`:not([data-active])`).
+ */
+export const RADIX_RENAMES = {
+  attributes: [
+    { value: "open", baseUi: "data-open", parts: OPEN_CLOSED_PARTS },
+    { value: "open", baseUi: "data-popup-open", parts: POPUP_TRIGGERS },
+    { value: "open", baseUi: "data-panel-open", parts: ["Accordion trigger"] },
+    { value: "closed", baseUi: "data-closed", parts: OPEN_CLOSED_PARTS },
+    { value: "delayed-open", baseUi: "data-open", parts: ["Tooltip"] },
+    { value: "instant-open", baseUi: "data-open", parts: ["Tooltip"] },
+    { value: "checked", baseUi: "data-checked", parts: CHECKED_PARTS },
+    { value: "checked", baseUi: "data-selected", parts: ["Select item"] },
+    { value: "unchecked", baseUi: "data-unchecked", parts: CHECKED_PARTS },
+    {
+      value: "indeterminate",
+      baseUi: "data-indeterminate",
+      parts: ["Checkbox"],
+    },
+    { value: "active", baseUi: "data-active", parts: ["Tabs trigger"] },
+    {
+      value: "inactive",
+      baseUi: null,
+      parts: ["Tabs trigger"],
+      note: "the trigger without `data-active`",
+    },
+    { value: "on", baseUi: "data-pressed", parts: ["Toggle", "OptionCard"] },
+    {
+      value: "off",
+      baseUi: null,
+      parts: ["Toggle", "OptionCard"],
+      note: "the part without `data-pressed`",
+    },
+  ],
+  variables: [
+    {
+      radix: "--radix-<family>-content-transform-origin",
+      baseUi: "--transform-origin",
+    },
+    {
+      radix: "--radix-<family>-content-available-width",
+      baseUi: "--available-width",
+    },
+    {
+      radix: "--radix-<family>-content-available-height",
+      baseUi: "--available-height",
+    },
+    { radix: "--radix-<family>-trigger-width", baseUi: "--anchor-width" },
+    { radix: "--radix-<family>-trigger-height", baseUi: "--anchor-height" },
+    {
+      radix: "--radix-accordion-content-height",
+      baseUi: "--accordion-panel-height",
+      parts: ["Accordion panel"],
+    },
+    {
+      radix: "--radix-accordion-content-width",
+      baseUi: "--accordion-panel-width",
+      parts: ["Accordion panel"],
+    },
+  ],
+  /** Attributes the port left alone, for the table's footnote. */
+  unchanged: [
+    "data-highlighted",
+    "data-side",
+    "data-orientation",
+    "data-disabled",
+    "data-slot",
+  ],
+  /** New under Base UI: a part entering or leaving carries one of these while it transitions. */
+  added: ["data-starting-style", "data-ending-style"],
+  /** Zenith's own parts that still set `data-state`, with the values they use. */
+  keptDataState: [
+    { part: "List group", values: ["open", "closed"] },
+    { part: "Table row and DataTable row", values: ["selected"] },
+    { part: "DataTable body", values: ["loading", "error", "empty"] },
+  ],
+}
+
+const RADIX_STATE_VALUES = new Set(RADIX_RENAMES.attributes.map((a) => a.value))
+/** `open` and `closed` are also Zenith's List values, so a hit on them is only probably Radix. */
+const SHARED_STATE_VALUES = new Set(
+  RADIX_RENAMES.keptDataState
+    .flatMap((k) => k.values)
+    .filter((v) => RADIX_STATE_VALUES.has(v))
+)
+
+/**
+ * `data-state` wherever consumer code spells it: an attribute selector (`[data-state="open"]`,
+ * `[data-state=open]`, inside a CSS-in-JS string too), a JSX attribute, a Tailwind variant
+ * (`data-[state=open]:…`) and a test query (`toHaveAttribute("data-state", "open")`,
+ * `getAttribute("data-state")`). Group 1: the Tailwind value; 3: the selector or attribute
+ * value; 4: the query's value argument.
+ */
+const DATA_STATE_RE =
+  /data-\[state=([a-z-]+)\]|\bdata-state\b(?![a-z0-9-])(?:\s*[~|^$*]?=\s*(["']?)([a-z-]+)\2|["']\s*,\s*["']([a-z-]+)["'])?/g
+const RADIX_VAR_RE = /--radix-[a-z0-9-]+/g
+
+const familyPattern = `(?<family>${RADIX_VARIABLE_FAMILIES.map((f) => f.radix).join("|")})`
+const VARIABLE_MATCHERS = RADIX_RENAMES.variables.map((v) => ({
+  ...v,
+  re: new RegExp(`^${v.radix.replace("<family>", familyPattern)}$`),
+}))
+
+const describeParts = (parts) => parts.join(", ")
+
+/** What replaces `data-state="<value>"`, per family, or null for a value Radix never set. */
+export function dataStateReplacement(value) {
+  if (!value) {
+    return "one attribute per state on the Base UI part: data-open/data-closed (overlays, Accordion), data-popup-open (triggers), data-checked/data-unchecked (Checkbox, Switch, Radio, SegmentedControl, menu items), data-selected (Select item), data-active (Tabs), data-pressed (Toggle, OptionCard); see the upgrade guide's rename table."
+  }
+  const rows = RADIX_RENAMES.attributes.filter((a) => a.value === value)
+  if (!rows.length) return null
+  return rows
+    .map((r) =>
+      r.baseUi
+        ? `${r.baseUi} on ${describeParts(r.parts)}`
+        : `no attribute on ${describeParts(r.parts)} (${r.note})`
+    )
+    .join("; ")
+}
+
+/** The Base UI variable for a `--radix-*` name, or null when no Zenith family used it. */
+export function radixVariableReplacement(name) {
+  for (const m of VARIABLE_MATCHERS) {
+    const hit = m.re.exec(name)
+    if (!hit) continue
+    const family = hit.groups?.family
+    const parts = family
+      ? RADIX_VARIABLE_FAMILIES.find((f) => f.radix === family).zenith
+      : describeParts(m.parts)
+    return { baseUi: m.baseUi, parts }
+  }
+  return null
+}
+
+function radixFindings(identity, fileLabel, stripped, lineOf, colOf) {
+  const findings = []
+  for (const m of stripped.matchAll(DATA_STATE_RE)) {
+    const value = m[1] ?? m[3] ?? m[4]
+    if (value && !RADIX_STATE_VALUES.has(value)) continue // Zenith's own values (selected, loading, …)
+    const replacement = dataStateReplacement(value)
+    findings.push(
+      makeFinding(identity, {
+        code: "radix-data-state-selector",
+        severity: "warning",
+        confidence:
+          !value || SHARED_STATE_VALUES.has(value) ? "medium" : "high",
+        file: fileLabel,
+        line: lineOf(m.index),
+        column: colOf(m.index),
+        evidence: m[0],
+        explanation: value
+          ? `Radix set data-state="${value}"; the Base UI part carries a dedicated attribute instead, so this selector or query matches nothing after the upgrade.${SHARED_STATE_VALUES.has(value) ? " Zenith's List still uses this value on its groups; leave the selector if it targets one." : ""}`
+          : "Radix set data-state on every stateful part; the Base UI parts carry one attribute per state instead. Zenith's List, Table and DataTable keep their own data-state values, so check what this reads.",
+        suggestion: `Use ${replacement}.`,
+      })
+    )
+  }
+  for (const m of stripped.matchAll(RADIX_VAR_RE)) {
+    const replacement = radixVariableReplacement(m[0])
+    findings.push(
+      makeFinding(identity, {
+        code: "radix-css-variable",
+        severity: "error",
+        confidence: "high",
+        file: fileLabel,
+        line: lineOf(m.index),
+        column: colOf(m.index),
+        evidence: m[0],
+        explanation:
+          "Base UI publishes no --radix-* custom property, so this resolves to nothing after the upgrade.",
+        suggestion: replacement
+          ? `Read ${replacement.baseUi} instead (${replacement.parts}).`
+          : "No Zenith family sets a Base UI counterpart for this variable; the declaration that reads it needs another source.",
+      })
+    )
+  }
   return findings
 }
 
+/** The upgrade guide's rename table, from RADIX_RENAMES: one Markdown document with two tables. */
+export function renderRadixRenamesMarkdown() {
+  const code = (s) => `\`${s}\``
+  const attributeRows = RADIX_RENAMES.attributes.map(
+    (a) =>
+      `| ${code(`data-state="${a.value}"`)} | ${a.baseUi ? code(a.baseUi) : `none (${a.note})`} | ${describeParts(a.parts)} |`
+  )
+  const variableRows = RADIX_RENAMES.variables.map((v) => {
+    const parts = v.parts
+      ? describeParts(v.parts)
+      : RADIX_VARIABLE_FAMILIES.map((f) => f.zenith).join(", ")
+    return `| ${code(v.radix)} | ${code(v.baseUi)} | ${parts} |`
+  })
+  const families = RADIX_VARIABLE_FAMILIES.map(
+    (f) => `${code(f.radix)} (${f.zenith})`
+  ).join(", ")
+  const kept = RADIX_RENAMES.keptDataState
+    .map((k) => `${k.part} (${k.values.map((v) => code(`"${v}"`)).join(", ")})`)
+    .join("; ")
+  return [
+    "<!-- Generated by packages/react/scripts/migration-renames.mjs from RADIX_RENAMES in migration-diagnostics-core.mjs. Do not edit; run `bun scripts/migration-renames.mjs --write`. -->",
+    "",
+    "### State attributes",
+    "",
+    "| Radix | Base UI | Zenith parts |",
+    "| --- | --- | --- |",
+    ...attributeRows,
+    "",
+    `${RADIX_RENAMES.added.map(code).join(" and ")} are new: a part carries one while it enters or leaves. ${RADIX_RENAMES.unchanged.map(code).join(", ")} and the ${code("aria-*")} attributes are unchanged. Zenith's own parts keep ${code("data-state")}: ${kept}.`,
+    "",
+    "### CSS variables",
+    "",
+    "| Radix | Base UI | Zenith parts |",
+    "| --- | --- | --- |",
+    ...variableRows,
+    "",
+    `${code("<family>")} is ${families}.`,
+    "",
+  ].join("\n")
+}
+
 // ---------------------------------------------------------------------------
 // Rule 3: syntax-aware (TypeScript AST) palette-install analysis
 // ---------------------------------------------------------------------------

package/scripts/migration-sweep.mjs

@@ -16,6 +16,14 @@ import {
 const DEFAULT_PACKAGE_DIR = resolve(import.meta.dirname, "..")
 const KNOWN_FLAGS = new Set(["--json", "--package", "--exclude"])
 
+/** One finding: where and what, then the fix on its own line so the text report carries it too. */
+function printFinding(f) {
+  console.log(
+    `      [${f.severity}] ${f.code.padEnd(28)} ${f.file}:${f.line}:${f.column}  ${f.evidence}`
+  )
+  if (f.suggestion) console.log(`          → ${f.suggestion}`)
+}
+
 function usage() {
   return (
     "usage: node migration-sweep.mjs [--json] [--package <dir>] [--exclude <path>]... <path> [...]\n" +
@@ -157,11 +165,7 @@ export async function runCli(argv) {
               ? ` (${r.findings.length} finding(s) from the rules that did run, below)`
               : "")
         )
-        for (const f of r.findings) {
-          console.log(
-            `      [${f.severity}] ${f.code.padEnd(28)} ${f.file}:${f.line}:${f.column}  ${f.evidence}`
-          )
-        }
+        for (const f of r.findings) printFinding(f)
         continue
       }
       if (!r.findings.length) {
@@ -171,11 +175,7 @@ export async function runCli(argv) {
         continue
       }
       console.log(`  ✗ ${name} — ${r.findings.length} finding(s)`)
-      for (const f of r.findings) {
-        console.log(
-          `      [${f.severity}] ${f.code.padEnd(28)} ${f.file}:${f.line}:${f.column}  ${f.evidence}`
-        )
-      }
+      for (const f of r.findings) printFinding(f)
     }
     console.log("")
   }

package/testing/setup.cjs

@@ -0,0 +1,87 @@
+/**
+ * Test setup for consumers of this package, for Vitest and Jest alike.
+ *
+ * WHY THIS EXISTS. Base UI, which sits under Switch, Checkbox, Radio and Select, re-dispatches a
+ * label's click as `new PointerEvent("click")`, the event type browsers use for clicks. jsdom
+ * added `PointerEvent` in 27; on an older jsdom (26 and below) the constructor does not exist, the
+ * dispatch throws, and the click never reaches the control. Nothing is wrong in the app.
+ *
+ * It installs a `PointerEvent` only where there is none. It mirrors Chromium's defaults for
+ * `new PointerEvent(type)`, and steps aside wherever the environment already has one, so it is
+ * safe to keep after a jsdom upgrade. It does nothing outside a DOM (a Node test environment).
+ *
+ * USAGE
+ *
+ *   // vitest.config.ts
+ *   export default defineConfig({
+ *     test: {
+ *       environment: "jsdom",
+ *       setupFiles: ["@epilot/zenith-react/testing/setup.cjs"],
+ *     },
+ *   })
+ *
+ *   // jest.config.cjs
+ *   const griffel = require("@epilot/zenith-react/testing/jest-preset.cjs")
+ *
+ *   module.exports = griffel.withGriffel(
+ *     {
+ *       testEnvironment: "jsdom",
+ *       setupFiles: ["@epilot/zenith-react/testing/setup.cjs"],
+ *       // Jest 28+ resolves package exports with the `require` condition, which
+ *       // @epilot/zenith-react does not have: without the mapping the first import
+ *       // fails with "Cannot find module".
+ *       moduleNameMapper: {
+ *         "^@epilot/zenith-react$":
+ *           "<rootDir>/node_modules/@epilot/zenith-react/dist/index.js",
+ *         "^@epilot/zenith-runtime/v1$":
+ *           "<rootDir>/node_modules/@epilot/zenith-runtime/dist/v1/index.js",
+ *       },
+ *     },
+ *     { alsoTransform: ["@epilot/zenith-runtime", "@base-ui", "@floating-ui"] }
+ *   )
+ *
+ * Keep it in `setupFiles` (it runs before the test framework and the first import of a component);
+ * a setup run later still works, but a module that read `PointerEvent` at import time would not
+ * see it.
+ */
+function installPointerEvent(scope) {
+  if (typeof scope.MouseEvent === "undefined") return false
+  if (typeof scope.PointerEvent !== "undefined") return false
+
+  class PointerEvent extends scope.MouseEvent {
+    constructor(type, init = {}) {
+      super(type, init)
+      this.pointerId = init.pointerId ?? 0
+      this.width = init.width ?? 1
+      this.height = init.height ?? 1
+      this.pressure = init.pressure ?? 0
+      this.tangentialPressure = init.tangentialPressure ?? 0
+      this.tiltX = init.tiltX ?? 0
+      this.tiltY = init.tiltY ?? 0
+      this.twist = init.twist ?? 0
+      this.pointerType = init.pointerType ?? ""
+      this.isPrimary = init.isPrimary ?? false
+      this._coalescedEvents = init.coalescedEvents ?? []
+      this._predictedEvents = init.predictedEvents ?? []
+    }
+
+    getCoalescedEvents() {
+      return [...this._coalescedEvents]
+    }
+
+    getPredictedEvents() {
+      return [...this._predictedEvents]
+    }
+  }
+
+  scope.PointerEvent = PointerEvent
+  // Vitest copies the jsdom window onto `globalThis` once; the class has to reach both.
+  if (typeof globalThis !== "undefined" && globalThis !== scope) {
+    globalThis.PointerEvent = PointerEvent
+  }
+  return true
+}
+
+if (typeof window !== "undefined") installPointerEvent(window)
+
+module.exports = { installPointerEvent }