@carto/ps-react-ui 4.17.2 → 4.17.3

package/dist/types/legend/components/legend-actions/legend-actions.d.ts

@@ -7,8 +7,8 @@ export interface LegendActionsProps {
  * parity): the wrapper partitions its children by component identity and
  * renders this slot inside the header, wrapped in the hover-fade group
  * (`PsLegend-rowFade` in rows, `PsLegend-groupFade` in group headers —
- * resolved from the nearest context). Compose the ⋮ menu last so it sits
- * rightmost, per design.
+ * resolved from the nearest context). Compose the visibility toggle last so
+ * it sits rightmost, per design.
  *
  * @experimental This API is new and may change in a future release.
  */

package/dist/types/legend/components/legend-group/styles.d.ts

@@ -13,6 +13,22 @@ export declare const styles: {
             borderTop: string;
             borderColor: "divider";
         };
+    };
+    groupDragging: {
+        opacity: number;
+    };
+    header: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+        padding: ({ spacing }: Theme) => string;
+        minHeight: number;
+        borderBottom: string;
+        borderColor: "divider";
+        position: "sticky";
+        top: number;
+        zIndex: number;
+        backgroundColor: "background.default";
         '& .PsLegend-groupFade > *': {
             opacity: number;
             transition: ({ transitions }: Theme) => string;
@@ -23,10 +39,14 @@ export declare const styles: {
                 opacity: number;
             };
         };
