@zvndev/yable-react 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { Table as Table$1, RowData, Cell, Header, Row, TableOptions, ColumnDef, SortDirection, CellContext, ClipboardOptions, CellFlashInfo } from '@zvndev/yable-core';
+import { Table as Table$1, RowData, Cell, Header, Row, TableOptions, TableState, Updater, Column, ColumnDef, ColumnDefBase, SortDirection, CellContext, ClipboardOptions, CellFlashInfo } from '@zvndev/yable-core';
 export { AccessorFnColumnDef, AccessorKeyColumnDef, AggregationFn, Cell, CellStatus as CellCommitStatus, CellContext, CellFlashEvent, CellPatch, ClipboardOptions, Column, ColumnDef, ColumnDefBase, ColumnFiltersState, ColumnMeta, ColumnOrderState, ColumnPinningState, ColumnSizingInfoState, ColumnSizingState, CommitError, CommitErrorCells, CommitRecord, CommitResult, CommitsSlice, DisplayColumnDef, EditingState, ExpandedState, FillHandleState, FilterFn, FormulaEngine, FormulaError, FormulaFunction, FormulaState, GroupColumnDef, Header, HeaderContext, HeaderGroup, KeyboardNavigationAction, KeyboardNavigationCell, KeyboardNavigationDirection, KeyboardNavigationState, OnChangeFn, OnCommitFn, PaginationState, PartialLocale, PivotColumn, PivotConfig, PivotEngine, PivotFieldConfig, PivotRow, PivotState, PivotValueConfig, Row, RowData, RowDragEndEvent, RowDragEvent, RowDragState, RowEditCommitEvent, RowEditEvent, RowPinningState, RowReorderEvent, RowSelectionState, SortDirection, SortingFn, SortingState, Table as TableInstance, TableOptions, TableOptionsResolved, TableState, UndoAction, UndoRedoOptions, UndoRedoState, UndoStack, Updater, VisibilityState, YableLocale, aggregationFns, createColumnHelper, createLocale, createUndoRedoIntegration, en, filterFns, formulaFunctions, functionalUpdate, generatePivotColumnDefs, getDefaultLocale, getInitialPivotState, getPivotRowModel, resetLocale, setDefaultLocale, sortingFns } from '@zvndev/yable-core';
 import * as React$1 from 'react';
