twico-ui 1.17.2 → 1.18.0

package/dist/index.d.cts

@@ -1901,6 +1901,19 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
    *  column. Use it to trim a wide grid's editor **without** touching `editable` (which would also
    *  disable inline cell editing). */
   batchEditFields?: string[];
+  /** Persist the full view state (filters, sort, quick-search, page, page size, column order / widths /
+   *  visibility / pinning, density) to `localStorage` under this key, and restore it on mount (#259).
+   *  SSR-safe: storage is never read during render — the server and first client render start from the
+   *  defaults, then the saved state is applied in a mount effect (so hydration never mismatches). Unknown
+   *  columns in a saved snapshot are ignored, so a later column change won't break restore. */
+  stateKey?: string;
+  /** Seed the view state on first mount (used only when `stateKey` has nothing stored yet). A partial
+   *  `DatatableState` — omitted keys keep their defaults. */
+  initialState?: Partial<DatatableState>;
+  /** Fired whenever the view state changes, with the complete `DatatableState`. Use it to persist the
+   *  state yourself (URL query, server, …) instead of — or in addition to — `stateKey`. Not fired on
+   *  the initial mount for the default state; fires once after a `stateKey`/`initialState` restore. */
+  onStateChange?: (state: DatatableState) => void;
   /** Show a "Go to" page jumper in the footer when there are more than 5 pages. @default true */
   showPageJumper?: boolean;
   /** Click-to-select mode: "row" highlights the clicked row, "cell" highlights a single cell. @default "none" */
@@ -1991,6 +2004,37 @@ interface DatatableQuery {
   hiddenColumns?: string[];
 }
 
