@toolbox-web/grid 0.2.6 → 0.2.8

package/index.d.ts

@@ -61,6 +61,48 @@ export declare const aggregatorRegistry: {
     list(): string[];
 };
 
+/**
+ * Grid-wide animation configuration.
+ * Controls global animation behavior - individual plugins define their own animation styles.
+ * Duration and easing values set corresponding CSS variables on the grid element.
+ */
+export declare interface AnimationConfig {
+    /**
+     * Global animation mode.
+     * @default 'reduced-motion'
+     */
+    mode?: AnimationMode;
+    /**
+     * Default animation duration in milliseconds.
+     * Sets `--tbw-animation-duration` CSS variable.
+     * @default 200
+     */
+    duration?: number;
+    /**
+     * Default easing function.
+     * Sets `--tbw-animation-easing` CSS variable.
+     * @default 'ease-out'
+     */
+    easing?: string;
+}
+
+/**
+ * Animation behavior mode.
+ * - `true` or `'on'`: Animations always enabled
+ * - `false` or `'off'`: Animations always disabled
+ * - `'reduced-motion'`: Respects `prefers-reduced-motion` media query (default)
+ */
+export declare type AnimationMode = boolean | 'on' | 'off' | 'reduced-motion';
+
+/**
+ * Animation style for visual transitions.
+ * - `'slide'`: Slide/transform animation (e.g., expand down, slide left/right)
+ * - `'fade'`: Opacity fade animation
+ * - `'flip'`: FLIP technique for position changes (First, Last, Invert, Play)
+ * - `false`: No animation for this specific feature
+ */
+export declare type AnimationStyle = 'slide' | 'fade' | 'flip' | false;
+
 /**
  * Base contract for a column. Public; kept intentionally lean so host apps can extend via intersection types.
  * Prefer adding optional properties here only when broadly useful to most grids.
@@ -697,6 +739,12 @@ export declare abstract class BaseGridPlugin<TConfig = unknown> implements GridP
     getHeaderContent?(): HeaderContentDefinition | undefined;
 }
 
+/**
+ * Built-in sort implementation using column comparator or default.
+ * This is the default sortHandler when none is configured.
+ */
+export declare function builtInSort<T>(rows: T[], sortState: SortState, columns: ColumnConfig<T>[]): T[];
+
 /**
  * Cell click event
  */
@@ -1211,9 +1259,18 @@ export declare interface DataGridEventMap<TRow = unknown> {
     'column-state-change': GridColumnState;
 }
 
+/** Default animation configuration */
+export declare const DEFAULT_ANIMATION_CONFIG: Required<Omit<AnimationConfig, 'sort'>>;
+
 /** Default icons used when not overridden */
 export declare const DEFAULT_GRID_ICONS: Required<GridIcons>;
 
