aplance-ui 1.0.1

package/registry/components/ui/data-table/types.ts

@@ -0,0 +1,594 @@
+import type {
+  Cell,
+  ColumnDef,
+  ColumnOrderState,
+  ColumnPinningState,
+  ColumnSizingState,
+  ExpandedState,
+  GroupingState,
+  Header,
+  OnChangeFn,
+  RowData,
+  Row,
+  RowSelectionState,
+  SortingState,
+  Table,
+  TableMeta as TanstackTableMeta,
+  VisibilityState,
+} from "@tanstack/react-table";
+import type { ReactNode } from "react";
+
+// ─── Column meta augmentation ─────────────────────────────────────────────────
+// Attach presentation hints directly to the column definition so consumers
+// stay in TanStack's idiomatic API surface (`columns: [{ ..., meta: {...} }]`)
+// instead of inventing parallel prop maps on the table.
+declare module "@tanstack/react-table" {
+  /* eslint-disable @typescript-eslint/no-unused-vars -- generics must mirror tanstack's signature exactly */
+  interface ColumnMeta<TData extends RowData, TValue> {
+    /** Horizontal alignment of cell + header content. Default: `'left'`. */
+    align?: "left" | "center" | "right";
+    /**
+     * Whether to truncate overflowing text with an ellipsis. Default: `true`.
+     * Set to `false` for cells that host interactive controls (inputs,
+     * selects, buttons) so focus rings and dropdowns are not clipped.
+     */
+    truncate?: boolean;
+    /** Extra class merged onto the `<th>` element. */
+    headerClassName?: string;
+    /** Extra class merged onto the `<td>` element. */
+    cellClassName?: string;
+  }
+  /* eslint-enable @typescript-eslint/no-unused-vars */
+}
+
+// ─── Filter fields ────────────────────────────────────────────────────────────
+// Two headless primitives - nothing else. Every concrete filter (search,
+// select, date picker, custom slider, …) plugs in through the same
+// `value`/`onChange` render-prop contract, so the data-table has zero
+// compile-time dependency on any specific input component.
+
+/** Any input-like field with a string value. Render anything that fulfils the API. */
+export interface FilterInputField {
+  type: "field";
+  key: string;
+  /** Grid column width template. Default: `'1fr'` (shares remaining space). */
+  width?: string;
+  render: (api: {
+    value: string;
+    onChange: (value: string) => void;
+  }) => ReactNode;
+}
+
+/** Any non-value slot - button, menu, custom control, … */
+export interface FilterAction {
+  type: "action";
+  /** Grid column width template. Default: `'auto'` (hugs content). */
+  width?: string;
+  render: () => ReactNode;
+}
+
+export type FilterField = FilterInputField | FilterAction;
+
+export interface FilterBarProps {
+  fields: FilterField[];
+  values: Record<string, string>;
+  onChange: (key: string, value: string) => void;
+}
+
+// ─── Table meta ───────────────────────────────────────────────────────────────
+
+export interface DataTableMeta<TData> extends TanstackTableMeta<TData> {
+  editingRowId: string | null;
+  updateData: (rowId: string, columnId: string, value: unknown) => void;
+}
+
+// ─── State persistence ────────────────────────────────────────────────────────
+// `useDataTable` wires the table's persistable state slices to one of three
+// destinations via its `persistState` option. The persisted blob shape
+// (`PersistedState`) is identical across modes - the mode just decides where
+// it lives.
+
+/** Snapshot of every persistable table state slice. Each is optional. */
+export interface PersistedState {
+  filterValues?: Record<string, string>;
+  pagination?: PaginationState;
+  sorting?: SortingState;
+  columnOrder?: ColumnOrderState;
+  columnVisibility?: VisibilityState;
+  columnPinning?: ColumnPinningState;
+  columnSizing?: ColumnSizingState;
+  grouping?: GroupingState;
+  expanded?: ExpandedState;
+}
+
+export type PersistMode = "search-params" | "local-storage" | "manual";
+
+/** Base shared by every mode. */
+interface PersistStateBase {
+  enabled: boolean;
+  /**
+   * Fired whenever any persistable slice changes, *in addition* to the mode's
+   * primary destination (URL / localStorage / your handler). Useful for
+   * telemetry, debug inspectors, or mirroring state into React for display.
+   */
+  onChange?: (state: PersistedState) => void;
+}
+
+interface PersistSearchParams extends PersistStateBase {
+  mode: "search-params";
+  /**
+   * Optional URL param renames. Keys are the canonical state names
+   * (`pageIndex`, `sortBy`, filter keys, etc.); values are the URL params
+   * actually written. Unmapped keys default to their canonical name.
+   */
+  paramMap?: Partial<Record<string, string>>;
+}
+
+interface PersistLocalStorage extends PersistStateBase {
+  mode: "local-storage";
+  /** Storage key for the JSON blob. */
+  storageKey: string;
+}
+
+interface PersistManual extends PersistStateBase {
+  mode: "manual";
+  /** Hydrated once on mount. */
+  initialState?: PersistedState;
+}
+
+export type PersistState =
+  | PersistSearchParams
+  | PersistLocalStorage
+  | PersistManual;
+
+// ─── Pagination ───────────────────────────────────────────────────────────────
+
+export interface PaginationState {
+  pageIndex: number;
+  pageSize: number;
+}
+
+export interface PaginationBarProps<TData> {
+  table: Table<TData>;
+  pagination: PaginationState;
+  onPaginationChange: (next: PaginationState) => void;
+  pageSizeOptions: number[];
+  showPageSizeSelect: boolean;
+  totalCount: number | undefined;
+  rowLabel: string;
+  rowsSelectable: boolean;
+  selectedCount: number;
+  extra: ReactNode;
+}
+
+// ─── Re-exports for column-control state ─────────────────────────────────────
+// Re-exposed from tanstack so consumers do not need to import two modules.
+export type {
+  ColumnOrderState,
+  ColumnPinningState,
+  ColumnSizingState,
+  ExpandedState,
+  GroupingState,
+  VisibilityState,
+};
+
+// ─── Main DataTable props ─────────────────────────────────────────────────────
+
+export interface DataTableProps<TData extends { id: string }> {
+  data: TData[];
+  /**
+   * TanStack Table's ColumnDef is invariant on its value type parameter.
+   * `ColumnDef<Email, string>` is NOT assignable to `ColumnDef<Email, unknown>`
+   * because `footer`/`header` templates place the value param in a contravariant
+   * position. `any` is the correct solution - it is bivariant (simultaneously
+   * supertype and subtype of every type), which is the only param that lets
+   * columns of any concrete value type pass here without errors.
+   * This matches how TanStack Table itself types its own internal APIs.
+   *
+   * In consumers: do NOT write `useMemo<ColumnDef<X, unknown>[]>(...)`.
+   * Just write `useMemo(() => [...], [deps])` - let TypeScript infer the
+   * column types. The inferred union widens correctly into `ColumnDef<X, any>`
+   * at the prop boundary with zero errors.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  columns: ColumnDef<TData, any>[];
+
+  isLoading?: boolean;
+  emptyMessage?: string;
+
+  filters?: FilterField[];
+  filterValues?: Record<string, string>;
+  onFilterChange?: (key: string, value: string) => void;
+
+  sorting: SortingState;
+  onSortingChange: OnChangeFn<SortingState>;
+
+  /**
+   * When true, TanStack tracks sorting state but does NOT sort data
+   * client-side. Use for server-side sorting where the API returns
+   * pre-sorted results. Default: `false`.
+   */
+  manualSorting?: boolean;
+
+  showPagination?: boolean;
+  pagination?: PaginationState;
+  onPaginationChange?: (next: PaginationState) => void;
+  totalPages?: number;
+  totalCount?: number;
+  pageSizeOptions?: number[];
+  showPageSizeSelect?: boolean;
+  rowLabel?: string;
+
+  rowsSelectable?: boolean;
+  rowSelection?: RowSelectionState;
+  onRowSelectionChange?: OnChangeFn<RowSelectionState>;
+
+  editingRowId?: string | null;
+  onUpdateData?: (rowId: string, columnId: string, value: unknown) => void;
+
+  // ─── Column controls (all opt-in) ───────────────────────────────────────────
+
+  /**
+   * Called whenever any internal data changes (e.g. from inline edits or drag-and-drop).
+   * Perfect for triggering API updates.
+   */
+  onDataChange?: (data: TData[]) => void;
+
+  /** Enable drag-and-drop row reordering. Fires `onDataChange` when reordered if using `useDataTable`, or `onRowOrderChange` if fully controlled. */
+  enableRowOrdering?: boolean;
+  onRowOrderChange?: (draggedRow: TData, targetRow: TData) => void;
+
+  /**
+   * Drag-and-drop column reordering via the header.
+   * Pass `columnOrder` + `onColumnOrderChange` to control externally,
+   * or omit to use the default order from `columns`.
+   */
+  enableColumnOrdering?: boolean;
+  columnOrder?: ColumnOrderState;
+  onColumnOrderChange?: OnChangeFn<ColumnOrderState>;
+
+  /** Column resize handles on the right edge of each header cell. */
+  enableColumnResizing?: boolean;
+  columnSizing?: ColumnSizingState;
+  onColumnSizingChange?: OnChangeFn<ColumnSizingState>;
+
+  /**
+   * Sticky column pinning. When enabled, pinned columns stay visible
+   * during horizontal scroll. Per-column opt-out: `enablePinning: false`.
+   */
+  enableColumnPinning?: boolean;
+  columnPinning?: ColumnPinningState;
+  onColumnPinningChange?: OnChangeFn<ColumnPinningState>;
+  defaultColumnPinning?: ColumnPinningState;
+
+  /** Show/hide columns. Pass with a UI to let users toggle visibility. */
+  columnVisibility?: VisibilityState;
+  onColumnVisibilityChange?: OnChangeFn<VisibilityState>;
+
+  /**
+   * Row grouping by column id. Renders a collapsible group row per
+   * unique value. Pair with a UI control to add/remove grouping columns.
+   */
+  enableGrouping?: boolean;
+  grouping?: GroupingState;
+  onGroupingChange?: OnChangeFn<GroupingState>;
+  expanded?: ExpandedState;
+  onExpandedChange?: OnChangeFn<ExpandedState>;
+
+  /**
+   * Visual: draw 1px vertical dividers between columns in both the header
+   * and body. Useful for spreadsheet-style tables. Default: `false`.
+   */
+  showVerticalBorders?: boolean;
+
+  /**
+   * Called when a data row is clicked. Receives the row's original data.
+   * Adds cursor-pointer to rows automatically when provided.
+   */
+  onRow?: (row: TData) => void;
+
+  /**
+   * Slot rendered inside the pagination bar next to the count text.
+   * Perfect for bulk-action buttons. Does not shift table layout.
+   */
+  paginationExtra?: ReactNode;
+
+  className?: string;
+}
+
+// ─── Internal subcomponent props ──────────────────────────────────────────────
+// Kept here (rather than next to each subcomponent) so all data-table types
+// live in one place. Subcomponents are not exported, but their prop shapes
+// matter for review and editor tooling.
+
+export interface HeaderActionButtonProps {
+  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+  ariaLabel: string;
+  ariaPressed?: boolean;
+  active?: boolean;
+  children: ReactNode;
+}
+
+export interface HeaderCellProps<TData> {
+  header: Header<TData, unknown>;
+  extraWidth: number;
+  enableColumnOrdering: boolean;
+  enableColumnResizing: boolean;
+  enableColumnPinning: boolean;
+  enableGrouping: boolean;
+  draggedColumnId: string | null;
+  dropTargetColumnId: string | null;
+  onDragStartCol: (id: string) => void;
+  onDragEndCol: () => void;
+  onDragOverCol: (id: string | null) => void;
+  onDropCol: (sourceId: string, targetId: string) => void;
+}
+
+export interface BodyRowProps<TData extends { id: string }> {
+  row: Row<TData>;
+  editingRowId: string | null;
+  onRow?: (row: TData) => void;
+  enableGrouping: boolean;
+  columnExtraWidths: Record<string, number>;
+  enableRowOrdering?: boolean;
+  draggedRowId?: string | null;
+  dropTargetRowId?: string | null;
+  onDragStartRow?: (id: string) => void;
+  onDragOverRow?: (id: string | null) => void;
+  onDragEndRow?: () => void;
+  onDropRow?: (draggedId: string, targetId: string) => void;
+}
+
+export interface BodyCellProps<TData> {
+  cell: Cell<TData, unknown>;
+  extraWidth: number;
+  groupSourceCell?: Cell<TData, unknown>;
+  isGroupAnchorCell: boolean;
+}
+
+// ─── useDataTable hook ────────────────────────────────────────────────────────
+
+export interface UseDataTableOptions<TData extends { id: string }> {
+  /** Full dataset. The hook slices it per page automatically (client-side mode). */
+  data: TData[];
+
+  /** Initial page size. Default: 10. */
+  pageSize?: number;
+
+  /**
+   * Initial filter values keyed by filter field key. The keys here also act
+   * as the "universe" of filter keys when persisting state - only these keys
+   * are read from / written to the URL or storage.
+   * @example { search: '', status: '' }
+   */
+  defaultFilterValues?: Record<string, string>;
+
+  /**
+   * Client-side filter function.
+   * Called with the full dataset + current filter values.
+   * Return a filtered subset - the hook handles paging on top of it.
+   *
+   * If omitted, the full dataset is used as-is (no client filtering).
+   *
+   * @example
+   * filterFn: (rows, filters) =>
+   *   rows.filter(r =>
+   *     !filters.search || r.name.toLowerCase().includes(filters.search.toLowerCase())
+   *   )
+   */
+  filterFn?: (rows: TData[], filters: Record<string, string>) => TData[];
+
+  /**
+   * Called whenever a filter value changes (after internal state update).
+   * Use for server-side filtering: trigger your API call here.
+   * pageIndex is automatically reset to 0 on every filter change.
+   */
+  onFilterChange?: (
+    key: string,
+    value: string,
+    allValues: Record<string, string>,
+  ) => void;
+
+  /** Called whenever pagination changes (page or page size). */
+  onPaginationChange?: (next: PaginationState) => void;
+
+  /** Called whenever sorting changes. */
+  onSortingChange?: (next: SortingState) => void;
+
+  /** Called whenever row selection changes. */
+  onRowSelectionChange?: (next: RowSelectionState) => void;
+
+  /**
+   * Called whenever internal data changes (e.g. from inline edits or drag-and-drop).
+   * Used to trigger API sync.
+   */
+  onDataChange?: (data: TData[]) => void;
+
+  /**
+   * If true (default), the hook slices `data` for the current page.
+   * Set to false when using server-side pagination - you control `data` externally
+   * and just want the hook to manage state.
+   */
+  clientSidePagination?: boolean;
+
+  /**
+   * When `true`, sorting state is tracked but not applied to data - your code
+   * is responsible for returning pre-sorted rows (typically via a server API).
+   * Default: `false` (rows are sorted client-side).
+   */
+  manualSorting?: boolean;
+
+  /** Total record count for server-side scenarios. */
+  totalCount?: number;
+  /** Total page count for server-side scenarios. */
+  totalPages?: number;
+
+  // ─── Column controls (all opt-in) ───────────────────────────────────────────
+
+  /** Initial drag-drop column order. */
+  defaultColumnOrder?: ColumnOrderState;
+  /** Initial column visibility map. */
+  defaultColumnVisibility?: VisibilityState;
+  /** Initial column pinning state. This also acts as the "anchors" for normalization. */
+  defaultColumnPinning?: ColumnPinningState;
+  /** Initial column sizing state. */
+  defaultColumnSizing?: ColumnSizingState;
+  /** Initial grouping state (column ids to group by). */
+  defaultGrouping?: GroupingState;
+  /** Initial expansion state. Default: `true` (all groups expanded). */
+  defaultExpanded?: ExpandedState;
+
+  /**
+   * State persistence - wires the hook's persistable slices to the URL,
+   * localStorage, or a manual handler. The persisted blob shape is the same
+   * across modes; the mode just decides where it lives.
+   */
+  persistState?: PersistState;
+}
+
+export interface UseDataTableState<TData extends { id: string }> {
+  filterValues: Record<string, string>;
+  pagination: PaginationState;
+  sorting: SortingState;
+  rowSelection: RowSelectionState;
+  editingRowId: string | null;
+  columnOrder: ColumnOrderState;
+  columnVisibility: VisibilityState;
+  columnPinning: ColumnPinningState;
+  columnSizing: ColumnSizingState;
+  grouping: GroupingState;
+  expanded: ExpandedState;
+  /** Rows in the current page (already sliced when clientSidePagination=true) */
+  pageData: TData[];
+  /** All rows after filtering (before paging) */
+  filteredData: TData[];
+  /** IDs of selected rows */
+  selectedIds: string[];
+  /** Full row objects that are selected */
+  selectedRows: TData[];
+}
+
+export interface UseDataTableActions {
+  /** Set a single filter value (resets page to 0 automatically) */
+  setFilter: (key: string, value: string) => void;
+  /** Set multiple filter values at once (resets page to 0 automatically) */
+  setFilters: (values: Record<string, string>) => void;
+  /** Reset all filters to their default values */
+  resetFilters: () => void;
+  /** Go to a specific page index (0-based) */
+  goToPage: (index: number) => void;
+  /** Set page size (resets page to 0 automatically) */
+  setPageSize: (size: number) => void;
+  /** Clear row selection */
+  clearSelection: () => void;
+  /** Start editing a row by id (saves snapshot for cancel) */
+  startEdit: (rowId: string) => void;
+  /** Cancel editing - restores row to snapshot */
+  cancelEdit: () => void;
+  /** Confirm save - clears editing state (actual save is your responsibility) */
+  confirmSave: () => void;
+  /** Update a single field on a row (for inline editing) */
+  updateRowData: (rowId: string, columnId: string, value: unknown) => void;
+  /** Toggle visibility of a single column. */
+  toggleColumnVisibility: (columnId: string) => void;
+  /** Replace the visibility map. */
+  setColumnVisibility: (next: VisibilityState) => void;
+  /** Replace the column order. */
+  setColumnOrder: (next: ColumnOrderState) => void;
+  /** Replace the column pinning state. */
+  setColumnPinning: (next: ColumnPinningState) => void;
+  /** Replace the column sizing state. */
+  setColumnSizing: (next: ColumnSizingState) => void;
+  /** Toggle grouping on/off for a column id. */
+  toggleGrouping: (columnId: string) => void;
+  /** Replace the grouping state. */
+  setGrouping: (next: GroupingState) => void;
+  /** Replace the expansion state. */
+  setExpanded: (next: ExpandedState) => void;
+}
+
+export interface UseDataTableReturn<TData extends { id: string }> {
+  /**
+   * Spread directly onto <DataTable> - contains all wired props.
+   * Only `columns` and `filters` are omitted since those are defined by the consumer.
+   *
+   * @example
+   * <DataTable {...table.props} columns={columns} filters={filters} />
+   */
+  props: Omit<DataTableProps<TData>, "columns" | "filters" | "className">;
+  /** Current table state - use to build columns, bulk actions, etc. */
+  state: UseDataTableState<TData>;
+  /** Imperative helpers */
+  actions: UseDataTableActions;
+}
+
+// ─── Internal persist-wiring args ─────────────────────────────────────────────
+// Used by the `usePersist` helper inside `useDataTable` and the pure
+// snapshot/apply helpers in `utils.ts`.
+
+export interface PersistArgs {
+  config: PersistState | undefined;
+  filterKeys: string[];
+  filterValues: Record<string, string>;
+  setFilterValues: (next: Record<string, string>) => void;
+  pagination: PaginationState;
+  setPagination: (next: PaginationState) => void;
+  sorting: SortingState;
+  setSorting: (next: SortingState) => void;
+  columnOrder: ColumnOrderState;
+  setColumnOrder: (next: ColumnOrderState) => void;
+  columnVisibility: VisibilityState;
+  setColumnVisibility: (next: VisibilityState) => void;
+  columnPinning: ColumnPinningState;
+  setColumnPinning: (next: ColumnPinningState) => void;
+  columnSizing: ColumnSizingState;
+  setColumnSizing: (next: ColumnSizingState) => void;
+  grouping: GroupingState;
+  setGrouping: (next: GroupingState) => void;
+  expanded: ExpandedState;
+  setExpanded: (next: ExpandedState) => void;
+}
+
+// ─── Snapshot / apply helpers shape ───────────────────────────────────────────
+
+/** Inputs needed to produce a `PersistedState` snapshot from current state. */
+export interface SnapshotInput {
+  filterValues: Record<string, string>;
+  pagination: PaginationState;
+  /** Used to skip persisting pagination when both index and size are at defaults. */
+  defaultPageSize: number;
+  sorting: SortingState;
+  columnOrder: ColumnOrderState;
+  columnVisibility: VisibilityState;
+  columnPinning: ColumnPinningState;
+  columnSizing: ColumnSizingState;
+  grouping: GroupingState;
+  expanded: ExpandedState;
+}
+
+/** Setters used by `applyPersistedState` to push hydrated values back into state. */
+export interface ApplyPersistedTarget {
+  filterValues: Record<string, string>;
+  filterKeys: string[];
+  setFilterValues: (next: Record<string, string>) => void;
+  setPagination: (next: PaginationState) => void;
+  setSorting: (next: SortingState) => void;
+  setColumnOrder: (next: ColumnOrderState) => void;
+  setColumnVisibility: (next: VisibilityState) => void;
+  setColumnPinning: (next: ColumnPinningState) => void;
+  setColumnSizing: (next: ColumnSizingState) => void;
+  setGrouping: (next: GroupingState) => void;
+  setExpanded: (next: ExpandedState) => void;
+}
+
+/**
+ * Source for resolving the runtime column id from a raw `ColumnDef`. Mirrors
+ * how tanstack derives ids: explicit `id` first, then `accessorKey`. Typed
+ * structurally on the two fields actually read so callers can pass any
+ * concrete `ColumnDef<…>` without tripping tanstack's invariance on the
+ * value-type parameter.
+ */
+export interface ColumnIdSource {
+  id?: string;
+  accessorKey?: string | number | symbol;
+}