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

package/codemods/migrate/lib/types.ts

@@ -0,0 +1,114 @@
+/**
+ * The contract between an entry transform (`from-volt.ts`, `from-base-elements.ts`) and the rule
+ * modules it runs. A rule module is one file per legacy component:
+ *
+ *   export const handles = ["CircularProgress", "CircularProgressProps"]
+ *   export function migrate(ctx: MigrateContext) { … }
+ *
+ * and is listed in its source's registry (`migrate/<source>/index.ts`). The entry finds the legacy
+ * imports, calls `migrate` once per file for every rule with at least one handled name imported,
+ * then rewrites the imports from the rule's `move`/`keep` decisions and prints one report line
+ * per TODO. A rule never touches import declarations itself.
+ */
+import type {
+  ASTPath,
+  Collection,
+  FileInfo,
+  Identifier,
+  JSCodeshift,
+  JSXElement,
+  ImportDeclaration,
+} from "jscodeshift"
+import type { JsxHelpers } from "./jsx"
+
+export const ZENITH = "@epilot/zenith-react"
+
+/** The marker in every comment the migration leaves behind; `rg 'TODO\(zenith-migrate\)'` lists them. */
+export const TODO_TAG = "TODO(zenith-migrate)"
+
+export type MigrationRule = {
+  /**
+   * Export names of the legacy package this rule owns, value and type names alike. The runner
+   * rejects a registry where two rules claim the same name.
+   */
+  handles: readonly string[]
+  /**
+   * Bare module specifiers this rule owns besides named exports, such as a stylesheet
+   * (`<package>/style.css`). The rule runs when the file imports any of them.
+   */
+  handlesModules?: readonly string[]
+  migrate(ctx: MigrateContext): void
+}
+
+export type MigrateContext = {
+  j: JSCodeshift
+  root: Collection
+  file: FileInfo
+  /** The legacy package, e.g. `@epilot/base-elements`. */
+  source: string
+  /** Legacy export name → local binding, for every name this file imports from `source`. */
+  names: Readonly<Record<string, string>>
+  /** Zenith export name → local binding, for what the file already imports from Zenith. */
+  zenith: Readonly<Record<string, string>>
+  /** JSX helpers bound to this file's `j`. */
+  jsx: JsxHelpers
+
+  /**
+   * Move legacy export `name` onto the Zenith import as `target` (default: the same name). An
+   * un-aliased binding is renamed throughout the file (`<CircularProgress>` → `<Spinner>`); an
+   * alias is kept (`CircularProgress as Progress` → `Spinner as Progress`). No-op when the
+   * file does not import `name`.
+   */
+  move(name: string, target?: string): void
+  /**
+   * Like `move`, onto another package's import (a type Zenith does not re-export but its
+   * upstream library does). The import is created next to the Zenith one when missing.
+   */
+  moveTo(module: string, name: string, target?: string): void
+  /**
+   * Leave legacy export `name` on its import and report why, as one TODO at the import. The
+   * message is the fix: say what to use instead, in one line, so the reader needs no mapping doc.
+   * Without a message the name is kept silently, for a rule that already reported every use
+   * site (one report per TODO comment stays true).
+   */
+  keep(name: string, message?: string): void
+  /**
+   * References to legacy export `name` as a value outside JSX tags: `styled(X)`, `component={X}`,
+   * `const Y = X`, `export { X }`. Moving such a binding swaps the component under code the
+   * rule did not rewrite, so a rule checks this before `move` or uses `moveElements`.
+   */
+  valueUses(name: string): Collection<Identifier>
+  /**
+   * `move(name, target)` when `name` is only used as JSX tags; otherwise the JSX elements are
+   * retagged to the Zenith export (`ensureZenith(target)`), the legacy binding is kept silently
+   * and each value use gets a TODO. Returns the local tag the elements now carry, or undefined
+   * when nothing was imported.
+   */
+  moveElements(name: string, target?: string): string | undefined
+  /**
+   * Remove legacy export `name` from its import with no TODO and no Zenith counterpart, for a
+   * name whose every use the rule rewrote away (MUI's DialogContent body → `<div>`). Wins over
+   * `move` and `keep`; the declaration is pruned when nothing is left on it.
+   */
+  drop(name: string): void
+  /**
+   * Report a TODO at `path`: a `TODO(zenith-migrate): <component>: <message>` comment on the node
+   * (a JSX comment sibling inside JSX children) plus one report line `<line> <component>: <message>`.
+   * A moved element must still compile against Zenith's types: drop what has no equivalent and
+   * name it here (`dropped value={progress}: …`).
+   */
+  todo(path: ASTPath, component: string, message: string): void
+  /**
+   * Import Zenith export `name` (added to the Zenith import when missing) and return its local
+   * binding. For rules that rewrite one element at a time instead of moving the whole binding.
+   */
+  ensureZenith(name: string): string
+  /** JSX elements whose tag is the local binding of legacy export `name`. */
+  elements(name: string): Collection<JSXElement>
+  /** Import declarations of exactly this module specifier (for `handlesModules`). */
+  imports(moduleSpecifier: string): Collection<ImportDeclaration>
+  /** Remove an import declaration (a stylesheet, for instance). */
+  removeImport(path: ASTPath<ImportDeclaration>): void
+}
+
+export type TodoEntry = { line: number; component: string; message: string }

