@carto/ps-react-ui 4.12.2 → 4.13.0

package/dist/types/legend/components/legend-visibility-toggle/legend-visibility-toggle.d.ts

@@ -0,0 +1,35 @@
+import { LegendVisibility } from '../../stores';
+import { LegendLabels } from '../../provider/labels';
+export type LegendVisibilityToggleProps = {
+    /**
+     * Override the aria labels (defaults: the layer pair in rows and controlled
+     * mode, the group pair in group headers) — e.g.
+     * `labels={{ hideLayer: 'Hide section', showLayer: 'Show section' }}`.
+     */
+    labels?: Pick<LegendLabels, 'hideLayer' | 'showLayer'>;
+} & ({
+    /**
+     * Controlled mode: current state — renders the matching eye (`mixed` →
+     * the indeterminate icon). Use it for element kinds beyond layer/group.
+     */
+    visibility: LegendVisibility;
+    /**
+     * Controlled mode: called with the **next** visibility (`hidden` →
+     * `true`; `visible`/`mixed` → `false`) — mirrors the store setters.
+     */
+    onToggle: (visible: boolean) => void;
+} | {
+    visibility?: never;
+    onToggle?: never;
+});
+/**
+ * Agnostic visibility eye. Pass `visibility` + `onToggle` to control it for
+ * any element kind (no context needed); without them it wires itself to the
+ * nearest context — the layer eye inside a `Legend.Row`, the tri-state group
+ * eye (cascading to every member) inside a `Legend.Group`. Pinned `.active`
+ * in the hover-fade group while not fully visible. Renders nothing without
+ * props or context (dev-only warning).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendVisibilityToggle({ visibility, onToggle, labels, }: LegendVisibilityToggleProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/types/legend/index.d.ts

@@ -0,0 +1,88 @@
+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 { 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 declare const Legend: {
+    readonly Provider: typeof LegendProvider;
+    readonly Group: typeof LegendGroup;
+    readonly Row: typeof LegendRow;
+    readonly Actions: typeof LegendActions;
+    readonly VisibilityToggle: typeof LegendVisibilityToggle;
+    readonly RowMenu: typeof LegendRowMenu;
+    readonly ZoomTo: typeof LegendZoomTo;
+    readonly Opacity: {
+        Trigger: () => import("react/jsx-runtime").JSX.Element | null;
+        Popover: () => import("react/jsx-runtime").JSX.Element | null;
+    };
+    readonly ConfigSelect: typeof LegendConfigSelect;
+    readonly Item: typeof LegendItem;
+    readonly ItemUI: typeof LegendItemUI;
+    readonly Swatch: typeof LegendSwatch;
+    readonly CategoryUI: typeof LegendCategoryUI;
+    readonly RampUI: typeof LegendRampUI;
+    readonly ProportionUI: typeof LegendProportionUI;
+    readonly IconUI: typeof LegendIconUI;
+};
+export { DEFAULT_LEGEND_LABELS } from './provider';
+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';
+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/dist/types/legend/provider/index.d.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/dist/types/legend/provider/labels.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 {
+    expandLayer: string;
+    collapseLayer: string;
+    hideLayer: string;
+    showLayer: string;
+    layerOptions: string;
+    zoomTo: string;
+    hideGroup: string;
+    showGroup: string;
+    expandGroup: string;
+    collapseGroup: string;
+    opacity: string;
+    attribute: string;
+    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 declare const DEFAULT_LEGEND_LABELS: LegendLabels;

package/dist/types/legend/provider/legend-config-context.d.ts

@@ -0,0 +1,7 @@
+import { LegendLabels } from './labels';
+/** Per-panel configuration delivered by `Legend.Provider` to all containers. */
+export interface LegendConfig {
+    labels: LegendLabels;
+}
+export declare const LegendConfigContext: import('react').Context<LegendConfig>;
+export declare function useLegendConfig(): LegendConfig;

package/dist/types/legend/provider/legend-provider.d.ts

