@carto/ps-react-ui 4.15.0 → 4.16.0

package/src/legend/components/run-async-menu-action.ts

@@ -0,0 +1,20 @@
+import type { LegendMenuController } from './contexts'
+
+/**
+ * Run an async menu action with busy gating. Uses `isBusy()` (ref-backed) so a
+ * second click before React re-renders cannot fire the handler twice. Keeps
+ * the menu open while pending, then clears busy and closes when it settles.
+ */
+export async function runAsyncMenuAction(
+  menu: LegendMenuController,
+  action: () => void | Promise<void>,
+): Promise<void> {
+  if (menu.isBusy()) return
+  menu.setBusy(true)
+  try {
+    await action()
+  } finally {
+    menu.setBusy(false)
+    menu.close()
+  }
+}

package/src/legend/index.ts

@@ -6,6 +6,20 @@ import { LegendActions } from './components/legend-actions/legend-actions'
 import { LegendVisibilityToggle } from './components/legend-visibility-toggle/legend-visibility-toggle'
 import { LegendRowMenu } from './components/legend-row-menu/legend-row-menu'
 import { LegendZoomTo } from './components/legend-row-menu/legend-zoom-to'
+import {
+  LegendShowOnlyLayer,
+  LegendShowAllLayers,
+} from './components/legend-row-menu/legend-row-menu-items'
+import { LegendGroupMenu } from './components/legend-group-menu/legend-group-menu'
+import {
+  LegendShowOnlyGroup,
+  LegendShowAllGroups,
+  LegendCollapseAllGroups,
+  LegendZoomToGroup,
+} from './components/legend-group-menu/legend-group-menu-items'
+import { LegendPanelMenu } from './components/legend-panel-menu/legend-panel-menu'
+import { LegendVisibleLayers } from './components/legend-visible-layers/legend-visible-layers'
+import { LegendSortable } from './components/legend-sortable/legend-sortable'
 import { LegendOpacity } from './components/legend-opacity/legend-opacity'
 import { LegendConfigSelect } from './components/legend-config-select/legend-config-select'
 import { LegendItem } from './components/legend-item/legend-item'
@@ -25,31 +39,58 @@ import { LegendIconUI } from './components/legend-icon/legend-icon-ui'
  * children — `<Legend.Actions>` renders in the sticky header (hover-fade),
  * everything else in the collapsible body.
  *