+/**
+ * The complete, serializable view state of a `Datatable` (#259) — everything the user can adjust
+ * from the toolbar and column headers. Persisted by `stateKey`, seeded by `initialState`, and
+ * reported by `onStateChange`. Every field is optional in `initialState`/a stored snapshot: unknown
+ * columns are dropped and missing keys fall back to the table's defaults, so a snapshot survives a
+ * schema change. `columnVisibility` lists only hidden columns (`{ field: false }`; absent = visible);
+ * `columnPinning` lists only pinned columns (`{ field: "left" | "right" }`).
+ */
+interface DatatableState {
+  /** Active per-column filters (without the internal row id). */
+  filters: DatatableFilter[];
+  /** Active sort, or null. */
+  sort: { field: string; dir: "asc" | "desc" } | null;
+  /** Quick-search text. */
+  quickFilter: string;
+  /** Zero-based current page. */
+  page: number;
+  /** Rows per page. */
+  pageSize: number;
+  /** Column `field`s in their current left-to-right order. */
+  columnOrder: string[];
+  /** User-resized column widths in px, keyed by `field`. */
+  columnWidths: Record<string, number>;
+  /** Hidden columns, keyed by `field` (`false` = hidden; a visible column is simply absent). */
+  columnVisibility: Record<string, boolean>;
+  /** Pinned columns, keyed by `field`. */
+  columnPinning: Record<string, "left" | "right">;
+  /** Row-density preset. */
+  density: "compact" | "standard" | "comfortable";
+}
+
 interface DatatableColumn<T = any> {
   /** Row object key (also the default sort/filter/search/group/export key). */
   field: string;
@@ -4174,7 +4218,9 @@ declare function useLocalStorage<T>(
   initialValue: T
 ): [T, (value: T | ((prev: T) => T)) => void];
 
-/** Copy text to the clipboard with a `copied` flag that auto-resets. */
+/** Copy text to the clipboard with a `copied` flag that auto-resets. Uses the async Clipboard API in a
+ *  secure context and falls back to a legacy `execCommand("copy")` path over plain HTTP on a LAN IP
+ *  (where `navigator.clipboard` is undefined) and in older browsers, so `copy()` works off-secure-origin. */
 declare function useCopyToClipboard(timeout?: number): {
   copied: boolean;
   copy: (text: string) => Promise<boolean>;
@@ -4239,4 +4285,4 @@ declare function useFocusTrap<T extends HTMLElement = HTMLElement>(
  */
 declare function usePortal(): (node: React.ReactNode) => React.ReactPortal | React.ReactNode | null;
 
-export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxOwnProps, type BoxProps, Boxplot, type BoxplotDatum, type BoxplotProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, BubbleChart, type BubbleChartProps, Button, type ButtonProps, Candlestick, type CandlestickDatum, type CandlestickProps, Card, CardGrid, type CardGridFilter, type CardGridProps, type CardGridQuery, type CardGridSort, type CardGridSortOption, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, ColorSchemeScript, type ColorSchemeScriptOptions, type ColorSchemeScriptProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableBatchActionContext, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, DateTimePicker, type DateTimePickerProps, Dialog, type DialogProps, type DiffOp, DiffTable, type DiffTableColumn, type DiffTableProps, Divider, type DividerProps, DonutChart, type DonutChartDatum, type DonutChartProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, FilterBar, type FilterBarProps, type FilterClause, type FilterField, type FilterFieldType, type FilterValues, Form, type FormProps, FunnelChart, type FunnelChartProps, type FunnelDatum, Gauge, type GaugeProps, type GaugeSeries, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, Heatmap, type HeatmapDatum, type HeatmapProps, IconButton, type IconButtonProps, Image, type ImageProps, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, Label, type LabelProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, PieChart, type PieChartDatum, type PieChartProps, PolarAreaChart, type PolarAreaChartProps, type PolarAreaDatum, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, RadarChart, type RadarChartProps, type RadarDatum, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, RangeChart, type RangeChartProps, type RangeDatum, Rating, type RatingProps, type ResponsiveColumns, ScatterChart, type ScatterChartProps, type ScatterPoint, type ScatterSeries, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineDatum, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, TimePicker, type TimePickerProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, Treemap, type TreemapDatum, type TreemapProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, VisuallyHidden, type VisuallyHiddenProps, type WithSx, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };
+export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxOwnProps, type BoxProps, Boxplot, type BoxplotDatum, type BoxplotProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, BubbleChart, type BubbleChartProps, Button, type ButtonProps, Candlestick, type CandlestickDatum, type CandlestickProps, Card, CardGrid, type CardGridFilter, type CardGridProps, type CardGridQuery, type CardGridSort, type CardGridSortOption, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, ColorSchemeScript, type ColorSchemeScriptOptions, type ColorSchemeScriptProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableBatchActionContext, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableState, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, DateTimePicker, type DateTimePickerProps, Dialog, type DialogProps, type DiffOp, DiffTable, type DiffTableColumn, type DiffTableProps, Divider, type DividerProps, DonutChart, type DonutChartDatum, type DonutChartProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, FilterBar, type FilterBarProps, type FilterClause, type FilterField, type FilterFieldType, type FilterValues, Form, type FormProps, FunnelChart, type FunnelChartProps, type FunnelDatum, Gauge, type GaugeProps, type GaugeSeries, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, Heatmap, type HeatmapDatum, type HeatmapProps, IconButton, type IconButtonProps, Image, type ImageProps, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, Label, type LabelProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, PieChart, type PieChartDatum, type PieChartProps, PolarAreaChart, type PolarAreaChartProps, type PolarAreaDatum, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, RadarChart, type RadarChartProps, type RadarDatum, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, RangeChart, type RangeChartProps, type RangeDatum, Rating, type RatingProps, type ResponsiveColumns, ScatterChart, type ScatterChartProps, type ScatterPoint, type ScatterSeries, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineDatum, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, TimePicker, type TimePickerProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, Treemap, type TreemapDatum, type TreemapProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, VisuallyHidden, type VisuallyHiddenProps, type WithSx, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };

package/dist/index.d.ts

@@ -1901,6 +1901,19 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
    *  column. Use it to trim a wide grid's editor **without** touching `editable` (which would also
    *  disable inline cell editing). */
   batchEditFields?: string[];
+  /** Persist the full view state (filters, sort, quick-search, page, page size, column order / widths /
+   *  visibility / pinning, density) to `localStorage` under this key, and restore it on mount (#259).
+   *  SSR-safe: storage is never read during render — the server and first client render start from the
+   *  defaults, then the saved state is applied in a mount effect (so hydration never mismatches). Unknown
+   *  columns in a saved snapshot are ignored, so a later column change won't break restore. */
+  stateKey?: string;
+  /** Seed the view state on first mount (used only when `stateKey` has nothing stored yet). A partial
+   *  `DatatableState` — omitted keys keep their defaults. */
+  initialState?: Partial<DatatableState>;
+  /** Fired whenever the view state changes, with the complete `DatatableState`. Use it to persist the
+   *  state yourself (URL query, server, …) instead of — or in addition to — `stateKey`. Not fired on
+   *  the initial mount for the default state; fires once after a `stateKey`/`initialState` restore. */
+  onStateChange?: (state: DatatableState) => void;
   /** Show a "Go to" page jumper in the footer when there are more than 5 pages. @default true */
   showPageJumper?: boolean;
   /** Click-to-select mode: "row" highlights the clicked row, "cell" highlights a single cell. @default "none" */
