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

package/dist/types/widgets/stores/widget-store.d.ts

@@ -0,0 +1,39 @@
+import { WidgetStore } from './types';
+/**
+ * Zustand store for managing widget state across the application.
+ *
+ * This store provides centralized state management for all widget UI components
+ *
+ * @example
+ * ```tsx
+ * // Import the store
+ * import { useWidgetStore } from '@carto/ps-react-ui/widgets'
+ *
+ * // Use in a component
+ * function MyWidget() {
+ *   const setWidget = useWidgetStore((state) => state.setWidget)
+ *   const widget = useWidgetStore((state) => state.widgets['my-widget'])
+ *
+ *   useEffect(() => {
+ *     setWidget({
+ *       id: 'my-widget',
+ *       type: 'formula',
+ *       title: 'Total Sales',
+ *       isLoading: false,
+ *       visible: true,
+ *       data: { value: 1000, prefix: '$' }
+ *     })
+ *   }, [setWidget])
+ *
+ *   return <div>{widget?.data?.value}</div>
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Get widgets by type
+ * const getWidgetsByType = useWidgetStore((state) => state.getWidgetsByType)
+ * const formulaWidgets = getWidgetsByType('formula')
+ * ```
+ */
+export declare const useWidgetStore: import('zustand').UseBoundStore<import('zustand').StoreApi<WidgetStore>>;

package/dist/types/widgets/stores/widget-store.test.d.ts

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

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

@@ -0,0 +1,2 @@
+export { Subheader } from './subheader';
+export type { SubheaderComponentProps } from './types';

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

@@ -0,0 +1,19 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    root: {
+        display: "flex";
+        alignItems: "center";
+        gap: ({ spacing }: Theme) => string;
+        minHeight: ({ spacing }: Theme) => string;
+    };
+    slotLeft: {
+        flexShrink: number;
+    };
+    slotRight: {
+        flexGrow: number;
+        display: "flex";
+        justifyContent: "flex-end";
+        alignItems: "center";
+        gap: ({ spacing }: Theme) => string;
+    };
+};

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

@@ -0,0 +1,2 @@
+import { SubheaderComponentProps } from './types';
+export declare function Subheader({ slotLeft, slotRight, sx, }: SubheaderComponentProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,10 @@
+import { SxProps, Theme } from '@mui/material';
+import { ReactNode } from 'react';
+export interface SubheaderComponentProps {
+    /** Content for the left slot */
+    slotLeft?: ReactNode;
+    /** Content for the right slot*/
+    slotRight?: ReactNode;
+    /** Custom styles */
+    sx?: SxProps<Theme>;
+}

package/dist/types/widgets/table/components/cell-header.d.ts

@@ -0,0 +1,5 @@
+import { CellHeaderProps } from '../types';
+/**
+ * Table cell header component with optional sorting and select-all checkbox
+ */
+export declare function CellHeader({ column, sortState, onSort, isSelectAll, isAllSelected, isIndeterminate, onSelectAll, }: CellHeaderProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,16 @@
+import { TableColumn } from '../types';
+/**
+ * Props for Cell component
+ */
+export interface CellProps {
+    /** Column definition */
+    column: TableColumn;
+    /** Cell value */
+    value: unknown;
+}
+/**
+ * Table cell component with automatic markdown support for string values
+ * Markdown is rendered when the raw value is a string and no formatter is defined.
+ * If a formatter is used, its output is rendered directly without markdown parsing.
+ */
+export declare function Cell({ column, value }: CellProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,4 @@
+export { CellHeader } from './cell-header';
+export { Row } from './row';
+export { Pagination } from './pagination';
+export { PaginationActions } from './pagination-actions';

package/dist/types/widgets/table/components/pagination-actions.d.ts

@@ -0,0 +1,5 @@
+import { PaginationActionsProps } from '../types';
+/**
+ * Custom pagination actions with first/prev/next/last buttons
+ */
+export declare function PaginationActions({ count, page, rowsPerPage, onPageChange, }: PaginationActionsProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,5 @@
+import { PaginationProps } from '../types';
+/**
+ * Table pagination component
+ */
+export declare function Pagination({ page, rowsPerPage, total, rowsPerPageOptions, onPageChange, onRowsPerPageChange, }: PaginationProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,5 @@
+import { RowProps } from '../types';
+/**
+ * Table row component with selection and hover support
+ */
+export declare function Row({ row, columns, isSelected, selectable, onClick, onSelect, onMouseEnter, onMouseLeave, }: RowProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,11 @@
+import { ConfigProps } from '../root/types';
+import { TableDownloadConfig, TableWidgetConfig, TableColumn } from './types';
+/**
+ * Default table download configuration
+ * Supports PNG export (screenshot) and CSV export (data)
+ */
+export declare function tableDownloadConfig({ refUI, }: ConfigProps): TableDownloadConfig;
+/**
+ * Default table widget configuration
+ */
+export declare function tableConfig(columns?: TableColumn[]): TableWidgetConfig;

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

@@ -0,0 +1,38 @@
+import { ReactNode } from 'react';
+/**
+ * Get formatted cell value for display
+ * Handles primitives, arrays, objects, and custom formatters
+ *
+ * @param cellValue - Raw cell value
+ * @param formatter - Optional formatter function
+ * @returns Formatted value for display
+ */
+export declare function getCellValue<T>(cellValue: T): ReactNode;
+/**
+ * Compare two values for sorting
+ * Handles strings, numbers, and other types
+ *
+ * @param a - First value
+ * @param b - Second value
+ * @param direction - Sort direction
+ * @returns Comparison result (-1, 0, 1)
+ */
+export declare function compareValues(a: unknown, b: unknown, direction: 'asc' | 'desc'): number;
+/**
+ * Sort data array by column
+ *
+ * @param data - Data array to sort
+ * @param columnId - Column ID to sort by
+ * @param direction - Sort direction
+ * @returns Sorted data array (new array, does not mutate original)
+ */
+export declare function sortData<T extends Record<string, unknown>>(data: T[], columnId: string, direction: 'asc' | 'desc'): T[];
+/**
+ * Paginate data array
+ *
+ * @param data - Data array to paginate
+ * @param page - Current page (0-indexed)
+ * @param rowsPerPage - Number of rows per page
+ * @returns Paginated data slice
+ */
+export declare function paginateData<T>(data: T[], page: number, rowsPerPage: number): T[];

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

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

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

@@ -0,0 +1,6 @@
+export { usePagination } from './use-pagination';
+export { useSort } from './use-sort';
+export { useSelection } from './use-selection';
+export type { UsePaginationOptions, UsePaginationResult, } from './use-pagination';
+export type { UseSortOptions, UseSortResult } from './use-sort';
+export type { UseSelectionOptions, UseSelectionResult } from './use-selection';

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

@@ -0,0 +1,45 @@
+import { TableRow, PaginationMode } from '../types';
+export interface UsePaginationOptions {
+    /** Pagination mode: local or remote */
+    mode: PaginationMode;
+    /** Initial page (0-indexed) */
+    initialPage?: number;
+    /** Initial rows per page */
+    initialRowsPerPage?: number;
+    /** Available rows per page options */
+    rowsPerPageOptions?: number[];
+    /** Total rows (for remote pagination) */
+    total?: number;
+    /** Callback when page changes (for remote pagination) */
+    onPageChange?: (page: number, rowsPerPage: number) => void;
+}
+export interface UsePaginationResult<T> {
+    /** 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[], options: UsePaginationOptions): 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,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

@@ -0,0 +1,5 @@
+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

@@ -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;