@carto/ps-react-ui 5.0.0-widgets.9 → 5.0.0

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

@@ -0,0 +1,35 @@
+import { LegendVisibility } from '../../stores/index.js';
+import { LegendLabels } from '../../provider/labels.js';
+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.Element | null;

package/dist/types/legend/components/legend-visible-layers/legend-visible-layers.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Panel checklist of visible layers — each entry hides its layer; the menu
+ * closes when nothing remains to list.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendVisibleLayers(): import('react').JSX.Element;

package/dist/types/legend/components/legend-visible-layers/styles.d.ts

@@ -0,0 +1,48 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    triggerWrap: {
+        display: "inline-flex";
+    };
+    paper: {
+        width: number;
+        maxHeight: number;
+        paddingBottom: number;
+    };
+    stickyHeader: {
+        position: "sticky";
+        top: number;
+        zIndex: number;
+        backgroundColor: "background.paper";
+        padding: number;
+        marginBlockEnd: number;
+        lineHeight: string;
+        borderBottom: string;
+        borderColor: "divider";
+    };
+    groupCaption: {
+        display: "block";
+        padding: ({ spacing }: Theme) => string;
+    };
+    item: {
+        minHeight: number;
+        display: "flex";
+        alignItems: "center";
+        justifyContent: "space-between";
+        gap: number;
+        padding: ({ spacing }: Theme) => string;
+    };
+    itemName: {
+        minWidth: number;
+        overflow: "hidden";
+        textOverflow: "ellipsis";
+        whiteSpace: "nowrap";
+    };
+    eye: {
+        fontSize: number;
+        color: "action.active";
+        flexShrink: number;
+    };
+    divider: {
+        marginY: number;
+    };
+};

package/dist/types/legend/components/run-async-menu-action.d.ts