@@ -1991,6 +2004,37 @@ interface DatatableQuery {
   hiddenColumns?: string[];
 }
 
+/**
+ * The complete, serializable view state of a `Datatable` (#259) — everything the user can adjust
+ * from the toolbar and column headers. Persisted by `stateKey`, seeded by `initialState`, and
+ * reported by `onStateChange`. Every field is optional in `initialState`/a stored snapshot: unknown
+ * columns are dropped and missing keys fall back to the table's defaults, so a snapshot survives a
+ * schema change. `columnVisibility` lists only hidden columns (`{ field: false }`; absent = visible);
+ * `columnPinning` lists only pinned columns (`{ field: "left" | "right" }`).
+ */
+interface DatatableState {
+  /** Active per-column filters (without the internal row id). */
+  filters: DatatableFilter[];
+  /** Active sort, or null. */
+  sort: { field: string; dir: "asc" | "desc" } | null;
+  /** Quick-search text. */
+  quickFilter: string;
+  /** Zero-based current page. */
+  page: number;
+  /** Rows per page. */
+  pageSize: number;
+  /** Column `field`s in their current left-to-right order. */
+  columnOrder: string[];
+  /** User-resized column widths in px, keyed by `field`. */
+  columnWidths: Record<string, number>;
+  /** Hidden columns, keyed by `field` (`false` = hidden; a visible column is simply absent). */
+  columnVisibility: Record<string, boolean>;
+  /** Pinned columns, keyed by `field`. */
+  columnPinning: Record<string, "left" | "right">;
+  /** Row-density preset. */
+  density: "compact" | "standard" | "comfortable";
+}
+
 interface DatatableColumn<T = any> {
   /** Row object key (also the default sort/filter/search/group/export key). */
   field: string;
@@ -4174,7 +4218,9 @@ declare function useLocalStorage<T>(
   initialValue: T
 ): [T, (value: T | ((prev: T) => T)) => void];
 
-/** Copy text to the clipboard with a `copied` flag that auto-resets. */
+/** Copy text to the clipboard with a `copied` flag that auto-resets. Uses the async Clipboard API in a
+ *  secure context and falls back to a legacy `execCommand("copy")` path over plain HTTP on a LAN IP
+ *  (where `navigator.clipboard` is undefined) and in older browsers, so `copy()` works off-secure-origin. */
 declare function useCopyToClipboard(timeout?: number): {
   copied: boolean;
   copy: (text: string) => Promise<boolean>;
@@ -4239,4 +4285,4 @@ declare function useFocusTrap<T extends HTMLElement = HTMLElement>(
  */
 declare function usePortal(): (node: React.ReactNode) => React.ReactPortal | React.ReactNode | null;
 
-export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxOwnProps, type BoxProps, Boxplot, type BoxplotDatum, type BoxplotProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, BubbleChart, type BubbleChartProps, Button, type ButtonProps, Candlestick, type CandlestickDatum, type CandlestickProps, Card, CardGrid, type CardGridFilter, type CardGridProps, type CardGridQuery, type CardGridSort, type CardGridSortOption, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, ColorSchemeScript, type ColorSchemeScriptOptions, type ColorSchemeScriptProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableBatchActionContext, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, DateTimePicker, type DateTimePickerProps, Dialog, type DialogProps, type DiffOp, DiffTable, type DiffTableColumn, type DiffTableProps, Divider, type DividerProps, DonutChart, type DonutChartDatum, type DonutChartProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, FilterBar, type FilterBarProps, type FilterClause, type FilterField, type FilterFieldType, type FilterValues, Form, type FormProps, FunnelChart, type FunnelChartProps, type FunnelDatum, Gauge, type GaugeProps, type GaugeSeries, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, Heatmap, type HeatmapDatum, type HeatmapProps, IconButton, type IconButtonProps, Image, type ImageProps, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, Label, type LabelProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, PieChart, type PieChartDatum, type PieChartProps, PolarAreaChart, type PolarAreaChartProps, type PolarAreaDatum, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, RadarChart, type RadarChartProps, type RadarDatum, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, RangeChart, type RangeChartProps, type RangeDatum, Rating, type RatingProps, type ResponsiveColumns, ScatterChart, type ScatterChartProps, type ScatterPoint, type ScatterSeries, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineDatum, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, TimePicker, type TimePickerProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, Treemap, type TreemapDatum, type TreemapProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, VisuallyHidden, type VisuallyHiddenProps, type WithSx, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };
+export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxOwnProps, type BoxProps, Boxplot, type BoxplotDatum, type BoxplotProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, BubbleChart, type BubbleChartProps, Button, type ButtonProps, Candlestick, type CandlestickDatum, type CandlestickProps, Card, CardGrid, type CardGridFilter, type CardGridProps, type CardGridQuery, type CardGridSort, type CardGridSortOption, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, ColorSchemeScript, type ColorSchemeScriptOptions, type ColorSchemeScriptProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableBatchActionContext, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableState, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, DateTimePicker, type DateTimePickerProps, Dialog, type DialogProps, type DiffOp, DiffTable, type DiffTableColumn, type DiffTableProps, Divider, type DividerProps, DonutChart, type DonutChartDatum, type DonutChartProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, FilterBar, type FilterBarProps, type FilterClause, type FilterField, type FilterFieldType, type FilterValues, Form, type FormProps, FunnelChart, type FunnelChartProps, type FunnelDatum, Gauge, type GaugeProps, type GaugeSeries, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, Heatmap, type HeatmapDatum, type HeatmapProps, IconButton, type IconButtonProps, Image, type ImageProps, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, Label, type LabelProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, PieChart, type PieChartDatum, type PieChartProps, PolarAreaChart, type PolarAreaChartProps, type PolarAreaDatum, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, RadarChart, type RadarChartProps, type RadarDatum, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, RangeChart, type RangeChartProps, type RangeDatum, Rating, type RatingProps, type ResponsiveColumns, ScatterChart, type ScatterChartProps, type ScatterPoint, type ScatterSeries, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineDatum, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, TimePicker, type TimePickerProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, Treemap, type TreemapDatum, type TreemapProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, VisuallyHidden, type VisuallyHiddenProps, type WithSx, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };

package/dist/index.mjs

@@ -8990,6 +8990,9 @@ function Datatable({
   onBatchUpdate,
   showBatchEdit = true,
   batchEditFields = null,
+  stateKey,
+  initialState,
+  onStateChange,
   showPageJumper = true,
   selectionMode = "none",
   onRowClick,
@@ -9152,6 +9155,75 @@ function Datatable({
   const [rowGrab, setRowGrab] = React51__default.useState(null);
   const [reorderMsg, setReorderMsg] = React51__default.useState("");
   const rowFocusRef = React51__default.useRef(null);
+  const serializeState = () => ({
+    filters: filters.map(({ id, ...f }) => f),
+    // strip the internal row id
+    sort,
+    quickFilter: quick,
+    page: pageVal,
+    pageSize: sizeVal,
+    columnOrder: order,
+    columnWidths: widths,
+    columnVisibility: Object.fromEntries([...hidden].map((f) => [f, false])),
+    // absent = visible
+    columnPinning: Object.fromEntries([...pins.left.map((f) => [f, "left"]), ...pins.right.map((f) => [f, "right"])]),
+    density
+  });
+  const applyState = (s) => {
+    if (!s || typeof s !== "object") return;
+    const known = new Set(cols.map((c) => c.field).filter(Boolean));
+    if (Array.isArray(s.filters)) setFilters(s.filters.filter((f) => f && known.has(f.field)).map((f, i) => ({ id: Date.now() + Math.random() + i, field: f.field, op: f.op, value: f.value })));
+    if ("sort" in s) setSort(s.sort && known.has(s.sort.field) ? { field: s.sort.field, dir: s.sort.dir === "desc" ? "desc" : "asc" } : null);
+    if (typeof s.quickFilter === "string" && quickFilter === void 0) setInternalQuick(s.quickFilter);
+    if (typeof s.page === "number" && !pageControlled) setInternalPage(Math.max(0, Math.floor(s.page)));
+    if (typeof s.pageSize === "number" && !pageSizeControlled) setInternalRpp(s.pageSize > 0 ? s.pageSize : 10);
+    if (Array.isArray(s.columnOrder)) {
+      const savedOrder = s.columnOrder.filter((f) => known.has(f));
+      const missing = cols.map((c) => c.field).filter((f) => f && !savedOrder.includes(f));
+      setOrder([...savedOrder, ...missing]);
+    }
+    if (s.columnWidths && typeof s.columnWidths === "object") setWidths(Object.fromEntries(Object.entries(s.columnWidths).filter(([f, w]) => known.has(f) && typeof w === "number")));
+    if (s.columnVisibility && typeof s.columnVisibility === "object") setHidden(new Set(Object.keys(s.columnVisibility).filter((f) => known.has(f) && s.columnVisibility[f] === false)));
+    if (s.columnPinning && typeof s.columnPinning === "object") {
+      const l = [], r2 = [];
+      for (const [f, side] of Object.entries(s.columnPinning)) {
+        if (!known.has(f)) continue;
+        if (side === "left") l.push(f);
+        else if (side === "right") r2.push(f);
+      }
+      setPins({ left: l, right: r2 });
+    }
+    if (s.density === "compact" || s.density === "standard" || s.density === "comfortable") setDensity(s.density);
+  };
+  const stateReadyRef = React51__default.useRef(false);
+  const onStateChangeRef = React51__default.useRef(onStateChange);
+  onStateChangeRef.current = onStateChange;
+  React51__default.useEffect(() => {
+    if (!stateReadyRef.current) return void 0;
+    if (!stateKey && !onStateChange) return void 0;
+    const state = serializeState();
+    onStateChangeRef.current?.(state);
+    if (stateKey) {
+      try {
+        window.localStorage.setItem(stateKey, JSON.stringify(state));
+      } catch {
+      }
+    }
+    return void 0;
+  }, [filters, sort, quick, pageVal, sizeVal, order, widths, hidden, pins, density, stateKey]);
+  React51__default.useEffect(() => {
+    let saved = null;
+    if (stateKey) {
+      try {
+        const raw = window.localStorage.getItem(stateKey);
+        if (raw) saved = JSON.parse(raw);
+      } catch {
+      }
+    }
+    if (!saved && initialState) saved = initialState;
+    if (saved) applyState(saved);
+    stateReadyRef.current = true;
+  }, []);
   const rootRef = React51__default.useRef(null);
   const [compact, setCompact] = React51__default.useState(false);
   React51__default.useEffect(() => {
@@ -9193,13 +9265,20 @@ function Datatable({
       return [...kept, ...added];
     });
   }, [columns]);
+  const densitySyncedRef = React51__default.useRef(false);
   React51__default.useEffect(() => {
-    setDensity(densityProp);
+    if (densitySyncedRef.current) setDensity(densityProp);
+    else densitySyncedRef.current = true;
   }, [densityProp]);
   React51__default.useEffect(() => {
     setAggOn(showAggregation);
   }, [showAggregation]);
+  const pageSizeSyncedRef = React51__default.useRef(false);
   React51__default.useEffect(() => {
+    if (!pageSizeSyncedRef.current) {
+      pageSizeSyncedRef.current = true;
+      return;
+    }
     if (pageSizeControlled) return;
     setInternalRpp(pageSize > 0 ? pageSize : 10);
     setInternalPage(0);
@@ -17788,21 +17867,47 @@ function useLocalStorage(key, initialValue) {
   );
   return [stored, setValue];
 }
+function legacyCopy(text) {
+  try {
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.setAttribute("readonly", "");
+    ta.style.cssText = "position:fixed;top:0;left:0;width:1px;height:1px;padding:0;border:none;opacity:0;pointer-events:none;";
+    document.body.appendChild(ta);
+    const sel = document.getSelection();
+    const prev = sel && sel.rangeCount > 0 ? sel.getRangeAt(0) : null;
+    ta.focus();
+    ta.select();
+    ta.setSelectionRange(0, ta.value.length);
+    const ok = document.execCommand("copy");
+    document.body.removeChild(ta);
+    if (prev && sel) {
+      sel.removeAllRanges();
+      sel.addRange(prev);
+    }
+    return ok;
+  } catch {
+    return false;
+  }
+}
 function useCopyToClipboard(timeout = 1500) {
   const [copied, setCopied] = React51__default.useState(false);
   const copy = React51__default.useCallback(async (text) => {
-    if (!canUseDOM2 || !navigator.clipboard) {
+    if (!canUseDOM2) {
       setCopied(false);
       return false;
     }
-    try {
-      await navigator.clipboard.writeText(text);
-      setCopied(true);
-      return true;
-    } catch (e) {
-      setCopied(false);
-      return false;
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      try {
+        await navigator.clipboard.writeText(text);
+        setCopied(true);
+        return true;
+      } catch {
+      }
     }
+    const ok = legacyCopy(String(text ?? ""));
+    setCopied(ok);
+    return ok;
   }, []);
   React51__default.useEffect(() => {
     if (!copied) return void 0;