@carto/ps-react-ui 4.2.7 → 4.3.0

package/dist/types/widgets/table/hooks/use-pagination.d.ts

@@ -0,0 +1,33 @@
+import { TableRow } from '../types';
+export interface UsePaginationResult<T> {
+    /** Whether pagination is enabled */
+    paginationEnabled: boolean;
+    /** Current page (0-indexed) */
+    page: number;
+    /** Rows per page */
+    rowsPerPage: number;
+    /** Total row count */
+    total: number;
+    /** Available rows per page options */
+    rowsPerPageOptions: number[];
+    /** Paginated data (for local mode) */
+    paginatedData: T[];
+    /** Set current page */
+    setPage: (page: number) => void;
+    /** Set rows per page */
+    setRowsPerPage: (rowsPerPage: number) => void;
+    /** Go to first page */
+    goToFirstPage: () => void;
+    /** Go to last page */
+    goToLastPage: () => void;
+    /** Go to next page */
+    goToNextPage: () => void;
+    /** Go to previous page */
+    goToPreviousPage: () => void;
+}
+/**
+ * Hook for managing table pagination
+ * Supports both local (client-side) and remote (server-side) pagination
+ * State is persisted in the widget store for the given widgetId
+ */
+export declare function usePagination<T extends TableRow>(widgetId: string, data: T[]): UsePaginationResult<T>;

package/dist/types/widgets/table/hooks/use-pagination.test.d.ts

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

package/dist/types/widgets/table/hooks/use-selection.d.ts

@@ -0,0 +1,30 @@
+import { TableRow } from '../types';
+export interface UseSelectionOptions {
+    /** Callback when selection changes */
+    onSelectionChange?: (selectedIds: (string | number)[]) => void;
+}
+export interface UseSelectionResult {
+    /** Array of selected row IDs */
+    selectedIds: (string | number)[];
+    /** Check if a row is selected */
+    isSelected: (id: string | number) => boolean;
+    /** Check if all provided rows are selected */
+    isAllSelected: (rows: TableRow[]) => boolean;
+    /** Check if some but not all rows are selected (for indeterminate state) */
+    isIndeterminate: (rows: TableRow[]) => boolean;
+    /** Toggle selection of a single row */
+    toggleRow: (id: string | number) => void;
+    /** Toggle selection of all provided rows */
+    toggleAll: (rows: TableRow[]) => void;
+    /** Select specific rows */
+    selectRows: (ids: (string | number)[]) => void;
+    /** Deselect specific rows */
+    deselectRows: (ids: (string | number)[]) => void;
+    /** Clear all selections */
+    clearSelection: () => void;
+}
+/**
+ * Hook for managing table row selection
+ * Selection persists across pagination and is stored in the widget store
+ */
+export declare function useSelection(widgetId: string, options?: UseSelectionOptions): UseSelectionResult;

package/dist/types/widgets/table/hooks/use-selection.test.d.ts

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

package/dist/types/widgets/table/hooks/use-sort.d.ts

@@ -0,0 +1,22 @@
+import { TableRow, SortDirection, SortState } from '../types';
+export interface UseSortResult<T> extends SortState {
+    /** Whether sorting is enabled */
+    sortEnabled: boolean;
+    /** Current sort state */
+    columnId: string | null;
+    direction: SortDirection;
+    /** Sorted data (for local mode) */
+    sortedData: T[];
+    /** Toggle sort on a column */
+    toggleSort: (columnId: string) => void;
+    /** Set sort state directly */
+    setSort: (columnId: string | null, direction: SortDirection) => void;
+    /** Clear sort */
+    clearSort: () => void;
+}
+/**
+ * Hook for managing table sorting
+ * Supports both local (client-side) and remote (server-side) sorting
+ * State is persisted in the widget store for the given widgetId
+ */
+export declare function useSort<T extends TableRow>(widgetId: string, data: T[]): UseSortResult<T>;

package/dist/types/widgets/table/hooks/use-sort.test.d.ts

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

package/dist/types/widgets/table/index.d.ts

