@carto/ps-react-ui 5.0.0 → 6.0.0

package/src/legend/components/legend-ramp/legend-ramp-ui.tsx

@@ -1,6 +1,6 @@
 import { Box, Typography } from '@mui/material'
 import { Tooltip } from '../../../components/tooltip/tooltip'
-import { ErrorOutline as ErrorIcon } from '@mui/icons-material'
+import { ErrorOutlineOutlined as ErrorIcon } from '@mui/icons-material'
 import { styles } from './styles'
 import { DEFAULT_LEGEND_LABELS, type LegendLabels } from '../../provider/labels'
 import type { LegendRampVariable } from '../../stores'
@@ -60,10 +60,20 @@ export function LegendRampUI({
 
   const attributeHeader = attribute && (
     <Box sx={styles.attribute}>
-      <Typography variant='overline' color='text.secondary'>
+      <Typography
+        variant='overline'
+        sx={{
+          color: 'text.secondary',
+        }}
+      >
         {labels.colorBasedOn}
       </Typography>
-      <Typography variant='caption' color='text.primary'>
+      <Typography
+        variant='caption'
+        sx={{
+          color: 'text.primary',
+        }}
+      >
         {attribute}
       </Typography>
     </Box>
@@ -132,12 +142,16 @@ export function LegendRampUI({
               <Typography
                 key={`${stop.label}-${index}`}
                 variant='overline'
-                color='text.secondary'
-                sx={styles.boundaryLabel}
                 style={{
                   left: `${(index / colors.length) * 100}%`,
                   transform,
                 }}
+                sx={[
+                  {
+                    color: 'text.secondary',
+                  },
+                  styles.boundaryLabel,
+                ]}
               >
                 {stop.label}
               </Typography>
@@ -147,10 +161,20 @@ export function LegendRampUI({
       ) : (
         // Continuous gradients show only the range endpoints.
         <Box sx={styles.labels}>
-          <Typography variant='overline' color='text.secondary'>
+          <Typography
+            variant='overline'
+            sx={{
+              color: 'text.secondary',
+            }}
+          >
             {first?.label}
           </Typography>
-          <Typography variant='overline' color='text.secondary'>
+          <Typography
+            variant='overline'
+            sx={{
+              color: 'text.secondary',
+            }}
+          >
             {last?.label}
           </Typography>
         </Box>

package/src/legend/components/legend-row/legend-row.tsx

@@ -114,8 +114,8 @@ export function LegendRow({ layerId, children }: LegendRowProps) {
             {layer.subtitle && !effectivelyCollapsed && (
               <Typography
                 variant='caption'
-                color='text.secondary'
                 component='p'
+                sx={{ color: 'text.secondary' }}
               >
                 {layer.subtitle}
               </Typography>
@@ -147,8 +147,8 @@ export function LegendRow({ layerId, children }: LegendRowProps) {
                 // theme rather than on this component.
                 <Typography
                   variant='caption'
-                  color='text.secondary'
                   component='p'
+                  sx={{ color: 'text.secondary' }}
                 >
                   {layer.helperText}
                 </Typography>

package/src/legend/components/legend-row/styles.ts

@@ -12,7 +12,7 @@ export const styles = {
       borderTop: '1px solid',
       borderColor: 'divider',
     },
-    // Hover-fade actions (widgets-v2 Wrapper parity). Direct children of
+    // Hover-fade actions (widgets Wrapper parity). Direct children of
     // `.PsLegend-rowFade` are hidden on fine-pointer devices and fade in when
     // the row is hovered or holds focus; a control carrying `.active` (dirty
     // state — hidden layer, open menu, opacity ≠ 1) stays visible. Coarse-

package/src/legend/components/legend-sortable/legend-sortable.tsx

@@ -184,9 +184,13 @@ function OverlayCard({ activeId }: { activeId: string }) {
       )}
       <Typography
         variant='button'
-        fontWeight={parsed.kind === 'group' ? 'bold' : undefined}
-        color='text.primary'
-        sx={styles.overlayLabel}
+        sx={[
+          {
+            fontWeight: parsed.kind === 'group' ? 'bold' : undefined,
+            color: 'text.primary',
+          },
+          styles.overlayLabel,
+        ]}
       >
         {label}
       </Typography>

package/src/legend/components/legend-swatch/legend-swatch.tsx

@@ -1,4 +1,5 @@
 import { useId } from 'react'
+import type { CssColor } from '../../../components/types'
 import type {
   LegendFillPattern,
   LegendStrokeStyle,
@@ -9,7 +10,7 @@ export interface LegendSwatchProps {
   /** Shape to render. Default `'circle'`. */
   shape?: LegendSwatchShape
   /** CSS color string (hex / rgb / named). */
-  color: string
+  color: CssColor
   /** Paint the outline/border instead of the fill (square/circle only). */
   isStrokeColor?: boolean
   /** Fill pattern when filled. Default `'solid'`. */

package/src/legend/components/legend-visible-layers/legend-visible-layers.tsx

@@ -82,16 +82,21 @@ export function LegendVisibleLayers() {
         anchorEl={anchorEl}
         open={open}
         onClose={handleClose}
-        TransitionProps={{ onExited: handleClose }}
-        // No list padding — sticky header sits flush (avoids scroll peek-through).
-        MenuListProps={{ disablePadding: true }}
-        slotProps={{ paper: { sx: styles.paper } }}
+        slotProps={{
+          paper: { sx: styles.paper },
+          list: { disablePadding: true },
+          transition: { onExited: handleClose },
+        }}
       >
         <Typography
           component='div'
           variant='caption'
-          color='text.primary'
-          sx={styles.stickyHeader}
+          sx={[
+            {
+              color: 'text.primary',
+            },
+            styles.stickyHeader,
+          ]}
         >
           {`${labels.enabledLayers} (${count})`}
         </Typography>
@@ -106,9 +111,13 @@ export function LegendVisibleLayers() {
             <Typography
               key={`caption-${section.group.id}`}
               variant='caption'
-              fontWeight='medium'
-              color='text.secondary'
-              sx={styles.groupCaption}
+              sx={[
+                {
+                  fontWeight: 'medium',
+                  color: 'text.secondary',
+                },
+                styles.groupCaption,
+              ]}
             >
               {section.group.label}
             </Typography>

package/src/legend/index.ts

@@ -33,7 +33,7 @@ import { LegendIconUI } from './components/legend-icon/legend-icon-ui'
 /**
  * Curated namespace export — the entry point to the legend module.
  *
- * Composable, widgets-v2 style: the lib ships wrapper shells + standalone
+ * Composable, widgets style: the lib ships wrapper shells + standalone
  * store-connected actions, and the **app mounts the legend** in its own
  * chrome (panel/drawer/sidebar). `Legend.Row`/`Legend.Group` partition their
  * children — `<Legend.Actions>` renders in the sticky header (hover-fade),

package/src/legend/provider/legend-provider.tsx

@@ -22,7 +22,7 @@ export interface LegendProviderProps {
   /**
    * Layer definitions. Interactive fields (visible/opacity/…) are seeded.
    * Pass stable references — `layers`, `groups`, and each layer's `variables`
-   * should be memoized or module constants (same contract as widgets-v2
+   * should be memoized or module constants (same contract as widgets
    * `data`); the store bails out of unchanged syncs by reference.
    */
   layers: LegendLayerInput[]
@@ -47,7 +47,7 @@ export interface LegendProviderProps {
  * state), and exposes the `id` via `LegendContext` so descendants resolve their
  * store with `useLegendId()`. Labels are surfaced via `LegendConfigContext`.
  *
- * Modeled on the widgets-v2 `Widget.Provider`.
+ * Modeled on the widgets `Widget.Provider`.
  *
  * @experimental This API is new and may change in a future release.
  */

package/src/legend/stores/legend-store-registry.ts

@@ -17,7 +17,7 @@ import type {
 import { selectLayersByGroup, selectOrderedGroups } from './selectors'
 
 // Per-panel legend store registry. One store per `<Legend.Provider id>`.
-// Mirrors the widgets-v2 registry pattern (keyed Map + refcounted mounts),
+// Mirrors the widgets registry pattern (keyed Map + refcounted mounts),
 // without the chart-pipeline machinery.
 const legendStores = new Map<string, LegendStoreApi>()
 const legendMountCounts = new Map<string, number>()

package/src/migration/v4/classes.ts

@@ -0,0 +1,56 @@
+/**
+ * The v9 class consolidation, as a function.
+ *
+ * v9 split every compound class into its parts: `<slot><Modifier>` became
+ * `<slot>` plus `color<Color>` or `size<Size>`. A selector naming the old
+ * compound matches nothing and nothing errors — the styling simply stops
+ * applying, which is why this is the highest-risk item in the migration.
+ *
+ *     .MuiButton-textPrimary  ->  .MuiButton-text.MuiButton-colorPrimary
+ *     .MuiChip-labelSmall     ->  .MuiChip-label.MuiChip-sizeSmall
+ */
+const COLORS = ['Primary', 'Secondary', 'Error', 'Warning', 'Info', 'Success']
+const SIZES = ['Small', 'Medium', 'Large']
+
+const PATTERN = new RegExp(
+  `^(Mui[A-Z][A-Za-z]*)-([a-z][A-Za-z]*?)(?:(${COLORS.join('|')})|(?:Size)?(${SIZES.join('|')}))$`,
+)
+
+/**
+ * The classes a consolidated name splits into, or `null` if the name is
+ * already a v9 one.
+ *
+ * `MuiButton-colorPrimary` and `MuiChip-sizeSmall` are the *result* of the
+ * consolidation, not input to it, so a slot of `color` or `size` is left
+ * alone — rewriting those would produce `MuiButton-color`, a class that
+ * does not exist.
+ */
+export function consolidateClassName(name: string): string[] | null {
+  const match = PATTERN.exec(name)
+  if (!match) return null
+
+  const [, component, slot, color, size] = match
+  if (slot === 'color' || slot === 'size') return null
+
+  return [
+    `${component}-${slot}`,
+    `${component}-${color ? `color${color}` : `size${size}`}`,
+  ]
+}
+
+/**
+ * Rewrites every consolidated class inside a selector or a class list,
+ * preserving the leading `.` where there is one so it works on both
+ * `.MuiButton-textPrimary` and a bare `className` value.
+ */
+export function consolidateSelectors(text: string): string {
+  return text.replace(
+    /(\.?)\b(Mui[A-Z][A-Za-z]*-[a-z][A-Za-z]*)\b/g,
+    (whole, dot: string, name: string) => {
+      const parts = consolidateClassName(name)
+      if (!parts) return whole
+      // Without a dot this is a class list, where the separator is a space.
+      return dot ? parts.map((part) => `.${part}`).join('') : parts.join(' ')
+    },
+  )
+}

package/src/migration/v4/icons.ts

@@ -0,0 +1,56 @@
+/**
+ * The 17 `*Outline` icons Material UI v9 removed, mapped to the icon whose
+ * SVG path is byte-identical in 9.4.0. `null` means no icon anywhere in v9
+ * draws this glyph.
+ *
+ * Built by diffing the path data of `@mui/icons-material` 5.18.0 against
+ * 9.4.0, not from the changelog, because the obvious rename is wrong: for 15
+ * of these 17, replacing the `Outline` suffix with `Outlined` resolves to
+ * the outlined variant of the *solid* icon — `ErrorOutline` is a ring,
+ * `ErrorOutlined` is a filled circle. It compiles and nothing fails.
+ *
+ * Both authorities you would otherwise consult give the wrong answer here:
+ * the compiler suggests the naive rename, and Meridian's own changelog
+ * states it.
+ */
+export const REMOVED_OUTLINE_ICONS: Readonly<Record<string, string | null>> = {
+  AddCircleOutline: 'AddCircleOutlineOutlined',
+  ChatBubbleOutline: 'ChatBubbleOutlineOutlined',
+  CheckCircleOutline: null,
+  DeleteOutline: 'DeleteOutlineOutlined',
+  DoneOutline: null,
+  ErrorOutline: 'ErrorOutlineOutlined',
+  HelpOutline: 'HelpOutlineOutlined',
+  MailOutline: 'MailOutlineOutlined',
+  ModeEditOutline: null,
+  PauseCircleOutline: 'PauseCircleOutlineOutlined',
+  PeopleOutline: null,
+  PersonOutline: 'PersonOutlineOutlined',
+  PieChartOutline: 'PieChartOutlineOutlined',
+  PlayCircleOutline: 'PlayCircleOutlineOutlined',
+  RemoveCircleOutline: 'RemoveCircleOutlineOutlined',
+  StarOutline: 'StarOutlineOutlined',
+  WorkOutline: 'WorkOutlineOutlined',
+}
+
+export const REMOVED_ICON_NAMES = Object.keys(REMOVED_OUTLINE_ICONS)
+
+/**
+ * The v9 replacement for a removed icon: a name when one exists, `null` when
+ * no icon draws the glyph, `undefined` when the name was never removed.
+ *
+ * Goes through `Object.hasOwn` because the name comes from the source, and a
+ * bare lookup on an identifier called `toString` or `constructor` returns
+ * whatever `Object.prototype` has under that key.
+ */
+export function replacementFor(name: string): string | null | undefined {
+  return Object.hasOwn(REMOVED_OUTLINE_ICONS, name)
+    ? REMOVED_OUTLINE_ICONS[name]
+    : undefined
+}
+
+/**
+ * What the naive rename produces for each removed icon. These names exist in
+ * v9, so nothing fails — they are just a different drawing.
+ */
+export const NAIVE_RENAMES = REMOVED_ICON_NAMES.map((name) => `${name}d`)

package/src/migration/v4/index.ts

@@ -0,0 +1,17 @@
+/**
+ * MUI v9 / Meridian 5 migration codemod.
+ *
+ * The rules are applied by a jscodeshift transform — see `./transform.ts`
+ * for how to run it — and exported here as data, so a tool can report what
+ * a jump involves without running it:
+ *
+ *   import { RULES, jumpsFor } from '@carto/ps-react-ui/migration/v4'
+ *
+ * The prose walkthrough is `docs/migration/mui-9-meridian-5.md`, which
+ * documents the rules in `./rules`; a test keeps the two in sync.
+ */
+export { RULES, JUMPS, jumpsFor } from './rules'
+export type { Rule, Jump, Handling, Severity } from './rules'
+export { REMOVED_OUTLINE_ICONS } from './icons'
+export { consolidateClassName, consolidateSelectors } from './classes'
+export { default as transform } from './transform'