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

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

@@ -0,0 +1,10 @@
+import { LegendIconVariable } from '../../stores/index.js';
+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.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.js';
+import { LegendVariable } from '../../stores/index.js';
+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.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.Element | null;

package/dist/types/{widgets/root/style.d.ts → legend/components/legend-item/styles.d.ts}

@@ -1,8 +1,7 @@
-import { Theme } from '@mui/material';
 export declare const styles: {
-    root: {
+    stack: {
         display: "flex";
         flexDirection: "column";
-        gap: (theme: Theme) => string;
+        gap: number;
     };
 };

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

@@ -0,0 +1,22 @@
+/**
+ * Opacity menu item — toggles the row's inline bar; self-hides when hidden or no `opacityControl`.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+declare function OpacityItem(): import('react').JSX.Element | null;
+/**
+ * Inline opacity bar (first body child of `Legend.Row`). Slider commits on release; input commits live.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+declare function OpacityInline(): import('react').JSX.Element | null;
+/**
+ * Compound opacity control: `Item` in the row menu, `Inline` in the body.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare const LegendOpacity: {
+    Item: typeof OpacityItem;
+    Inline: typeof OpacityInline;
+};
+export {};

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

@@ -0,0 +1,28 @@
+export declare const styles: {
+    inline: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+        borderRadius: number;
+    };
+    inlineHeader: {
+        display: "flex";
+        alignItems: "center";
+        justifyContent: "space-between";
+    };
+    inlineControls: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+    };
+    slider: {
+        flex: number;
+    };
+    input: {
+        width: number;
+        flexShrink: number;
+        '& input': {
+            textAlign: "right";
+        };
+    };
+};

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

@@ -0,0 +1,12 @@
+import { ReactNode } from 'react';
+export interface LegendOverflowMenuProps {
+    /** Menu items; async items use `stopPropagation` + `runAsyncMenuAction`. */
+    children?: ReactNode;
+    /** When `false`, render nothing. Defaults to `true`. */
+    gate?: boolean;
+    /** `aria-label` for the ⋮ trigger. */
+    ariaLabel: string;
+    /** Extra `.active` pin (e.g. inline opacity bar open). */
+    active?: boolean;
+}
+export declare function LegendOverflowMenu({ children, gate, ariaLabel, active, }: LegendOverflowMenuProps): import('react').JSX.Element | null;

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

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+export interface LegendPanelMenuProps {
+    /** Menu items; async items use `stopPropagation` + `runAsyncMenuAction`. */
+    children?: ReactNode;
+}
+/**
+ * Overflow (⋮) menu for the panel header (no row/group context).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendPanelMenu({ children }: LegendPanelMenuProps): import('react').JSX.Element;

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

@@ -0,0 +1,16 @@
+import { LegendLabels } from '../../provider/labels.js';
+import { LegendProportionVariable } from '../../stores/index.js';
+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.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.js';
+import { LegendRampVariable } from '../../stores/index.js';
+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.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,16 @@
+import { ReactNode } from 'react';
+export interface LegendRowProps {
+    layerId: string;
+    /**
+     * `<Legend.Actions>` in the sticky header; body children + `helperText` footer.
+     * Place `<Legend.Opacity.Inline />` first in the body.
+     */
+    children?: ReactNode;
+}
+/**
+ * Store-connected layer row. Provides row context for actions; hidden layers
+ * force-collapse the body.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendRow({ layerId, children }: LegendRowProps): import('react').JSX.Element | null;

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

@@ -0,0 +1,149 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    row: {
+        display: "flex";
+        flexDirection: "column";
+        position: "relative";
+        '& + &': {
+            borderTop: string;
+            borderColor: "divider";
+        };
+        '& .PsLegend-rowFade > *': {
+            opacity: number;
+            transition: ({ transitions }: Theme) => string;
+            '@media (hover: hover)': {
+                opacity: number;
+            };
+            '&.active': {
+                opacity: number;
+            };
+        };
+        '@media (hover: hover)': {
+            '& .PsLegend-rowFade > *:not(.active)': {
+                width: number;
+                minWidth: number;
+                padding: number;
+                overflow: "hidden";
+                pointerEvents: "none";
+            };
+            '& .PsLegend-rowActions:not(:has(.active))': {
+                width: number;
+                minWidth: number;
+                overflow: "hidden";
+                marginInlineStart: ({ spacing }: Theme) => string;
+                pointerEvents: "none";
+            };
+        };
+        '&:hover .PsLegend-rowFade > *, &:focus-within .PsLegend-rowFade > *': {
+            opacity: number;
+            width: string;
+            minWidth: number;
+            padding: string;
+            overflow: "visible";
+            pointerEvents: "auto";
+        };
+        '&:hover .PsLegend-rowActions, &:focus-within .PsLegend-rowActions': {
+            width: string;
+            minWidth: number;
+            overflow: "visible";
+            marginInlineStart: number;
+            pointerEvents: "auto";
+        };
+        '&:hover .PsLegend-value, &:focus-within .PsLegend-value': {
+            opacity: number;
+        };
+        '& .PsLegend-dragHandle-layer > *': {
+            opacity: number;
+            transition: ({ transitions }: Theme) => string;
+            '@media (hover: none)': {
+                opacity: number;
+            };
+        };
+        '&:hover .PsLegend-dragHandle-layer > *, &:focus-within .PsLegend-dragHandle-layer > *': {
+            opacity: number;
+        };
+    };
+    rowDragging: {
+        opacity: number;
+    };
+    header: {
+        display: "flex";
+        alignItems: "flex-start";
+        gap: number;
+        minHeight: number;
+        padding: ({ spacing }: Theme) => string;
+        position: "sticky";
+        zIndex: number;
+        backgroundColor: "background.paper";
+    };
+    headerGrouped: {
+        paddingLeft: number;
+    };
+    titleBox: {
+        flex: number;
+        minWidth: number;
+        display: "flex";
+        flexDirection: "column";
+    };
+    titleBoxInteractive: {
+        cursor: "pointer";
+        userSelect: "none";
+        '&:focus-visible': {
+            outline: string;
+            outlineColor: "primary.main";
+            outlineOffset: number;
+        };
+    };
+    titleLine: {
+        minHeight: number;
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+    };
+    title: {
+        minWidth: number;
+        overflow: "hidden";
+        textOverflow: "ellipsis";
+        whiteSpace: "nowrap";
+    };
+    chevron: {
+        fontSize: number;
+        color: "text.secondary";
+        flexShrink: number;
+        transition: ({ transitions }: Theme) => string;
+        '@media (hover: none)': {
+            display: "none";
+        };
+    };
+    chevronCollapsed: {
+        transform: "rotate(-90deg)";
+    };
+    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;
+    };
+    contentGrouped: {
+        paddingLeft: number;
+    };
+    footer: {
+        padding: ({ spacing }: Theme) => string;
+    };
+    footerGrouped: {
+        paddingLeft: number;
+    };
+    dimmed: {
+        opacity: number;
+    };
+};

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

@@ -0,0 +1,12 @@
+/**
+ * Show only this layer (and hide siblings in the same bucket).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendShowOnlyLayer(): import('react').JSX.Element | null;
+/**
+ * Show all layers in the enclosing group, or all ungrouped layers at row scope.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendShowAllLayers(): import('react').JSX.Element | null;

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

@@ -0,0 +1,12 @@
+import { ReactNode } from 'react';
+export interface LegendRowMenuProps {
+    /** Menu items; async items use `stopPropagation` + `runAsyncMenuAction`. */
+    children?: ReactNode;
+}
+/**
+ * Overflow (⋮) menu for a layer row. Pins `.active` while open, busy, or the
+ * inline opacity bar is open. Items self-gate when hidden.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendRowMenu({ children }: LegendRowMenuProps): import('react').JSX.Element;

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

@@ -0,0 +1,10 @@
+export interface LegendZoomToProps {
+    /** Fit viewport to the layer; may return a Promise for async menu feedback. */
+    onZoomTo: (layerId: string) => void | Promise<void>;
+}
+/**
+ * Zoom-to-layer menu item for `Legend.RowMenu`. Self-hides when the layer is hidden.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendZoomTo({ onZoomTo }: LegendZoomToProps): import('react').JSX.Element | null;

package/dist/types/legend/components/legend-sortable/contexts.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Present (true) below a `<Legend.Sortable>` wrapper — `Legend.Group` /
+ * `Legend.Row` read it to become draggable (sortable shell + drag handle).
+ */
+export declare const LegendSortableContext: import('react').Context<boolean>;
+/** Whether the nearest legend composition is wrapped in `Legend.Sortable`. */
+export declare function useLegendSortable(): boolean;

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

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+export interface LegendSortableProps {
+    /** Panel content (`Legend.Group` / ungrouped `Legend.Row` children). */
+    children?: ReactNode;
+}
+/**
+ * Opt-in DnD reordering for legend groups and layers (within bucket only).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function LegendSortable({ children }: LegendSortableProps): import('react').JSX.Element;

package/dist/types/legend/components/legend-sortable/sortable-entity.d.ts

@@ -0,0 +1,27 @@
+import { CSSProperties, ReactElement, ReactNode } from 'react';
+import { SortableKind } from './sortable-ids.js';
+/** What `SortableEntity` hands to its render callback. */
+export interface SortableEntityRenderProps {
+    /** Attach to the entity's existing root element. */
+    rootRef: (el: HTMLElement | null) => void;
+    /** Sort transform/transition for the root (inline, per-frame values). */
+    rootStyle: CSSProperties;
+    /** The original is dimmed in place while its overlay clone is dragged. */
+    dragging: boolean;
+    /** The drag handle — absolutely positioned, place anywhere in the header. */
+    handle: ReactNode;
+}
+export interface SortableEntityProps {
+    kind: SortableKind;
+    id: string;
+    render: (sortable: SortableEntityRenderProps) => ReactElement;
+}
+/**
+ * Sortable shell for a legend group/row. Render-prop (instead of a wrapper
+ * element) so the entity keeps its own root — sibling CSS like the `& + &`
+ * dividers keeps working. Hosts `useSortable` and builds the drag handle
+ * (keyboard-activatable, labelled `labels.reorder`).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function SortableEntity({ kind, id, render }: SortableEntityProps): ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;

package/dist/types/legend/components/legend-sortable/sortable-ids.d.ts

@@ -0,0 +1,6 @@
+export type SortableKind = 'group' | 'layer';
+export declare const toSortableId: (kind: SortableKind, id: string) => string;
+export declare function parseSortableId(sortableId: string): {
+    kind: SortableKind;
+    id: string;
+} | null;

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

@@ -0,0 +1,55 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    handleSlot: {
+        position: "absolute";
+        zIndex: number;
+        display: "flex";
+        alignItems: "center";
+        justifyContent: "center";
+        left: number;
+        top: number;
+    };
+    handleSlotLayer: {
+        height: number;
+    };
+    handleSlotGroup: {
+        height: number;
+    };
+    handle: {
+        padding: string;
+        cursor: "grab";
+        touchAction: "none";
+        color: "text.secondary";
+        '& .MuiSvgIcon-root': {
+            fontSize: number;
+        };
+        '&:active': {
+            cursor: "grabbing";
+        };
+        '&:hover': {
+            backgroundColor: "transparent";
+        };
+    };
+    overlay: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+        padding: ({ spacing }: Theme) => string;
+        backgroundColor: "background.paper";
+        borderRadius: number;
+        boxShadow: number;
+        height: string;
+        maxWidth: string;
+        overflow: "hidden";
+    };
+    overlayIcon: {
+        display: "flex";
+        color: "text.secondary";
+    };
+    overlayLabel: {
+        minWidth: number;
+        overflow: "hidden";
+        textOverflow: "ellipsis";
+        whiteSpace: "nowrap";
+    };
+};

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

@@ -0,0 +1,26 @@
+import { LegendFillPattern, LegendStrokeStyle, LegendSwatchShape } from '../../stores/index.js';
+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.Element;