@@ -0,0 +1,13 @@
+export { CellHeader } from './components/cell-header';
+export { Row } from './components/row';
+export { Pagination } from './components/pagination';
+export { PaginationActions } from './components/pagination-actions';
+export { Table } from './table-ui';
+export { usePagination, useSort, useSelection } from './hooks';
+export { tableConfig, tableDownloadConfig } from './config';
+export { TableSkeleton } from './skeleton';
+export { sanitizeTableRow, sanitizeTableData } from './serializer';
+export { getCellValue, compareValues, sortData, paginateData } from './helpers';
+export { styles as tableStyles } from './style';
+export type { TableUIProps, TableColumn, TableRow, TableWidgetData, TablePaginationState, SortDirection, SortState, Mode, TableWidgetConfig, TableWidgetState, TableDownloadConfig, TableProps, CellHeaderProps, RowProps, PaginationProps, PaginationActionsProps, } from './types';
+export type { UsePaginationResult, UseSortResult, UseSelectionOptions, UseSelectionResult, } from './hooks';

package/dist/types/widgets/table/serializer.d.ts

@@ -0,0 +1,16 @@
+import { TableRow, TableWidgetData } from './types';
+/**
+ * Sanitizes a table row by ensuring all values are serializable.
+ * Converts ReactNode and function values to undefined.
+ *
+ * @param row - The table row to sanitize
+ * @returns A sanitized table row
+ */
+export declare function sanitizeTableRow(row: TableRow): TableRow;
+/**
+ * Sanitizes table widget data by ensuring all rows are serializable.
+ *
+ * @param data - The table data to sanitize
+ * @returns Sanitized table data
+ */
+export declare function sanitizeTableData(data: TableWidgetData | undefined): TableWidgetData | undefined;

package/dist/types/widgets/table/skeleton.d.ts

@@ -0,0 +1,10 @@
+export interface TableSkeletonProps {
+    /** Number of columns to display */
+    columns?: number;
+    /** Number of rows to display */
+    rows?: number;
+}
+/**
+ * Table skeleton loader component
+ */
+export declare function TableSkeleton({ columns, rows }: TableSkeletonProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/table/style.d.ts

@@ -0,0 +1,33 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    container: {
+        width: string;
+        overflow: "auto";
+    };
+    table: {
+        minWidth: number;
+    };
+    headerCell: {
+        fontWeight: number;
+        backgroundColor: (theme: Theme) => string;
+    };
+    row: {
+        '&:last-child td, &:last-child th': {
+            border: number;
+        };
+    };
+    rowHover: {
+        '&:hover': {
+            backgroundColor: (theme: Theme) => string;
+        };
+    };
+    rowSelected: {
+        backgroundColor: (theme: Theme) => string;
+        '&:hover': {
+            backgroundColor: (theme: Theme) => string;
+        };
+    };
+    pagination: {
+        borderTop: (theme: Theme) => string;
+    };
+};

package/dist/types/widgets/table/table-ui.d.ts

