@carto/ps-react-ui 5.1.0 → 6.0.0

package/src/migration/v4/transforms/v7-v9-props.ts

@@ -0,0 +1,529 @@
+/**
+ * MUI v7 → v9 rewrites: props, slots and system props.
+ *
+ * The mechanical half of the largest jump. The half that needs judgement —
+ * class names, icons, DOM queries — is in `v7-v9-dom.ts`.
+ */
+import type {
+  ASTPath,
+  Collection,
+  JSCodeshift,
+  JSXAttribute,
+  JSXOpeningElement,
+} from 'jscodeshift'
+import {
+  annotate,
+  attribute,
+  attributeValue,
+  elementName,
+  elementsNamed,
+  importSourceOf,
+  mergeIntoObjectProp,
+  mergeIntoSx,
+  removeAttributes,
+  type Expression,
+  type RuleContext,
+} from './helpers'
+
+/**
+ * Where a JSX tag's component comes from, or undefined when the file does
+ * not import it.
+ *
+ * `<Foo.Bar />` resolves through `Foo`, which is the name an import can
+ * bind; the member is a property of whatever that import brought in.
+ */
+function tagSource(
+  j: JSCodeshift,
+  root: Collection,
+  opening: JSXOpeningElement,
+): string | undefined {
+  const { name } = opening
+  let node: JSXOpeningElement['name'] = name
+  while (node.type === 'JSXMemberExpression') node = node.object
+  return node.type === 'JSXIdentifier'
+    ? importSourceOf(j, root, node.name)
+    : undefined
+}
+
+/** Whether a tag is a component this codebase imported from another package. */
+function isForeign(source: string | undefined): boolean {
+  return source !== undefined && !source.startsWith('@mui/')
+}
+
+/** The components that carried system props, and the props they carried. */
+const SYSTEM_PROP_HOSTS = ['Box', 'Typography', 'Grid', 'Stack', 'Link']
+
+const SYSTEM_PROPS = [
+  'display',
+  'alignItems',
+  'justifyContent',
+  'flexDirection',
+  'flexWrap',
+  'flexGrow',
+  'gap',
+  'bgcolor',
+  'fontWeight',
+  'fontSize',
+  'textAlign',
+  'borderRadius',
+  'gridTemplateColumns',
+  'm',
+  'mt',
+  'mr',
+  'mb',
+  'ml',
+  'mx',
+  'my',
+  'p',
+  'pt',
+  'pr',
+  'pb',
+  'pl',
+  'px',
+  'py',
+]
+
+/** System props are gone from Box/Typography/Grid/Stack/Link; move to `sx`. */
+export function systemProps({ j, root }: RuleContext): number {
+  let changed = 0
+
+  elementsNamed(j, root, SYSTEM_PROP_HOSTS).forEach((path) => {
+    const opening = path.node.openingElement
+    const found = SYSTEM_PROPS.map(
+      (name) => [name, attribute(opening, name)] as const,
+    ).filter((entry) => entry[1] !== undefined)
+    if (found.length === 0) return
+
+    const entries = found.flatMap(([name, attr]) =>
+      attr ? [[name, attributeValue(j, attr)] as const] : [],
+    )
+    if (!mergeIntoSx(j, opening, entries)) {
+      if (
+        annotate(
+          j,
+          path,
+          `system props (${found.map(([name]) => name).join(', ')}) must move into \`sx\`, which here is not an object literal.`,
+        )
+      ) {
+        changed += 1
+      }
+      return
+    }
+
+    removeAttributes(
+      opening,
+      found.map(([name]) => name),
+    )
+    changed += found.length
+  })
+
+  return changed
+}
+
+/** Prop bags that fold into `slotProps`, old name → slot name. */
+const PROP_BAGS: Readonly<Record<string, string>> = {
+  PaperProps: 'paper',
+  InputProps: 'input',
+  inputProps: 'htmlInput',
+  MenuListProps: 'list',
+  primaryTypographyProps: 'primary',
+  secondaryTypographyProps: 'secondary',
+  TransitionProps: 'transition',
+  SelectProps: 'select',
+}
+
+/** `PaperProps={{…}}` → `slotProps={{ paper: {…} }}`. */
+export function renamedPropBags({ j, root }: RuleContext): number {
+  let changed = 0
+
+  root.find(j.JSXOpeningElement).forEach((path) => {
+    const opening = path.node
+    // `@mui/codemod` rewrites these by name alone and breaks components that
+    // merely share a prop. `slot-props-off-mui` reports what it did; this
+    // rule declines to repeat it.
+    if (isForeign(tagSource(j, root, opening))) return
+
+    const found = Object.entries(PROP_BAGS)
+      .map(([bag, slot]) => [bag, slot, attribute(opening, bag)] as const)
+      .filter((entry) => entry[2] !== undefined)
+    if (found.length === 0) return
+
+    const entries = found.flatMap(([, slot, attr]) =>
+      attr ? [[slot, attributeValue(j, attr)] as const] : [],
+    )
+    if (!mergeIntoObjectProp(j, opening, 'slotProps', entries)) {
+      if (
+        annotate(
+          j,
+          path,
+          `prop bags (${found.map(([bag]) => bag).join(', ')}) must move into \`slotProps\`, which here is not an object literal.`,
+        )
+      ) {
+        changed += 1
+      }
+      return
+    }
+
+    removeAttributes(
+      opening,
+      found.map(([bag]) => bag),
+    )
+    changed += found.length
+  })
+
+  return changed
+}
+
+/** `components`/`componentsProps` → `slots`/`slotProps`. */
+export function componentsProp({ j, root }: RuleContext): number {
+  let changed = 0
+
+  root.find(j.JSXAttribute).forEach((path) => {
+    const name = path.node.name
+    if (name.type !== 'JSXIdentifier') return
+    if (name.name === 'components') {
+      name.name = 'slots'
+      changed += 1
+    } else if (name.name === 'componentsProps') {
+      name.name = 'slotProps'
+      changed += 1
+    }
+  })
+
+  return changed
+}
+
+/**
+ * `color='text.secondary'` → `sx={{ color: 'text.secondary' }}`.
+ *
+ * Silent: v9 stopped resolving the theme path and renders the string as a
+ * literal CSS color, which browsers discard. The element keeps rendering,
+ * in the inherited color.
+ */
+function moveDotPathColor(
+  { j, root }: RuleContext,
+  hosts?: readonly string[],
+): number {
+  let changed = 0
+
+  const elements = hosts
+    ? elementsNamed(j, root, hosts)
+    : root.find(j.JSXElement)
+
+  elements.forEach((path) => {
+    const opening = path.node.openingElement
+    const color = attribute(opening, 'color')
+    if (!color || color.value?.type !== 'StringLiteral') return
+
+    const value = String(color.value.value)
+    // `color='primary'` and `color='textSecondary'` are the component's own
+    // prop and still work; only a dot path was the system-prop spelling.
+    if (!/^[a-z][A-Za-z]*\.[A-Za-z0-9]+$/.test(value)) return
+
+    if (!mergeIntoSx(j, opening, [['color', j.stringLiteral(value)]])) {
+      if (
+        annotate(
+          j,
+          path,
+          `\`color='${value}'\` is inert in v9 and must move into \`sx\`, which here is not an object literal.`,
+        )
+      ) {
+        changed += 1
+      }
+      return
+    }
+    removeAttributes(opening, ['color'])
+    changed += 1
+  })
+
+  return changed
+}
+
+/** `Typography`'s dot-path `color`, which survived until v9. */
+export function typographyColorSystemProp(context: RuleContext): number {
+  return moveDotPathColor(context, ['Typography'])
+}
+
+/** The same break on every other component, including re-exported ones. */
+export function dotPathColor(context: RuleContext): number {
+  return moveDotPathColor(context)
+}
+
+/** Components that lost `disableEscapeKeyDown` — not just `Popover`. */
+const ESCAPE_HOSTS = ['Popover', 'Dialog', 'Modal']
+
+/**
+ * Removes `disableEscapeKeyDown`, and says so where it changes behaviour.
+ *
+ * With no `onClose` the prop was already doing nothing. With one, escape now
+ * reaches the handler, so a dialog that could only be closed explicitly
+ * becomes dismissable unless the handler ignores that reason — which is not
+ * something a codemod can write into someone else's close logic.
+ */
+export function disableEscapeKeyDown({ j, root }: RuleContext): number {
+  let changed = 0
+
+  elementsNamed(j, root, ESCAPE_HOSTS).forEach((path) => {
+    const opening = path.node.openingElement
+    if (!attribute(opening, 'disableEscapeKeyDown')) return
+
+    removeAttributes(opening, ['disableEscapeKeyDown'])
+    changed += 1
+
+    if (attribute(opening, 'onClose')) {
+      annotate(
+        j,
+        path,
+        "escape now reaches `onClose`. To keep this undismissable, ignore `reason === 'escapeKeyDown'` in the handler.",
+      )
+    }
+  })
+
+  return changed
+}
+
+/** `slots={{ actions: X }}` → `ActionsComponent={X}` on TablePagination. */
+export function tablePaginationSlotsActions({ j, root }: RuleContext): number {
+  let changed = 0
+
+  elementsNamed(j, root, ['TablePagination']).forEach((path) => {
+    const opening = path.node.openingElement
+    const slots = attribute(opening, 'slots')
+    if (
+      slots?.value?.type !== 'JSXExpressionContainer' ||
+      slots.value.expression.type !== 'ObjectExpression'
+    ) {
+      return
+    }
+
+    const object = slots.value.expression
+    const actions = object.properties.find(
+      (property) =>
+        property.type === 'ObjectProperty' &&
+        property.key.type === 'Identifier' &&
+        property.key.name === 'actions',
+    )
+    if (actions?.type !== 'ObjectProperty') return
+
+    // In v9 `slots.actions` names the actions SUB-slots (firstButton,
+    // lastButton, …). Replacing the whole component is `ActionsComponent`.
+    object.properties = object.properties.filter(
+      (property) => property !== actions,
+    )
+    opening.attributes = [
+      ...(opening.attributes ?? []),
+      j.jsxAttribute(
+        j.jsxIdentifier('ActionsComponent'),
+        j.jsxExpressionContainer(actions.value as Expression),
+      ),
+    ]
+    if (object.properties.length === 0) removeAttributes(opening, ['slots'])
+    changed += 1
+  })
+
+  return changed
+}
+
+/** `renderTags` → `renderValue`; `ListboxComponent`/`PaperComponent` → slots. */
+export function autocompleteRenderTags({ j, root }: RuleContext): number {
+  let changed = 0
+
+  elementsNamed(j, root, ['Autocomplete']).forEach((path) => {
+    const opening = path.node.openingElement
+
+    const renderTags = attribute(opening, 'renderTags')
+    if (renderTags?.name.type === 'JSXIdentifier') {
+      renderTags.name.name = 'renderValue'
+      changed += 1
+    }
+
+    for (const [prop, slot] of [
+      ['ListboxComponent', 'listbox'],
+      ['PaperComponent', 'paper'],
+    ] as const) {
+      const attr = attribute(opening, prop)
+      if (!attr) continue
+      if (
+        mergeIntoObjectProp(j, opening, 'slots', [
+          [slot, attributeValue(j, attr)],
+        ])
+      ) {
+        removeAttributes(opening, [prop])
+        changed += 1
+      } else if (
+        annotate(j, path, `\`${prop}\` moves into \`slots.${slot}\`.`)
+      ) {
+        changed += 1
+      }
+    }
+  })
+
+  return changed
+}
+
+/** `Divider` lost `light`. */
+export function dividerLight({ j, root }: RuleContext): number {
+  let changed = 0
+
+  elementsNamed(j, root, ['Divider']).forEach((path) => {
+    if (!attribute(path.node.openingElement, 'light')) return
+    removeAttributes(path.node.openingElement, ['light'])
+    changed += 1
+  })
+
+  return changed
+}
+
+/** The pickers whose `placeholder` is deprecated and reaches nobody. */
+const PICKERS = [
+  'DatePicker',
+  'DateTimePicker',
+  'DateRangePicker',
+  'TimePicker',
+  'DesktopDatePicker',
+  'MobileDatePicker',
+]
+
+/** Removes a `placeholder` the pickers field no longer renders. */
+export function datepickerPlaceholder({ j, root }: RuleContext): number {
+  let changed = 0
+
+  elementsNamed(j, root, PICKERS).forEach((path) => {
+    if (!attribute(path.node.openingElement, 'placeholder')) return
+    removeAttributes(path.node.openingElement, ['placeholder'])
+    changed += 1
+  })
+
+  return changed
+}
+
+/**
+ * Flags a `freeSolo` Autocomplete.
+ *
+ * v9 types what `freeSolo` always did at runtime: the committed value can be
+ * a string that is not an option. The fix is to narrow inside the handler,
+ * and which branch means what is the author's decision — a cast would put
+ * the old lie back.
+ */
+export function autocompleteFreeSoloValue({ j, root }: RuleContext): number {
+  let changed = 0
+
+  elementsNamed(j, root, ['Autocomplete']).forEach((path) => {
+    if (!attribute(path.node.openingElement, 'freeSolo')) return
+    if (
+      annotate(
+        j,
+        path,
+        '`freeSolo` widens the value to `T | string`. Narrow it wherever the value is read — `isOptionEqualToValue` as well as `onChange` — and do not cast.',
+      )
+    ) {
+      changed += 1
+    }
+  })
+
+  return changed
+}
+
+/** Components whose props `@mui/codemod` rewrites, by name alone. */
+const REWRITTEN_SLOT_PROPS = ['slots', 'slotProps', 'ActionsComponent']
+
+/**
+ * Flags a `@mui/codemod` rewrite that landed on something that is not a
+ * Material UI component.
+ *
+ * `deprecations/all` matches on the prop name, not on where the component
+ * comes from, so a third-party component that happens to take `PaperProps`
+ * or `inputProps` gets its API rewritten to one it does not have. On this
+ * codebase it turned `PaperProps` into `slotProps.paper` on a design-system
+ * component and broke the build.
+ *
+ * A component declared in the same file is left alone; one imported from
+ * anywhere but `@mui/*` is flagged, a relative path included — the codemod is
+ * just as wrong about your own components as about a vendor's.
+ */
+export function slotPropsOffMui({ j, root }: RuleContext): number {
+  let changed = 0
+
+  root.find(j.JSXElement).forEach((path) => {
+    const opening = path.node.openingElement
+    if (!REWRITTEN_SLOT_PROPS.some((name) => attribute(opening, name))) return
+
+    const source = tagSource(j, root, opening)
+    if (!isForeign(source)) return
+
+    if (
+      annotate(
+        j,
+        path,
+        `<${elementName(opening)}> comes from '${source}', not from Material UI. ` +
+          '`@mui/codemod` rewrites by prop name alone — check this prop against that package, not against the v9 slot table.',
+      )
+    ) {
+      changed += 1
+    }
+  })
+
+  return changed
+}
+
+/** Style keys that take a colour, where a palette path is plausible. */
+const COLOR_STYLE_KEYS = new Set([
+  'color',
+  'backgroundColor',
+  'borderColor',
+  'outlineColor',
+  'fill',
+  'stroke',
+])
+
+/**
+ * Flags a palette path written into an inline `style`, where nothing resolves
+ * it.
+ *
+ * `sx` is what reads the theme; `style` goes straight to the DOM, so
+ * `'text.secondary'` is invalid CSS and the browser drops the declaration —
+ * no error, no styling. It is a plausible landing spot for a value moved out
+ * of a `color` prop during this jump, and it is the shape the rewrite above
+ * cannot produce for you: only the author knows whether the element should
+ * use `sx` instead or resolve the path against the theme first.
+ */
+export function themePathInInlineStyle({ j, root }: RuleContext): number {
+  let changed = 0
+
+  root
+    .find(j.JSXAttribute, { name: { name: 'style' } })
+    .forEach((path: ASTPath<JSXAttribute>) => {
+      const value = path.node.value
+      if (value?.type !== 'JSXExpressionContainer') return
+      const object = value.expression
+      if (object.type !== 'ObjectExpression') return
+
+      const paths = object.properties.flatMap((property) => {
+        if (property.type !== 'ObjectProperty') return []
+        const key = property.key
+        const name =
+          key.type === 'Identifier'
+            ? key.name
+            : key.type === 'StringLiteral'
+              ? String(key.value)
+              : undefined
+        if (!name || !COLOR_STYLE_KEYS.has(name)) return []
+        if (property.value.type !== 'StringLiteral') return []
+        const literal = String(property.value.value)
+        return /^[a-z][A-Za-z]*\.[A-Za-z0-9]+$/.test(literal) ? [literal] : []
+      })
+
+      if (paths.length === 0) return
+      if (
+        annotate(
+          j,
+          path,
+          `\`${paths.join('`, `')}\` is a palette path in an inline \`style\`, which has no theme resolver: it is invalid CSS and the browser drops it. Use \`sx\`, or resolve the path against the theme before painting.`,
+        )
+      ) {
+        changed += 1
+      }
+    })
+
+  return changed
+}