@carto/ps-react-ui 5.1.0 → 6.0.0

package/src/migration/v4/rules.ts

@@ -0,0 +1,444 @@
+/**
+ * The rule set for the MUI v9 / Meridian 5 migration.
+ *
+ * This is the single source of truth. `docs/migration/mui-9-meridian-5.md`
+ * walks a reader through the same rules in prose, and `migration.test.ts`
+ * fails if the guide stops covering a jump, so the two cannot drift apart
+ * at the level the guide is written.
+ *
+ * Every rule either REWRITES the code or ANNOTATES it with a `TODO(mui9)`
+ * comment. Nothing is reported and then dropped: a rule with no mechanical
+ * rewrite — a `Grid container` whose parent lives in another file, a
+ * `freeSolo` handler only the author can narrow — leaves the question in the
+ * file, where the next person to open it will see it.
+ *
+ * Order matters within a jump, and the array order is the run order:
+ * `grid-legacy` renames `GridLegacy` to `Grid` so that `grid-item-prop`,
+ * which runs next, can convert its props.
+ */
+import type { RuleContext } from './transforms/helpers'
+import * as v5v6 from './transforms/v5-v6'
+import * as v6v7 from './transforms/v6-v7'
+import * as v7v9Props from './transforms/v7-v9-props'
+import * as v7v9Dom from './transforms/v7-v9-dom'
+import * as meridian from './transforms/meridian-5'
+import * as psReactUi from './transforms/ps-react-ui'
+
+/**
+ * The version hops, in the order they must be done. There is no MUI v8.
+ * `ps-react-ui` is this library's own major, the one that ships v9: it
+ * removed widgets v1 and moved widgets v2 onto the `widgets` paths.
+ */
+export const JUMPS = [
+  'v5-v6',
+  'v6-v7',
+  'v7-v9',
+  'meridian-5',
+  'ps-react-ui',
+] as const
+
+export type Jump = (typeof JUMPS)[number]
+
+/**
+ * What the rule does to the code. `annotate` marks the rules that cannot be
+ * applied mechanically — they are the ones worth reading one by one, and
+ * several of them fail at runtime rather than at compile time.
+ */
+export type Handling = 'rewrite' | 'annotate'
+
+/**
+ * `silent` marks the rules that produce no error anywhere: the class name
+ * stops matching, the styling disappears, and every build and test stays
+ * green. They are the reason this codemod exists.
+ */
+export type Severity = 'silent' | 'build-error' | 'runtime-error'
+
+export interface Rule {
+  id: string
+  jump: Jump
+  handling: Handling
+  severity: Severity
+  /** One line, imperative: what the rule does, or what the reader must do. */
+  action: string
+  /** Applies the rule to a parsed module. Returns the number of sites hit. */
+  apply?: (context: RuleContext) => number
+  /**
+   * Applies the rule to a file jscodeshift cannot parse — a stylesheet, an
+   * `.md` or an `.mdx`. The codemods never touch documentation, so sample
+   * snippets keep teaching the old API long after the source moved on, and
+   * people copy them. Found the hard way: this repo's docs still had 58
+   * `<Grid item>` and a documented `componentsProps` prop after the source
+   * was fully migrated.
+   */
+  applyText?: (source: string) => string
+}
+
+export const RULES: readonly Rule[] = [
+  // ---------------------------------------------------------------- v5 → v6
+  {
+    id: 'listitem-removed-props',
+    jump: 'v5-v6',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action:
+      '`ListItem` lost `button`/`autoFocus`/`disabled`/`selected`; rewritten to `ListItemButton`.',
+    apply: v5v6.listItemRemovedProps,
+  },
+  {
+    id: 'typography-color-callback',
+    jump: 'v5-v6',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action:
+      "`Typography`'s `color` no longer takes a theme callback; moved into `sx`.",
+    apply: v5v6.typographyColorCallback,
+  },
+  {
+    id: 'divider-hr-selector',
+    jump: 'v5-v6',
+    handling: 'rewrite',
+    severity: 'silent',
+    action:
+      'A vertical `Divider` renders a `<div>`, not an `<hr>`; `hr` selectors rewritten to `.MuiDivider-root`.',
+    apply: v5v6.dividerHrSelector,
+    applyText: v5v6.dividerHrSelectorText,
+  },
+
+  // ---------------------------------------------------------------- v6 → v7
+  {
+    id: 'grid-legacy',
+    jump: 'v6-v7',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action:
+      '`GridLegacy` is removed in v9; renamed to `Grid` so the props migrate with it.',
+    apply: v6v7.gridLegacy,
+  },
+  {
+    id: 'grid-item-prop',
+    jump: 'v6-v7',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action:
+      'The new `Grid` has no `item`; breakpoints moved into `size={{ xs, md }}`.',
+    apply: v6v7.gridItemProp,
+  },
+  {
+    id: 'grid-container-width',
+    jump: 'v6-v7',
+    handling: 'annotate',
+    severity: 'silent',
+    action:
+      'The v1 Grid container was 100% wide; the new one shrinks to its content inside a flex parent. Check each container still fills its parent.',
+    apply: v6v7.gridContainerWidth,
+  },
+  {
+    id: 'deep-import',
+    jump: 'v6-v7',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action:
+      'No imports deeper than one level; `Variant` renamed to `TypographyVariant`.',
+    apply: v6v7.deepImport,
+  },
+  {
+    id: 'mui-lab-import',
+    jump: 'v6-v7',
+    handling: 'rewrite',
+    severity: 'build-error',
+    // What did not merge never went stable either: every `@mui/lab` dist-tag
+    // points at a beta (`latest-v9` is 9.0.0-beta.9), so a `^9` range does
+    // not resolve. `Timeline` is lab-only at every major, so the dependency
+    // survives this rule.
+    action:
+      'The `@mui/lab` exports that merged into core now import from `@mui/material`. For what is left, pin the beta `npm dist-tag ls @mui/lab` names.',
+    apply: v6v7.muiLabImport,
+  },
+  {
+    id: 'slider-value-narrowing',
+    jump: 'v6-v7',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action:
+      "v7 narrows `Slider`'s value to `number`; the cast and the `Array.isArray` guard around it are dead and leak `any`.",
+    apply: v6v7.sliderValueNarrowing,
+  },
+
+  // ---------------------------------------------------------------- v7 → v9
+  {
+    id: 'system-props',
+    jump: 'v7-v9',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action:
+      'System props are gone from Box/Typography/Grid/Stack/Link; moved into `sx`.',
+    apply: v7v9Props.systemProps,
+  },
+  {
+    id: 'renamed-prop-bags',
+    jump: 'v7-v9',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action:
+      'Prop bags fold into `slotProps` (PaperProps→paper, inputProps→htmlInput, MenuListProps→list, …).',
+    apply: v7v9Props.renamedPropBags,
+  },
+  {
+    id: 'components-prop',
+    jump: 'v7-v9',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action: '`components`/`componentsProps` become `slots`/`slotProps`.',
+    apply: v7v9Props.componentsProp,
+  },
+  {
+    id: 'theme-path-inline-style',
+    jump: 'v7-v9',
+    handling: 'annotate',
+    severity: 'silent',
+    // Not a v9 change — inline `style` never read the theme. It is filed
+    // here because this is the jump that makes people move a colour out of
+    // a `color` prop, and `style` is the wrong place to land it.
+    action:
+      'A palette path in an inline `style` has no resolver; use `sx` or resolve it first.',
+    apply: v7v9Props.themePathInInlineStyle,
+  },
+  {
+    id: 'typography-color-system-prop',
+    jump: 'v7-v9',
+    handling: 'rewrite',
+    severity: 'silent',
+    // v5, v6 and v7 all still run `extendSxProp` in Typography (v6 carries a
+    // `TODO: Remove in v7` that did not happen), so a dot path keeps working
+    // until v9 drops the resolver and renders it as a literal CSS color.
+    // `color='primary'` and `color='textSecondary'` are the component's own
+    // prop and are fine in v9.
+    action:
+      "Typography's `color` no longer resolves a theme path; moved into `sx`.",
+    apply: v7v9Props.typographyColorSystemProp,
+  },
+  {
+    id: 'dot-path-color',
+    jump: 'v7-v9',
+    handling: 'rewrite',
+    severity: 'silent',
+    action:
+      "Dot-path palette colors are inert on MUI components; moved into `sx={{ color: '…' }}`.",
+    apply: v7v9Props.dotPathColor,
+  },
+  {
+    id: 'disable-escape-key-down',
+    jump: 'v7-v9',
+    handling: 'rewrite',
+    severity: 'build-error',
+    // Filed under `Popover` at first, which was too narrow: `Dialog` and
+    // `Modal` lost it too, and there deleting the prop changes behaviour —
+    // escape now reaches `onClose`, so a dialog that could not be dismissed
+    // becomes dismissable unless the handler ignores that reason.
+    action:
+      '`disableEscapeKeyDown` is gone from `Popover`, `Dialog` and `Modal`. Removed; where an `onClose` exists, the behaviour change is flagged.',
+    apply: v7v9Props.disableEscapeKeyDown,
+  },
+  {
+    id: 'tablepagination-slots-actions',
+    jump: 'v7-v9',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action:
+      '`slots.actions` now means the actions sub-slots; replacing the component is `ActionsComponent`.',
+    apply: v7v9Props.tablePaginationSlotsActions,
+  },
+  {
+    id: 'autocomplete-render-tags',
+    jump: 'v7-v9',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action:
+      '`Autocomplete`: `renderTags`→`renderValue`; `ListboxComponent`/`PaperComponent`→`slots`.',
+    apply: v7v9Props.autocompleteRenderTags,
+  },
+  {
+    id: 'divider-light',
+    jump: 'v7-v9',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action: '`Divider` lost the `light` prop.',
+    apply: v7v9Props.dividerLight,
+  },
+  {
+    id: 'datepicker-placeholder',
+    jump: 'v7-v9',
+    handling: 'rewrite',
+    severity: 'silent',
+    action:
+      "`DatePicker`'s `placeholder` is deprecated and reaches nobody — the field renders editable sections, not one input.",
+    apply: v7v9Props.datepickerPlaceholder,
+  },
+  {
+    id: 'autocomplete-free-solo-value',
+    jump: 'v7-v9',
+    handling: 'annotate',
+    severity: 'build-error',
+    // v9 types what `freeSolo` always did at runtime: the user can commit a
+    // value that is not an option.
+    action:
+      '`freeSolo` widens the value to `T | string`, so anything typed against your option type stops compiling — `isOptionEqualToValue` as often as `onChange`. Narrow at the read; do not cast.',
+    apply: v7v9Props.autocompleteFreeSoloValue,
+  },
+  {
+    id: 'slot-props-off-mui',
+    jump: 'v7-v9',
+    handling: 'annotate',
+    severity: 'build-error',
+    // `@mui/codemod` matches on the prop name and ignores the import, so it
+    // rewrites third-party components that happen to share a prop.
+    action:
+      "A `slots`/`slotProps`/`ActionsComponent` rewrite landed on a component that is not Material UI's. Check the prop against the package it actually comes from.",
+    apply: v7v9Props.slotPropsOffMui,
+  },
+  {
+    id: 'consolidated-class-names',
+    jump: 'v7-v9',
+    handling: 'rewrite',
+    severity: 'silent',
+    // Both spellings of the size modifier exist: `textSizeSmall` on Button,
+    // plain `labelSmall` on Chip. Handling only the former misses half the
+    // consolidated classes.
+    action:
+      'v9 split compound classes: `<slot><Modifier>` → `<slot>` + `color<Color>`/`size<Size>`. The selector stops matching with no error.',
+    apply: v7v9Dom.consolidatedClassNames,
+    applyText: v7v9Dom.consolidatedClassNamesText,
+  },
+  {
+    id: 'style-overrides-consolidated-keys',
+    jump: 'v7-v9',
+    handling: 'annotate',
+    severity: 'silent',
+    action:
+      'A `styleOverrides` key naming a consolidated class no longer applies. Check every key against the v9 class table.',
+    apply: v7v9Dom.styleOverridesConsolidatedKeys,
+  },
+  {
+    id: 'styled-targeting-mui-classes',
+    jump: 'v7-v9',
+    handling: 'annotate',
+    severity: 'silent',
+    action:
+      'A `styled()` wrapper selecting `.Mui*` internals is the most common silent breakage; verify each selector still matches.',
+    apply: v7v9Dom.styledTargetingMuiClasses,
+  },
+  {
+    id: 'role-attribute-selector',
+    jump: 'v7-v9',
+    handling: 'rewrite',
+    severity: 'silent',
+    // `AccordionSummary` went from `<div role="button">` to a native
+    // `<button>` inside the new heading slot, so an attribute selector stops
+    // matching while `getByRole('button')` matches both.
+    action:
+      'Query by role, not by `[role="..."]`: components that became native elements carry the role implicitly.',
+    apply: v7v9Dom.roleAttributeSelector,
+  },
+  {
+    id: 'menuitem-outside-menulist',
+    jump: 'v7-v9',
+    handling: 'annotate',
+    severity: 'runtime-error',
+    action:
+      '`MenuItem` throws outside a `Menu`/`MenuList`. Compiles clean — tests that mount it bare fail.',
+    apply: v7v9Dom.menuItemOutsideMenuList,
+  },
+  {
+    id: 'outline-icons',
+    jump: 'v7-v9',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action:
+      'The 17 removed `*Outline` icons are renamed to the icon with identical path data — NOT by swapping the `Outline` suffix for `Outlined`, which resolves to a different glyph.',
+    apply: v7v9Dom.outlineIcons,
+    applyText: v7v9Dom.outlineIconsText,
+  },
+  {
+    id: 'outline-icon-naive-rename',
+    jump: 'v7-v9',
+    handling: 'annotate',
+    severity: 'silent',
+    action:
+      'These icon names exist in v9, but they are the outlined variant of the SOLID glyph. If they came from renaming a removed `*Outline` icon, the drawing changed.',
+    apply: v7v9Dom.outlineIconNaiveRename,
+  },
+  {
+    id: 'pickers-field-dom',
+    jump: 'v7-v9',
+    handling: 'annotate',
+    severity: 'silent',
+    action:
+      "The pickers field renders `role='spinbutton'` sections instead of an `<input>`; the `PickersYear` / `PickersMonth` wrappers are gone.",
+    apply: v7v9Dom.pickersFieldDom,
+  },
+
+  // ------------------------------------------------------------- Meridian 5
+  {
+    id: 'carto-theme-options',
+    jump: 'meridian-5',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action:
+      'Read values from the exported `theme`, not `cartoThemeOptions`; the `as unknown as Theme` cast is dropped.',
+    apply: meridian.cartoThemeOptions,
+  },
+  {
+    id: 'meridian-removed-widgets',
+    jump: 'meridian-5',
+    handling: 'annotate',
+    severity: 'build-error',
+    action:
+      'Meridian 4.0.0 removed the Builder chart widgets and their prop types; use `@carto/ps-react-ui` or Meridian `./charts`.',
+    apply: meridian.meridianRemovedWidgets,
+  },
+  {
+    id: 'meridian-renamed-api',
+    jump: 'meridian-5',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action:
+      'Meridian 3.0.0 renames: `AiTool`→`McpTool`, `CodeAreaProps`→`CodeAreaFieldProps`.',
+    apply: meridian.meridianRenamedApi,
+  },
+
+  // ------------------------------------------------------------ ps-react-ui
+  // Flag before renaming: a v1 import still points at `widgets/*` and a v2
+  // one at `widgets-v2/*`, so the order keeps the two apart on a first run.
+  {
+    id: 'widgets-v1-removed',
+    jump: 'ps-react-ui',
+    handling: 'annotate',
+    severity: 'build-error',
+    action:
+      'Widgets v1 is removed; imports of names only v1 exported are flagged for the v1 → v2 migration guide.',
+    apply: psReactUi.widgetsV1Removed,
+  },
+  {
+    id: 'widgets-v2-path',
+    jump: 'ps-react-ui',
+    handling: 'rewrite',
+    severity: 'build-error',
+    action:
+      '`@carto/ps-react-ui/widgets-v2/*` moved to `@carto/ps-react-ui/widgets/*`; the exports are unchanged.',
+    apply: psReactUi.widgetsV2Path,
+    applyText: psReactUi.widgetsV2PathText,
+  },
+]
+
+/** Which jumps a codebase still has to do, given what it currently has. */
+export function jumpsFor(muiMajor: number, meridianMajor: number): Jump[] {
+  const jumps: Jump[] = []
+  if (muiMajor < 6) jumps.push('v5-v6')
+  if (muiMajor < 7) jumps.push('v6-v7')
+  if (muiMajor < 9) jumps.push('v7-v9')
+  if (meridianMajor < 5) jumps.push('meridian-5')
+  // Always due: a codebase running this codemod is installing the major that
+  // made it, and the rules are no-ops where nothing imports the widgets.
+  jumps.push('ps-react-ui')
+  return jumps
+}

