@carto/ps-react-ui 4.3.0-widgets.0 → 5.0.0-widgets.1

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

@@ -0,0 +1,32 @@
+import { TableRow } from '../types';
+export interface UseSelectionOptions {
+    /** Initial selected IDs */
+    initialSelectedIds?: Set<string | number>;
+    /** Callback when selection changes */
+    onSelectionChange?: (selectedIds: Set<string | number>) => void;
+}
+export interface UseSelectionResult {
+    /** Set of selected row IDs */
+    selectedIds: Set<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,29 @@
+import { TableRow, SortMode, SortDirection, SortState } from '../types';
+export interface UseSortOptions {
+    /** Sort mode: local or remote */
+    mode: SortMode;
+    /** Initial sort column ID */
+    initialColumnId?: string | null;
+    /** Initial sort direction */
+    initialDirection?: SortDirection;
+    /** Callback when sort changes (for remote sorting) */
+    onSortChange?: (columnId: string, direction: SortDirection) => void;
+}
+export interface UseSortResult<T> {
+    /** Current sort state */
+    sortState: SortState;
+    /** 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[], options: UseSortOptions): 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, PaginationMode, SortMode, TableWidgetConfig, TableWidgetState, TableDownloadConfig, TableProps, CellHeaderProps, RowProps, PaginationProps, PaginationActionsProps, } from './types';
+export type { UsePaginationOptions, UsePaginationResult, UseSortOptions, 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("@mui/material/OverridableComponent").OverridableComponent<import("@mui/material").TableHeadTypeMap<{}, "thead">>;
+    var CellHeader: typeof import(".").CellHeader;
+    var Body: import("@mui/material/OverridableComponent").OverridableComponent<import("@mui/material").TableBodyTypeMap<{}, "tbody">>;
+    var Row: typeof import(".").Row;
+    var Cell: typeof TableCell;
+    var Container: typeof TableContainer;
+    var Paper: import("@mui/material/OverridableComponent").OverridableComponent<import("@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,201 @@
+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 mode
+ */
+export type PaginationMode = 'local' | 'remote';
+/**
+ * Sort mode
+ */
+export type SortMode = 'local' | 'remote';
+/**
+ * Table widget configuration
+ */
+export interface TableWidgetConfig {
+    /** Column definitions */
+    columns?: TableColumn[];
+    /** Enable row selection with checkboxes */
+    selectable?: boolean;
+    /** Pagination configuration */
+    pagination?: {
+        /** Pagination mode: local (client-side) or remote (server-side) */
+        mode: PaginationMode;
+        /** Available rows per page options */
+        rowsPerPageOptions?: number[];
+        /** Default rows per page */
+        defaultRowsPerPage?: number;
+        /** Total rows for remote pagination */
+        total?: number;
+    };
+    /** Sort configuration */
+    sort?: {
+        /** Sort mode: local (client-side) or remote (server-side) */
+        mode: SortMode;
+        /** Default sort column */
+        defaultColumnId?: string;
+        /** Default sort direction */
+        defaultDirection?: 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?: (selectedIds: Set<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
+ */
+export type TableWidgetState = BaseWidgetState<WrapperState<TableWidgetConfig> & {
+    data: TableWidgetData;
+    paginationState?: TablePaginationState;
+    sortState?: SortState;
+    selectedIds?: Set<string | number>;
+}>;
+/**
+ * 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

@@ -1,4 +1,5 @@
-import { TimeseriesConfig } from './types';
-export declare const timeseriesConfig: (config: TimeseriesConfig & {
-    refUI?: import('react').Ref<HTMLElement | null>;
-}) => import('../_shared/chart-config/config-factory').ChartWidgetConfigResult<import('../echart').EchartWidgetData, TimeseriesConfig, "timeseries">;
+import { TimeseriesConfig, TimeseriesWidgetConfig, TimeseriesWidgetData } from './types';
+import { DownloadItem } from '../actions';
+import { ConfigProps } from '../root/types';
+export declare function timeseriesDownloadConfig({ refUI, }: ConfigProps): DownloadItem<TimeseriesWidgetData>[];
+export declare function timeseriesConfig(props: TimeseriesConfig): TimeseriesWidgetConfig;

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

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

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

@@ -1,15 +1,9 @@
-import { BaseWidgetProps } from '../widget/types';
-import { BaseConfig } from '../config-loader';
-import { EchartWidgetConfig, EchartWidgetData, EchartWidgetState } from '../echart';
-export interface TimeseriesProps extends Omit<BaseWidgetProps<TimeseriesWidgetConfig>, 'data'> {
-    type: 'timeseries';
-    data: TimeseriesWidgetData | undefined;
-}
+import { EchartWidgetData, EchartWidgetState } from '../echart';
+import { EchartWidgetOptionProps, EchartWidgetProps } from '../echart/types';
+import { ConfigProps } from '../root';
 export type TimeseriesWidgetData = EchartWidgetData;
 export type TimeseriesWidgetState = EchartWidgetState;
-export type TimeseriesWidgetConfig = TimeseriesConfig & EchartWidgetConfig<TimeseriesWidgetData> & {
-    type: TimeseriesProps['type'];
+export type TimeseriesWidgetConfig = EchartWidgetProps & {
+    type: 'timeseries';
 };
-export interface TimeseriesConfig extends Omit<BaseConfig, 'data'> {
-    data?: TimeseriesWidgetData;
-}
+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/index.d.ts

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

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

@@ -80,4 +80,10 @@ export declare const styles: {
             pointerEvents: "auto";
         };
     };
+    detail: {
+        display: "flex";
+        flexDirection: "column";
+        gap: ({ spacing }: Theme) => string;
+        paddingTop: ({ spacing }: Theme) => string;
+    };
 };

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

@@ -1,17 +1,19 @@
 import { ReactNode, SyntheticEvent } from 'react';
 import { SxProps, Theme } from '@mui/material';
 import { BaseWidgetState } from '../stores/types';
-export interface WrapperProps extends Pick<WrapperUIProps, 'sx' | 'actions' | 'options' | 'labels' | 'children' | 'onChangeCollapsed'> {
+export interface WrapperProps extends Pick<WrapperUIProps, 'sx' | 'actions' | 'options' | 'labels' | 'children' | 'onChangeCollapsed'>, Pick<WrapperState, 'disabled' | 'title'> {
     id: WrapperState['id'];
-    Component?: ReactNode;
+    defaultCollapsed?: boolean;
 }
-export type WrapperState<T = unknown> = BaseWidgetState<T & Pick<WrapperUIProps, 'collapsed' | 'disabled' | 'title'>>;
-export interface WrapperUIProps extends WrapperActionsProps, Omit<WrapperOptionsProps, 'labels' | ''> {
-    children: ReactNode;
+export type WrapperState<T = unknown> = BaseWidgetState<T & {
     title: string;
     disabled?: boolean;
     collapsed?: boolean;
     isLoading?: boolean;
+}>;
+export interface WrapperUIProps extends WrapperActionsProps, Omit<WrapperOptionsProps, 'labels' | ''> {
+    id: WrapperState['id'];
+    children: ReactNode;
     sx?: SxProps<Theme>;
     labels?: {
         options?: WrapperOptionsProps['labels'];

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

@@ -1,2 +1,2 @@
 import { WrapperUIProps } from './types';
-export declare function WrapperUI({ children, title, actions, disabled, isLoading, collapsed, sx, labels, options, onChangeCollapsed, }: WrapperUIProps): import("react/jsx-runtime").JSX.Element;
+export declare function WrapperUI({ children, id, actions, sx, labels, options, onChangeCollapsed, }: WrapperUIProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,2 +1,2 @@
 import { WrapperProps } from './types';
-export declare function WrapperWidget({ id, sx, actions, options, labels, Component, children, onChangeCollapsed, }: WrapperProps): string | number | bigint | boolean | Iterable<import('react').ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<import('react').ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element;
+export declare function WidgetWrapper({ id, title, defaultCollapsed, disabled, sx, actions, options, labels, children, onChangeCollapsed, }: WrapperProps): import("react/jsx-runtime").JSX.Element;