@multiplatform.one/table 6.0.0

package/src/index.ts

@@ -0,0 +1,137 @@
+/**
+ * @multiplatform.one/table
+ *
+ * Advanced table components with filtering, pagination, sorting, and URL state management.
+ */
+
+// Export types
+export type * from "./types";
+
+// Export hooks - main entry point
+export { useDataTable, createUrlStrategy } from "./hooks/useDataTable";
+export { useRowSelection } from "./components/DataTableBulkActions";
+
+// Export hooks - decomposed feature hooks for advanced compositions
+export { useTableFiltering } from "./hooks/useTableFiltering";
+export type { UseTableFilteringOptions, UseTableFilteringReturn } from "./hooks/useTableFiltering";
+export { useTableSorting } from "./hooks/useTableSorting";
+export type { UseTableSortingOptions, UseTableSortingReturn } from "./hooks/useTableSorting";
+export { useTablePagination } from "./hooks/useTablePagination";
+export type {
+  UseTablePaginationOptions,
+  UseTablePaginationReturn,
+} from "./hooks/useTablePagination";
+export { useTableSearch } from "./hooks/useTableSearch";
+export type { UseTableSearchOptions, UseTableSearchReturn } from "./hooks/useTableSearch";
+export { useTableSelection } from "./hooks/useTableSelection";
+export type { UseTableSelectionOptions, UseTableSelectionReturn } from "./hooks/useTableSelection";
+export { useTableGrouping } from "./hooks/useTableGrouping";
+export type { UseTableGroupingOptions, UseTableGroupingReturn } from "./hooks/useTableGrouping";
+export { useTableUrlSync } from "./hooks/useTableUrlSync";
+export type { UseTableUrlSyncOptions, UseTableUrlSyncReturn } from "./hooks/useTableUrlSync";
+export { useTableColumnPinning } from "./hooks/useTableColumnPinning";
+export type {
+  UseTableColumnPinningOptions,
+  UseTableColumnPinningReturn,
+} from "./hooks/useTableColumnPinning";
+export { useTableViews } from "./hooks/useTableViews";
+export type { UseTableViewsOptions, UseTableViewsReturn } from "./hooks/useTableViews";
+export { useTableKeyboard } from "./hooks/useTableKeyboard";
+export type { UseTableKeyboardOptions, UseTableKeyboardReturn } from "./hooks/useTableKeyboard";
+export { useDragScroll } from "./hooks/useDragScroll";
+
+// Export components - compound DataTable
+export { DataTable } from "./components/DataTable";
+export { DataTableVirtualized } from "./components/DataTable/DataTableVirtualized";
+export { DataTableContext } from "./components/DataTable/DataTableContext";
+export {
+  DataTableStateContext,
+  useDataTableState,
+} from "./components/DataTable/DataTableStateContext";
+export type { DataTableStateContextValue } from "./components/DataTable/DataTableStateContext";
+export type { DataTableRootProps } from "./components/DataTable/DataTableRoot";
+
+// Export components - SimpleTable (lightweight, zero TanStack Table dependency)
+export { SimpleTable } from "./components/SimpleTable";
+export type { SimpleTableProps, SimpleTableColumn } from "./components/SimpleTable";
+
+// Export sub-components (for standalone usage)
+export { DataTableToolbar } from "./components/DataTableToolbar";
+export { DataTableFilters } from "./components/DataTableFilters";
+export { DataTablePagination } from "./components/DataTablePagination";
+export { DataTableViewOptions } from "./components/DataTableViewOptions";
+export { DataTableBulkActions } from "./components/DataTableBulkActions";
+export { DataTableExport, type ExportOptions } from "./components/DataTableExport";
+export {
+  DataTableSearch,
+  useFullTextSearch,
+  type SearchOptions,
+} from "./components/DataTableSearch";
+export {
+  DataTableDateFilter,
+  useDateFilter,
+  type DateFilterValue,
+} from "./components/DataTableDateFilter";
+export {
+  DataTableGrouping,
+  DataTableGroupingConfig,
+  type GroupingConfig,
+  useGrouping,
+  groupData,
+} from "./components/DataTableGrouping";
+export {
+  DataTableColumnPinning,
+  useColumnPinning,
+  type StickyColumnProps,
+  type PinnedIndicatorProps,
+} from "./components/DataTableColumnPinning";
+export {
+  Table,
+  TableCellContext,
+  useIsInTableCell,
+  useTableCellContext,
+} from "@multiplatform.one/table-primitives";
+export type {
+  TableBodyProps,
+  TableCaptionProps,
+  TableCellContextValue,
+  TableCellProps,
+  TableFootProps,
+  TableHeadProps,
+  TableHeaderCellProps,
+  TableProps,
+  TableRowProps,
+} from "@multiplatform.one/table-primitives";
+
+export { TableInput, type TableInputProps } from "./components/TableInput";
+export { ChildTable, type ChildTableProps } from "./components/ChildTable";
+export { DataTableCell, type DataTableCellProps } from "./components/DataTableCell";
+export { FilterManager, type FilterManagerProps } from "./components/FilterManager";
+export {
+  SavedFilterDropdown,
+  type SavedFilterDropdownProps,
+} from "./components/SavedFilterDropdown";
+
+// Export hooks - saved filters
+export {
+  useSavedFilters,
+  type SavedFilter,
+  type ParsedFilter,
+  type SavedFiltersStorage,
+  type UseSavedFiltersOptions,
+  type SavedFiltersHook,
+} from "./hooks/useSavedFilters";
+
+// Export utilities
+export * from "./utils/filterUtils";
+export * from "./utils/urlStateUtils";
+
+// Re-export TanStack Table types for convenience
+export type {
+  ColumnDef,
+  Table as TanStackTable,
+  Row,
+  Cell,
+  Header,
+  Column,
+} from "@tanstack/react-table";