package/codemods/migrate/volt/class-helpers.ts

@@ -0,0 +1,37 @@
+/**
+ * Volt's Tailwind-era class helpers have no Zenith equivalent: Zenith styles with Griffel atoms
+ * (`makeZenithStyles`) and composes class names with `mergeClasses`. Each stays on the Volt import
+ * with the replacement in its TODO.
+ */
+import type { MigrateContext } from "../lib/types"
+
+const VARIANTS = [
+  "buttonVariants",
+  "textVariants",
+  "toggleVariants",
+  "avatarVariants",
+  "badgeVariants",
+  "pillVariants",
+  "skeletonVariants",
+] as const
+
+export const handles = ["cn", "CloseIcon", ...VARIANTS] as const
+
+export function migrate(ctx: MigrateContext): void {
+  ctx.keep(
+    "cn",
+    "use mergeClasses from @epilot/zenith-react for class strings (no object syntax, no Tailwind dedupe); Tailwind utilities become makeZenithStyles atoms"
+  )
+  ctx.keep(
+    "CloseIcon",
+    "not exported by Zenith; render your icon set's X (lucide-react `X`) at 1rem, or use DialogClose/DrawerClose which draw their own"
+  )
+  for (const name of VARIANTS) {
+    const component = name.replace(/Variants$/, "")
+    const Component = component[0].toUpperCase() + component.slice(1)
+    ctx.keep(
+      name,
+      `no class-variance helpers in Zenith; render <${Component} variant size> or compose with makeZenithStyles + mergeClasses`
+    )
+  }
+}

package/codemods/migrate/volt/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Registry of Volt rules. One module per family or concern; every module exports `handles` and
+ * `migrate` (see `../lib/types.ts`).
+ */
+import type { MigrationRule } from "../lib/types"
+import * as classHelpers from "./class-helpers"
+import * as pagination from "./pagination"
+import * as sameName from "./same-name"
+import * as stylesheets from "./stylesheets"
+import * as tanstackTypes from "./tanstack-types"
+
+export const rules: readonly MigrationRule[] = [
+  sameName,
+  stylesheets,
+  tanstackTypes,
+  classHelpers,
+  pagination,
+]

package/codemods/migrate/volt/pagination.ts