-        '&:hover .PsLegend-groupFade > *, &:focus-within .PsLegend-groupFade > *': {
-            opacity: number;
-        };
         '@media (hover: hover)': {
+            '& .PsLegend-groupFade > *:not(.active)': {
+                width: number;
+                minWidth: number;
+                padding: number;
+                overflow: "hidden";
+                pointerEvents: "none";
+            };
             '& .PsLegend-groupActions:not(:has(.active))': {
                 width: number;
                 minWidth: number;
@@ -35,6 +55,14 @@ export declare const styles: {
                 pointerEvents: "none";
             };
         };
+        '&:hover .PsLegend-groupFade > *, &:focus-within .PsLegend-groupFade > *': {
+            opacity: number;
+            width: string;
+            minWidth: number;
+            padding: string;
+            overflow: "visible";
+            pointerEvents: "auto";
+        };
         '&:hover .PsLegend-groupActions, &:focus-within .PsLegend-groupActions': {
             width: string;
             minWidth: number;
@@ -53,22 +81,6 @@ export declare const styles: {
             opacity: number;
         };
     };
-    groupDragging: {
-        opacity: number;
-    };
-    header: {
-        display: "flex";
-        alignItems: "center";
-        gap: number;
-        padding: ({ spacing }: Theme) => string;
-        minHeight: number;
-        borderBottom: string;
-        borderColor: "divider";
-        position: "sticky";
-        top: number;
-        zIndex: number;
-        backgroundColor: "background.default";
-    };
     titleArea: {
         flex: number;
         minWidth: number;
@@ -88,7 +100,6 @@ export declare const styles: {
         color: "text.secondary";
     };
     label: {
-        flex: number;
         minWidth: number;
         overflow: "hidden";
         textOverflow: "ellipsis";

package/dist/types/legend/components/legend-row/styles.d.ts

@@ -18,10 +18,14 @@ export declare const styles: {
                 opacity: number;
             };
         };
-        '&:hover .PsLegend-rowFade > *, &:focus-within .PsLegend-rowFade > *': {
-            opacity: number;
-        };
         '@media (hover: hover)': {
+            '& .PsLegend-rowFade > *:not(.active)': {
+                width: number;
+                minWidth: number;
+                padding: number;
+                overflow: "hidden";
+                pointerEvents: "none";
+            };
             '& .PsLegend-rowActions:not(:has(.active))': {
                 width: number;
                 minWidth: number;
@@ -30,6 +34,14 @@ export declare const styles: {
                 pointerEvents: "none";
             };
         };
+        '&:hover .PsLegend-rowFade > *, &:focus-within .PsLegend-rowFade > *': {
+            opacity: number;
+            width: string;
+            minWidth: number;
+            padding: string;
+            overflow: "visible";
+            pointerEvents: "auto";
+        };
         '&:hover .PsLegend-rowActions, &:focus-within .PsLegend-rowActions': {
             width: string;
             minWidth: number;
@@ -64,6 +76,9 @@ export declare const styles: {
         zIndex: number;
         backgroundColor: "background.paper";
     };
+    headerGrouped: {
+        paddingLeft: number;
+    };
     titleBox: {
         flex: number;
         minWidth: number;
@@ -86,7 +101,6 @@ export declare const styles: {
         gap: number;
     };
     title: {
-        flex: number;
         minWidth: number;
         overflow: "hidden";
         textOverflow: "ellipsis";
@@ -120,9 +134,15 @@ export declare const styles: {
         gap: number;
         padding: ({ spacing }: Theme) => string;
     };
+    contentGrouped: {
+        paddingLeft: number;
+    };
     footer: {
         padding: ({ spacing }: Theme) => string;
     };
+    footerGrouped: {
+        paddingLeft: number;
+    };
     dimmed: {
         opacity: number;
     };

package/dist/types/legend/components/legend-sortable/styles.d.ts

@@ -6,13 +6,14 @@ export declare const styles: {
         display: "flex";
         alignItems: "center";
         justifyContent: "center";
-        height: number;
+        left: number;
+        top: number;
     };
     handleSlotLayer: {
-        right: number;
+        height: number;
     };
     handleSlotGroup: {
-        right: number;
+        height: number;
     };
     handle: {
         padding: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carto/ps-react-ui",
-  "version": "4.17.2",
+  "version": "4.17.3",
   "description": "CARTO's Professional Service React Material library",
   "type": "module",
   "devDependencies": {
@@ -17,8 +17,8 @@
     "react-dom": "19.2.4",
     "react-markdown": "10.1.0",
     "zustand": "5.0.12",
-    "@carto/ps-utils": "2.1.0",
-    "@carto/ps-common-types": "1.0.0"
+    "@carto/ps-common-types": "1.0.0",
+    "@carto/ps-utils": "2.1.0"
   },
   "peerDependencies": {
     "@carto/meridian-ds": "^2.0.0",

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

@@ -17,8 +17,8 @@ export interface LegendActionsProps {
  * parity): the wrapper partitions its children by component identity and
  * renders this slot inside the header, wrapped in the hover-fade group
  * (`PsLegend-rowFade` in rows, `PsLegend-groupFade` in group headers —
- * resolved from the nearest context). Compose the ⋮ menu last so it sits
- * rightmost, per design.
+ * resolved from the nearest context). Compose the visibility toggle last so
+ * it sits rightmost, per design.
  *
  * @experimental This API is new and may change in a future release.
  */

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

@@ -15,16 +15,46 @@ export const styles = {
       borderTop: '1px solid',
       borderColor: 'divider',
     },
-    // Hover-fade group actions (widgets-v2 Wrapper parity). Revealed by
-    // hovering anywhere in the group block (including member rows); a control
-    // carrying `.active` (hidden group) stays visible. Touch devices always
-    // show them. The collapse chevron sits outside the fade group. Member
-    // rows use the distinct `PsLegend-rowFade` class, so group hover never
-    // lights up row actions.
+  },
+  // The original stays in place, dimmed, while its overlay clone is dragged.
+  groupDragging: {
+    opacity: 0.4,
+  },
+  // Figma: 48px tall, 16px left inset (matches the row's own left inset),
+  // 8px gap to the label, actions right-aligned with ~8px edge inset (the
+  // small icon-button padding brings the glyphs to the design's 16px optical
+  // inset), hairline divider below. Sticky: pins to the top of the panel's
+  // scroll container.
+  header: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 1,
+    padding: ({ spacing }) => spacing(1.5, 2, 1.5, 2),
+    minHeight: LEGEND_GROUP_HEADER_HEIGHT,
+    borderBottom: '1px solid',
+    borderColor: 'divider',
+    position: 'sticky',
+    top: 0,
+    // Above the sticky row headers (2), which in turn sit above MUI's
+    // z-index-1 form internals in row content.
+    zIndex: 3,
+    // Distinct from the row header / panel body (both `background.paper`) so
+    // the group header visually separates from the rest.
+    backgroundColor: 'background.default',
+    // Hover-fade group actions (widgets-v2 Wrapper parity). Scoped to the
+    // header itself (not the group root) so hovering a member row's body
+    // below never lights up the group's own actions/handle — only hovering
+    // the header (title/handle/actions) does. A control carrying `.active`
+    // (hidden group) stays visible. Touch devices always show them. The
+    // collapse chevron sits outside the fade group. Each non-active child
+    // also collapses to zero width on its own (not just the whole actions
+    // slot) so a sibling's `.active` pin (e.g. the eye on a mixed-visibility
+    // group) doesn't leave a same-sized invisible hole where the still-faded
+    // ⋮ menu would've been.
     '& .PsLegend-groupFade > *': {
       opacity: 1,
       transition: ({ transitions }: Theme) =>
-        transitions.create('opacity', {
+        transitions.create(['opacity', 'width'], {
           duration: transitions.duration.standard,
           easing: transitions.easing.easeInOut,
         }),
@@ -35,14 +65,21 @@ export const styles = {
         opacity: 1,
       },
     },
-    '&:hover .PsLegend-groupFade > *, &:focus-within .PsLegend-groupFade > *': {
-      opacity: 1,
-    },
     // Faded actions don't reserve flex space on fine-pointer devices — the
     // label grows to the trailing edge. Hover/focus-within restores the slot
     // so the label reflows with the buttons; a dirty `.active` child keeps
     // the slot open even outside hover.
     '@media (hover: hover)': {
+      '& .PsLegend-groupFade > *:not(.active)': {
+        width: 0,
+        minWidth: 0,
+        // border-box IconButtons keep their padding inside `width` — zero it
+        // too, otherwise the fixed 2px+2px padding survives as a tiny but
+        // needless residual gap.
+        padding: 0,
+        overflow: 'hidden',
+        pointerEvents: 'none',
+      },
       '& .PsLegend-groupActions:not(:has(.active))': {
         width: 0,
         minWidth: 0,
@@ -52,6 +89,14 @@ export const styles = {
         pointerEvents: 'none',
       },
     },
+    '&:hover .PsLegend-groupFade > *, &:focus-within .PsLegend-groupFade > *': {
+      opacity: 1,
+      width: 'auto',
+      minWidth: 0,
+      padding: '2px',
+      overflow: 'visible',
+      pointerEvents: 'auto',
+    },
     '&:hover .PsLegend-groupActions, &:focus-within .PsLegend-groupActions': {
       width: 'auto',
       minWidth: 0,
@@ -78,31 +123,6 @@ export const styles = {
         opacity: 1,
       },
   },
-  // The original stays in place, dimmed, while its overlay clone is dragged.
-  groupDragging: {
-    opacity: 0.4,
-  },
-  // Figma: 48px tall, icon at 12px from the left, 8px gap to the label,
-  // actions right-aligned with ~8px edge inset (the small icon-button padding
-  // brings the glyphs to the design's 16px optical inset), hairline divider
-  // below. Sticky: pins to the top of the panel's scroll container.
-  header: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: 1,
-    padding: ({ spacing }) => spacing(1.5, 2, 1.5, 1),
-    minHeight: LEGEND_GROUP_HEADER_HEIGHT,
-    borderBottom: '1px solid',
-    borderColor: 'divider',
-    position: 'sticky',
-    top: 0,
-    // Above the sticky row headers (2), which in turn sit above MUI's
-    // z-index-1 form internals in row content.
-    zIndex: 3,
-    // Distinct from the row header / panel body (both `background.paper`) so
-    // the group header visually separates from the rest.
-    backgroundColor: 'background.default',
-  },
   // Accordion click target: everything in the header but the actions box.
   // Non-native button (role='button'), so it carries its own focus ring.
   titleArea: {
@@ -123,8 +143,11 @@ export const styles = {
     display: 'flex',
     color: 'text.secondary',
   },
+  // No `flex:1` here — the label sizes to its own text (shrinking to
+  // ellipsis when too long) so the chevron sits right after it, instead of
+  // being dragged to the trailing edge of `titleArea` (which keeps its own
+  // `flex:1` to fill the header up to the actions).
   label: {
-    flex: 1,
     minWidth: 0,
     overflow: 'hidden',
     textOverflow: 'ellipsis',

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

@@ -74,7 +74,10 @@ export function LegendRow({ layerId, children }: LegendRowProps) {
           sortableProps?.dragging === true && styles.rowDragging,
         ]}
       >
-        <Box sx={styles.header} style={{ top: stickyTop }}>
+        <Box
+          sx={[styles.header, inGroup && styles.headerGrouped]}
+          style={{ top: stickyTop }}
+        >
           {sortableProps?.handle}
           <Box
             sx={[styles.titleBox, canToggle && styles.titleBoxInteractive]}
@@ -122,16 +125,16 @@ export function LegendRow({ layerId, children }: LegendRowProps) {
 
         <Collapse in={!effectivelyCollapsed}>
           <Box
-            sx={
-              layer.visible
-                ? styles.content
-                : { ...styles.content, ...styles.dimmed }
-            }
+            sx={[
+              styles.content,
+              inGroup && styles.contentGrouped,
+              !layer.visible && styles.dimmed,
+            ]}
           >
             {body}
           </Box>
           {layer.helperText && (
-            <Box sx={styles.footer}>
+            <Box sx={[styles.footer, inGroup && styles.footerGrouped]}>
               {typeof layer.helperText === 'string' ? (
                 <Typography variant='caption' color='text.secondary'>
                   {layer.helperText}

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

@@ -16,14 +16,16 @@ export const styles = {
     // `.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-
-    // pointer (touch) devices always show them. The actions slot itself also
-    // collapses to zero width while faded (see `PsLegend-rowActions` below)
-    // so the title can grow to the trailing edge. The collapse chevron sits
-    // outside the fade group and never fades.
+    // pointer (touch) devices always show them. Each non-active child also
+    // collapses to zero width on its own (not just the whole actions slot —
+    // see `PsLegend-rowActions` below) so a sibling's `.active` pin (e.g. the
+    // eye while hidden) doesn't leave a same-sized invisible hole where the
+    // still-faded ⋮ menu would've been; the title grows into that space. The
+    // collapse chevron sits outside the fade group and never fades.
     '& .PsLegend-rowFade > *': {
       opacity: 1,
       transition: ({ transitions }: Theme) =>
-        transitions.create('opacity', {
+        transitions.create(['opacity', 'width'], {
           duration: transitions.duration.standard,
           easing: transitions.easing.easeInOut,
         }),
@@ -34,14 +36,21 @@ export const styles = {
         opacity: 1,
       },
     },
-    '&:hover .PsLegend-rowFade > *, &:focus-within .PsLegend-rowFade > *': {
-      opacity: 1,
-    },
     // Faded actions don't reserve flex space on fine-pointer devices — the
     // title grows to the trailing edge. Hover/focus-within restores the slot
     // so the title reflows with the buttons; a dirty `.active` child keeps
     // the slot open even outside hover.
     '@media (hover: hover)': {
+      '& .PsLegend-rowFade > *:not(.active)': {
+        width: 0,
+        minWidth: 0,
+        // border-box IconButtons keep their padding inside `width` — zero it
+        // too, otherwise the fixed 2px+2px padding survives as a tiny but
+        // needless residual gap.
+        padding: 0,
+        overflow: 'hidden',
+        pointerEvents: 'none',
+      },
       '& .PsLegend-rowActions:not(:has(.active))': {
         width: 0,
         minWidth: 0,
@@ -51,6 +60,14 @@ export const styles = {
         pointerEvents: 'none',
       },
     },
+    '&:hover .PsLegend-rowFade > *, &:focus-within .PsLegend-rowFade > *': {
+      opacity: 1,
+      width: 'auto',
+      minWidth: 0,
+      padding: '2px',
+      overflow: 'visible',
+      pointerEvents: 'auto',
+    },
     '&:hover .PsLegend-rowActions, &:focus-within .PsLegend-rowActions': {
       width: 'auto',
       minWidth: 0,
@@ -91,7 +108,9 @@ export const styles = {
   // band (subtitle flows below them) — hence `flex-start` with the title
   // optically centered against the 30px icon-button row. Sticky: pins inside
   // the panel's scroll container; `top` is applied inline per row (0, or the
-  // group-header height for grouped rows).
+  // group-header height for grouped rows). Grouped rows get an extra 20px
+  // left inset (36px total) so member layers read as nested under the group
+  // and line up with the group's own icon+label text start.
   header: {
     display: 'flex',
     alignItems: 'flex-start',
@@ -104,6 +123,9 @@ export const styles = {
     zIndex: 2,
     backgroundColor: 'background.paper',
   },
+  headerGrouped: {
+    paddingLeft: 4.5,
+  },
   titleBox: {
     flex: 1,
     minWidth: 0,
@@ -130,8 +152,11 @@ export const styles = {
     alignItems: 'center',
     gap: 0.5,
   },
+  // No `flex:1` here — the title sizes to its own text (shrinking to
+  // ellipsis when too long) so the chevron sits right after it, instead of
+  // being dragged to the trailing edge of `titleLine` (which spans the full
+  // width of `titleBox`, itself `flex:1` to fill the header up to actions).
   title: {
-    flex: 1,
     minWidth: 0,
     overflow: 'hidden',
     textOverflow: 'ellipsis',
@@ -178,10 +203,16 @@ export const styles = {
     gap: 1,
     padding: ({ spacing }) => spacing(0.5, 2, 1, 2),
   },
+  contentGrouped: {
+    paddingLeft: 4.5,
+  },
   // ~16px above the note (content's 8px bottom inset + 8px here), per design.
   footer: {
     padding: ({ spacing }) => spacing(1, 2, 1, 2),
   },
+  footerGrouped: {
+    paddingLeft: 4.5,
+  },
   dimmed: {
     opacity: 0.5,
   },

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

@@ -1,20 +1,29 @@
 import type { SxProps, Theme } from '@mui/material'
+import { LEGEND_GROUP_HEADER_HEIGHT } from '../legend-group/styles'
 
 export const styles = {
-  // Absolute handle — no flex slot; sticky header is the containing block.
+  // Absolute handle, flush against the header's top-left corner — no flex
+  // slot; sticky header is the containing block.
   handleSlot: {
     position: 'absolute',
     zIndex: 1,
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',
-    height: 24,
+    left: 0,
+    top: 0,
   },
+  // Both headers center their title on the same 24px band from the header's
+  // top edge (group: 48px header, `alignItems:'center'`; row: 12px top
+  // padding + 24px `titleLine`, `alignItems:'flex-start'`) — so `height:48`
+  // centers the icon on the title in both cases, even though the row's own
+  // header is only 32px tall (a 32px-tall slot would center at 16px, 8px
+  // short of the title).
   handleSlotLayer: {
-    right: 2,
+    height: LEGEND_GROUP_HEADER_HEIGHT,
   },
   handleSlotGroup: {
-    right: 2,
+    height: LEGEND_GROUP_HEADER_HEIGHT,
   },
   handle: {
     padding: '2px',

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

@@ -238,15 +238,21 @@ function mergeLayerEntity(
   } as LegendLayer
 }
 
-/** Group counterpart of {@link mergeLayerEntity}. */
+/**
+ * Group counterpart of {@link mergeLayerEntity}. A group with no `prev`
+ * state (first sync) defaults collapsed when none of its member layers is
+ * visible yet — `hasVisibleLayer` is ignored once the group exists so a
+ * user's manual expand/collapse always sticks.
+ */
 function mergeGroupEntity(
   prev: LegendGroup | undefined,
   input: LegendGroupInput,
   fallbackOrder: number,
+  hasVisibleLayer: boolean,
 ): LegendGroup {
   return {
     ...input,
-    collapsed: prev?.collapsed ?? input.collapsed ?? false,
+    collapsed: prev?.collapsed ?? input.collapsed ?? !hasVisibleLayer,
     collapsedBeforeHide: prev?.collapsedBeforeHide,
     order: prev?.order ?? input.order ?? fallbackOrder,
   } as LegendGroup
@@ -274,9 +280,19 @@ function syncState(
   }))
   normalizeOrders(layerEntries, (l) => l.groupId)
 
+  const groupsWithVisibleLayer = new Set(
+    layerEntries
+      .filter(({ merged }) => merged.visible && merged.groupId != null)
+      .map(({ merged }) => merged.groupId!),
+  )
   const groupEntries = groupInputs.map((input, index) => ({
     index,
-    merged: mergeGroupEntity(state.groups[input.id], input, index),
+    merged: mergeGroupEntity(
+      state.groups[input.id],
+      input,
+      index,
+      groupsWithVisibleLayer.has(input.id),
+    ),
   }))
   normalizeOrders(groupEntries, () => undefined)
 
@@ -382,7 +398,15 @@ function upsertGroupState(
   const count = Object.values(state.groups).filter(
     (g) => g.id !== input.id,
   ).length
-  const merged = mergeGroupEntity(state.groups[input.id], input, count)
+  const hasVisibleLayer = Object.values(state.layers).some(
+    (l) => l.groupId === input.id && l.visible,
+  )
+  const merged = mergeGroupEntity(
+    state.groups[input.id],
+    input,
+    count,
+    hasVisibleLayer,
+  )
   const groups = rebuildRecord(
     state.groups,
     { ...state.groups, [input.id]: merged },

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

@@ -148,6 +148,29 @@ describe('legend store', () => {
     expect(store.getState().groups.g1!.collapsed).toBe(true)
   })
 
+  it('a group with no visible member starts collapsed', () => {
+    const store = createLegendStore('s', {
+      layers: layers.map((l) =>
+        l.groupId === 'g1' ? { ...l, visible: false } : l,
+      ),
+      groups: [
+        { id: 'g1', label: 'One' },
+        { id: 'g2', label: 'Empty' },
+      ],
+    })
+    expect(store.getState().groups.g1!.collapsed).toBe(true)
+    // No members at all also counts as "nothing enabled".
+    expect(store.getState().groups.g2!.collapsed).toBe(true)
+  })
+
+  it('a group with at least one visible member starts expanded', () => {
+    const store = createLegendStore('s', {
+      layers,
+      groups: [{ id: 'g1', label: 'One' }],
+    })
+    expect(store.getState().groups.g1!.collapsed).toBe(false)
+  })
+
   it('selectGroupVisibility derives the tri-state from member layers', () => {
     const store = createLegendStore('s', {
       layers,