@@ -0,0 +1,32 @@
+import { TableCell, TableProps as MuiTableProps } from '@mui/material';
+import { Ref } from 'react';
+import { TableUIProps } from './types';
+/**
+ * Props for the base Table component
+ */
+export interface TableComponentProps extends MuiTableProps {
+    /** Table element ref */
+    ref?: Ref<HTMLTableElement>;
+}
+/**
+ * Base Table component with compound component pattern
+ * Provides Table.Head, Table.Body, Table.Row, Table.Cell, Table.CellHeader, Table.Pagination
+ */
+declare function Table({ children, ref, stickyHeader, ...props }: TableComponentProps): import("react/jsx-runtime").JSX.Element;
+declare namespace Table {
+    var Head: import("node_modules/@mui/material/OverridableComponent").OverridableComponent<import("node_modules/@mui/material").TableHeadTypeMap<{}, "thead">>;
+    var CellHeader: typeof import(".").CellHeader;
+    var Body: import("node_modules/@mui/material/OverridableComponent").OverridableComponent<import("node_modules/@mui/material").TableBodyTypeMap<{}, "tbody">>;
+    var Row: typeof import(".").Row;
+    var Cell: typeof TableCell;
+    var Container: typeof TableContainer;
+    var Paper: import("node_modules/@mui/material/OverridableComponent").OverridableComponent<import("node_modules/@mui/material").PaperTypeMap<{}, "div">>;
+    var Pagination: typeof import(".").Pagination;
+    var PaginationActions: typeof import(".").PaginationActions;
+}
+export { Table };
+/**
+ * TableContainer widget component
+ * Integrates with widget store and provides ref registration using custom hook
+ */
+declare function TableContainer(props: TableUIProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/table/types.d.ts

@@ -0,0 +1,196 @@
+import { ReactNode, Ref } from 'react';
+import { TableProps as MuiTableProps } from '@mui/material';
+import { BaseWidgetState, WidgetsStoreProps } from '../stores/types';
+import { WrapperState } from '../wrapper/types';
+import { DownloadItem } from '../actions/download/types';
+/**
+ * Table UI component props
+ */
+export interface TableUIProps {
+    id: WidgetsStoreProps['id'];
+    children?: ReactNode;
+}
+/**
+ * Table column definition
+ */
+export interface TableColumn {
+    /** Unique column identifier, matches key in row data */
+    id: string;
+    /** Column header label */
+    label: string | ReactNode;
+    /** Text alignment */
+    align?: 'left' | 'center' | 'right';
+    /** Column width (number for px, string for CSS value) */
+    width?: number | string;
+    /** Enable sorting for this column */
+    sortable?: boolean;
+    /** Custom cell value formatter */
+    formatter?: (value: unknown) => ReactNode;
+}
+/**
+ * Table row data - extends Record for flexible data
+ */
+export interface TableRow extends Record<string, unknown> {
+    /** Unique row identifier */
+    id: string | number;
+}
+/**
+ * Table widget data type - array of row records
+ */
+export type TableWidgetData = TableRow[];
+/**
+ * Pagination state
+ */
+export interface TablePaginationState {
+    /** Current page (0-indexed) */
+    page: number;
+    /** Rows per page */
+    rowsPerPage: number;
+    /** Total number of rows (for remote pagination) */
+    total: number;
+}
+/**
+ * Sort direction
+ */
+export type SortDirection = 'asc' | 'desc';
+/**
+ * Sort state for single-column sorting
+ */
+export interface SortState {
+    /** Column ID being sorted */
+    columnId: string | null;
+    /** Sort direction */
+    direction: SortDirection;
+}
+/**
+ * Pagination and sort mode
+ */
+export type Mode = 'local' | 'remote';
+/**
+ * Table widget configuration
+ */
+export interface TableWidgetConfig {
+    /** Column definitions */
+    columns?: TableColumn[];
+    /** Enable row selection with checkboxes */
+    selectable?: boolean;
+    /** Currently selected row IDs */
+    selected: (string | number)[];
+    /** Pagination and sort mode: local (client-side) or remote (server-side) */
+    mode: Mode;
+    /** Pagination configuration */
+    pagination?: {
+        /** Current page (0-indexed) */
+        page?: number;
+        /** Available rows per page options */
+        rowsPerPageOptions?: number[];
+        /** Default rows per page */
+        rowsPerPage?: number;
+        /** Total rows for remote pagination */
+        total?: number;
+    };
+    /** Sort configuration */
+    sort?: {
+        /** Default sort column */
+        columnId: string | null;
+        /** Default sort direction */
+        direction?: SortDirection;
+    };
+    /** Callback when a row is clicked */
+    onRowClick?: (row: TableRow) => void;
+    /** Callback when hovering over a row (null when leaving table) */
+    onRowHover?: (row: TableRow | null) => void;
+    /** Callback when selection changes */
+    onSelectionChange?: (selected: (string | number)[]) => void;
+    /** Callback when page changes (for remote pagination) */
+    onPageChange?: (page: number, rowsPerPage: number) => void;
+    /** Callback when sort changes (for remote sorting) */
+    onSortChange?: (columnId: string, direction: SortDirection) => void;
+}
+/**
+ * Table widget state - includes both configuration and runtime state
+ */
+export type TableWidgetState = BaseWidgetState<WrapperState<TableWidgetConfig & {}> & {
+    data: TableWidgetData;
+}>;
+/**
+ * Table download configuration
+ */
+export type TableDownloadConfig = DownloadItem<TableWidgetData>[];
+/**
+ * Props for the base Table component
+ */
+export interface TableProps extends MuiTableProps {
+    /** Table element ref */
+    ref?: Ref<HTMLTableElement>;
+}
+/**
+ * Props for CellHeader component
+ */
+export interface CellHeaderProps {
+    /** Column definition */
+    column: TableColumn;
+    /** Current sort state */
+    sortState?: SortState;
+    /** Callback when sort is triggered */
+    onSort?: (columnId: string) => void;
+    /** Whether this is a select-all checkbox header */
+    isSelectAll?: boolean;
+    /** Whether all rows are selected */
+    isAllSelected?: boolean;
+    /** Whether some rows are selected (indeterminate state) */
+    isIndeterminate?: boolean;
+    /** Callback for select-all toggle */
+    onSelectAll?: () => void;
+}
+/**
+ * Props for Row component
+ */
+export interface RowProps {
+    /** Row data */
+    row: TableRow;
+    /** Column definitions */
+    columns: TableColumn[];
+    /** Whether row is selected */
+    isSelected?: boolean;
+    /** Whether selection is enabled */
+    selectable?: boolean;
+    /** Callback when row is clicked */
+    onClick?: (row: TableRow) => void;
+    /** Callback when row selection is toggled */
+    onSelect?: (row: TableRow) => void;
+    /** Callback when mouse enters row */
+    onMouseEnter?: (row: TableRow) => void;
+    /** Callback when mouse leaves row */
+    onMouseLeave?: () => void;
+}
+/**
+ * Props for Pagination component
+ */
+export interface PaginationProps {
+    /** Current page (0-indexed) */
+    page: number;
+    /** Rows per page */
+    rowsPerPage: number;
+    /** Total row count */
+    total: number;
+    /** Available rows per page options */
+    rowsPerPageOptions?: number[];
+    /** Callback when page changes */
+    onPageChange: (page: number) => void;
+    /** Callback when rows per page changes */
+    onRowsPerPageChange: (rowsPerPage: number) => void;
+}
+/**
+ * Props for PaginationActions component
+ */
+export interface PaginationActionsProps {
+    /** Current page (0-indexed) */
+    page: number;
+    /** Total row count */
+    count: number;
+    /** Rows per page */
+    rowsPerPage: number;
+    /** Callback when page changes */
+    onPageChange: (event: React.MouseEvent<HTMLButtonElement> | null, newPage: number) => void;
+}

package/dist/types/widgets/timeseries/config.d.ts

@@ -0,0 +1,5 @@
+import { TimeseriesConfig, TimeseriesWidgetConfig, TimeseriesWidgetData } from './types';
+import { DownloadItem } from '../actions';
+import { ConfigProps } from '../loader/types';
+export declare function timeseriesDownloadConfig({ refUI, }: ConfigProps): DownloadItem<TimeseriesWidgetData>[];
+export declare function timeseriesConfig(props: TimeseriesConfig): TimeseriesWidgetConfig;

package/dist/types/widgets/timeseries/index.d.ts

@@ -0,0 +1,3 @@
+export type { TimeseriesWidgetData, TimeseriesWidgetState, TimeseriesWidgetConfig, TimeseriesConfig, } from './types';
+export { timeseriesConfig, timeseriesDownloadConfig } from './config';
+export { TimeseriesSkeleton } from './skeleton';

package/dist/types/widgets/timeseries/skeleton.d.ts

@@ -0,0 +1 @@
+export declare function TimeseriesSkeleton(): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/timeseries/style.d.ts

@@ -0,0 +1,38 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    skeleton: {
+        graph: {
+            container: {
+                position: "relative";
+                display: "flex";
+                alignItems: "center";
+                justifyContent: "space-between";
+                flexDirection: "column";
+                gap: ({ spacing }: Theme) => string;
+                height: ({ spacing }: Theme) => string;
+            };
+            grid: {
+                display: "flex";
+                justifyContent: "space-between";
+                flex: "1 1 auto";
+                alignItems: "flex-end";
+                width: "100%";
+            };
+        };
+        histogram: {
+            item: {
+                flex: number;
+                maxWidth: ({ spacing }: Theme) => string;
+                '& + &': {
+                    marginLeft: string;
+                };
+            };
+        };
+        legend: {
+            display: "flex";
+            alignItems: "center";
+            gap: ({ spacing }: Theme) => string;
+            height: ({ spacing }: Theme) => string;
+        };
+    };
+};