package/src/migration/v4/transform.ts

@@ -0,0 +1,92 @@
+/**
+ * The MUI v9 / Meridian 5 codemod.
+ *
+ * A jscodeshift transform, so it runs the same way as `@mui/codemod`:
+ *
+ *     npx jscodeshift \
+ *       --parser=tsx --extensions=ts,tsx,js,jsx,css,scss,md,mdx \
+ *       -t node_modules/@carto/ps-react-ui/src/migration/v4/transform.ts \
+ *       --jump=v7-v9 \
+ *       ./src
+ *
+ * `--jump` takes one jump or a comma-separated list; without it every jump
+ * runs, which is only what you want on a codebase starting at v5. Do the
+ * jumps one at a time and commit between them: the rules are written per
+ * major, and running the v9 rules over a v5 codebase skips the intermediate
+ * renames rather than composing with them.
+ *
+ * Point it at SOURCE, not at a workspace root. `@mui/codemod` produced 576
+ * parse errors when it was given one, from `.json`, built `dist/` output and
+ * recorded fixtures; the same applies here.
+ */
+import { extname } from 'node:path'
+import type { API, FileInfo, Options } from 'jscodeshift'
+import { JUMPS, RULES, type Jump } from './rules'
+
+/** Extensions jscodeshift's tsx parser can handle. Everything else is text. */
+const PARSEABLE = new Set([
+  '.ts',
+  '.tsx',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.cjs',
+  '.mts',
+  '.cts',
+])
+
+function requestedJumps(option: unknown): readonly Jump[] {
+  if (typeof option !== 'string' || option.trim() === '') return JUMPS
+
+  const requested = option
+    .split(',')
+    .map((jump) => jump.trim())
+    .filter(Boolean)
+
+  const unknown = requested.filter((jump) => !JUMPS.includes(jump as Jump))
+  if (unknown.length > 0) {
+    throw new Error(
+      `Unknown jump(s): ${unknown.join(', ')}. Expected one of ${JUMPS.join(', ')}.`,
+    )
+  }
+  return requested as Jump[]
+}
+
+export default function transform(
+  file: FileInfo,
+  api: API,
+  options: Options,
+): string | undefined {
+  const jumps = requestedJumps(options.jump)
+  const rules = RULES.filter((rule) => jumps.includes(rule.jump))
+
+  // Stylesheets and documentation, which the parser cannot take but which
+  // hold the class names and the icon names all the same.
+  if (!PARSEABLE.has(extname(file.path))) {
+    let source = file.source
+    for (const rule of rules) {
+      if (rule.applyText) source = rule.applyText(source)
+    }
+    return source === file.source ? undefined : source
+  }
+
+  const j = api.jscodeshift
+  const root = j(file.source)
+
+  let changed = 0
+  for (const rule of rules) {
+    if (rule.apply) changed += rule.apply({ j, root, api, path: file.path })
+  }
+
+  // Returning nothing for an untouched file is what keeps this codemod from
+  // having the defect it documents in MUI's: recast reprints whatever it is
+  // asked to print, adding semicolons against the repo's style, so a run
+  // that prints every file it parsed buries its real changes in reformatting
+  // that no automatic test can separate out afterwards.
+  if (changed === 0) return undefined
+
+  return root.toSource({ quote: 'single', objectCurlySpacing: true })
+}
+
+/** jscodeshift reads this instead of being told `--parser` on every run. */
+export const parser = 'tsx'