-import React__default, { HTMLAttributes, TdHTMLAttributes, ThHTMLAttributes } from 'react';
+import React__default, { HTMLAttributes, TdHTMLAttributes, ThHTMLAttributes, ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { RowDragState } from '@zvndev/yable-core/features/rowDragging';
 
@@ -53,6 +53,14 @@ interface TableProps<TData extends RowData> extends Omit<HTMLAttributes<HTMLDivE
     sidebarPanels?: ('columns' | 'filters')[];
     /** Default sidebar panel */
     defaultSidebarPanel?: 'columns' | 'filters';
+    /** Render a second header row with per-column floating filters */
+    floatingFilters?: boolean;
+    /** Virtualize wide tables horizontally when safe to do so */
+    columnVirtualization?: boolean;
+    /** Additional columns rendered beyond the viewport when column virtualization is enabled */
+    columnVirtualizationOverscan?: number;
+    /** Accessible label for the grid container. Default: "Data table" */
+    ariaLabel?: string;
 }
 /** Status bar panel configuration */
 interface StatusBarPanelConfig {
@@ -91,6 +99,69 @@ interface TableHeaderCellProps<TData extends RowData, TValue = unknown> extends
  */
 declare function useTable<TData extends RowData>(options: TableOptions<TData>): Table$1<TData>;
 
+interface UseTablePersistenceOptions {
+    /** Storage key used for getItem/setItem. */
+    key: string;
+    /** Which TableState slices to persist. Defaults to column layout keys. */
+    persistedKeys?: (keyof TableState)[];
+    /** Milliseconds to debounce storage writes. Default: 100. */
+    debounce?: number;
+    /** Schema version — bumping this discards any stale stored data. */
+    version?: number;
+    /** Custom Storage implementation. Default: localStorage. */
+    storage?: Storage;
+}
+interface UseTablePersistenceReturn {
+    /**
+     * Partial state hydrated from storage — pass to `useTable({ initialState })`.
+     * Only useful when NOT passing `onStateChange` (i.e., uncontrolled mode).
+     */
+    initialState: Partial<TableState>;
+    /**
+     * State-change handler that persists relevant slices on each update.
+     * When passed to `useTable({ onStateChange })`, the persistence hook
+     * takes over state management (controlled mode). You MUST also pass
+     * `state` to useTable in this case.
+     */
+    onStateChange: (updater: Updater<TableState>) => void;
+    /**
+     * Current table state managed by the persistence hook.
+     * Pass to `useTable({ state })` alongside `onStateChange`.
+     */
+    state: Partial<TableState>;
+    /** Manually clear all persisted state for this key. */
+    clearPersistedState: () => void;
+}
+/**
+ * React hook that persists selected table state slices to storage.
+ *
+ * Returns `initialState` (hydrated from storage), `state`, and
+ * `onStateChange` — pass all three to `useTable` so that persisted
+ * slices survive page reloads.
+ *
+ * @example
+ * ```tsx
+ * const persistence = useTablePersistence({ key: 'my-table', version: 1 })
+ *
+ * // Controlled mode (recommended) — persistence manages state:
+ * const table = useTable({
+ *   data,
+ *   columns,
+ *   initialState: persistence.initialState,
+ *   state: persistence.state,
+ *   onStateChange: persistence.onStateChange,
+ * })
+ *
+ * // Uncontrolled mode — only hydrate, no live persistence:
+ * const table = useTable({
+ *   data,
+ *   columns,
+ *   initialState: persistence.initialState,
+ * })
+ * ```
+ */
+declare function useTablePersistence(options: UseTablePersistenceOptions): UseTablePersistenceReturn;
+
 interface VirtualRow {
     index: number;
     start: number;
@@ -106,6 +177,12 @@ interface UseVirtualizationOptions {
     pretextHeights?: Float64Array | null;
     /** Pre-computed prefix sums for O(log n) scroll lookups */
     pretextPrefixSums?: Float64Array | null;
+    /**
+     * Opaque key that changes when column widths change.
+     * When this value changes the height cache is invalidated because column
+     * resizing can affect text wrapping and therefore row heights.
+     */
+    columnSizingHash?: string | number;
 }
 interface UseVirtualizationResult {
     virtualRows: VirtualRow[];
@@ -113,19 +190,51 @@ interface UseVirtualizationResult {
     startIndex: number;
     endIndex: number;
     scrollTo: (index: number) => void;
+    /**
+     * Manually clear the row-height cache and force recalculation.
+     * Call this when cell content changes (data mutations, font-size changes, etc.)
+     * that may affect row heights.
+     */
+    invalidateRowHeights: () => void;
 }
 /**
  * Computes which rows are visible in a scrollable container and returns
  * positioning data so only those rows (plus an overscan buffer) are rendered.
  *
- * Returns `{ virtualRows, totalHeight, startIndex, endIndex, scrollTo }`.
+ * Returns `{ virtualRows, totalHeight, startIndex, endIndex, scrollTo, invalidateRowHeights }`.
  * Re-renders are triggered by scroll (rAF-throttled) and ResizeObserver
  * container resize. Supports fixed, variable, and Pretext-pre-measured heights.
  *
- * Gotcha: variable-height mode caches measured heights per index — pass new
- * `pretextHeights` arrays (or change `totalRows`) to invalidate the cache.
+ * The height cache is automatically invalidated when `totalRows`, `isFixedHeight`,
+ * or `columnSizingHash` changes. For manual invalidation (e.g. after data mutations
+ * or font-size changes), call `invalidateRowHeights()`.
  */
-declare function useVirtualization({ containerRef, totalRows, rowHeight, overscan, estimateRowHeight: _estimateRowHeight, pretextHeights, pretextPrefixSums, }: UseVirtualizationOptions): UseVirtualizationResult;
+declare function useVirtualization({ containerRef, totalRows, rowHeight, overscan, estimateRowHeight: _estimateRowHeight, pretextHeights, pretextPrefixSums, columnSizingHash, }: UseVirtualizationOptions): UseVirtualizationResult;
+
+interface VirtualColumn<TData extends RowData> {
+    column: Column<TData, unknown>;
+    index: number;
+    start: number;
+    size: number;
+}
+interface UseColumnVirtualizationOptions<TData extends RowData> {
+    containerRef: React.RefObject<HTMLElement | null>;
+    columns: Column<TData, unknown>[];
+    overscan?: number;
+    enabled?: boolean;
+}
+interface UseColumnVirtualizationResult<TData extends RowData> {
+    virtualColumns: VirtualColumn<TData>[];
+    startOffset: number;
+    endOffset: number;
+    totalWidth: number;
+    visibleWidth: number;
+    startIndex: number;
+    endIndex: number;
+    isVirtualized: boolean;
+    scrollToIndex: (index: number) => void;
+}
+declare function useColumnVirtualization<TData extends RowData>({ containerRef, columns, overscan, enabled, }: UseColumnVirtualizationOptions<TData>): UseColumnVirtualizationResult<TData>;
 
 interface CellMeasurement {
     /** Column ID */
@@ -360,18 +469,68 @@ declare function getRegisteredCellTypes(): readonly string[];
 declare const TableProvider: React$1.Provider<Table$1<any> | null>;
 declare function useTableContext<TData extends RowData>(): Table$1<TData>;
 
-declare function Table<TData extends RowData>({ table, stickyHeader, striped, bordered, compact, theme, clickableRows, footer, loading, loadingComponent, loadingText, emptyMessage, emptyComponent, emptyIcon, emptyDetail, renderEmpty, renderLoading, children, className, direction, statusBar, statusBarPanels, sidebar, sidebarPanels, defaultSidebarPanel, ...rest }: TableProps<TData>): react_jsx_runtime.JSX.Element;
+/**
+ * Project-wide default table and column options.
+ *
+ * Wrap your app (or a subtree) in `<YableProvider>` so every `<Table>` and
+ * `useTable` call inherits these defaults without repeating config.
+ *
+ * Component-level and hook-level values always take precedence over provider
+ * defaults.
+ */
+interface YableDefaults {
+    /** Default props applied to every `<Table>` in the subtree */
+    tableProps?: Partial<Pick<TableProps<any>, 'striped' | 'bordered' | 'compact' | 'stickyHeader' | 'theme' | 'direction' | 'ariaLabel'>>;
+    /** Default column definition merged under every table's own `defaultColumnDef` */
+    defaultColumnDef?: Partial<ColumnDefBase<any, unknown>>;
+}
+/**
+ * Read the nearest `YableProvider` defaults.
+ *
+ * Safe to call outside a provider — returns an empty object.
+ */
+declare function useYableDefaults(): YableDefaults;
+/**
+ * Provide project-wide defaults for all Yable tables in a subtree.
+ *
+ * @example
+ * ```tsx
+ * <YableProvider
+ *   striped
+ *   stickyHeader
+ *   theme="stripe"
+ *   defaultColumnDef={{ enableSorting: true }}
+ * >
+ *   <EmployeeTable />
+ *   <ProjectTable />
+ * </YableProvider>
+ * ```
+ */
+declare function YableProvider({ children, defaultColumnDef, striped, stickyHeader, bordered, compact, theme, direction, ariaLabel, }: YableDefaults & {
+    children: ReactNode;
+    striped?: boolean;
+    stickyHeader?: boolean;
+    bordered?: boolean;
+    compact?: boolean;
+    theme?: string;
+    direction?: 'ltr' | 'rtl';
+    ariaLabel?: string;
+}): react_jsx_runtime.JSX.Element;
+
+declare function Table<TData extends RowData>({ table, stickyHeader: stickyHeaderProp, striped: stripedProp, bordered: borderedProp, compact: compactProp, theme: themeProp, clickableRows, footer, loading, loadingComponent, loadingText, emptyMessage, emptyComponent, emptyIcon, emptyDetail, renderEmpty, renderLoading, children, className, direction: directionProp, statusBar, statusBarPanels, sidebar, sidebarPanels, defaultSidebarPanel, floatingFilters, columnVirtualization, columnVirtualizationOverscan, ariaLabel: ariaLabelProp, ...rest }: TableProps<TData>): react_jsx_runtime.JSX.Element;
 
 interface TableHeaderProps<TData extends RowData> {
     table: Table$1<TData>;
+    floatingFilters?: boolean;
 }
-declare function TableHeader<TData extends RowData>({ table, }: TableHeaderProps<TData>): react_jsx_runtime.JSX.Element;
+declare function TableHeader<TData extends RowData>({ table, floatingFilters, }: TableHeaderProps<TData>): react_jsx_runtime.JSX.Element;
 
 interface TableBodyProps<TData extends RowData> {
     table: Table$1<TData>;
     clickableRows?: boolean;
+    colgroup?: React__default.ReactNode;
 }
-declare function TableBody<TData extends RowData>({ table, clickableRows, }: TableBodyProps<TData>): react_jsx_runtime.JSX.Element;
+declare function TableBody<TData extends RowData>({ table, clickableRows, colgroup, }: TableBodyProps<TData>): react_jsx_runtime.JSX.Element;
 
 interface TableCellProps<TData extends RowData> {
     cell: Cell<TData, unknown>;
@@ -386,7 +545,7 @@ declare function TableCell<TData extends RowData>({ cell, table, rowIndex, colum
 interface TableFooterProps<TData extends RowData> {
     table: Table$1<TData>;
 }
-declare function TableFooter<TData extends RowData>({ table, }: TableFooterProps<TData>): react_jsx_runtime.JSX.Element | null;
+declare function TableFooter<TData extends RowData>({ table }: TableFooterProps<TData>): react_jsx_runtime.JSX.Element | null;
 
 interface PaginationProps<TData extends RowData> {
     table: Table$1<TData>;
@@ -412,6 +571,17 @@ interface GlobalFilterProps<TData extends RowData> {
 }
 declare function GlobalFilter<TData extends RowData>({ table, placeholder, debounce, className, }: GlobalFilterProps<TData>): react_jsx_runtime.JSX.Element;
 
+interface FloatingFilterProps<TData extends RowData> {
+    column: Column<TData, unknown>;
+}
+declare function FloatingFilter<TData extends RowData>({ column }: FloatingFilterProps<TData>): react_jsx_runtime.JSX.Element;
+
+interface SetFilterProps<TData extends RowData> {
+    column: Column<TData, unknown>;
+    className?: string;
+}
+declare function SetFilter<TData extends RowData>({ column, className }: SetFilterProps<TData>): react_jsx_runtime.JSX.Element;
+
 interface SortIndicatorProps {
     direction: SortDirection | false;
     index?: number;
@@ -956,7 +1126,7 @@ interface UsePrintLayoutOptions {
      */
     additionalCSS?: string;
 }
-declare function usePrintLayout<TData extends RowData>(table: Table$1<TData>, options?: UsePrintLayoutOptions): {
+declare function usePrintLayout<TData extends RowData>(_table: Table$1<TData>, options?: UsePrintLayoutOptions): {
     preparePrint: () => void;
     isPrinting: boolean;
 };
@@ -970,11 +1140,89 @@ interface UseThemeOptions {
 declare function useTheme(options?: UseThemeOptions): {
     theme: string;
     setTheme: (newTheme: string) => void;
-    colorScheme: "auto" | "light" | "dark";
+    colorScheme: "auto" | "dark" | "light";
     setColorScheme: (scheme: "light" | "dark" | "auto") => void;
     toggleColorScheme: () => void;
-    resolvedColorScheme: "light" | "dark";
+    resolvedColorScheme: "dark" | "light";
     containerRef: React$1.RefObject<HTMLElement | null>;
 };
 
-export { type AutoMeasurementsOptions, CellBadge, type CellBadgeProps, CellBoolean, type CellBooleanProps, CellCheckbox, CellCurrency, type CellCurrencyProps, CellDate, CellDatePicker, type CellDateProps, CellErrorBoundary, CellInput, CellLink, type CellLinkProps, type CellMeasureRecipe, type CellMeasurement, CellNumeric, type CellNumericProps, CellProgress, type CellProgressProps, CellRating, type CellRatingProps, CellSelect, CellStatus, CellStatusBadge, type CellStatusBadgeProps, type CellStatusProps, CellToggle, ColumnsPanel, ContextMenu, ContextMenuItem, type ContextMenuItemDef, DEFAULT_TEXT_RECIPE, DragHandle, ErrorBoundary, ExpandIcon, FillHandle, type FillHandleDragState, type FillHandleProps, FiltersPanel, FlashCell, GlobalFilter, LoadingOverlay, type LoadingOverlayProps, MasterDetail, NoRowsOverlay, type NoRowsOverlayProps, Pagination, PivotConfigPanel, type PivotConfigProps, type PivotFieldItem, type PivotValueItem, PrintLayout, Sidebar, SortIndicator, StatusBar, StatusBarPanelComponent, type StatusBarPanelComponentProps, type StatusBarPanelConfig, type StatusBarPanelProps, Table, TableBody, TableCell, type TableCellProps$1 as TableCellProps, TableFooter, TableHeader, type TableHeaderCellProps, type TableProps, TableProvider, type TableRowProps, Tooltip, type TooltipPosition, type TooltipProps, TreeToggle, type UseCellFlashOptions, type UseClipboardOptions, type UseFillHandleOptions, type UseFillHandleReturn, type UseKeyboardNavigationOptions, type UsePretextMeasurementOptions, type UsePretextMeasurementResult, type UsePrintLayoutOptions, type UseRowAnimationOptions, type UseRowDragOptions, type UseRowDragReturn, type UseTableRowHeightsOptions, type UseThemeOptions, type UseTooltipOptions, type UseVirtualizationOptions, type UseVirtualizationResult, type VirtualRow, getMeasureRecipeForCellType, getRegisteredCellTypes, resolveMeasureRecipe, useAutoMeasurements, useCellFlash, useClipboard, useContextMenu, useFillHandle, useKeyboardNavigation, usePretextMeasurement, usePrintLayout, useRowAnimation, useRowDrag, useTable, useTableContext, useTableRowHeights, useTheme, useTooltip, useVirtualization };
+interface SelectColumnOptions {
+    id?: string;
+    size?: number;
+    headerAriaLabel?: string;
+}
+declare function selectColumn<TData extends RowData>(options?: SelectColumnOptions): ColumnDef<TData, unknown>;
+
+interface RowNumberColumnOptions {
+    id?: string;
+    header?: string;
+    size?: number;
+    startFrom?: number;
+}
+declare function rowNumberColumn<TData extends RowData>(options?: RowNumberColumnOptions): ColumnDef<TData, unknown>;
+
+interface ActionItem<TData extends RowData> {
+    label: string;
+    icon?: ReactNode;
+    onClick: (row: Row<TData>) => void;
+    hidden?: (row: Row<TData>) => boolean;
+    disabled?: (row: Row<TData>) => boolean;
+}
+interface ActionsColumnOptions<TData extends RowData> {
+    id?: string;
+    header?: string;
+    size?: number;
+    actions: ActionItem<TData>[] | ((row: Row<TData>) => ActionItem<TData>[]);
+}
+declare function actionsColumn<TData extends RowData>(options: ActionsColumnOptions<TData>): ColumnDef<TData, unknown>;
+
+interface ExpandColumnOptions {
+    id?: string;
+    size?: number;
+}
+declare function expandColumn<TData extends RowData>(options?: ExpandColumnOptions): ColumnDef<TData, unknown>;
+
+interface CellStackProps {
+    children: React__default.ReactNode;
+    gap?: number;
+}
+declare function CellStack({ children, gap }: CellStackProps): react_jsx_runtime.JSX.Element;
+
+interface CellRowProps {
+    children: React__default.ReactNode;
+    gap?: number;
+    align?: 'start' | 'center' | 'end' | 'baseline';
+    justify?: 'start' | 'center' | 'end' | 'between';
+}
+declare function CellRow({ children, gap, align, justify }: CellRowProps): react_jsx_runtime.JSX.Element;
+
+interface CellWithIconProps {
+    icon: React__default.ReactNode;
+    children: React__default.ReactNode;
+    gap?: number;
+    iconSize?: number;
+}
+declare function CellWithIcon({ icon, children, gap, iconSize }: CellWithIconProps): react_jsx_runtime.JSX.Element;
+
+interface CellTextProps {
+    children: React__default.ReactNode;
+    variant?: 'primary' | 'secondary' | 'muted';
+    bold?: boolean;
+    truncate?: boolean;
+    size?: 'sm' | 'md' | 'lg';
+}
+declare function CellText({ children, variant, bold, truncate, size, }: CellTextProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Merges edit-commit changes into a data array, returning a new array
+ * with matching rows shallow-merged. Rows without changes keep their
+ * original reference so downstream memoisation works.
+ *
+ * @param data     Current data array
+ * @param changes  Map of row ID -> partial row values (same shape as `onEditCommit`)
+ * @param getRowId Optional row-ID resolver; defaults to string index
+ */
+declare function mergeEditChanges<TData>(data: TData[], changes: Record<string, Partial<TData>>, getRowId?: (row: TData, index: number) => string): TData[];
+
+export { type ActionItem, type ActionsColumnOptions, type AutoMeasurementsOptions, CellBadge, type CellBadgeProps, CellBoolean, type CellBooleanProps, CellCheckbox, CellCurrency, type CellCurrencyProps, CellDate, CellDatePicker, type CellDateProps, CellErrorBoundary, CellInput, CellLink, type CellLinkProps, type CellMeasureRecipe, type CellMeasurement, CellNumeric, type CellNumericProps, CellProgress, type CellProgressProps, CellRating, type CellRatingProps, CellRow, type CellRowProps, CellSelect, CellStack, type CellStackProps, CellStatus, CellStatusBadge, type CellStatusBadgeProps, type CellStatusProps, CellText, type CellTextProps, CellToggle, CellWithIcon, type CellWithIconProps, ColumnsPanel, ContextMenu, ContextMenuItem, type ContextMenuItemDef, DEFAULT_TEXT_RECIPE, DragHandle, ErrorBoundary, type ExpandColumnOptions, ExpandIcon, FillHandle, type FillHandleDragState, type FillHandleProps, FiltersPanel, FlashCell, FloatingFilter, GlobalFilter, LoadingOverlay, type LoadingOverlayProps, MasterDetail, NoRowsOverlay, type NoRowsOverlayProps, Pagination, PivotConfigPanel, type PivotConfigProps, type PivotFieldItem, type PivotValueItem, PrintLayout, type RowNumberColumnOptions, type SelectColumnOptions, SetFilter, Sidebar, SortIndicator, StatusBar, StatusBarPanelComponent, type StatusBarPanelComponentProps, type StatusBarPanelConfig, type StatusBarPanelProps, Table, TableBody, TableCell, type TableCellProps$1 as TableCellProps, TableFooter, TableHeader, type TableHeaderCellProps, type TableProps, TableProvider, type TableRowProps, Tooltip, type TooltipPosition, type TooltipProps, TreeToggle, type UseCellFlashOptions, type UseClipboardOptions, type UseColumnVirtualizationOptions, type UseColumnVirtualizationResult, type UseFillHandleOptions, type UseFillHandleReturn, type UseKeyboardNavigationOptions, type UsePretextMeasurementOptions, type UsePretextMeasurementResult, type UsePrintLayoutOptions, type UseRowAnimationOptions, type UseRowDragOptions, type UseRowDragReturn, type UseTablePersistenceOptions, type UseTablePersistenceReturn, type UseTableRowHeightsOptions, type UseThemeOptions, type UseTooltipOptions, type UseVirtualizationOptions, type UseVirtualizationResult, type VirtualColumn, type VirtualRow, type YableDefaults, YableProvider, actionsColumn, expandColumn, getMeasureRecipeForCellType, getRegisteredCellTypes, mergeEditChanges, resolveMeasureRecipe, rowNumberColumn, selectColumn, useAutoMeasurements, useCellFlash, useClipboard, useColumnVirtualization, useContextMenu, useFillHandle, useKeyboardNavigation, usePretextMeasurement, usePrintLayout, useRowAnimation, useRowDrag, useTable, useTableContext, useTablePersistence, useTableRowHeights, useTheme, useTooltip, useVirtualization, useYableDefaults };