package/dist/types/widgets/timeseries/types.d.ts

@@ -0,0 +1,9 @@
+import { EchartWidgetData, EchartWidgetState } from '../echart';
+import { EchartWidgetOptionProps, EchartWidgetProps } from '../echart/types';
+import { ConfigProps } from '../loader';
+export type TimeseriesWidgetData = EchartWidgetData;
+export type TimeseriesWidgetState = EchartWidgetState;
+export type TimeseriesWidgetConfig = EchartWidgetProps & {
+    type: 'timeseries';
+};
+export type TimeseriesConfig = ConfigProps & EchartWidgetOptionProps<TimeseriesWidgetData>;

package/dist/types/widgets/toolbar-actions/index.d.ts

@@ -0,0 +1,2 @@
+export type { ToolbarAction, ToolbarActionsLabels, ToolbarActionsProps, } from './types';
+export { ToolbarActions } from './toolbar-actions';

package/dist/types/widgets/toolbar-actions/styles.d.ts

@@ -0,0 +1,37 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    root: {
+        display: "flex";
+        alignItems: "center";
+        width: string;
+        overflow: "hidden";
+        borderRadius: ({ spacing }: Theme) => string;
+        gap: ({ spacing }: Theme) => string;
+    };
+    preview: {
+        display: "flex";
+        alignItems: "center";
+        gap: ({ spacing }: Theme) => string;
+    };
+    actionsContainer: {
+        position: "absolute";
+        display: "flex";
+        alignItems: "center";
+        backgroundColor: ({ palette }: Theme) => string;
+        padding: ({ spacing }: Theme) => string;
+        gap: ({ spacing }: Theme) => string;
+    };
+    iconButton: {
+        width: ({ spacing }: Theme) => string;
+        height: ({ spacing }: Theme) => string;
+        borderRadius: number;
+        '.MuiTouchRipple-ripple .MuiTouchRipple-child': {
+            borderRadius: number;
+        };
+    };
+    triggerButton: {
+        '&[data-active="true"]': {
+            backgroundColor: ({ palette }: Theme) => string;
+        };
+    };
+};