@@ -0,0 +1,26 @@
+/**
+ * `useClientPagination` did not move to Zenith; its pure parts (`calculatePagination`,
+ * `clampPage`, `getPageNumbers`) did, so the hook is a few lines of `useState` on top of them.
+ */
+import type { MigrateContext } from "../lib/types"
+
+export const handles = [
+  "useClientPagination",
+  "UseClientPaginationOptions",
+  "UseClientPaginationReturn",
+] as const
+
+export function migrate(ctx: MigrateContext): void {
+  ctx.keep(
+    "useClientPagination",
+    "not in Zenith; keep page/pageSize in useState and derive the slice with calculatePagination + clampPage from @epilot/zenith-react"
+  )
+  ctx.keep(
+    "UseClientPaginationOptions",
+    "not in Zenith; type the options of your own hook (see useClientPagination)"
+  )
+  ctx.keep(
+    "UseClientPaginationReturn",
+    "not in Zenith; PaginationMeta from @epilot/zenith-react covers the derived part"
+  )
+}

package/codemods/migrate/volt/same-name.ts

@@ -0,0 +1,293 @@
+/**
+ * Zenith kept Volt's names: everything listed here moves onto the Zenith import unchanged
+ * (components, hooks, helpers and their prop types). The list is Volt 1.7's barrel intersected
+ * with Zenith's public exports; `same-name.test.ts` keeps it honest against `src/index.ts`. A Volt
+ * name missing here is kept on the Volt import with a TODO, never silently mapped.
+ */
+import type { MigrateContext } from "../lib/types"
+
+export const handles = [
+  "ClearButton",
+  "Breadcrumb",
+  "BreadcrumbItem",
+  "Button",
+  "ButtonGroup",
+  "ButtonGroupSeparator",
+  "ButtonGroupText",
+  "Field",
+  "FieldSet",
+  "FieldContent",
+  "FieldDescription",
+  "FieldError",
+  "FieldGroup",
+  "FieldLabel",
+  "FieldLabelContent",
+  "useFieldContext",
+  "FieldInput",
+  "FieldInputGroup",
+  "FieldGroupAddon",
+  "FieldTextarea",
+  "FieldCombobox",
+  "FieldComboboxGroup",
+  "FieldComboboxGroupLabel",
+  "FieldComboboxValue",
+  "FieldComboboxTrigger",
+  "FieldComboboxContent",
+  "FieldComboboxItem",
+  "FieldComboboxItemCheckIcon",
+  "FieldComboboxEmpty",
+  "FieldComboboxSeparator",
+  "FieldComboboxInput",
+  "FieldComboboxList",
+  "FieldComboboxLoading",
+  "FieldComboboxClear",
+  "FieldComboboxClearValue",
+  "FieldComboboxPlaceholder",
+  "Select",
+  "SelectContent",
+  "SelectGroup",
+  "SelectItem",
+  "SelectLabel",
+  "SelectScrollDownButton",
+  "SelectScrollUpButton",
+  "SelectSeparator",
+  "SelectTrigger",
+  "SelectTriggerClear",
+  "SelectValue",
+  "Label",
+  "List",
+  "ListItem",
+  "ListItemActions",
+  "ListItemText",
+  "ListItemDescription",
+  "ListGroup",
+  "ListGroupLabel",
+  "ListGroupContent",
+  "ListProps",
+  "ListItemProps",
+  "ListItemActionsProps",
+  "ListItemTextProps",
+  "ListItemDescriptionProps",
+  "ListGroupProps",
+  "ListGroupLabelProps",
+  "ListGroupContentProps",
+  "ListDensity",
+  "ListItemStatus",
+  "Text",
+  "Tooltip",
+  "TooltipTrigger",
+  "TooltipContent",
+  "TooltipProvider",
+  "Switch",
+  "Toggle",
+  "ToggleProps",
+  "ToggleGroup",
+  "ToggleGroupItem",
+  "ToggleGroupProps",
+  "ToggleGroupItemProps",
+  "Separator",
+  "Popover",
+  "PopoverTrigger",
+  "PopoverContent",
+  "PopoverAnchor",
+  "PopoverPortal",
+  "Dialog",
+  "DialogClose",
+  "DialogContent",
+  "DialogDescription",
+  "DialogFooter",
+  "DialogHeader",
+  "DialogOverlay",
+  "DialogPortal",
+  "DialogTitle",
+  "DialogTrigger",
+  "Drawer",
+  "DrawerClose",
+  "DrawerContent",
+  "DrawerDescription",
+  "DrawerFooter",
+  "DrawerHeader",
+  "DrawerOverlay",
+  "DrawerPortal",
+  "DrawerTitle",
+  "DrawerTrigger",
+  "Checkbox",
+  "RadioGroup",
+  "RadioGroupItem",
+  "SegmentedControl",
+  "SegmentedControlItem",
+  "SegmentedControlProps",
+  "SegmentedControlItemProps",
+  "SegmentedControlLayout",
+  "OptionCard",
+  "OptionCardGroup",
+  "OptionCardMedia",
+  "OptionCardContent",
+  "OptionCardTitle",
+  "OptionCardDescription",
+  "OptionCardControl",
+  "OptionCardProps",
+  "OptionCardGroupProps",
+  "OptionCardLayout",
+  "OptionCardControlType",
+  "OptionCardControlProps",
+  "OptionCardContentProps",
+  "OptionCardMediaProps",
+  "OptionCardMediaVariant",
+  "OptionCardTitleProps",
+  "OptionCardDescriptionProps",
+  "Avatar",
+  "AvatarProps",
+  "AvatarColor",
+  "AvatarSize",
+  "AvatarGroup",
+  "AvatarGroupProps",
+  "Badge",
+  "Pill",
+  "Callout",
+  "CalloutTitle",
+  "CalloutDescription",
+  "CalloutAction",
+  "Accordion",
+  "AccordionItem",
+  "AccordionTrigger",
+  "AccordionContent",
+  "AlertDialog",
+  "AlertDialogPortal",
+  "AlertDialogOverlay",
+  "AlertDialogTrigger",
+  "AlertDialogContent",
+  "AlertDialogHeader",
+  "AlertDialogFooter",
+  "AlertDialogTitle",
+  "AlertDialogDescription",
+  "AlertDialogAction",
+  "AlertDialogCancel",
+  "Toaster",
+  "toast",
+  "Tabs",
+  "TabsList",
+  "TabsTrigger",
+  "TabsContent",
+  "Card",
+  "CardHeader",
+  "CardFooter",
+  "CardTitle",
+  "CardAction",
+  "CardDescription",
+  "CardContent",
+  "Skeleton",
+  "Spinner",
+  "Table",
+  "TableHeader",
+  "TableBody",
+  "TableFooter",
+  "TableRow",
+  "TableHead",
+  "TableCell",
+  "TableCaption",
+  "TablePagination",
+  "TablePaginationProps",
+  "TablePaginationLabels",
+  "calculatePagination",
+  "clampPage",
+  "getPageNumbers",
+  "PaginationParams",
+  "PaginationMeta",
+  "PageItem",
+  "DropdownMenu",
+  "DropdownMenuTrigger",
+  "DropdownMenuContent",
+  "DropdownMenuItem",
+  "DropdownMenuCheckboxItem",
+  "DropdownMenuRadioItem",
+  "DropdownMenuLabel",
+  "DropdownMenuSeparator",
+  "DropdownMenuShortcut",
+  "DropdownMenuGroup",
+  "DropdownMenuPortal",
+  "DropdownMenuSub",
+  "DropdownMenuSubContent",
+  "DropdownMenuSubTrigger",
+  "DropdownMenuRadioGroup",
+  "DataTable",
+  "DataTableProps",
+  "useDataTable",
+  "useDataTableVirtualizer",
+  "getSelectedRowData",
+  "DataTableVirtualizerContext",
+  "DataTableContextValue",
+  "DataTablePaginationConfig",
+  "DataTableVirtualizationConfig",
+  "DataTableVirtualizerContextValue",
+  "DataTableCellOverflow",
+  "DataTableContent",
+  "DataTableContentProps",
+  "DataTableHeader",
+  "DataTableHeaderProps",
+  "DataTableBody",
+  "DataTableBodyProps",
+  "DataTableLoading",
+  "DataTableLoadingProps",
+  "DataTableError",
+  "DataTableErrorProps",
+  "DataTableRow",
+  "DataTableRowProps",
+  "DataTablePagination",
+  "DataTablePaginationProps",
+  "DataTableColumnHeader",
+  "DataTableColumnHeaderProps",
+  "DataTableColumnVisibility",
+  "DataTableColumnVisibilityProps",
+  "DataTableColumnOrder",
+  "DataTableColumnOrderProps",
+  "DataTableToolbar",
+  "DataTableToolbarProps",
+  "DataTableFooter",
+  "DataTableFooterProps",
+  "DataTableResizeHandle",
+  "DataTableResizeHandleProps",
+  "getPinnedColumnOffset",
+  "isLastLeftPinnedColumn",
+  "isFirstRightPinnedColumn",
+  "PinningPosition",
+  "ColumnDef",
+  "ColumnSizingState",
+  "RowSelectionState",
+  "SortingState",
+  "VisibilityState",
+  "DateTimePicker",
+  "DateTimePickerRoot",
+  "DateTimePickerInput",
+  "DateTimePickerPopover",
+  "DateTimePickerPanel",
+  "Calendar",
+  "TimePicker",
+  "DateTimePickerProps",
+  "DateTimePickerRootProps",
+  "DateTimePickerInputProps",
+  "DateTimePickerPopoverProps",
+  "DateTimePickerPanelProps",
+  "CalendarProps",
+  "TimePickerProps",
+  "DateTimePickerLocale",
+  "DateRangePicker",
+  "RangeCalendar",
+  "DateRangePickerProps",
+  "DateRange",
+  "RangeCalendarProps",
+  "CollapsibleSidebar",
+  "CollapsibleSidebarContent",
+  "CollapsibleSidebarCondensed",
+  "CollapsibleSidebarToggle",
+  "useCollapsibleSidebar",
+  "ScrollOverflow",
+  "ScrollOverflowProps",
+  "useScrollOverflow",
+  "UseScrollOverflowOptions",
+  "UseScrollOverflowReturn",
+] as const
+
+export function migrate(ctx: MigrateContext): void {
+  for (const name of handles) ctx.move(name)
+}