@@ -0,0 +1,7 @@
+import { LegendMenuController } from './contexts.js';
+/**
+ * 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 declare function runAsyncMenuAction(menu: LegendMenuController, action: () => void | Promise<void>): Promise<void>;

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

@@ -0,0 +1,135 @@
+import { LegendProvider } from './provider/legend-provider.js';
+import { LegendGroup } from './components/legend-group/legend-group.js';
+import { LegendRow } from './components/legend-row/legend-row.js';
+import { LegendActions } from './components/legend-actions/legend-actions.js';
+import { LegendVisibilityToggle } from './components/legend-visibility-toggle/legend-visibility-toggle.js';
+import { LegendRowMenu } from './components/legend-row-menu/legend-row-menu.js';
+import { LegendZoomTo } from './components/legend-row-menu/legend-zoom-to.js';
+import { LegendShowOnlyLayer, LegendShowAllLayers } from './components/legend-row-menu/legend-row-menu-items.js';
+import { LegendGroupMenu } from './components/legend-group-menu/legend-group-menu.js';
+import { LegendShowOnlyGroup, LegendShowAllGroups, LegendCollapseAllGroups, LegendZoomToGroup } from './components/legend-group-menu/legend-group-menu-items.js';
+import { LegendPanelMenu } from './components/legend-panel-menu/legend-panel-menu.js';
+import { LegendVisibleLayers } from './components/legend-visible-layers/legend-visible-layers.js';
+import { LegendSortable } from './components/legend-sortable/legend-sortable.js';
+import { LegendConfigSelect } from './components/legend-config-select/legend-config-select.js';
+import { LegendItem } from './components/legend-item/legend-item.js';
+import { LegendItemUI } from './components/legend-item/legend-item-ui.js';
+import { LegendSwatch } from './components/legend-swatch/legend-swatch.js';
+import { LegendCategoryUI } from './components/legend-category/legend-category-ui.js';
+import { LegendRampUI } from './components/legend-ramp/legend-ramp-ui.js';
+import { LegendProportionUI } from './components/legend-proportion/legend-proportion-ui.js';
+import { LegendIconUI } from './components/legend-icon/legend-icon-ui.js';
+/**
+ * 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.
+ *
+ * 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: eye · ⋮ options
+ *       <Legend.Actions>
+ *         <Legend.VisibilityToggle />        // layer eye
+ *         <Legend.RowMenu>
+ *           <Legend.ShowOnlyLayer />
+ *           <Legend.Opacity.Item />
+ *           <Legend.ZoomTo onZoomTo={zoomTo} />
+ *         </Legend.RowMenu>
+ *       </Legend.Actions>
+ *       <Legend.Opacity.Inline />            // bar between header and body
+ *       <Legend.ConfigSelect />
+ *       <Legend.Item />
+ *     </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 declare const Legend: {
+    readonly Provider: typeof LegendProvider;
+    readonly Group: typeof LegendGroup;
+    readonly Row: typeof LegendRow;
+    readonly Actions: typeof LegendActions;
+    readonly Sortable: typeof LegendSortable;
+    readonly VisibilityToggle: typeof LegendVisibilityToggle;
+    readonly RowMenu: typeof LegendRowMenu;
+    readonly ZoomTo: typeof LegendZoomTo;
+    readonly ShowOnlyLayer: typeof LegendShowOnlyLayer;
+    readonly ShowAllLayers: typeof LegendShowAllLayers;
+    readonly GroupMenu: typeof LegendGroupMenu;
+    readonly ShowOnlyGroup: typeof LegendShowOnlyGroup;
+    readonly ShowAllGroups: typeof LegendShowAllGroups;
+    readonly CollapseAllGroups: typeof LegendCollapseAllGroups;
+    readonly ZoomToGroup: typeof LegendZoomToGroup;
+    readonly PanelMenu: typeof LegendPanelMenu;
+    readonly VisibleLayers: typeof LegendVisibleLayers;
+    readonly Opacity: {
+        Item: () => import('react').JSX.Element | null;
+        Inline: () => import('react').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/index.js';
+export type { LegendProviderProps, LegendLabels } from './provider/index.js';
+export type { LegendGroupProps } from './components/legend-group/legend-group.js';
+export type { LegendRowProps } from './components/legend-row/legend-row.js';
+export type { LegendActionsProps } from './components/legend-actions/legend-actions.js';
+export type { LegendSortableProps } from './components/legend-sortable/legend-sortable.js';
+export type { LegendVisibilityToggleProps } from './components/legend-visibility-toggle/legend-visibility-toggle.js';
+export type { LegendRowMenuProps } from './components/legend-row-menu/legend-row-menu.js';
+export type { LegendZoomToProps } from './components/legend-row-menu/legend-zoom-to.js';
+export type { LegendGroupMenuProps } from './components/legend-group-menu/legend-group-menu.js';
+export type { LegendZoomToGroupProps } from './components/legend-group-menu/legend-group-menu-items.js';
+export type { LegendPanelMenuProps } from './components/legend-panel-menu/legend-panel-menu.js';
+export type { LegendRowContextValue } from './components/contexts.js';
+export type { LegendItemUIProps } from './components/legend-item/legend-item-ui.js';
+export type { LegendSwatchProps } from './components/legend-swatch/legend-swatch.js';
+export type { LegendCategoryUIProps } from './components/legend-category/legend-category-ui.js';
+export type { LegendRampUIProps } from './components/legend-ramp/legend-ramp-ui.js';
+export type { LegendProportionUIProps } from './components/legend-proportion/legend-proportion-ui.js';
+export type { LegendIconUIProps } from './components/legend-icon/legend-icon-ui.js';
+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/index.js';

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

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

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

@@ -0,0 +1,48 @@
+/**
+ * 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;
+    /** In-flight label for Zoom to layer / Zoom to group. */
+    loading: string;
+    showOnlyLayer: string;
+    showAllLayers: string;
+    hideGroup: string;
+    showGroup: string;
+    expandGroup: string;
+    collapseGroup: string;
+    groupOptions: string;
+    showOnlyGroup: string;
+    showAllGroups: string;
+    collapseAllGroups: string;
+    expandAllGroups: string;
+    zoomToGroup: string;
+    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;
+    opacity: string;
+    attribute: string;
+    /** Generic close affordance (e.g. the inline opacity bar's ✕). */
+    close: 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.js';
+/** 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/index.js';
+import { LegendLabels } from './labels.js';
+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.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.js';
+export { LegendContext, useLegendId } from './legend-context.js';
+export { createLegendStore, getLegendStore, hasLegendStore, deleteLegendStore, clearAllLegendStores, setLegendStoreEntry, registerLegendStore, unregisterLegendStore, useLegendStore, useLegendShallow, } from './legend-store-registry.js';
+export type { LegendVisibility } from './selectors.js';
+export { selectOrderedGroups, selectLayersByGroup, selectOrderedLayers, selectGroupVisibility, selectLayerCollapsible, selectAllGroupsCollapsed, selectVisibleLayersGrouped, selectHasGroups, } from './selectors.js';

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.js';
+/**
+ * @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/selectors.d.ts

@@ -0,0 +1,64 @@
+import { LegendGroup, LegendLayer, LegendState } from './types.js';
+/**
+ * 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[];
+/**
+ * `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 declare function selectAllGroupsCollapsed(state: LegendState): boolean;
+/**
+ * Whether the legend has groups — gates panel-level group actions.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function selectHasGroups(state: LegendState): boolean;
+/**
+ * Visible layers grouped for the enabled-layers menu.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function selectVisibleLayersGrouped(state: LegendState): {
+    group?: LegendGroup;
+    layers: LegendLayer[];
+}[];
+/**
+ * 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 declare function selectLayerCollapsible(state: LegendState, layerId: string): boolean;
+/**
+ * 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;