+/**
+ * Default comparator for sorting values.
+ * Handles nulls (pushed to end), numbers, and string fallback.
+ */
+export declare function defaultComparator(a: unknown, b: unknown): number;
+
 export declare type DGEventName = (typeof DGEvents)[keyof typeof DGEvents];
 
 export declare const DGEvents: {
@@ -1253,6 +1310,20 @@ declare interface EditorExecContext<T = any> extends CellContext<T> {
     cancel: () => void;
 }
 
+/**
+ * Tree Data Plugin Types
+ *
+ * Type definitions for hierarchical tree data with expand/collapse functionality.
+ */
+/** Animation style for expand/collapse */
+declare type ExpandCollapseAnimation = false | 'slide' | 'fade';
+
+/** Animation style for expand/collapse */
+declare type ExpandCollapseAnimation_2 = false | 'slide' | 'fade';
+
+/** Animation style for expand/collapse */
+declare type ExpandCollapseAnimation_3 = false | 'slide' | 'fade';
+
 /**
  * Export Plugin Types
  *
@@ -1304,7 +1375,7 @@ export declare interface ExternalMountViewDetail<TRow = unknown> {
 }
 
 /** Configuration options for the filtering plugin */
-export declare interface FilterConfig {
+export declare interface FilterConfig<TRow = unknown> {
     /** Debounce delay in ms for filter input (default: 300) */
     debounceMs?: number;
     /** Whether text filtering is case sensitive (default: false) */
@@ -1315,8 +1386,46 @@ export declare interface FilterConfig {
     useWorker?: boolean;
     /** Custom filter panel renderer (replaces default panel content) */
     filterPanelRenderer?: FilterPanelRenderer;
+    /**
+     * Async handler for fetching unique values from a server.
+     * When provided, this is called instead of extracting values from local rows.
+     * Useful for server-side datasets where not all data is loaded.
+     */
+    valuesHandler?: FilterValuesHandler;
+    /**
+     * Async handler for applying filters on a server.
+     * When provided, filtering is delegated to the server instead of local filtering.
+     * Should return the filtered rows from the server.
+     *
+     * Note: When using filterHandler, processRows() becomes a passthrough
+     * and the returned rows replace the grid's data.
+     */
+    filterHandler?: FilterHandler<TRow>;
 }
 
+/**
+ * Async handler for applying filters on a server.
+ *
+ * For server-side filtering, this handler is called when filters change.
+ * It should fetch filtered data from the server and return the new rows.
+ * The plugin will replace the grid's rows with the returned data.
+ *
+ * @param filters - Current active filter models
+ * @param currentRows - Current row array (for reference/optimistic updates)
+ * @returns Promise resolving to filtered rows
+ *
+ * @example
+ * ```ts
+ * filterHandler: async (filters) => {
+ *   const params = new URLSearchParams();
+ *   filters.forEach(f => params.append(f.field, `${f.operator}:${f.value}`));
+ *   const response = await fetch(`/api/data?${params}`);
+ *   return response.json();
+ * }
+ * ```
+ */
+export declare type FilterHandler<TRow = unknown> = (filters: FilterModel[], currentRows: TRow[]) => TRow[] | Promise<TRow[]>;
+
 /** Filter model representing a single filter condition */
 export declare interface FilterModel {
     /** The field/column to filter on */
@@ -1362,6 +1471,27 @@ declare type FilterPanelRenderer = (container: HTMLElement, params: FilterPanelP
 /** Supported filter types */
 export declare type FilterType = 'text' | 'number' | 'date' | 'set' | 'boolean';
 
+/**
+ * Async handler for fetching unique filter values from a server.
+ *
+ * For server-side datasets where not all values are available locally,
+ * this handler is called when the filter panel opens to fetch all
+ * possible values for the column.
+ *
+ * @param field - The field/column name
+ * @param column - The column configuration
+ * @returns Promise resolving to array of unique values
+ *
+ * @example
+ * ```ts
+ * valuesHandler: async (field, column) => {
+ *   const response = await fetch(`/api/distinct/${field}`);
+ *   return response.json(); // ['Engineering', 'Marketing', 'Sales', ...]
+ * }
+ * ```
+ */
+export declare type FilterValuesHandler = (field: string, column: ColumnConfig) => Promise<unknown[]>;
+
 export declare type FitMode = (typeof FitModeEnum)[keyof typeof FitModeEnum];
 
 export declare const FitModeEnum: {
@@ -1539,6 +1669,41 @@ export declare interface GridConfig<TRow = any> {
      * Plugins will use these by default but can override with their own config.
      */
     icons?: GridIcons;
+    /**
+     * Grid-wide animation configuration.
+     * Controls animations for expand/collapse, reordering, and other visual transitions.
+     * Individual plugins can override these defaults in their own config.
+     */
+    animation?: AnimationConfig;
+    /**
+     * Custom sort handler for full control over sorting behavior.
+     *
+     * When provided, this handler is called instead of the built-in sorting logic.
+     * Enables custom sorting algorithms, server-side sorting, or plugin-specific sorting.
+     *
+     * The handler receives:
+     * - `rows`: Current row array to sort
+     * - `sortState`: Sort field and direction (1 = asc, -1 = desc)
+     * - `columns`: Column configurations (for accessing sortComparator)
+     *
+     * Return the sorted array (sync) or a Promise that resolves to the sorted array (async).
+     * For server-side sorting, return a Promise that resolves when data is fetched.
+     *
+     * @example
+     * ```ts
+     * // Custom stable sort
+     * sortHandler: (rows, state, cols) => {
+     *   return stableSort(rows, (a, b) => compare(a[state.field], b[state.field]) * state.direction);
+     * }
+     *
+     * // Server-side sorting
+     * sortHandler: async (rows, state) => {
+     *   const response = await fetch(`/api/data?sort=${state.field}&dir=${state.direction}`);
+     *   return response.json();
+     * }
+     * ```
+     */
+    sortHandler?: SortHandler<TRow>;
 }
 
 export declare type GridCSSVar = (typeof GridCSSVars)[keyof typeof GridCSSVars];
@@ -1678,6 +1843,14 @@ export declare interface GroupingRowsConfig {
     formatLabel?: (value: any, depth: number, key: string) => string;
     /** Whether to render group row as full-width spanning cell (default: true) */
     fullWidth?: boolean;
+    /**
+     * Animation style for expanding/collapsing groups.
+     * - `false`: No animation
+     * - `'slide'`: Slide animation (default)
+     * - `'fade'`: Fade animation
+     * @default 'slide'
+     */
+    animation?: ExpandCollapseAnimation_3;
 }
 
 /** Parameters passed to custom group row renderer */
@@ -1853,6 +2026,14 @@ export declare interface PivotConfig {
     indentWidth?: number;
     /** Whether to show the pivot configuration tool panel (default: true) */
     showToolPanel?: boolean;
+    /**
+     * Animation style for expanding/collapsing groups.
+     * - `false`: No animation
+     * - `'slide'`: Slide animation (default)
+     * - `'fade'`: Fade animation
+     * @default 'slide'
+     */
+    animation?: ExpandCollapseAnimation_2;
 }
 
 export declare interface PivotResult {
@@ -2327,6 +2508,16 @@ export declare interface SortChangeDetail {
     direction: 1 | -1 | 0;
 }
 
+/**
+ * Custom sort handler function signature.
+ *
+ * @param rows - Current row array to sort
+ * @param sortState - Sort field and direction
+ * @param columns - Column configurations (for accessing sortComparator)
+ * @returns Sorted array (sync) or Promise resolving to sorted array (async)
+ */
+export declare type SortHandler<TRow = any> = (rows: TRow[], sortState: SortState, columns: ColumnConfig<TRow>[]) => TRow[] | Promise<TRow[]>;
+
 /**
  * Multi-Sort Plugin Types
  *
@@ -2340,6 +2531,16 @@ export declare interface SortModel {
     direction: 'asc' | 'desc';
 }
 
+/**
+ * Sort state passed to custom sort handlers.
+ */
+export declare interface SortState {
+    /** Field to sort by */
+    field: string;
+    /** Sort direction: 1 = ascending, -1 = descending */
+    direction: 1 | -1;
+}
+
 /**
  * Toolbar button defined via config (programmatic approach).
  * Supports three modes:
@@ -2420,11 +2621,6 @@ export declare interface ToolPanelDefinition {
     order?: number;
 }
 
-/**
- * Tree Data Plugin Types
- *
- * Type definitions for hierarchical tree data with expand/collapse functionality.
- */
 /** Configuration options for the tree plugin */
 export declare interface TreeConfig {
     /** Field name containing child rows (default: 'children') */
@@ -2437,6 +2633,14 @@ export declare interface TreeConfig {
     indentWidth?: number;
     /** Show expand/collapse icons (default: true) */
     showExpandIcons?: boolean;
+    /**
+     * Animation style for expanding/collapsing tree nodes.
+     * - `false`: No animation
+     * - `'slide'`: Slide animation (default)
+     * - `'fade'`: Fade animation
+     * @default 'slide'
+     */
+    animation?: ExpandCollapseAnimation;
 }
 
 /** Event detail emitted when a tree node is expanded or collapsed */