@carto/ps-react-ui 4.12.2 → 4.14.0

package/dist/types/legend/components/legend-config-select/legend-config-select.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The layer configuration select — resolves its layer from the enclosing
+ * `Legend.Row` context. The closed field shows the **first section's** active
+ * option; the menu lists every section under its title (omitted when the
+ * layer has a single section) and each section highlights its own active
+ * option. Picking an option writes `setSectionValue` and closes the menu.
+ * Renders nothing when the layer declares no sections (or outside a row).
+ *
+ * A native single-value `Select` can't represent one active per section,
+ * hence the outlined-trigger + `Menu` composition.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendConfigSelect(): import("react/jsx-runtime").JSX.Element | null;

package/dist/types/legend/components/legend-config-select/styles.d.ts

@@ -0,0 +1,44 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    trigger: {
+        width: string;
+        minHeight: number;
+        display: "flex";
+        alignItems: "center";
+        justifyContent: "space-between";
+        gap: number;
+        padding: ({ spacing }: Theme) => string;
+        border: "1px solid";
+        borderColor: "divider";
+        borderRadius: number;
+        backgroundColor: "background.paper";
+        color: "text.primary";
+        '&:hover': {
+            borderColor: "text.primary";
+        };
+    };
+    value: {
+        minWidth: number;
+        overflow: "hidden";
+        textOverflow: "ellipsis";
+        whiteSpace: "nowrap";
+    };
+    chevron: {
+        flexShrink: number;
+        color: "action.active";
+        transition: ({ transitions }: Theme) => string;
+    };
+    chevronOpen: {
+        transform: "rotate(180deg)";
+    };
+    sectionTitle: {
+        padding: ({ spacing }: Theme) => string;
+        lineHeight: number;
+    };
+    option: {
+        '&.Mui-selected, &.Mui-selected:hover': {
+            backgroundColor: "transparent";
+            color: "primary.main";
+        };
+    };
+};

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

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react';
+export interface LegendGroupProps {
+    groupId: string;
+    /**
+     * Composition slots: `<Legend.Actions>` children render in the sticky
+     * header (hover-fade); everything else is the collapsible body — the
+     * consumer renders the member `<Legend.Row>`s explicitly (use
+     * `selectLayersByGroup` to resolve them).
+     */
+    children?: ReactNode;
+}
+/**
+ * Store-connected group wrapper (widgets-v2 `Wrapper` parity). Renders the
+ * sticky 48px header — group icon + label from the store, the partitioned
+ * `<Legend.Actions>` slot, and the collapse chevron — over the collapsible
+ * body. Provides the group composition context so `Legend.VisibilityToggle`
+ * placed in the header becomes the tri-state group eye.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendGroup({ groupId, children }: LegendGroupProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,63 @@
+import { Theme } from '@mui/material';
+/**
+ * Design height of the group header (Figma "Group layers header", 48px).
+ * Grouped layer-row headers use it as their sticky `top` offset so they pin
+ * just below their group's header while the panel scrolls.
+ */
+export declare const LEGEND_GROUP_HEADER_HEIGHT = 48;
+export declare const styles: {
+    group: {
+        display: "flex";
+        flexDirection: "column";
+        '& + &': {
+            borderTop: string;
+            borderColor: "divider";
+        };
+        '& .PsLegend-groupFade > *': {
+            opacity: number;
+            transition: ({ transitions }: Theme) => string;
+            '@media (hover: hover)': {
+                opacity: number;
+            };
+            '&.active': {
+                opacity: number;
+            };
+        };
+        '&:hover .PsLegend-groupFade > *, &:focus-within .PsLegend-groupFade > *': {
+            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.paper";
+    };
+    groupIcon: {
+        display: "flex";
+        color: "text.secondary";
+    };
+    label: {
+        flex: number;
+        minWidth: number;
+        overflow: "hidden";
+        textOverflow: "ellipsis";
+        whiteSpace: "nowrap";
+    };
+    actions: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+        flexShrink: number;
+        '& .MuiIconButton-root': {
+            padding: string;
+        };
+    };
+};

package/dist/types/legend/components/legend-icon/legend-icon-ui.d.ts

