@softium/table-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,447 @@
+/**
+ * softium-ui — core type system (SPEC §3).
+ *
+ * This file is the contract. Guardrails encoded here:
+ *   - `label` (immutable, export/binding key) ≠ `labelOverride` (user-facing, display only)
+ *   - `rowId` (stable PK) ≠ `displayIndex` (per-page position) ≠ `globalIndex` (dataset position)
+ *   - no `any`; the row type `T` is inferred end-to-end via generics
+ *   - no React/DOM: cell/header renderers return a generic `TNode` (the React layer
+ *     binds `TNode = ReactNode`), so table-core stays framework-agnostic.
+ */
+type ColumnType = 'text' | 'number' | 'date' | 'boolean' | 'select' | 'custom';
+type ColumnAlign = 'left' | 'center' | 'right';
+interface ColumnDef<T, TNode = unknown> {
+    /** data-binding key (unique, immutable) */
+    key: keyof T & string;
+    /** original header text — the export/binding anchor. The user cannot change this. */
+    label: string;
+    type?: ColumnType;
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    /** grow weight: a column with flex > 0 absorbs leftover horizontal space so the
+     *  table fills its container (no empty gap on the right). 0/undefined = fixed width. */
+    flex?: number;
+    align?: ColumnAlign;
+    sortable?: boolean;
+    /** sort by a derived value instead of `row[key]` (e.g. an enum's rank). */
+    sortAccessor?: (row: T) => string | number | boolean | Date | null | undefined;
+    /** full custom comparator (ascending); overrides type/accessor. Receives raw rows. */
+    sortComparator?: (a: T, b: T) => number;
+    filterable?: boolean;
+    resizable?: boolean;
+    pinnable?: boolean;
+    hideable?: boolean;
+    /** allow inline editing of this column's cells (DataGrid). Default false. */
+    editable?: boolean;
+    /** allow copying a selected cell's value (Ctrl/Cmd+C) in a grid. Default true. */
+    copyable?: boolean;
+    /** override the exported value for this column (CSV/JSON/XML/XLSX). Defaults to
+     *  the raw cell value; dates/numbers are handled automatically otherwise. */
+    exportValue?: (row: T) => string | number | boolean | null | undefined;
+    /** custom cell renderer. Returns `TNode` so core has no React dependency. */
+    renderCell?: (ctx: CellContext<T>) => TNode;
+    renderHeader?: (ctx: HeaderContext<T, TNode>) => TNode;
+}
+type PinSide = 'left' | 'right' | null;
+interface ColumnState {
+    key: string;
+    visible: boolean;
+    order: number;
+    width?: number;
+    pinned?: PinSide;
+    /** user-chosen text alignment override (falls back to ColumnDef.align) */
+    align?: ColumnAlign;
+    /** user-renamed column header. Kept SEPARATE from `label` so data mapping never breaks. */
+    labelOverride?: string;
+}
+interface Row<T> {
+    /** stable identifier (PK). Never conflate with displayIndex. */
+    rowId: string;
+    /** 1-based position within the current page/view. Resets when the page changes. */
+    displayIndex: number;
+    /** 1-based position within the full dataset. Page-independent and unique. */
+    globalIndex: number;
+    /** the original object (immutable — never mutated by the library) */
+    data: T;
+    selected?: boolean;
+}
+interface CellContext<T> {
+    row: Row<T>;
+    column: ColumnDef<T>;
+    value: T[keyof T];
+}
+interface HeaderContext<T, TNode = unknown> {
+    column: ColumnDef<T, TNode>;
+    /** the label currently shown (labelOverride ?? label) */
+    displayLabel: string;
+}
+interface SearchState {
+    query: string;
+    /** which columns to search; 'all' or an explicit list of column keys */
+    scope: 'all' | string[];
+}
+type FilterOperator = 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'between' | 'in';
+interface Filter {
+    columnKey: string;
+    operator: FilterOperator;
+    value: unknown;
+    /** second operand for `between` */
+    value2?: unknown;
+}
+type SortDirection = 'asc' | 'desc';
+interface SortRule {
+    columnKey: string;
+    direction: SortDirection;
+}
+interface TableInput<T, TNode = unknown> {
+    data: T[];
+    columns: ColumnDef<T, TNode>[];
+    /** stable row id resolver. Falls back to a global-index string when absent. */
+    getRowId?: (row: T) => string;
+}
+interface ResolvedColumn<T, TNode = unknown> {
+    key: keyof T & string;
+    /** immutable original label */
+    label: string;
+    /** what the header should display: labelOverride ?? label */
+    displayLabel: string;
+    type: ColumnType;
+    align: ColumnAlign;
+    order: number;
+    visible: boolean;
+    pinned: PinSide;
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    flex?: number;
+    sortable: boolean;
+    filterable: boolean;
+    resizable: boolean;
+    pinnable: boolean;
+    hideable: boolean;
+    editable: boolean;
+    copyable: boolean;
+    renderCell?: (ctx: CellContext<T>) => TNode;
+    renderHeader?: (ctx: HeaderContext<T, TNode>) => TNode;
+    /** the originating definition (escape hatch for advanced renderers) */
+    def: ColumnDef<T, TNode>;
+}
+
+/**
+ * adaptArray — the simplest ERP response: a plain array of row objects.
+ *
+ *   const data = adaptArray<Employee>(raw); // raw: [ {...}, {...} ]
+ *
+ * Columns are supplied separately by the developer. This only normalizes/validates
+ * the data array.
+ */
+declare function adaptArray<T>(raw: unknown): T[];
+
+/**
+ * adaptPaginated — the common `{ data, total, page, pageSize }` wrapper.
+ *
+ *   const { data, total, page, pageSize } =
+ *     adaptPaginated<Employee>(raw, { dataKey: 'data' });
+ *
+ * Key names are configurable for legacy ERP servers (e.g. rows/count/pageNo).
+ */
+interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+interface AdaptPaginatedOptions {
+    dataKey?: string;
+    totalKey?: string;
+    pageKey?: string;
+    pageSizeKey?: string;
+}
+declare function adaptPaginated<T>(raw: unknown, options?: AdaptPaginatedOptions): PaginatedResult<T>;
+
+/**
+ * adaptDynamicSchema — legacy ERP that sends column definitions alongside rows
+ * (the table shape is decided by the server at runtime, not hardcoded in the app).
+ *
+ *   const { columns, data } = adaptDynamicSchema(raw, {
+ *     columnsKey: 'columns', rowsKey: 'rows', fieldKey: 'field', labelKey: 'label',
+ *   });
+ *
+ * Produces real `ColumnDef`s so the rest of the library treats dynamic and static
+ * schemas identically.
+ */
+
+interface DynamicSchemaResult<T> {
+    columns: ColumnDef<T>[];
+    data: T[];
+}
+interface AdaptDynamicSchemaOptions {
+    /** key under which the server lists column descriptors. Default 'columns'. */
+    columnsKey?: string;
+    /** key under which the server lists row objects. Default 'rows'. */
+    rowsKey?: string;
+    /** descriptor field holding the data-binding key. Default 'field'. */
+    fieldKey?: string;
+    /** descriptor field holding the header text. Default 'label'. */
+    labelKey?: string;
+    /** descriptor field holding the column type (optional). Default 'type'. */
+    typeKey?: string;
+}
+declare function adaptDynamicSchema<T = Record<string, unknown>>(raw: unknown, options?: AdaptDynamicSchemaOptions): DynamicSchemaResult<T>;
+
+/**
+ * Column derivation (SPEC §2): the final render columns are a pure composition of
+ * the immutable `columnDefs` (developer) and the mutable `columnState` (end user).
+ *
+ *   renderColumns = columnDefs
+ *     .map(def => merge(def, columnState[def.key]))
+ *     .filter(c => c.visible)
+ *     .sort by (pinned group, order)
+ *
+ * `columnDefs` and the input `columnState` are never mutated.
+ */
+
+/** Build the default view state for a set of column defs (order = declaration order). */
+declare function createInitialColumnState<T, TNode>(defs: ColumnDef<T, TNode>[]): ColumnState[];
+/**
+ * Reconcile a persisted (e.g. localStorage) columnState against the current defs:
+ *   - keep stored entries for columns that still exist
+ *   - drop stored entries for columns that no longer exist
+ *   - append defaults for newly added columns (so a schema change never breaks)
+ *
+ * This makes persistence forward-compatible with evolving column definitions.
+ */
+declare function reconcileColumnState<T, TNode>(defs: ColumnDef<T, TNode>[], stored: ColumnState[]): ColumnState[];
+/**
+ * Merge defs with state, drop hidden columns, and order them.
+ * Ordering: left-pinned first, then unpinned, then right-pinned; `order` breaks ties.
+ */
+declare function resolveColumns<T, TNode>(defs: ColumnDef<T, TNode>[], state: ColumnState[]): ResolvedColumn<T, TNode>[];
+
+/**
+ * Column operations (SPEC §3, §10): every user gesture on the table — hide, reorder,
+ * resize, pin, rename — is a pure transformation of `ColumnState[]` into a NEW array.
+ *
+ * Invariants enforced by these functions:
+ *   - `columnDefs` and `data` are never referenced here (this layer only knows view state)
+ *   - the input `state` array is never mutated; a fresh array is always returned
+ *   - renaming writes `labelOverride`, NEVER the immutable `label`
+ */
+
+/** Apply a partial patch to one column's state, returning a new array. */
+declare function patchColumnState(state: ColumnState[], key: string, patch: Partial<Omit<ColumnState, 'key'>>): ColumnState[];
+declare function setColumnVisible(state: ColumnState[], key: string, visible: boolean): ColumnState[];
+declare function setColumnPinned(state: ColumnState[], key: string, pinned: PinSide): ColumnState[];
+declare function setColumnWidth(state: ColumnState[], key: string, width: number): ColumnState[];
+declare function setColumnAlign(state: ColumnState[], key: string, align: ColumnAlign): ColumnState[];
+/**
+ * Rename a column. An empty/whitespace override clears back to the original `label`.
+ * The original `label` lives on the ColumnDef and is untouched.
+ */
+declare function setColumnLabelOverride(state: ColumnState[], key: string, labelOverride: string | undefined): ColumnState[];
+/**
+ * Reorder so that `activeKey` lands where `overKey` currently sits (DnD semantics),
+ * then renumber `order` densely (0..n-1) in the resulting sequence.
+ */
+declare function moveColumn(state: ColumnState[], activeKey: string, overKey: string): ColumnState[];
+
+/**
+ * Sorting (SPEC §5): single and multi-column. Pure — returns a NEW array, never
+ * mutates the input. JS sort is stable, so a single comparator that walks the rule
+ * list in priority order yields correct multi-sort with stable ties.
+ */
+
+/** Per-column sort configuration. */
+interface ColumnSort<T> {
+    type?: ColumnType;
+    /** sort by a derived value instead of row[key] */
+    accessor?: (row: T) => unknown;
+    /** full custom comparator (ascending); overrides type/accessor */
+    comparator?: (a: T, b: T) => number;
+}
+type SortLookup<T> = (columnKey: string) => ColumnSort<T> | undefined;
+/**
+ * Sort by the active rules. `getSort` supplies each column's sort behavior:
+ *   - comparator: full custom (ascending) comparator over rows
+ *   - accessor:   sort by a derived value instead of row[key]
+ *   - type:       typed comparison (number/date/boolean/text)
+ */
+declare function sortRows<T>(data: T[], rules: SortRule[], getSort: SortLookup<T>): T[];
+/**
+ * Cycle a column's sort for click-to-sort headers: none → asc → desc → none.
+ * `multi` keeps existing rules (appending/updating this column); otherwise this
+ * column becomes the sole sort.
+ */
+declare function toggleSort(rules: SortRule[], columnKey: string, multi?: boolean): SortRule[];
+
+/**
+ * Column filters (SPEC §3, §5): structured per-column data queries. Distinct from
+ * global search (which is free-text UX). Pure — returns a NEW filtered array.
+ */
+
+declare function matchesFilter(value: unknown, filter: Filter, type?: ColumnType): boolean;
+type TypeLookup = (columnKey: string) => ColumnType | undefined;
+/** Apply all filters with AND semantics. An empty filter list returns the input as-is. */
+declare function applyFilters<T>(data: T[], filters: Filter[], getType: TypeLookup): T[];
+
+/**
+ * Global search (SPEC §3): free-text UX matching, kept deliberately separate from
+ * structured column filters. Case-insensitive substring match over the column scope.
+ * Pure — returns a NEW array (or the input untouched when the query is empty).
+ */
+
+declare function applySearch<T>(data: T[], search: SearchState, allKeys: string[]): T[];
+
+/**
+ * Pagination (SPEC §5, §6). Pure slicing over the already filtered/searched/sorted
+ * data. The companion `offset` lets buildRows keep `globalIndex` dataset-absolute
+ * while `displayIndex` resets per page.
+ */
+declare function getPageCount(total: number, pageSize: number): number;
+/** Clamp a requested page into the valid 1..pageCount range. */
+declare function clampPage(page: number, total: number, pageSize: number): number;
+interface PageSlice<T> {
+    /** the rows for this page */
+    items: T[];
+    /** number of rows preceding this page in the full set — pass to buildRows */
+    offset: number;
+    page: number;
+    pageCount: number;
+}
+declare function paginate<T>(data: T[], page: number, pageSize: number): PageSlice<T>;
+
+/**
+ * Pivot / cross-tab (AG-Grid style). Pure — groups `data` by one or more row
+ * fields and column fields, aggregating a value field into a matrix with row /
+ * column / grand totals. The original data is never mutated.
+ *
+ * v1: row + column fields are composite keys (joined paths); a single value field
+ * with sum / count / avg / min / max.
+ */
+type PivotAggregate = 'sum' | 'count' | 'avg' | 'min' | 'max';
+interface PivotConfig<T> {
+    rows: (keyof T & string)[];
+    columns: (keyof T & string)[];
+    value: keyof T & string;
+    aggregate: PivotAggregate;
+}
+interface PivotResult {
+    rowFields: string[];
+    columnFields: string[];
+    value: string;
+    aggregate: PivotAggregate;
+    /** ordered row-key paths (one entry per row-field value combination) */
+    rowKeys: string[][];
+    /** ordered column-key paths */
+    columnKeys: string[][];
+    /** values[rowIndex][colIndex] — null when a cell has no data */
+    values: (number | null)[][];
+    rowTotals: (number | null)[];
+    columnTotals: (number | null)[];
+    grandTotal: number | null;
+}
+declare function pivot<T>(data: T[], config: PivotConfig<T>): PivotResult;
+
+/**
+ * Row indexing (SPEC §3).
+ *
+ * Three distinct numbers, never conflated:
+ *   - rowId       stable PK (from getRowId, or a global-index fallback string)
+ *   - displayIndex 1-based position within the current page/view slice
+ *   - globalIndex  1-based position within the full dataset (page-independent)
+ *
+ * The original row objects are referenced, never mutated.
+ */
+
+interface BuildRowsOptions<T> {
+    /** stable id resolver; falls back to the globalIndex as a string */
+    getRowId?: (row: T) => string;
+    /** how many rows precede this slice in the full dataset (for pagination). Default 0. */
+    offset?: number;
+}
+/**
+ * Turn a (possibly paginated) data slice into indexed rows.
+ * Pass the full array with offset 0 for the non-paginated case.
+ */
+declare function buildRows<T>(data: T[], options?: BuildRowsOptions<T>): Row<T>[];
+
+/** a single exportable cell value */
+type ExportCell = string | number | boolean | null | undefined;
+/** a rectangular export view: header labels + a matrix of stringifiable cells */
+interface ExportTable {
+    headers: string[];
+    rows: ExportCell[][];
+}
+/** the supported export formats */
+type ExportFormat = 'csv' | 'json' | 'xml' | 'xlsx';
+
+interface CsvOptions {
+    /** field delimiter. Default ",". Use "\t" for TSV. */
+    delimiter?: string;
+}
+/** Serialize an export table to RFC-4180 CSV (CRLF line breaks). */
+declare function toCSV(table: ExportTable, options?: CsvOptions): string;
+
+interface JsonOptions {
+    /** pretty-print with 2-space indent. Default true. */
+    pretty?: boolean;
+}
+/** Serialize an export table to a JSON array of header-keyed record objects. */
+declare function toJSON(table: ExportTable, options?: JsonOptions): string;
+
+interface XmlOptions {
+    /** wrapping root element. Default "rows". */
+    rootTag?: string;
+    /** per-row element. Default "row". */
+    rowTag?: string;
+}
+/** XML-escape a text value for element content / attributes. */
+declare function escapeXml(value: ExportCell): string;
+/** Serialize an export table to XML: <root><row><header>value</header>…</row></root>. */
+declare function toXML(table: ExportTable, options?: XmlOptions): string;
+
+interface XlsxOptions {
+    /** worksheet tab name. Default "Sheet1". Excel caps names at 31 chars. */
+    sheetName?: string;
+}
+/**
+ * Serialize an export table to a real .xlsx workbook (OOXML zip) as raw bytes —
+ * no dependencies. Numeric cells are written as numbers; everything else as
+ * inline strings. Open the returned bytes in Excel / Numbers / Google Sheets.
+ */
+declare function toXLSX(table: ExportTable, options?: XlsxOptions): Uint8Array;
+
+/**
+ * Minimal store-only (uncompressed) ZIP writer — just enough to assemble a
+ * valid .xlsx (an OOXML zip) with no dependencies. Files are stored with
+ * method 0 (no compression), which Excel/Numbers/LibreOffice all open fine.
+ */
+interface ZipEntry {
+    name: string;
+    data: Uint8Array;
+}
+/** Build a ZIP archive (stored, no compression) from the given entries. */
+declare function zipStore(entries: ZipEntry[]): Uint8Array;
+
+/** MIME type + file extension for each export format. */
+declare const EXPORT_FORMAT_META: Record<ExportFormat, {
+    mime: string;
+    ext: string;
+}>;
+/**
+ * Serialize an export table to the given format. Text formats return a string;
+ * xlsx returns raw bytes (a Uint8Array). Framework-agnostic — the download
+ * itself (Blob + anchor) lives in the React layer.
+ */
+declare function serializeExport(table: ExportTable, format: ExportFormat): string | Uint8Array;
+
+/**
+ * @softium/table-core
+ *
+ * Headless core for the softium-ui Table.
+ * Pure TypeScript — does not import React, DOM, or `window`.
+ */
+declare const VERSION = "0.0.0";
+
+export { type AdaptDynamicSchemaOptions, type AdaptPaginatedOptions, type BuildRowsOptions, type CellContext, type ColumnAlign, type ColumnDef, type ColumnSort, type ColumnState, type ColumnType, type CsvOptions, type DynamicSchemaResult, EXPORT_FORMAT_META, type ExportCell, type ExportFormat, type ExportTable, type Filter, type FilterOperator, type HeaderContext, type JsonOptions, type PageSlice, type PaginatedResult, type PinSide, type PivotAggregate, type PivotConfig, type PivotResult, type ResolvedColumn, type Row, type SearchState, type SortDirection, type SortLookup, type SortRule, type TableInput, VERSION, type XlsxOptions, type XmlOptions, type ZipEntry, adaptArray, adaptDynamicSchema, adaptPaginated, applyFilters, applySearch, buildRows, clampPage, createInitialColumnState, escapeXml, getPageCount, matchesFilter, moveColumn, paginate, patchColumnState, pivot, reconcileColumnState, resolveColumns, serializeExport, setColumnAlign, setColumnLabelOverride, setColumnPinned, setColumnVisible, setColumnWidth, sortRows, toCSV, toJSON, toXLSX, toXML, toggleSort, zipStore };