+ * Collapse is the title row itself (whole header minus the actions), with an
+ * informative chevron that touch devices don't show. The ⋮ menus are
+ * extensible shells: compose the built-in items and append your own
+ * `MenuItem`s. The built-in items are **self-contained** — their effect is
+ * implemented inside the component through the store's primitive setters, so
+ * they mount with zero wiring; only `ZoomTo`/`ZoomToGroup` take an `onZoomTo`
+ * handler (zooming is the map's concern). Pass an async handler to keep the
+ * menu open with in-item loading feedback until it settles.
+ *
  * ```tsx
  * import { Legend } from '@carto/ps-react-ui/legend'
  *
  * <Legend.Provider id='map-legend' layers={layers} groups={groups}>
+ *   // Panel-wide actions (Show all groups / Collapse all) live once here,
+ *   // not repeated per group.
+ *   <Legend.PanelMenu>
+ *     <Legend.ShowAllGroups />
+ *     <Legend.CollapseAllGroups />
+ *   </Legend.PanelMenu>
+ *
  *   <Legend.Group groupId='demographics'>
  *     <Legend.Actions>
  *       <Legend.VisibilityToggle />          // tri-state group eye
+ *       <Legend.GroupMenu>                   // ⋮ (rightmost)
+ *         <Legend.ShowOnlyGroup />
+ *         <Legend.ShowAllLayers />           // this group's members
+ *         <Legend.ZoomToGroup onZoomTo={zoomToGroup} />
+ *       </Legend.GroupMenu>
  *     </Legend.Actions>
  *     <Legend.Row layerId='income'>
- *       // Actions read L→R: options · opacity · visibility
+ *       // Actions read L→R: eye · ⋮ options
  *       <Legend.Actions>
+ *         <Legend.VisibilityToggle />        // layer eye
  *         <Legend.RowMenu>
+ *           <Legend.ShowOnlyLayer />
+ *           <Legend.Opacity.Item />
  *           <Legend.ZoomTo onZoomTo={zoomTo} />
  *         </Legend.RowMenu>
- *         <Legend.Opacity.Trigger />
- *         <Legend.VisibilityToggle />        // layer eye
  *       </Legend.Actions>
+ *       <Legend.Opacity.Inline />            // bar between header and body
  *       <Legend.ConfigSelect />
  *       <Legend.Item />
- *       <Legend.Opacity.Popover />           // anchors to the row header
  *     </Legend.Row>
  *   </Legend.Group>
  * </Legend.Provider>
  * ```
  *
+ * `Legend.ShowAllLayers` is composed at whichever site it targets: directly
+ * in a `Legend.GroupMenu` for that group's members (as above), or in an
+ * ungrouped row's `Legend.RowMenu` for the loose-layer bucket — it resolves
+ * its own scope from context either way.
+ *
  * @experimental This API is new and may change in a future release.
  */
 export const Legend = {
@@ -58,11 +99,21 @@ export const Legend = {
   Group: LegendGroup,
   Row: LegendRow,
   Actions: LegendActions,
+  Sortable: LegendSortable,
 
   // Store-connected actions & controls (context-driven)
   VisibilityToggle: LegendVisibilityToggle,
   RowMenu: LegendRowMenu,
   ZoomTo: LegendZoomTo,
+  ShowOnlyLayer: LegendShowOnlyLayer,
+  ShowAllLayers: LegendShowAllLayers,
+  GroupMenu: LegendGroupMenu,
+  ShowOnlyGroup: LegendShowOnlyGroup,
+  ShowAllGroups: LegendShowAllGroups,
+  CollapseAllGroups: LegendCollapseAllGroups,
+  ZoomToGroup: LegendZoomToGroup,
+  PanelMenu: LegendPanelMenu,
+  VisibleLayers: LegendVisibleLayers,
   Opacity: LegendOpacity,
   ConfigSelect: LegendConfigSelect,
   Item: LegendItem,
@@ -85,9 +136,13 @@ export type { LegendProviderProps, LegendLabels } from './provider'
 export type { LegendGroupProps } from './components/legend-group/legend-group'
 export type { LegendRowProps } from './components/legend-row/legend-row'
 export type { LegendActionsProps } from './components/legend-actions/legend-actions'
+export type { LegendSortableProps } from './components/legend-sortable/legend-sortable'
 export type { LegendVisibilityToggleProps } from './components/legend-visibility-toggle/legend-visibility-toggle'
 export type { LegendRowMenuProps } from './components/legend-row-menu/legend-row-menu'
 export type { LegendZoomToProps } from './components/legend-row-menu/legend-zoom-to'
+export type { LegendGroupMenuProps } from './components/legend-group-menu/legend-group-menu'
+export type { LegendZoomToGroupProps } from './components/legend-group-menu/legend-group-menu-items'
+export type { LegendPanelMenuProps } from './components/legend-panel-menu/legend-panel-menu'
 export type { LegendRowContextValue } from './components/contexts'
 export type { LegendItemUIProps } from './components/legend-item/legend-item-ui'
 export type { LegendSwatchProps } from './components/legend-swatch/legend-swatch'

package/src/legend/provider/labels.ts

@@ -13,6 +13,10 @@ export interface LegendLabels {
   // Row overflow menu
   layerOptions: string
   zoomTo: string
+  /** In-flight label for Zoom to layer / Zoom to group. */
+  loading: string
+  showOnlyLayer: string
+  showAllLayers: string
 
   // Group
   hideGroup: string
@@ -20,9 +24,30 @@ export interface LegendLabels {
   expandGroup: string
   collapseGroup: string
 
+  // Group overflow menu
+  groupOptions: string
+  showOnlyGroup: string
+  showAllGroups: string
+  collapseAllGroups: string
+  expandAllGroups: string
+  zoomToGroup: string
+
+  // Panel
+  panelOptions: string
+  /** Sticky header of the visible-layers summary; the count is appended. */
+  enabledLayers: string
+  /** Tooltip of the visible-layers summary trigger. */
+  toggleEnabledLayers: string
+  /** Tooltip shared by the ⋮ menu triggers (row, group and panel). */
+  moreOptions: string
+  /** Drag handle of sortable groups/rows (aria + tooltip). */
+  reorder: string
+
   // Row controls
   opacity: string
   attribute: string
+  /** Generic close affordance (e.g. the inline opacity bar's ✕). */
+  close: string
 
   // Item renderers
   radiusRangeBy: string
@@ -41,15 +66,32 @@ export const DEFAULT_LEGEND_LABELS: LegendLabels = {
   showLayer: 'Show layer',
 
   layerOptions: 'Layer options',
-  zoomTo: 'Zoom to',
+  zoomTo: 'Zoom to layer',
+  loading: 'Loading…',
+  showOnlyLayer: 'Show only this layer',
+  showAllLayers: 'Show all layers',
 
   hideGroup: 'Hide group',
   showGroup: 'Show group',
   expandGroup: 'Expand group',
   collapseGroup: 'Collapse group',
 
+  groupOptions: 'Group options',
+  showOnlyGroup: 'Show only this group',
+  showAllGroups: 'Show all groups',
+  collapseAllGroups: 'Collapse all groups',
+  expandAllGroups: 'Expand all groups',
+  zoomToGroup: 'Zoom to group',
+
+  panelOptions: 'Legend options',
+  enabledLayers: 'Enabled layers',
+  toggleEnabledLayers: 'Quickly toggle enabled layers',
+  moreOptions: 'More options',
+  reorder: 'Reorder',
+
   opacity: 'Opacity',
   attribute: 'Attribute',
+  close: 'Close',
 
   radiusRangeBy: 'Radius range by',
   colorBasedOn: 'Color based on',

package/src/legend/stores/index.ts

@@ -43,4 +43,8 @@ export {
   selectLayersByGroup,
   selectOrderedLayers,
   selectGroupVisibility,
+  selectLayerCollapsible,
+  selectAllGroupsCollapsed,
+  selectVisibleLayersGrouped,
+  selectHasGroups,
 } from './selectors'

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

@@ -12,6 +12,7 @@ import type {
   LegendState,
   LegendStoreApi,
 } from './types'
+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),
@@ -81,6 +82,31 @@ function collapsePatch(
     : { collapsed, collapsedBeforeHide: collapsed }
 }
 
+/**
+ * Reorder one entity within its **ordered** bucket: splice it out, insert at
+ * the clamped index, and return the dense `order` rewrites (only the entries
+ * whose order actually changes). `null` when the position doesn't change or
+ * the id isn't in the bucket. Powers `moveLayer` / `moveGroup`.
+ */
+function movePatch<T extends { id: string; order: number }>(
+  bucket: T[],
+  id: string,
+  toIndex: number,
+): Map<string, number> | null {
+  const fromIndex = bucket.findIndex((e) => e.id === id)
+  if (fromIndex === -1) return null
+  const clamped = Math.max(0, Math.min(bucket.length - 1, toIndex))
+  if (clamped === fromIndex) return null
+  const next = [...bucket]
+  const [moved] = next.splice(fromIndex, 1)
+  next.splice(clamped, 0, moved!)
+  const orders = new Map<string, number>()
+  next.forEach((entity, index) => {
+    if (entity.order !== index) orders.set(entity.id, index)
+  })
+  return orders.size > 0 ? orders : null
+}
+
 function updateLayer(
   state: LegendState,
   id: string,
@@ -446,6 +472,24 @@ export function createLegendStore(
             'setSectionValue',
           ),
 
+        moveLayer: (lid, toIndex) =>
+          set(
+            (s) => {
+              const layer = s.layers[lid]
+              if (!layer) return {}
+              const bucket = selectLayersByGroup(s, layer.groupId)
+              const orders = movePatch(bucket, lid, toIndex)
+              if (!orders) return {}
+              const layers = { ...s.layers }
+              for (const [id, order] of orders) {
+                layers[id] = { ...layers[id]!, order }
+              }
+              return { layers }
+            },
+            false,
+            'moveLayer',
+          ),
+
         setGroupVisibility: (gid, visible) =>
           set(
             (s) => {
@@ -528,6 +572,22 @@ export function createLegendStore(
             'setGroupCollapsed',
           ),
 
+        moveGroup: (gid, toIndex) =>
+          set(
+            (s) => {
+              if (!s.groups[gid]) return {}
+              const orders = movePatch(selectOrderedGroups(s), gid, toIndex)
+              if (!orders) return {}
+              const groups = { ...s.groups }
+              for (const [id, order] of orders) {
+                groups[id] = { ...groups[id]!, order }
+              }
+              return { groups }
+            },
+            false,
+            'moveGroup',
+          ),
+
         setLegendLayer: (input) =>
           set((s) => upsertLayerState(s, input), false, 'setLegendLayer'),
         removeLegendLayer: (lid) =>

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

@@ -4,9 +4,11 @@ import {
   clearAllLegendStores,
 } from './legend-store-registry'
 import {
+  selectAllGroupsCollapsed,
   selectGroupVisibility,
   selectLayersByGroup,
   selectOrderedGroups,
+  selectVisibleLayersGrouped,
 } from './selectors'
 import type { LegendLayerInput, LegendVariable } from './types'
 
@@ -455,3 +457,117 @@ describe('legend store', () => {
     ).toContain('c')
   })
 })
+
+describe('moveLayer / moveGroup', () => {
+  // a, b ungrouped; c, d, e in g1; f in g2.
+  const moveLayers: LegendLayerInput[] = [
+    { id: 'a', name: 'A', variables: [cat] },
+    { id: 'b', name: 'B', variables: [cat] },
+    { id: 'c', name: 'C', variables: [cat], groupId: 'g1' },
+    { id: 'd', name: 'D', variables: [cat], groupId: 'g1' },
+    { id: 'e', name: 'E', variables: [cat], groupId: 'g1' },
+    { id: 'f', name: 'F', variables: [cat], groupId: 'g2' },
+  ]
+  const moveGroups = [
+    { id: 'g1', label: 'G1' },
+    { id: 'g2', label: 'G2' },
+    { id: 'g3', label: 'G3' },
+  ]
+  const orderedIds = (
+    s: ReturnType<ReturnType<typeof createLegendStore>['getState']>,
+    groupId: string | undefined,
+  ) => selectLayersByGroup(s, groupId).map((l) => l.id)
+
+  it('reorders within the bucket with dense orders', () => {
+    const store = createLegendStore('s', {
+      layers: moveLayers,
+      groups: moveGroups,
+    })
+    store.getState().moveLayer('e', 0)
+    expect(orderedIds(store.getState(), 'g1')).toEqual(['e', 'c', 'd'])
+    expect(
+      selectLayersByGroup(store.getState(), 'g1').map((l) => l.order),
+    ).toEqual([0, 1, 2])
+    // Other buckets untouched.
+    expect(orderedIds(store.getState(), undefined)).toEqual(['a', 'b'])
+    expect(orderedIds(store.getState(), 'g2')).toEqual(['f'])
+  })
+
+  it('moves ungrouped layers within their own bucket', () => {
+    const store = createLegendStore('s', {
+      layers: moveLayers,
+      groups: moveGroups,
+    })
+    store.getState().moveLayer('b', 0)
+    expect(orderedIds(store.getState(), undefined)).toEqual(['b', 'a'])
+  })
+
+  it('clamps the target index and no-ops on unknown ids / same position', () => {
+    const store = createLegendStore('s', {
+      layers: moveLayers,
+      groups: moveGroups,
+    })
+    store.getState().moveLayer('c', 99) // clamped to the end of g1
+    expect(orderedIds(store.getState(), 'g1')).toEqual(['d', 'e', 'c'])
+
+    const before = store.getState().layers
+    store.getState().moveLayer('nope', 0)
+    store.getState().moveLayer('c', 2) // already there
+    expect(store.getState().layers).toBe(before)
+  })
+
+  it('moveGroup reorders the group list and survives a resync', () => {
+    const store = createLegendStore('s', {
+      layers: moveLayers,
+      groups: moveGroups,
+    })
+    store.getState().moveGroup('g3', 0)
+    expect(selectOrderedGroups(store.getState()).map((g) => g.id)).toEqual([
+      'g3',
+      'g1',
+      'g2',
+    ])
+    // A provider resync with the original inputs preserves the user's order.
+    store.getState()._sync(moveLayers, moveGroups)
+    expect(selectOrderedGroups(store.getState()).map((g) => g.id)).toEqual([
+      'g3',
+      'g1',
+      'g2',
+    ])
+
+    const before = store.getState().groups
+    store.getState().moveGroup('nope', 0)
+    expect(store.getState().groups).toBe(before)
+  })
+})
+
+describe('summary selectors', () => {
+  // a, b ungrouped; c, d in g1 — plus a second group for cross-group checks.
+  const groupedLayers: LegendLayerInput[] = [
+    ...layers,
+    { id: 'e', name: 'E', variables: [cat], groupId: 'g2' },
+  ]
+  const groups = [
+    { id: 'g1', label: 'G1' },
+    { id: 'g2', label: 'G2' },
+  ]
+
+  it('selectVisibleLayersGrouped lists only visible layers, ungrouped last', () => {
+    const store = createLegendStore('s', { layers: groupedLayers, groups })
+    store.getState().setVisibility('d', false)
+    store.getState().setVisibility('e', false) // g2 fully hidden → dropped
+    const sections = selectVisibleLayersGrouped(store.getState())
+    expect(sections.map((x) => x.group?.id)).toEqual(['g1', undefined])
+    expect(sections[0]!.layers.map((l) => l.id)).toEqual(['c'])
+    expect(sections[1]!.layers.map((l) => l.id)).toEqual(['a', 'b'])
+  })
+
+  it('selectAllGroupsCollapsed flips only when every group is collapsed', () => {
+    const store = createLegendStore('s', { layers: groupedLayers, groups })
+    expect(selectAllGroupsCollapsed(store.getState())).toBe(false)
+    store.getState().setGroupCollapsed('g1', true)
+    expect(selectAllGroupsCollapsed(store.getState())).toBe(false)
+    store.getState().setGroupCollapsed('g2', true)
+    expect(selectAllGroupsCollapsed(store.getState())).toBe(true)
+  })
+})

package/src/legend/stores/selectors.ts

@@ -36,6 +36,69 @@ export function selectOrderedLayers(state: LegendState): LegendLayer[] {
   return Object.values(state.layers).sort(byOrder)
 }
 
+/**
+ * `true` when every group is collapsed (`false` with no groups) — drives the
+ * "Collapse all groups" / "Expand all groups" menu label flip.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function selectAllGroupsCollapsed(state: LegendState): boolean {
+  const groups = Object.values(state.groups)
+  return groups.length > 0 && groups.every((g) => g.collapsed)
+}
+
+/**
+ * Whether the legend has groups — gates panel-level group actions.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function selectHasGroups(state: LegendState): boolean {
+  return Object.keys(state.groups).length > 0
+}
+
+/**
+ * Visible layers grouped for the enabled-layers menu.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function selectVisibleLayersGrouped(
+  state: LegendState,
+): { group?: LegendGroup; layers: LegendLayer[] }[] {
+  const visible = (groupId: string | undefined) =>
+    selectLayersByGroup(state, groupId).filter((l) => l.visible)
+  const sections: { group?: LegendGroup; layers: LegendLayer[] }[] = []
+  for (const group of selectOrderedGroups(state)) {
+    const layers = visible(group.id)
+    if (layers.length > 0) sections.push({ group, layers })
+  }
+  const ungrouped = visible(undefined)
+  if (ungrouped.length > 0) sections.push({ layers: ungrouped })
+  return sections
+}
+
+/**
+ * Whether a layer has any collapsible body — something the row's `Collapse`
+ * can actually fold. A layer with no variables, sections, or helper note
+ * renders an empty body, so there is nothing to collapse. Gates the row's
+ * title-area collapse affordance (chevron + click).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function selectLayerCollapsible(
+  state: LegendState,
+  layerId: string,
+): boolean {
+  const layer = state.layers[layerId]
+  if (!layer) return false
+  return (
+    layer.variables.length > 0 ||
+    (layer.sections?.length ?? 0) > 0 ||
+    // Truthiness matches the render condition — an empty-string note renders
+    // no footer, so it must not enable the collapse affordance.
+    Boolean(layer.helperText)
+  )
+}
+
 /**
  * Tri-state visibility — derived for groups from their member layers, and the
  * state contract of a controlled `Legend.VisibilityToggle` for any custom
@@ -55,8 +118,7 @@ export function selectGroupVisibility(
 ): LegendVisibility {
   let anyVisible = false
   let anyHidden = false
-  for (const layer of Object.values(state.layers)) {
-    if (layer.groupId !== groupId) continue
+  for (const layer of selectLayersByGroup(state, groupId)) {
     if (layer.visible) anyVisible = true
     else anyHidden = true
   }

package/src/legend/stores/types.ts

@@ -292,6 +292,12 @@ export interface LegendState {
    * section's `options`.
    */
   setSectionValue: (id: string, sectionId: string, value: string) => void
+  /**
+   * Move a layer to `toIndex` **within its sibling bucket** (its group, or
+   * the ungrouped bucket). `toIndex` is clamped; orders stay dense. No-op
+   * for unknown ids or when the position doesn't change.
+   */
+  moveLayer: (id: string, toIndex: number) => void
 
   // Group setters
   /**
@@ -303,6 +309,11 @@ export interface LegendState {
    */
   setGroupVisibility: (id: string, visible: boolean) => void
   setGroupCollapsed: (id: string, collapsed: boolean) => void
+  /**
+   * Move a group to `toIndex` within the group list. `toIndex` is clamped;
+   * orders stay dense. No-op for unknown ids or an unchanged position.
+   */
+  moveGroup: (id: string, toIndex: number) => void
 
   // Imperative add/remove/update — an alternative to the Provider's bulk
   // `layers`/`groups` props. To use these, keep those props stable (pass the

package/src/widgets/actions/download/exports.test.tsx

@@ -1,4 +1,12 @@
-import { describe, test, expect, vi, beforeEach, afterEach } from 'vitest'
+import {
+  describe,
+  test,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type MockInstance,
+} from 'vitest'
 import { downloadToCSV, downloadToPNG } from './exports'
 import { createRef } from 'react'
 import type { RefObject } from 'react'
@@ -86,8 +94,10 @@ describe('downloadToCSV', () => {
 describe('downloadToPNG', () => {
   let mockRef: RefObject<HTMLDivElement>
   let mockElement: HTMLDivElement
+  let warnSpy: MockInstance<typeof console.warn>
 
   beforeEach(() => {
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
     // Create a real DOM element
     mockElement = document.createElement('div')
     mockElement.style.width = '800px'
@@ -104,6 +114,7 @@ describe('downloadToPNG', () => {
 
   afterEach(() => {
     document.body.removeChild(mockElement)
+    warnSpy.mockRestore()
     vi.clearAllMocks()
   })
 
@@ -121,6 +132,7 @@ describe('downloadToPNG', () => {
     const result = await downloadToPNG.modifier(nullRef)
 
     expect(result).toBeUndefined()
+    expect(warnSpy).toHaveBeenCalled()
   })
 
   test('modifier returns undefined when ref is a function', async () => {
@@ -129,6 +141,7 @@ describe('downloadToPNG', () => {
     const result = await downloadToPNG.modifier(functionRef)
 
     expect(result).toBeUndefined()
+    expect(warnSpy).toHaveBeenCalled()
   })
 
   test('removes toolbar and actions containers from clone', async () => {