@@ -0,0 +1,10 @@
+import { LegendIconVariable } from '../../stores';
+export interface LegendIconUIProps {
+    data: LegendIconVariable;
+}
+/**
+ * Icon legend — a list of icon images with labels (and optional values).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendIconUI({ data }: LegendIconUIProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,52 @@
+export declare const styles: {
+    list: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+        '&:hover .PsLegend-value, &:focus-within .PsLegend-value': {
+            opacity: number;
+        };
+        '@media (hover: none)': {
+            '& .PsLegend-value': {
+                opacity: number;
+            };
+        };
+    };
+    item: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+    };
+    icon: {
+        flexShrink: number;
+        width: number;
+        height: number;
+        objectFit: "contain";
+    };
+    label: {
+        flex: number;
+        minWidth: number;
+        overflow: "hidden";
+        textOverflow: "ellipsis";
+        whiteSpace: "nowrap";
+    };
+    value: {
+        flexShrink: number;
+        opacity: number;
+        transition: "opacity 120ms";
+    };
+    listHorizontal: {
+        flexDirection: "row";
+        flexWrap: "wrap";
+        columnGap: number;
+        rowGap: number;
+    };
+    itemHorizontal: {
+        gap: number;
+    };
+    labelHorizontal: {
+        flex: string;
+        overflow: "visible";
+        textOverflow: "clip";
+    };
+};

package/dist/types/legend/components/legend-item/legend-item-ui.d.ts

@@ -0,0 +1,14 @@
+import { LegendLabels } from '../../provider/labels';
+import { LegendVariable } from '../../stores';
+export interface LegendItemUIProps {
+    data: LegendVariable;
+    /** Forwarded to the renderers that show text (ramp header, proportion labels). */
+    labels?: Pick<LegendLabels, 'colorBasedOn' | 'colorGradient' | 'radiusRangeBy' | 'maxPrefix' | 'minPrefix'>;
+}
+/**
+ * Dispatches to the matching pure renderer based on the discriminated
+ * `variables.type`. Adding a new legend type is localized to this switch.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendItemUI({ data, labels }: LegendItemUIProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,10 @@
+/**
+ * Store-connected item renderer — reads the layer's `variables` from the
+ * enclosing `Legend.Row` context (plus the Provider's labels) and stacks one
+ * pure renderer per variable, top-to-bottom with the design's 16px section
+ * gap. Use `Legend.ItemUI` directly for store-free, single-variable
+ * composition.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendItem(): import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,7 @@
+export declare const styles: {
+    stack: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+    };
+};

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

@@ -0,0 +1,32 @@
+/**
+ * Opacity header action for a layer row: a checkerboard icon button, pinned
+ * `.active` in the hover-fade group while opacity ≠ 1 or the popover is open,
+ * disabled while the layer is hidden. Opens `Legend.Opacity.Popover` through
+ * the row context. Place it inside `<Legend.Actions>` of a `Legend.Row`.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+declare function OpacityTrigger(): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * The opacity editing surface — a popover **anchored to the row's sticky
+ * header, spanning its full width**, holding a slider (writes `setOpacity`
+ * only on release, widgets-v2 parity) and a percent input (commits live as
+ * soon as the draft parses, clamped 0–100; never ellipsizes "100 %").
+ * Declare it anywhere inside the `Legend.Row` (it renders in a portal);
+ * open it with `Legend.Opacity.Trigger`.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+declare function OpacityPopover(): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * Compound opacity control for layer rows (widgets-v2 `FullScreen` parity):
+ * `Trigger` lives in the header `<Legend.Actions>`, `Popover` anywhere in the
+ * row body — they share state through the row context.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare const LegendOpacity: {
+    Trigger: typeof OpacityTrigger;
+    Popover: typeof OpacityPopover;
+};
+export {};

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

@@ -0,0 +1,23 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    triggerWrap: {
+        display: "inline-flex";
+    };
+    popover: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+        padding: ({ spacing }: Theme) => string;
+        width: number;
+    };
+    slider: {
+        flex: number;
+    };
+    input: {
+        width: number;
+        flexShrink: number;
+        '& input': {
+            textAlign: "right";
+        };
+    };
+};

package/dist/types/legend/components/legend-proportion/legend-proportion-ui.d.ts

@@ -0,0 +1,16 @@
+import { LegendLabels } from '../../provider/labels';
+import { LegendProportionVariable } from '../../stores';
+export interface LegendProportionUIProps {
+    data: LegendProportionVariable;
+    /** Override the renderer's user-facing strings. */
+    labels?: Pick<LegendLabels, 'radiusRangeBy' | 'maxPrefix' | 'minPrefix'>;
+}
+/**
+ * Proportional-symbol legend — a stack of decorative nested circles with the
+ * value breaks labelled beside them (largest = MAX, smallest = MIN). Circle
+ * sizes are fixed/decorative, not value-derived, so the legend stays readable
+ * across very wide ranges.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendProportionUI({ data, labels, }: LegendProportionUIProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,37 @@
+export declare const styles: {
+    root: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+    };
+    attribute: {
+        display: "flex";
+        flexDirection: "column";
+    };
+    body: {
+        display: "flex";
+        alignItems: "flex-end";
+        gap: number;
+        paddingTop: number;
+    };
+    circles: {
+        position: "relative";
+        flexShrink: number;
+    };
+    circle: {
+        position: "absolute";
+        right: number;
+        bottom: number;
+        borderRadius: string;
+        backgroundColor: "grey.50";
+        border: "1px solid";
+        borderColor: "grey.100";
+        boxSizing: "border-box";
+    };
+    labels: {
+        flex: number;
+        display: "flex";
+        flexDirection: "column";
+        justifyContent: "space-between";
+    };
+};

package/dist/types/legend/components/legend-ramp/legend-ramp-ui.d.ts

@@ -0,0 +1,20 @@
+import { LegendLabels } from '../../provider/labels';
+import { LegendRampVariable } from '../../stores';
+export interface LegendRampUIProps {
+    data: LegendRampVariable;
+    /** Override the renderer's user-facing strings. */
+    labels?: Pick<LegendLabels, 'colorBasedOn' | 'colorGradient'>;
+}
+/**
+ * Color-ramp legend. `colors` and `stops` are both ordered low→high and are
+ * never reversed, so step colors and their labels stay aligned.
+ *
+ * Continuous mode renders a gradient with the endpoint labels. Discrete mode
+ * **requires `stops.length === colors.length + 1`** — stops are the boundaries
+ * between color steps (including both outer edges) and each label is centered
+ * on its boundary line. A discrete ramp with any other stop count is an
+ * incoherent state and renders a compact inline error instead of the bar.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendRampUI({ data, labels, }: LegendRampUIProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,53 @@
+export declare const styles: {
+    container: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+    };
+    attribute: {
+        display: "flex";
+        flexDirection: "column";
+    };
+    error: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+        color: "error.main";
+    };
+    barWrap: {
+        position: "relative";
+    };
+    bar: {
+        height: number;
+        borderRadius: string;
+        overflow: "hidden";
+        display: "flex";
+    };
+    avgLine: {
+        position: "absolute";
+        top: number;
+        bottom: number;
+        width: number;
+        borderLeft: string;
+        borderColor: "text.primary";
+        transform: "translateX(-50%)";
+    };
+    step: {
+        flex: number;
+        height: string;
+    };
+    labels: {
+        display: "flex";
+        justifyContent: "space-between";
+        gap: number;
+    };
+    boundaryLabels: {
+        position: "relative";
+        height: number;
+    };
+    boundaryLabel: {
+        position: "absolute";
+        top: number;
+        whiteSpace: "nowrap";
+    };
+};

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

@@ -0,0 +1,23 @@
+import { ReactNode } from 'react';
+export interface LegendRowProps {
+    layerId: string;
+    /**
+     * Composition slots: `<Legend.Actions>` children render in the sticky
+     * header next to the collapse chevron (hover-fade); everything else renders
+     * in the collapsible body, followed by the layer's `helperText` footer.
+     */
+    children?: ReactNode;
+}
+/**
+ * Store-connected layer-row wrapper (widgets-v2 `Wrapper` parity). Renders
+ * the sticky header — title + subtitle from the store with a smart-truncating
+ * tooltip, the partitioned `<Legend.Actions>` slot, and the collapse chevron —
+ * over the collapsible body. Provides the row composition context so actions
+ * (`Legend.VisibilityToggle`, `Legend.Opacity.*`, `Legend.RowMenu`,
+ * `Legend.ConfigSelect`, `Legend.Item`) resolve the layer without props.
+ * When the layer is hidden the body is force-collapsed, the content dims,
+ * and the chevron is disabled.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendRow({ layerId, children }: LegendRowProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,77 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    row: {
+        display: "flex";
+        flexDirection: "column";
+        '& + &': {
+            borderTop: string;
+            borderColor: "divider";
+        };
+        '& .PsLegend-rowFade > *': {
+            opacity: number;
+            transition: ({ transitions }: Theme) => string;
+            '@media (hover: hover)': {
+                opacity: number;
+            };
+            '&.active': {
+                opacity: number;
+            };
+        };
+        '&:hover .PsLegend-rowFade > *, &:focus-within .PsLegend-rowFade > *': {
+            opacity: number;
+        };
+        '&:hover .PsLegend-value, &:focus-within .PsLegend-value': {
+            opacity: number;
+        };
+    };
+    header: {
+        display: "flex";
+        alignItems: "flex-start";
+        gap: number;
+        minHeight: number;
+        padding: ({ spacing }: Theme) => string;
+        position: "sticky";
+        zIndex: number;
+        backgroundColor: "background.paper";
+    };
+    titleBox: {
+        flex: number;
+        minWidth: number;
+        display: "flex";
+        flexDirection: "column";
+    };
+    titleLine: {
+        minHeight: number;
+        display: "flex";
+        alignItems: "center";
+    };
+    title: {
+        flex: number;
+        minWidth: number;
+        overflow: "hidden";
+        textOverflow: "ellipsis";
+        whiteSpace: "nowrap";
+    };
+    actions: {
+        minHeight: number;
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+        flexShrink: number;
+        '& .MuiIconButton-root': {
+            padding: string;
+        };
+    };
+    content: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+        padding: ({ spacing }: Theme) => string;
+    };
+    footer: {
+        padding: ({ spacing }: Theme) => string;
+    };
+    dimmed: {
+        opacity: number;
+    };
+};

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

@@ -0,0 +1,18 @@
+import { ReactNode } from 'react';
+export interface LegendRowMenuProps {
+    /**
+     * The menu items — composed by the consumer (e.g. `<Legend.ZoomTo>` or any
+     * MUI `MenuItem`). A click on any item bubbles to the menu and closes it;
+     * an item that must keep the menu open should `event.stopPropagation()`.
+     */
+    children?: ReactNode;
+}
+/**
+ * Agnostic overflow (⋮) menu shell for a layer row — the items are passed as
+ * children, like `Legend.Actions`. Renders nothing without children, outside
+ * a row, or while the layer is hidden (a hidden row keeps only its
+ * visibility eye + collapse chevron).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendRowMenu({ children }: LegendRowMenuProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/types/legend/components/legend-row-menu/legend-zoom-to.d.ts

@@ -0,0 +1,15 @@
+export interface LegendZoomToProps {
+    /**
+     * Fit the map viewport to the layer. The handler lives at the composition
+     * site (not the Provider) — each menu can wire its own behavior.
+     */
+    onZoomTo: (layerId: string) => void;
+}
+/**
+ * "Zoom to" menu item for `Legend.RowMenu` — resolves its layer from the
+ * enclosing `Legend.Row` context and calls the `onZoomTo` it was composed
+ * with. The click bubbles to the menu, which closes itself.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendZoomTo({ onZoomTo }: LegendZoomToProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,26 @@
+import { LegendFillPattern, LegendStrokeStyle, LegendSwatchShape } from '../../stores';
+export interface LegendSwatchProps {
+    /** Shape to render. Default `'circle'`. */
+    shape?: LegendSwatchShape;
+    /** CSS color string (hex / rgb / named). */
+    color: string;
+    /** Paint the outline/border instead of the fill (square/circle only). */
+    isStrokeColor?: boolean;
+    /** Fill pattern when filled. Default `'solid'`. */
+    fillPattern?: LegendFillPattern;
+    /** Border style (stroked square/circle) or line style (`shape: 'line'`). Default `'solid'`. */
+    strokeStyle?: LegendStrokeStyle;
+    /** Primary dimension in px (square side / circle diameter / line length). Default 12. */
+    size?: number;
+}
+/** Default swatch dimension in px — shared with the category renderer. */
+export declare const DEFAULT_SWATCH_SIZE = 12;
+/**
+ * A single legend swatch rendered as inline SVG: a square, circle, or line,
+ * painted as a solid/patterned fill or a styled outline. Pure and theme-free —
+ * `color` is a raw CSS color. Decorative (`aria-hidden`); the adjacent label
+ * carries the accessible text.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendSwatch({ shape, color, isStrokeColor, fillPattern, strokeStyle, size, }: LegendSwatchProps): import("react/jsx-runtime").JSX.Element;

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;