@@ -0,0 +1,38 @@
+import { ReactNode } from 'react';
+import { LegendGroupInput, LegendLayerInput } from '../stores';
+import { 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 declare function LegendProvider({ id, layers, groups, labels, keepAlive, children, }: LegendProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/legend/stores/index.d.ts

@@ -0,0 +1,5 @@
+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/dist/types/legend/stores/legend-context.d.ts

@@ -0,0 +1,4 @@
+/** @experimental This API is new and may change in a future release. */
+export declare const LegendContext: import('react').Context<string | null>;
+/** @experimental This API is new and may change in a future release. */
+export declare function useLegendId(): string;

package/dist/types/legend/stores/legend-store-registry.d.ts

@@ -0,0 +1,39 @@
+import { LegendInit, LegendState, LegendStoreApi } from './types';
+/**
+ * @internal — used by Provider; not part of the public API.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function createLegendStore(id: string, init?: LegendInit): LegendStoreApi;
+/** @experimental This API is new and may change in a future release. */
+export declare function getLegendStore(id: string): LegendStoreApi;
+/** @experimental This API is new and may change in a future release. */
+export declare function hasLegendStore(id: string): boolean;
+/** @experimental This API is new and may change in a future release. */
+export declare function deleteLegendStore(id: string): void;
+/** @experimental This API is new and may change in a future release. */
+export declare function clearAllLegendStores(): void;
+/**
+ * @internal — used by Provider's lazy init so children can resolve the store first render.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function setLegendStoreEntry(id: string, store: LegendStoreApi): void;
+/**
+ * @internal — registers a Provider mount and warns on duplicate ids in dev.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function registerLegendStore(id: string, store: LegendStoreApi): void;
+/**
+ * @internal — Provider unmount counterpart; removes the entry on last unmount.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function unregisterLegendStore(id: string, options: {
+    keepAlive: boolean;
+}): void;
+/** @experimental This API is new and may change in a future release. */
+export declare function useLegendStore<T>(id: string, selector: (state: LegendState) => T): T;
+/** @experimental This API is new and may change in a future release. */
+export declare function useLegendShallow<T>(id: string, selector: (state: LegendState) => T): T;

package/dist/types/legend/stores/legend-store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/legend/stores/selectors.d.ts

@@ -0,0 +1,33 @@
+import { LegendGroup, LegendLayer, LegendState } from './types';
+/**
+ * Groups sorted by `order`.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function selectOrderedGroups(state: LegendState): LegendGroup[];
+/**
+ * Layers belonging to `groupId` (pass `undefined` for ungrouped, top-level
+ * layers), sorted by `order`.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function selectLayersByGroup(state: LegendState, groupId: string | undefined): LegendLayer[];
+/**
+ * All layers sorted by `order`, regardless of group.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function selectOrderedLayers(state: LegendState): LegendLayer[];
+/**
+ * Tri-state visibility — derived for groups from their member layers, and the
+ * state contract of a controlled `Legend.VisibilityToggle` for any custom
+ * element kind.
+ */
+export type LegendVisibility = 'visible' | 'hidden' | 'mixed';
+/**
+ * Tri-state group visibility: `'visible'` when every member layer is visible
+ * (also for empty groups), `'hidden'` when none is, `'mixed'` otherwise.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function selectGroupVisibility(state: LegendState, groupId: string): LegendVisibility;

package/dist/types/legend/stores/types.d.ts

@@ -0,0 +1,275 @@
+import { ReactNode } from 'react';
+import { StoreApi } from 'zustand';
+/** Floating panel anchor position. */
+export type LegendPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/**
+ * Layout direction of a category/icon legend's items. `'horizontal'` flows
+ * the swatch+label pairs left-to-right, wrapping onto multiple rows.
+ */
+export type LegendOrientation = 'vertical' | 'horizontal';
+/** Swatch shape for a category legend. */
+export type LegendSwatchShape = 'square' | 'circle' | 'line';
+/** Fill pattern for a filled square/circle swatch (`isStrokeColor: false`). */
+export type LegendFillPattern = 'solid' | 'horizontal' | 'vertical' | 'diagonal' | 'diagonal-alt' | 'cross' | 'dots' | 'grid';
+/**
+ * Border style for a stroked square/circle swatch (`isStrokeColor: true`), or
+ * the line style for `shape: 'line'`. `corners` applies to squares only;
+ * `dash-dot` applies to lines only — inapplicable values degrade gracefully.
+ */
+export type LegendStrokeStyle = 'solid' | 'dashed' | 'dotted' | 'dash-dot' | 'corners';
+export interface LegendCategoryItem {
+    label: string;
+    /** Fill or stroke color (see `isStrokeColor`). */
+    color: string;
+    /**
+     * Optional value shown alongside the label — a pre-formatted node, so the
+     * consumer controls the formatting (e.g. `'12%'`, `'1.2K'`, or any element).
+     */
+    value?: ReactNode;
+    /** Optional marker diameter/length in px (the "Small/Medium/Large/XL" sizes). */
+    size?: number;
+    /** Override the variable-level swatch shape for this item. */
+    shape?: LegendSwatchShape;
+    /** Override the variable-level fill pattern for this item (mix patterns in one list). */
+    fillPattern?: LegendFillPattern;
+    /** Override the variable-level border/line style for this item. */
+    strokeStyle?: LegendStrokeStyle;
+    /** Override the variable-level fill-vs-outline mode for this item. */
+    isStrokeColor?: boolean;
+}
+export interface LegendCategoryVariable {
+    type: 'category';
+    items: LegendCategoryItem[];
+    /** Default swatch shape for all items (each item may override). Default `'circle'`. */
+    shape?: LegendSwatchShape;
+    /**
+     * Default fill-vs-outline mode (each item may override). When true, `color`
+     * paints the marker border/outline instead of its fill.
+     */
+    isStrokeColor?: boolean;
+    /**
+     * Default fill pattern when filled (each item may override — mix patterns
+     * in one list). Default `'solid'`.
+     */
+    fillPattern?: LegendFillPattern;
+    /**
+     * Default border style when stroked, or line style for `shape: 'line'`
+     * (each item may override). Default `'solid'`.
+     */
+    strokeStyle?: LegendStrokeStyle;
+    /** Item layout direction. Default `'vertical'`. */
+    orientation?: LegendOrientation;
+}
+export interface LegendRampStop {
+    label: string;
+    value: number;
+}
+export interface LegendRampVariable {
+    type: 'ramp';
+    /** Ordered low→high colors (hex / rgb / css). */
+    colors: string[];
+    /**
+     * Ordered low→high stops. Discrete ramps **require `colors.length + 1`**
+     * stops — the boundaries between color steps, including both outer edges —
+     * and each label is centered on its boundary line (keep labels short, e.g.
+     * `20K`; there is no collision handling). A discrete ramp with any other
+     * stop count is incoherent and renders an inline error instead of the bar.
+     * Continuous ramps show only the first/last endpoints.
+     */
+    stops: LegendRampStop[];
+    /** Continuous gradient bar vs. discrete color steps. */
+    isContinuous: boolean;
+    /**
+     * Average value, marked as a dashed vertical line on the bar (tooltip shows
+     * the formatted value). Positioned linearly between the first and last stop
+     * `value`s; out-of-range averages clamp to the bar's edge.
+     */
+    avg?: number;
+    /**
+     * Formats `avg` for its tooltip. Default `String(avg)` — pass e.g.
+     * `(v) => formatNumber(v, 'es-ES')` or `(v) => `${v}%``. Use a stable
+     * reference (same contract as the other variable fields).
+     */
+    formatValue?: (value: number) => ReactNode;
+    /** Attribute the color is based on (shown as "Color based on"). */
+    attribute?: string;
+}
+export interface LegendProportionVariable {
+    type: 'proportion';
+    min: number;
+    max: number;
+    /**
+     * Explicit value breaks to label (order-insensitive — the renderer sorts
+     * descending and caps at the **4 largest**). When omitted (or fewer than 2
+     * entries), breaks are evenly spaced between `min` and `max` over `steps`.
+     */
+    stops?: number[];
+    /**
+     * Number of nested circles and derived value breaks, clamped to **2–4**.
+     * Defaults to 4. Ignored when explicit `stops` are provided (their count,
+     * capped at 4, wins). Circles and labels always match 1:1. Edge case: when
+     * `min === max` the renderer collapses to a **single** circle/break (the
+     * shared value), regardless of `steps`.
+     */
+    steps?: number;
+    /**
+     * Formats each derived break (MAX / middle / MIN). Default `String(value)`
+     * — pass e.g. `(v) => formatNumber(v, 'es-ES')`. Use a stable reference
+     * (same contract as the other variable fields).
+     */
+    formatValue?: (value: number) => ReactNode;
+    /** Attribute the size is based on (shown as "Radius range by"). */
+    attribute?: string;
+}
+export interface LegendIconItem {
+    label: string;
+    /** Icon URL (data URI or external). */
+    icon: string;
+    /**
+     * Optional value shown alongside the label — a pre-formatted node, so the
+     * consumer controls the formatting (e.g. `'12%'`, `'1.2K'`, or any element).
+     */
+    value?: ReactNode;
+}
+export interface LegendIconVariable {
+    type: 'icon';
+    items: LegendIconItem[];
+    /** Item layout direction. Default `'vertical'`. */
+    orientation?: LegendOrientation;
+}
+export type LegendVariable = LegendCategoryVariable | LegendRampVariable | LegendProportionVariable | LegendIconVariable;
+/**
+ * One section of a layer's configuration select. The select's menu lists each
+ * section under its `title` (omitted when the layer has a single section);
+ * every section keeps its own highlighted `active` option. The closed field
+ * displays the first section's `active`.
+ */
+export interface LegendConfigSection {
+    id: string;
+    /** Section heading in the menu (e.g. "Global"). Hidden for a single section. */
+    title?: string;
+    options: string[];
+    /** The section's currently-selected option. */
+    active: string;
+}
+/** A layer row in the legend. Holds both static definition and interactive state. */
+export interface LegendLayer {
+    id: string;
+    name: string;
+    /** Secondary line (e.g. "Zoom level 1 – 12"). */
+    subtitle?: string;
+    visible: boolean;
+    /** 0–1. */
+    opacity: number;
+    collapsed: boolean;
+    /**
+     * @internal Collapsed state snapshotted when the layer was hidden — restored
+     * on show so a manual collapse/expand persists across visibility toggles.
+     * Managed by `setVisibility`/`setCollapsed`; do not set from outside.
+     */
+    collapsedBeforeHide?: boolean;
+    /** Sort order among siblings (lower = first). */
+    order: number;
+    /** Owning group id, if the layer belongs to a group. */
+    groupId?: string;
+    /** Show the opacity header action (slider + input popover) for this layer. */
+    opacityControl?: boolean;
+    /**
+     * Configuration-select sections. When absent (or empty), the row renders no
+     * select. User-picked `active`s survive Provider re-syncs as long as the
+     * section id still exists and the pick is still among its `options`.
+     */
+    sections?: LegendConfigSection[];
+    /** Footer helper note — one per layer, shown after all variables. */
+    helperText?: ReactNode;
+    /**
+     * Ordered item renderers, stacked top-to-bottom in the row body (a layer
+     * can mix e.g. two category lists and a proportion). Pass a stable array
+     * reference — `_sync` compares it by reference, like the other prop-driven
+     * fields.
+     */
+    variables: LegendVariable[];
+}
+/**
+ * A group of layer rows. A group has no stored visibility of its own — it is
+ * derived from its member layers (see `selectGroupVisibility`): all visible →
+ * `'visible'`, none visible → `'hidden'`, otherwise `'mixed'`.
+ */
+export interface LegendGroup {
+    id: string;
+    label: string;
+    collapsed: boolean;
+    /**
+     * @internal Collapsed state snapshotted when the group was hidden via
+     * `setGroupVisibility` — restored on show. Managed by the setters.
+     */
+    collapsedBeforeHide?: boolean;
+    order: number;
+}
+/** @experimental This API is new and may change in a future release. */
+export interface LegendLayerInput extends Omit<LegendLayer, 'visible' | 'opacity' | 'collapsed' | 'collapsedBeforeHide' | 'order'> {
+    visible?: boolean;
+    opacity?: number;
+    collapsed?: boolean;
+    order?: number;
+}
+/** @experimental This API is new and may change in a future release. */
+export interface LegendGroupInput extends Omit<LegendGroup, 'collapsed' | 'collapsedBeforeHide' | 'order'> {
+    collapsed?: boolean;
+    order?: number;
+}
+export interface LegendState {
+    layers: Record<string, LegendLayer>;
+    groups: Record<string, LegendGroup>;
+    setVisibility: (id: string, visible: boolean) => void;
+    setOpacity: (id: string, opacity: number) => void;
+    setCollapsed: (id: string, collapsed: boolean) => void;
+    /**
+     * Pick a section's active option in the layer's configuration select.
+     * No-op for unknown layers/sections or when `value` is not one of the
+     * section's `options`.
+     */
+    setSectionValue: (id: string, sectionId: string, value: string) => void;
+    /**
+     * Show/hide **all member layers** of a group (the group itself has no stored
+     * visibility — it is derived from its members). Each member keeps its own
+     * collapse snapshot; the group additionally collapses when hiding and
+     * restores its pre-hide collapse state when showing. No-op when the group
+     * is already at the target state or has no members.
+     */
+    setGroupVisibility: (id: string, visible: boolean) => void;
+    setGroupCollapsed: (id: string, collapsed: boolean) => void;
+    /**
+     * Add a layer, or update it if `input.id` already exists. Interactive state
+     * (visible/opacity/collapsed/order and section actives) is preserved unless
+     * the input explicitly overrides it; new layers append to the end of their
+     * sibling bucket. No-op when an existing layer is unchanged.
+     */
+    setLegendLayer: (input: LegendLayerInput) => void;
+    /**
+     * Remove a layer and densely re-number the remaining siblings. No-op for an
+     * unknown id.
+     */
+    removeLegendLayer: (id: string) => void;
+    /**
+     * Add a group, or update it if `input.id` already exists (collapse/order
+     * preserved on update). No-op when unchanged.
+     */
+    setLegendGroup: (input: LegendGroupInput) => void;
+    /**
+     * Remove a group; its member layers are **un-grouped** (their `groupId` is
+     * cleared) so they survive as ungrouped rows rather than vanish. No-op for an
+     * unknown id.
+     */
+    removeLegendGroup: (id: string) => void;
+    /**
+     * @internal Provider prop-sync. Adds new entities, updates static fields of
+     * known ones (preserving their interactive state), and removes vanished ones.
+     */
+    _sync: (layers: LegendLayerInput[], groups: LegendGroupInput[]) => void;
+}
+export type LegendStoreApi = StoreApi<LegendState>;
+export interface LegendInit {
+    layers?: LegendLayerInput[];
+    groups?: LegendGroupInput[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carto/ps-react-ui",
-  "version": "4.12.2",
+  "version": "4.13.0",
   "description": "CARTO's Professional Service React Material library",
   "type": "module",
   "devDependencies": {
@@ -31,8 +31,8 @@
     "@mui/x-date-pickers": "^7.0.0",
     "echarts": "^6.0.0",
     "html2canvas": "^1.4.1",
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "react-markdown": "^10.0.0",
     "zustand": "^5.0.0",
     "@carto/ps-utils": "2.0.1"
@@ -46,6 +46,14 @@
       "import": "./dist/components.js",
       "types": "./dist/types/components/index.d.ts"
     },
+    "./legend": {
+      "import": "./dist/legend.js",
+      "types": "./dist/types/legend/index.d.ts"
+    },
+    "./legend/stores": {
+      "import": "./dist/legend/stores.js",
+      "types": "./dist/types/legend/stores/index.d.ts"
+    },
     "./widgets/actions": {
       "import": "./dist/widgets/actions.js",
       "types": "./dist/types/widgets/actions/index.d.ts"

package/src/components/geolocation-controls/geolocation-controls.test.tsx

@@ -111,6 +111,21 @@ describe('GeolocationControls', () => {
     expect(mockOnChange).toHaveBeenCalledWith(mockPosition.coords)
   })
 
+  test('does not re-query permissions when only the onError identity changes', () => {
+    mockPermissions.query.mockResolvedValue(mockPermissions)
+
+    const { rerender } = render(
+      <GeolocationControls onChange={mockOnChange} onError={vi.fn()} />,
+    )
+    expect(mockPermissions.query).toHaveBeenCalledTimes(1)
+
+    // `onError` is read through an Effect Event, so the permission-query
+    // effect depends on `hasGeolocation` alone. A fresh callback identity
+    // must NOT re-run the query or re-register the permission listener.
+    rerender(<GeolocationControls onChange={mockOnChange} onError={vi.fn()} />)
+    expect(mockPermissions.query).toHaveBeenCalledTimes(1)
+  })
+
   test('handles geolocation errors', () => {
     mockPermissions.query.mockResolvedValue(mockPermissions)