package/dist/types/widgets/toolbar-actions/toolbar-actions.d.ts

@@ -0,0 +1,8 @@
+import { JSX } from 'react';
+import { ToolbarActionsProps } from './types';
+/**
+ * A floating toolbar component that displays action buttons.
+ * Shows a trigger button when there are 3+ actions, which expands
+ * to reveal all actions with a close button.
+ */
+export declare function ToolbarActions({ children: _children, full, direction, labels, sx, IconButtonProps, TooltipProps, }: ToolbarActionsProps): JSX.Element | null;

package/dist/types/widgets/toolbar-actions/types.d.ts

@@ -0,0 +1,45 @@
+import { IconButtonProps, SxProps, Theme, TooltipProps } from '@mui/material';
+import { ReactNode } from 'react';
+/**
+ * Represents a single action in the toolbar
+ */
+export interface ToolbarAction {
+    /** Unique identifier for the action */
+    id: string;
+    /** Icon to display for the action */
+    icon: ReactNode;
+    /** Label displayed in tooltip */
+    label: string;
+    /** Callback when action is clicked */
+    onClick: () => void;
+    /** Whether the action is disabled */
+    disabled?: boolean;
+}
+/**
+ * Labels for toolbar UI elements
+ */
+export interface ToolbarActionsLabels {
+    /** Tooltip for the trigger button */
+    trigger?: string;
+    /** Tooltip for the close button */
+    close?: string;
+}
+/**
+ * Props for the ToolbarActions component
+ */
+export interface ToolbarActionsProps {
+    /** Array of React elements (typically IconButtons) to display in the toolbar */
+    children: ReactNode[] | ReactNode;
+    /** Direction in which the toolbar expands */
+    direction?: 'left' | 'right';
+    /** Whether the toolbar is in full mode */
+    full?: boolean;
+    /** Custom labels for UI elements */
+    labels?: ToolbarActionsLabels;
+    /** Custom styles for the root container */
+    sx?: SxProps<Theme>;
+    /** Props passed to action IconButtons */
+    IconButtonProps?: Omit<IconButtonProps, 'onClick' | 'disabled'>;
+    /** Props passed to Tooltips */
+    TooltipProps?: Omit<TooltipProps, 'title' | 'children'>;
+}

package/dist/types/widgets/wrapper/components/actions.d.ts

@@ -0,0 +1,2 @@
+import { WrapperActionsProps } from '../types';
+export declare function Actions({ actions }: WrapperActionsProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/wrapper/components/options.d.ts

@@ -0,0 +1,2 @@
+import { WrapperOptionsProps } from '../types';
+export declare function Options({ labels, options }: WrapperOptionsProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/wrapper/components/title.d.ts

@@ -0,0 +1,6 @@
+import { ReactNode } from 'react';
+import { WrapperOptionsProps } from '../types';
+export declare function Title({ label, children, }: {
+    children: ReactNode;
+    label?: NonNullable<WrapperOptionsProps['labels']>['title'];
+}): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/wrapper/index.d.ts

@@ -0,0 +1,6 @@
+export { Actions } from './components/actions';
+export { Options } from './components/options';
+export { Title } from './components/title';
+export { WidgetWrapper } from './wrapper';
+export { WrapperUI } from './wrapper-ui';
+export type { WrapperActionsProps, WrapperOption, WrapperOptionsProps, WrapperProps, WrapperState, WrapperUIProps, } from './types';