package/src/shims/primitives.ts

@@ -0,0 +1,15 @@
+/** Back-compat: `@multiplatform.one/table/primitives` → `@multiplatform.one/table-primitives` */
+export {
+  Table,
+  TableCellContext,
+  useIsInTableCell,
+  useTableCellContext,
+  type TableBodyProps,
+  type TableCaptionProps,
+  type TableCellProps,
+  type TableFootProps,
+  type TableHeadProps,
+  type TableHeaderCellProps,
+  type TableProps,
+  type TableRowProps,
+} from "@multiplatform.one/table-primitives";

package/src/shims/tableCellContext.ts

@@ -0,0 +1,7 @@
+/** Back-compat: `@multiplatform.one/table/tableCellContext` → `@multiplatform.one/table-primitives/tableCellContext` */
+export {
+  TableCellContext,
+  useIsInTableCell,
+  useTableCellContext,
+  type TableCellContextValue,
+} from "@multiplatform.one/table-primitives/tableCellContext";

package/src/types.ts

@@ -0,0 +1,492 @@
+import type { ColumnDef, ColumnFiltersState, Row } from "@tanstack/react-table";
+import type { UrlStateStrategy } from "./hooks/useDataTable";
+import type { AnyFormApi } from "@multiplatform.one/forms";
+
+// Core Data Types
+
+export type DataTableData = Record<string, any>;
+
+/**
+ * Field types - the UI component used to render/edit a cell.
+ * If no field is specified on a column, defaults to "input" (read-only).
+ */
+export type DataTableField =
+  // Text inputs
+  | "input"
+  | "textarea"
+  | "mentioninput"
+  // Numeric inputs
+  | "stepper"
+  | "slider"
+  // Selection inputs
+  | "select"
+  | "combobox"
+  | "radiogroup"
+  | "togglegroup"
+  // Boolean inputs
+  | "checkbox"
+  | "switch"
+  // Date/Time inputs
+  | "datepicker"
+  | "datetimepicker"
+  | "timepicker"
+  | "daterangepicker"
+  | "multidatepicker"
+  | "duration"
+  // Special inputs
+  | "colorpicker"
+  | "phoneinput"
+  | "otp"
+  | "barcode"
+  // Visual/feedback
+  | "rating"
+  | "progress"
+  // File inputs
+  | "fileupload"
+  | "image"
+  | "signature"
+  | "geolocation"
+  // Rich text
+  | "richtexteditor"
+  | "markdowneditor"
+  | "codeeditor"
+  // Custom
+  | "custom";
+
+/**
+ * Field-specific props passed to the underlying field component.
+ * Use this for options, validation, formatters, etc.
+ */
+export interface DataTableFieldProps {
+  /** Options for select/combobox/radiogroup/togglegroup fields */
+  options?: Array<{ label: string; value: any }>;
+  /** Placeholder text */
+  placeholder?: string;
+  /** Min value for number/slider fields */
+  min?: number;
+  /** Max value for number/slider fields */
+  max?: number;
+  /** Step for number/slider fields */
+  step?: number;
+  /** Precision for numeric fields */
+  precision?: number;
+  /** Currency code for currency fields */
+  currency?: string;
+  /** Doctype for link fields (Frappe) */
+  doctype?: string;
+  /** Default country for phone input (ISO 3166-1 alpha-2) */
+  defaultCountry?: string;
+  /** Number of OTP digits */
+  otpLength?: number;
+  /** Mentions data for mention input */
+  mentions?: Array<{ id: string; display: string }>;
+  /** Max stars for rating (default 5) */
+  maxRating?: number;
+  /** Date format for date pickers */
+  dateFormat?: string;
+  /** Time format (12h or 24h) for time pickers */
+  timeFormat?: "12h" | "24h";
+  /** Min date for date pickers */
+  minDate?: Date;
+  /** Max date for date pickers */
+  maxDate?: Date;
+  /**
+   * For daterange in 2-column mode: the accessor key of the linked column.
+   * When set, this column acts as the "from" date and the linked column acts as "to" date.
+   * Both columns share a single DateRangePicker UI.
+   */
+  dateRangeLinkedColumn?: string;
+  /** Whether this is the "to" column of a linked date range (internal use) */
+  dateRangeIsEndColumn?: boolean;
+  /** Allow multiple selection for togglegroup */
+  allowMultiple?: boolean;
+  /** Custom render function for 'custom' fieldType */
+  render?: (value: any, row: any, onChange: (value: any) => void) => React.ReactNode;
+  /** Any additional props to pass to the field component */
+  [key: string]: any;
+}
+
+export type DataTableColumn<TData extends DataTableData = DataTableData> = ColumnDef<TData> & {
+  accessorKey?: keyof TData;
+  filterable?: boolean;
+  sortable?: boolean;
+  searchable?: boolean;
+  hidden?: boolean;
+  width?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  /**
+   * UI component type for rendering/editing cells in this column.
+   * If not specified, defaults to "input" (read-only text display).
+   *
+   * Examples: "input", "stepper", "slider", "checkbox", "switch",
+   * "select", "combobox", "datepicker", "rating", etc.
+   */
+  field?: DataTableField;
+  /**
+   * Props passed to the field component (options, placeholder, min/max, etc.)
+   */
+  fieldProps?: DataTableFieldProps;
+  /** Custom validation function for cell values. Return error message or undefined. */
+  validate?: (value: any, row: TData) => string | undefined;
+};
+
+// Filter System Types
+
+export type FilterOperator =
+  // Text Filters
+  | "contains"
+  | "doesNotContain"
+  | "is"
+  | "isNot"
+  | "startsWith"
+  | "endsWith"
+  | "isEmpty"
+  | "isNotEmpty"
+  // Number Filters
+  | "is"
+  | "isNot"
+  | "isLessThan"
+  | "isGreaterThan"
+  | "isLessThanOrEqual"
+  | "isGreaterThanOrEqual"
+  | "isBetween"
+  | "isNotBetween"
+  // Date Filters
+  | "is"
+  | "isNot"
+  | "isBefore"
+  | "isAfter"
+  | "isOnOrBefore"
+  | "isOnOrAfter"
+  | "isBetween"
+  | "isNotBetween"
+  // Option Filters
+  | "is"
+  | "isNot"
+  | "isAnyOf"
+  | "isNoneOf"
+  // Boolean Filters
+  | "is"
+  | "isNot";
+
+export interface FilterValue {
+  operator: FilterOperator;
+  value: any;
+  values?: any[]; // For multi-value operators like "isAnyOf"
+}
+
+export interface TableFilter {
+  id: string;
+  columnId: string;
+  value: FilterValue;
+  label?: string; // Human-readable label for the filter
+}
+
+export interface FacetedFilterOption {
+  label: string;
+  value: string | number | boolean;
+  count: number; // Number of items matching this option
+}
+
+// Pagination Types
+
+export interface TablePagination {
+  pageIndex: number;
+  pageSize: number;
+}
+
+export interface TablePaginationState extends TablePagination {
+  totalCount?: number;
+  totalPages?: number;
+  hasNextPage?: boolean;
+  hasPreviousPage?: boolean;
+}
+
+// Sorting Types
+
+export interface TableSorting {
+  id: string;
+  desc: boolean;
+}
+
+// View & Column Management Types
+
+export interface ColumnView {
+  id: string;
+  visible: boolean;
+  width?: number;
+  order: number;
+}
+
+export interface TableView {
+  id: string;
+  name: string;
+  columns: Record<string, ColumnView>;
+  filters: TableFilter[];
+  sorting: TableSorting[];
+  pagination: TablePagination;
+  searchQuery?: string;
+}
+
+// Main Table State Type
+
+export interface DataTableState {
+  // Data
+  data: DataTableData[];
+  columns: DataTableColumn[];
+
+  // State
+  pagination: TablePaginationState;
+  sorting: TableSorting[];
+  filters: TableFilter[];
+  columnFilters: ColumnFiltersState;
+  globalFilter?: string;
+
+  // Column Management
+  columnVisibility: Record<string, boolean>;
+  columnOrder: string[];
+  columnSizing: Record<string, number>;
+
+  // Views
+  views?: TableView[];
+  activeViewId?: string;
+
+  // Metadata
+  isLoading?: boolean;
+  error?: string;
+  totalCount?: number;
+
+  // URL State (for persistence)
+  urlState?: {
+    page?: number;
+    pageSize?: number;
+    sort?: string;
+    filters?: string;
+    search?: string;
+    view?: string;
+  };
+}
+
+// Component Props Types
+
+export interface DataTableProps<TData extends DataTableData = DataTableData> {
+  data: TData[];
+  columns: DataTableColumn<TData>[];
+
+  // State Management
+  initialState?: Partial<DataTableState>;
+  onStateChange?: (state: DataTableState) => void;
+
+  // URL State Integration
+  syncWithUrl?: boolean;
+  urlDebounceMs?: number;
+  urlStrategy?: UrlStateStrategy;
+
+  // Server-side Features
+  manualFiltering?: boolean;
+  manualPagination?: boolean;
+  manualSorting?: boolean;
+
+  // Features
+  enableFiltering?: boolean;
+  enableSorting?: boolean;
+  enablePagination?: boolean;
+  enableColumnVisibility?: boolean;
+  enableColumnOrdering?: boolean;
+  enableColumnResizing?: boolean;
+  enableGlobalSearch?: boolean;
+  enableViews?: boolean;
+
+  // Column Layout
+  /**
+   * How columns are sized and whether table scrolls horizontally.
+   * - 'equal': All columns equal width, no horizontal scroll (default)
+   * - 'auto': Content-based width, last column fills remainder, squishes if needed
+   * - 'scroll': Content-based width, horizontal scroll when content exceeds container
+   */
+  columnLayout?: "equal" | "auto" | "scroll";
+
+  // Virtualization (Phase 3)
+  /** Use virtual scrolling for table body. Requires virtualizationHeight when true. */
+  enableVirtualization?: boolean;
+  /** Height (px) of scrollable body when enableVirtualization is true. Required when enabled. */
+  virtualizationHeight?: number;
+  /** Overscan count for virtualizer. Default 5. */
+  virtualizationOverscan?: number;
+
+  // Row expansion (Phase 4)
+  /** Enable expandable sub-rows. Requires getSubRows or subRows in row data. */
+  enableRowExpansion?: boolean;
+  /** Optional renderer for expanded sub-row content. */
+  renderSubComponent?: (row: Row<TData>) => React.ReactNode;
+  /** Custom accessor for child rows. Defaults to (row) => row.subRows */
+  getSubRows?: (row: TData) => TData[] | undefined;
+
+  // Column pinning (Phase 5)
+  /** Enable column pinning (left/right). Integrates DataTableColumnPinning. */
+  enableColumnPinning?: boolean;
+  /** Max columns per side (left/right) when pinning. Default 3. */
+  maxPinnedColumns?: number;
+
+  // Grouping
+  /**
+   * Enable row grouping. When true, rows can be grouped by column id via
+   * `table.setGrouping([...])`. Rows from `table.getRowModel()` will include
+   * group header rows (`row.getIsGrouped()` true) interleaved with leaf rows.
+   */
+  enableGrouping?: boolean;
+
+  // Keyboard navigation (Phase 6)
+  /** Enable Excel-like keyboard navigation. */
+  enableKeyboardNavigation?: boolean;
+
+  // Cell editing - cells are always fields, this controls behavior
+  /**
+   * Read-only mode: all cells display values but cannot be edited.
+   * Fields render without interactivity (no focus, no input).
+   */
+  readOnly?: boolean;
+  /**
+   * Callback when any cell value changes. Return false to reject the change.
+   * Called for every cell edit in standalone mode.
+   */
+  onCellChange?: (
+    rowIndex: number,
+    columnId: string,
+    value: any,
+    previousValue: any,
+  ) => boolean | void | Promise<boolean | void>;
+
+  // Form integration (alternative to data + onDataChange)
+  /**
+   * Form field name for TanStack Form binding (e.g., "items").
+   * When provided with form, data is read from form state.
+   */
+  name?: string;
+  /**
+   * TanStack Form instance. When provided with name, enables form binding.
+   */
+  form?: AnyFormApi;
+
+  // Row management
+  /** Show row number column. Default: false */
+  showRowNumbers?: boolean;
+  /** Show add row button. Default: false. Ignored when readOnly. */
+  showAddRow?: boolean;
+  /** Show delete button per row. Default: false. Ignored when readOnly. */
+  showDeleteRow?: boolean;
+  /** Minimum number of rows. Prevents deletion below this. Default: 0 */
+  minRows?: number;
+  /** Maximum number of rows. Prevents adding above this. */
+  maxRows?: number;
+  /** Default values for new rows when adding */
+  defaultRow?: Partial<TData>;
+  /** Callback when rows are added/deleted (standalone mode) */
+  onDataChange?: (data: TData[]) => void;
+
+  // Manual pagination metadata (Phase 7) - for server-side when manualPagination is true
+  /** Total row count from server for pagination UI. */
+  rowCount?: number;
+  /** Total page count from server. If omitted, derived from rowCount and pageSize. */
+  pageCount?: number;
+
+  // Customization
+  renderToolbar?: (props: DataTableToolbarProps) => React.ReactNode;
+  renderPagination?: (props: DataTablePaginationProps) => React.ReactNode;
+  renderFilters?: (props: DataTableFiltersProps) => React.ReactNode;
+
+  // Styling
+  className?: string;
+  size?: "sm" | "md" | "lg";
+
+  // Accessibility
+  "aria-label"?: string;
+  "aria-describedby"?: string;
+}
+
+export interface DataTableToolbarProps {
+  globalFilter: string;
+  onGlobalFilterChange: (value: string) => void;
+  onClearFilters: () => void;
+  onSaveView: (name: string) => void;
+  onLoadView: (viewId: string) => void;
+  views?: TableView[];
+  activeViewId?: string;
+  size?: string;
+  compact?: boolean;
+}
+
+export interface DataTableFiltersProps {
+  filters: TableFilter[];
+  onFiltersChange: (filters: TableFilter[]) => void;
+  onAddFilter: (filter: Omit<TableFilter, "id">) => void;
+  onRemoveFilter: (filterId: string) => void;
+  onClearFilters: () => void;
+  availableColumns: Array<{
+    id: string;
+    label: string;
+    type: "text" | "number" | "date" | "boolean" | "select";
+    options?: FacetedFilterOption[];
+  }>;
+}
+
+export interface DataTablePaginationProps {
+  /** Pagination state. When manualPagination is true, totalCount/totalPages come from rowCount/pageCount. */
+  pagination: TablePaginationState;
+  onPaginationChange: (pagination: TablePagination) => void;
+  pageSizeOptions?: number[];
+}
+
+// Hook Types
+
+export interface UseDataTableOptions<TData extends DataTableData = DataTableData> extends Omit<
+  DataTableProps<TData>,
+  "data" | "columns"
+> {
+  data?: TData[];
+  columns?: DataTableColumn<TData>[];
+}
+
+export interface UseDataTableReturn<TData extends DataTableData = DataTableData> {
+  table: any; // TanStack Table instance
+  state: DataTableState;
+  actions: {
+    setGlobalFilter: (value: string) => void;
+    setFilters: (filters: TableFilter[]) => void;
+    addFilter: (filter: Omit<TableFilter, "id">) => void;
+    removeFilter: (filterId: string) => void;
+    clearFilters: () => void;
+    setPagination: (pagination: TablePagination) => void;
+    setSorting: (sorting: TableSorting[]) => void;
+    toggleColumnVisibility: (columnId: string) => void;
+    setColumnOrder: (order: string[]) => void;
+    setColumnSizing: (sizing: Record<string, number>) => void;
+    saveView: (name: string) => void;
+    loadView: (viewId: string) => void;
+    resetToDefault: () => void;
+    /** For row expansion: set which rows are expanded. Only present when enableRowExpansion is true. */
+    setExpanded?: (expanded: Record<string, boolean>) => void;
+  };
+  computed: {
+    filteredData: TData[];
+    paginatedData: TData[];
+    totalPages: number;
+    hasActiveFilters: boolean;
+    activeFilterCount: number;
+  };
+}
+
+// Utility Types
+
+export type DataTableColumnType = "text" | "number" | "date" | "boolean" | "select";
+
+export interface DataTableColumnConfig {
+  type: DataTableColumnType;
+  filterable: boolean;
+  sortable: boolean;
+  searchable: boolean;
+  width?: number;
+  minWidth?: number;
+  maxWidth?: number;
+}