@carto/ps-react-ui 4.12.2 → 4.13.0

package/src/legend/index.ts

@@ -0,0 +1,121 @@
+// ─── Internal imports (used to assemble the curated `Legend` const) ─────────
+import { LegendProvider } from './provider/legend-provider'
+import { LegendGroup } from './components/legend-group/legend-group'
+import { LegendRow } from './components/legend-row/legend-row'
+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 { 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'
+import { LegendItemUI } from './components/legend-item/legend-item-ui'
+import { LegendSwatch } from './components/legend-swatch/legend-swatch'
+import { LegendCategoryUI } from './components/legend-category/legend-category-ui'
+import { LegendRampUI } from './components/legend-ramp/legend-ramp-ui'
+import { LegendProportionUI } from './components/legend-proportion/legend-proportion-ui'
+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
+ * 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),
+ * everything else in the collapsible body.
+ *
+ * ```tsx
+ * import { Legend } from '@carto/ps-react-ui/legend'
+ *
+ * <Legend.Provider id='map-legend' layers={layers} groups={groups}>
+ *   <Legend.Group groupId='demographics'>
+ *     <Legend.Actions>
+ *       <Legend.VisibilityToggle />          // tri-state group eye
+ *     </Legend.Actions>
+ *     <Legend.Row layerId='income'>
+ *       // Actions read L→R: options · opacity · visibility
+ *       <Legend.Actions>
+ *         <Legend.RowMenu>
+ *           <Legend.ZoomTo onZoomTo={zoomTo} />
+ *         </Legend.RowMenu>
+ *         <Legend.Opacity.Trigger />
+ *         <Legend.VisibilityToggle />        // layer eye
+ *       </Legend.Actions>
+ *       <Legend.ConfigSelect />
+ *       <Legend.Item />
+ *       <Legend.Opacity.Popover />           // anchors to the row header
+ *     </Legend.Row>
+ *   </Legend.Group>
+ * </Legend.Provider>
+ * ```
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export const Legend = {
+  // Composition shell
+  Provider: LegendProvider,
+  Group: LegendGroup,
+  Row: LegendRow,
+  Actions: LegendActions,
+
+  // Store-connected actions & controls (context-driven)
+  VisibilityToggle: LegendVisibilityToggle,
+  RowMenu: LegendRowMenu,
+  ZoomTo: LegendZoomTo,
+  Opacity: LegendOpacity,
+  ConfigSelect: LegendConfigSelect,
+  Item: LegendItem,
+
+  // Pure UI
+  ItemUI: LegendItemUI,
+  Swatch: LegendSwatch,
+  CategoryUI: LegendCategoryUI,
+  RampUI: LegendRampUI,
+  ProportionUI: LegendProportionUI,
+  IconUI: LegendIconUI,
+} as const
+
+// ─── Labels ────────────────────────────────────────────────────────────────
+// Exported separately so consumers can build customized label sets via spread.
+export { DEFAULT_LEGEND_LABELS } from './provider'
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+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 { 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 { LegendRowContextValue } from './components/contexts'
+export type { LegendItemUIProps } from './components/legend-item/legend-item-ui'
+export type { LegendSwatchProps } from './components/legend-swatch/legend-swatch'
+export type { LegendCategoryUIProps } from './components/legend-category/legend-category-ui'
+export type { LegendRampUIProps } from './components/legend-ramp/legend-ramp-ui'
+export type { LegendProportionUIProps } from './components/legend-proportion/legend-proportion-ui'
+export type { LegendIconUIProps } from './components/legend-icon/legend-icon-ui'
+
+// Store entity & variable types (re-exported for convenience; full store API
+// lives at `@carto/ps-react-ui/legend/stores`).
+export type {
+  LegendPosition,
+  LegendVisibility,
+  LegendOrientation,
+  LegendSwatchShape,
+  LegendFillPattern,
+  LegendStrokeStyle,
+  LegendVariable,
+  LegendCategoryItem,
+  LegendCategoryVariable,
+  LegendRampStop,
+  LegendRampVariable,
+  LegendProportionVariable,
+  LegendIconItem,
+  LegendIconVariable,
+  LegendConfigSection,
+  LegendLayer,
+  LegendGroup as LegendGroupModel,
+  LegendLayerInput,
+  LegendGroupInput,
+} from './stores'

package/src/legend/provider/index.ts

@@ -0,0 +1,6 @@
+export { LegendProvider } from './legend-provider'
+export type { LegendProviderProps } from './legend-provider'
+export { LegendConfigContext, useLegendConfig } from './legend-config-context'
+export type { LegendConfig } from './legend-config-context'
+export { DEFAULT_LEGEND_LABELS } from './labels'
+export type { LegendLabels } from './labels'

package/src/legend/provider/labels.ts

@@ -0,0 +1,59 @@
+/**
+ * Every user-facing string in the legend module. Override any subset via
+ * `<Legend.Provider labels={{ … }}>` — pure `*UI` components also accept a
+ * `labels` prop directly for store-free composition.
+ */
+export interface LegendLabels {
+  // Layer row
+  expandLayer: string
+  collapseLayer: string
+  hideLayer: string
+  showLayer: string
+
+  // Row overflow menu
+  layerOptions: string
+  zoomTo: string
+
+  // Group
+  hideGroup: string
+  showGroup: string
+  expandGroup: string
+  collapseGroup: string
+
+  // Row controls
+  opacity: string
+  attribute: string
+
+  // Item renderers
+  radiusRangeBy: string
+  colorBasedOn: string
+  colorGradient: string
+  /** Prefix for the largest proportion break, e.g. `"MAX: "`. */
+  maxPrefix: string
+  /** Prefix for the smallest proportion break, e.g. `"MIN: "`. */
+  minPrefix: string
+}
+
+export const DEFAULT_LEGEND_LABELS: LegendLabels = {
+  expandLayer: 'Expand layer',
+  collapseLayer: 'Collapse layer',
+  hideLayer: 'Hide layer',
+  showLayer: 'Show layer',
+
+  layerOptions: 'Layer options',
+  zoomTo: 'Zoom to',
+
+  hideGroup: 'Hide group',
+  showGroup: 'Show group',
+  expandGroup: 'Expand group',
+  collapseGroup: 'Collapse group',
+
+  opacity: 'Opacity',
+  attribute: 'Attribute',
+
+  radiusRangeBy: 'Radius range by',
+  colorBasedOn: 'Color based on',
+  colorGradient: 'Color gradient',
+  maxPrefix: 'MAX: ',
+  minPrefix: 'MIN: ',
+}

package/src/legend/provider/legend-config-context.ts

@@ -0,0 +1,15 @@
+import { createContext, useContext } from 'react'
+import { DEFAULT_LEGEND_LABELS, type LegendLabels } from './labels'
+
+/** Per-panel configuration delivered by `Legend.Provider` to all containers. */
+export interface LegendConfig {
+  labels: LegendLabels
+}
+
+export const LegendConfigContext = createContext<LegendConfig>({
+  labels: DEFAULT_LEGEND_LABELS,
+})
+
+export function useLegendConfig(): LegendConfig {
+  return useContext(LegendConfigContext)
+}

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

@@ -0,0 +1,102 @@
+import { useLayoutEffect, useMemo, useState, type ReactNode } from 'react'
+import {
+  LegendContext,
+  createLegendStore,
+  getLegendStore,
+  hasLegendStore,
+  registerLegendStore,
+  setLegendStoreEntry,
+  unregisterLegendStore,
+} from '../stores'
+import type {
+  LegendGroupInput,
+  LegendLayerInput,
+  LegendStoreApi,
+} from '../stores'
+import { LegendConfigContext, type LegendConfig } from './legend-config-context'
+import { DEFAULT_LEGEND_LABELS, type LegendLabels } from './labels'
+
+export interface LegendProviderProps {
+  /** Unique id for this legend panel — keys its store. */
+  id: string
+  /**
+   * 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
+   * `data`); the store bails out of unchanged syncs by reference.
+   */
+  layers: LegendLayerInput[]
+  /** Optional group definitions for grouping layers. */
+  groups?: LegendGroupInput[]
+  /** Override any subset of the legend's user-facing strings. */
+  labels?: Partial<LegendLabels>
+  /**
+   * When `true` (the default), the per-panel store survives unmount so
+   * visibility/opacity/order are preserved across remounts — the common case
+   * for a legend that toggles in and out of view. Consumers must call
+   * `deleteLegendStore(id)` when the legend is permanently removed. Set to
+   * `false` to tear the store down on unmount.
+   */
+  keepAlive?: boolean
+  children: ReactNode
+}
+
+/**
+ * Legend panel shell. Creates a per-panel Zustand store keyed by `id`, syncs
+ * the consumer's `layers`/`groups` definitions onto it (preserving interactive
+ * 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`.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendProvider({
+  id,
+  layers,
+  groups,
+  labels,
+  keepAlive = true,
+  children,
+}: LegendProviderProps) {
+  // Lazy init — reuse an existing keepAlive store, otherwise create one and
+  // synchronously place it in the registry so descendants can call
+  // useLegendStore(id, ...) on first render.
+  const [store] = useState<LegendStoreApi>(() => {
+    if (hasLegendStore(id)) return getLegendStore(id)
+    const created = createLegendStore(id, { layers, groups })
+    setLegendStoreEntry(id, created)
+    return created
+  })
+
+  useLayoutEffect(() => {
+    registerLegendStore(id, store)
+    return () => {
+      unregisterLegendStore(id, { keepAlive })
+    }
+  }, [id, store, keepAlive])
+
+  // Sync definitions in. The store's `_sync` preserves interactive state of
+  // known layers/groups and bails out (no state change) when the merged result
+  // is reference-identical, so stable props are a no-op.
+  useLayoutEffect(() => {
+    store.getState()._sync(layers, groups ?? [])
+  }, [store, layers, groups])
+
+  const config = useMemo<LegendConfig>(
+    () => ({
+      labels: labels
+        ? { ...DEFAULT_LEGEND_LABELS, ...labels }
+        : DEFAULT_LEGEND_LABELS,
+    }),
+    [labels],
+  )
+
+  return (
+    <LegendContext.Provider value={id}>
+      <LegendConfigContext.Provider value={config}>
+        {children}
+      </LegendConfigContext.Provider>
+    </LegendContext.Provider>
+  )
+}

package/src/legend/stores/index.ts

@@ -0,0 +1,46 @@
+export type {
+  LegendPosition,
+  LegendOrientation,
+  LegendSwatchShape,
+  LegendFillPattern,
+  LegendStrokeStyle,
+  LegendCategoryItem,
+  LegendCategoryVariable,
+  LegendRampStop,
+  LegendRampVariable,
+  LegendProportionVariable,
+  LegendIconItem,
+  LegendIconVariable,
+  LegendVariable,
+  LegendConfigSection,
+  LegendLayer,
+  LegendGroup,
+  LegendLayerInput,
+  LegendGroupInput,
+  LegendState,
+  LegendStoreApi,
+  LegendInit,
+} from './types'
+
+export { LegendContext, useLegendId } from './legend-context'
+
+export {
+  createLegendStore,
+  getLegendStore,
+  hasLegendStore,
+  deleteLegendStore,
+  clearAllLegendStores,
+  setLegendStoreEntry,
+  registerLegendStore,
+  unregisterLegendStore,
+  useLegendStore,
+  useLegendShallow,
+} from './legend-store-registry'
+
+export type { LegendVisibility } from './selectors'
+export {
+  selectOrderedGroups,
+  selectLayersByGroup,
+  selectOrderedLayers,
+  selectGroupVisibility,
+} from './selectors'

package/src/legend/stores/legend-context.ts

@@ -0,0 +1,17 @@
+import { createContext, useContext } from 'react'
+
+/** @experimental This API is new and may change in a future release. */
+export const LegendContext = createContext<string | null>(null)
+
+/** @experimental This API is new and may change in a future release. */
+export function useLegendId(): string {
+  const id = useContext(LegendContext)
+  if (id == null) {
+    throw new Error(
+      'useLegendId() must be called inside <Legend.Provider>. ' +
+        'If you are calling from outside the Provider tree, use the hooks ' +
+        '(useLegendStore, useLegendShallow) directly with an explicit id.',
+    )
+  }
+  return id
+}