package/codemods/migrate/volt/stylesheets.ts

@@ -0,0 +1,18 @@
+/**
+ * Volt's stylesheet imports are removed: Zenith injects its Griffel styles at runtime and ships
+ * no CSS files. `preflight.css` was a Tailwind reset; Zenith's AppearanceBoundary scopes its own.
+ */
+import type { MigrateContext } from "../lib/types"
+
+export const handles = [] as const
+
+export const handlesModules = [
+  "@epilot/volt-ui-react/style.css",
+  "@epilot/volt-ui-react/preflight.css",
+  "@epilot/volt-ui-react/font.css",
+] as const
+
+export function migrate(ctx: MigrateContext): void {
+  for (const m of handlesModules)
+    ctx.imports(m).forEach((path) => ctx.removeImport(path))
+}

package/codemods/migrate/volt/tanstack-types.ts

@@ -0,0 +1,20 @@
+/**
+ * Volt re-exported more TanStack Table types than Zenith does. The ones Zenith does not re-export
+ * come from `@tanstack/react-table` directly (a dependency the consumer already has through its
+ * table code; add it if not).
+ */
+import type { MigrateContext } from "../lib/types"
+
+export const TANSTACK = "@tanstack/react-table"
+
+export const handles = [
+  "ColumnFiltersState",
+  "ColumnOrderState",
+  "ColumnPinningState",
+  "FilterFn",
+  "PaginationState",
+] as const
+
+export function migrate(ctx: MigrateContext): void {
+  for (const name of handles) ctx.moveTo(TANSTACK, name)
+}