@krizaka/ui 2.10.0 → 3.1.0

package/dist/data-table.d.ts

@@ -1,9 +1,70 @@
+import * as _tanstack_react_table from '@tanstack/react-table';
+import { RowData, ReactTable } from '@tanstack/react-table';
 import * as tailwind_variants from 'tailwind-variants';
 import * as React from 'react';
 
+declare const features: {
+    columnFilteringFeature: _tanstack_react_table.TableFeature;
+    filteredRowModel: (table: _tanstack_react_table.Table<any, any>) => () => _tanstack_react_table.RowModel<any, any>;
+    columnFacetingFeature: _tanstack_react_table.TableFeature;
+    facetedRowModel: (table: _tanstack_react_table.Table<any, any>, columnId: string) => () => _tanstack_react_table.RowModel<any, any>;
+    facetedUniqueValues: (table: _tanstack_react_table.Table<_tanstack_react_table.TableFeatures, any>, columnId: string) => () => Map<any, number>;
+    facetedMinMaxValues: (table: _tanstack_react_table.Table<_tanstack_react_table.TableFeatures, any>, columnId: string) => () => undefined | [number, number];
+    columnGroupingFeature: _tanstack_react_table.TableFeature;
+    groupedRowModel: (table: _tanstack_react_table.Table<any, any>) => () => _tanstack_react_table.RowModel<any, any>;
+    rowSortingFeature: _tanstack_react_table.TableFeature;
+    sortedRowModel: (table: _tanstack_react_table.Table<any, any>) => () => _tanstack_react_table.RowModel<any, any>;
+    rowExpandingFeature: _tanstack_react_table.TableFeature;
+    expandedRowModel: (table: _tanstack_react_table.Table<any, any>) => () => _tanstack_react_table.RowModel<any, any>;
+    rowPaginationFeature: _tanstack_react_table.TableFeature;
+    paginatedRowModel: (table: _tanstack_react_table.Table<any, any>) => () => _tanstack_react_table.RowModel<any, any>;
+    rowSelectionFeature: _tanstack_react_table.TableFeature;
+    columnVisibilityFeature: _tanstack_react_table.TableFeature;
+    columnPinningFeature: _tanstack_react_table.TableFeature;
+    columnSizingFeature: _tanstack_react_table.TableFeature;
+    columnResizingFeature: _tanstack_react_table.TableFeature;
+};
+type Features = typeof features;
+/** The TanStack Table instance behind a DataTable — the escape hatch of `useDataTable()`. */
+type DataTableInstance<T extends RowData> = ReactTable<Features, T>;
+/** What a cell holds for sorting, filtering and the CSV export: a string, a number, a date, a boolean, or nothing. */
+type CellValue = string | number | boolean | Date | null | undefined;
+/** A filter's value: a text (`text`), the values chosen (`facet`), or bounds, either open (`range`). */
+type FilterValue = string | readonly string[] | readonly [number | null, number | null];
+/** The filters in force, by column id. */
+type DataTableFilterState = Readonly<Record<string, FilterValue>>;
+/** The order of two values: empty last, dates and numbers by value, text in natural order ("item 2" < "item 10"). */
+declare function compareValues(a: CellValue, b: CellValue): number;
+
+type CsvColumn<T> = {
+    id: string;
+    header: string;
+    value?: (row: T) => CellValue;
+};
+/** The rows as CSV text: a header line, then one line per row, separated by `\r\n`. */
+declare function dataTableCsv<T>(rows: readonly T[], columns: readonly CsvColumn<T>[], separator?: string): string;
+
+type PaginationLabels = {
+    /** The accessible name of the navigation ("Pagination", "Pages of results"). */
+    nav: string;
+    /** The previous-page control. */
+    previous: string;
+    /** The next-page control. */
+    next: string;
+    /** The accessible name of a page number: `(3) => "Page 3"`. */
+    page: (page: number) => string;
+    /** The folded form, in a narrow container: `(3, 12) => "Page 3 of 12"`. */
+    compact: (page: number, pageCount: number) => string;
+    /** The label of the page-size select ("Rows per page"). */
+    pageSize: string;
+};
+
 declare const dataTable: tailwind_variants.TVReturnType<{
     layout: {
-        table: {};
+        table: {
+            th: string;
+            td: string;
+        };
         auto: {
             table: string;
             caption: string;
@@ -14,6 +75,7 @@ declare const dataTable: tailwind_variants.TVReturnType<{
             tr: string;
             td: string;
             select: string;
+            expander: string;
         };
         cards: {
             table: string;
@@ -25,6 +87,7 @@ declare const dataTable: tailwind_variants.TVReturnType<{
             tr: string;
             td: string;
             select: string;
+            expander: string;
         };
     };
     density: {
@@ -36,6 +99,7 @@ declare const dataTable: tailwind_variants.TVReturnType<{
     };
 }, {
     root: string;
+    toolbar: string;
     scroller: string;
     table: string;
     caption: string;
@@ -43,16 +107,24 @@ declare const dataTable: tailwind_variants.TVReturnType<{
     headRow: string;
     th: string;
     sortButton: string;
+    resizer: string;
     tbody: string;
     tr: string;
+    groupRow: string;
     td: string;
     select: string;
+    expander: string;
+    toggle: string;
+    detail: string;
     message: string;
     skeleton: string;
     footer: string;
 }, undefined, {
     layout: {
-        table: {};
+        table: {
+            th: string;
+            td: string;
+        };
         auto: {
             table: string;
             caption: string;
@@ -63,6 +135,7 @@ declare const dataTable: tailwind_variants.TVReturnType<{
             tr: string;
             td: string;
             select: string;
+            expander: string;
         };
         cards: {
             table: string;
@@ -74,6 +147,7 @@ declare const dataTable: tailwind_variants.TVReturnType<{
             tr: string;
             td: string;
             select: string;
+            expander: string;
         };
     };
     density: {
@@ -85,6 +159,7 @@ declare const dataTable: tailwind_variants.TVReturnType<{
     };
 }, {
     root: string;
+    toolbar: string;
     scroller: string;
     table: string;
     caption: string;
@@ -92,16 +167,24 @@ declare const dataTable: tailwind_variants.TVReturnType<{
     headRow: string;
     th: string;
     sortButton: string;
+    resizer: string;
     tbody: string;
     tr: string;
+    groupRow: string;
     td: string;
     select: string;
+    expander: string;
+    toggle: string;
+    detail: string;
     message: string;
     skeleton: string;
     footer: string;
 }, tailwind_variants.TVReturnTypeLike<{
     layout: {
-        table: {};
+        table: {
+            th: string;
+            td: string;
+        };
         auto: {
             table: string;
             caption: string;
@@ -112,6 +195,7 @@ declare const dataTable: tailwind_variants.TVReturnType<{
             tr: string;
             td: string;
             select: string;
+            expander: string;
         };
         cards: {
             table: string;
@@ -123,6 +207,7 @@ declare const dataTable: tailwind_variants.TVReturnType<{
             tr: string;
             td: string;
             select: string;
+            expander: string;
         };
     };
     density: {
@@ -134,6 +219,7 @@ declare const dataTable: tailwind_variants.TVReturnType<{
     };
 }, {
     root: string;
+    toolbar: string;
     scroller: string;
     table: string;
     caption: string;
@@ -141,10 +227,15 @@ declare const dataTable: tailwind_variants.TVReturnType<{
     headRow: string;
     th: string;
     sortButton: string;
+    resizer: string;
     tbody: string;
     tr: string;
+    groupRow: string;
     td: string;
     select: string;
+    expander: string;
+    toggle: string;
+    detail: string;
     message: string;
     skeleton: string;
     footer: string;
@@ -154,26 +245,52 @@ type DataTableSort = {
     column: string;
     direction: SortDirection;
 } | null;
-type Sortable = string | number | boolean | Date | null | undefined;
+/** What the server needs to fetch a page (`manual` mode): given to `onStateChange` at each change. */
+type DataTableQuery = {
+    /** The sorted column, or `null`. */
+    sort: DataTableSort;
+    /** The filters in force, by column id. */
+    filters: DataTableFilterState;
+    /** The page, from 1 (1 without pagination). */
+    page: number;
+    /** Rows per page (`Infinity` without pagination). */
+    pageSize: number;
+};
 type DataTableColumn<T> = {
-    /** A key of the column (and of the row, for the default cell and sort). */
+    /** A key of the column (and of the row, for the default value). */
     id: string;
-    /** The column's name, passed translated: the header, and the label of the value in a card. */
+    /** The column's name, passed translated: the header, the label of the value in a card, the filter's name. */
     header: string;
-    /** What a cell shows. Default: `value(row)`, or `row[id]`. */
+    /** What a cell shows. Default: the value as text. */
     cell?: (row: T) => React.ReactNode;
-    /** The value sorted on (and shown by default): a string, a number, a date. Default `row[id]`. */
-    value?: (row: T) => Sortable;
+    /** The value sorted, filtered, grouped and exported. Default `row[id]`. */
+    value?: (row: T) => CellValue;
     /** The header becomes a sort button (ascending → descending → none). */
     sortable?: boolean;
+    /** How `DataTableFilters` filters it: `text` (a search), `facet` (values to choose), `range` (numbers between bounds). */
+    filter?: "text" | "facet" | "range";
+    /** The choices of a `facet` filter, with their words (and counts from the server). Default: the values found in the rows. */
+    options?: readonly {
+        value: string;
+        label: string;
+        count?: number;
+    }[];
+    /** The rows can be grouped by this column (`groupBy`). */
+    groupable?: boolean;
+    /** What a group's row shows in this column, from the group's rows (a sum, a count). */
+    aggregate?: (rows: readonly T[]) => React.ReactNode;
     /** Text alignment: `end` for amounts and counts. */
     align?: "start" | "center" | "end";
-    /** A CSS width (`"8rem"`, `"30%"`). */
-    width?: string;
+    /** The width, in px (the starting width when `resizing`). */
+    width?: number;
+    /** The narrowest a resized column may be, in px. Default 64. */
+    minWidth?: number;
     /** In a card: `title` (the heading of the card), `label` (default: "Header  value"), `hidden`. */
     card?: "title" | "label" | "hidden";
     /** Hides the header visually (an actions column), keeping it for screen readers. */
     headerHidden?: boolean;
+    /** Listed in `DataTableColumnsMenu`, so a person can hide it. Default `true`. */
+    hideable?: boolean;
 };
 type DataTableLabels = {
     /** The checkbox of the header ("Select all rows"). */
@@ -184,14 +301,44 @@ type DataTableLabels = {
     loading: string;
     /** The default empty state ("Nothing to show"). */
     empty: string;
+    /** The header of the column of the expand buttons, for screen readers ("Details"). */
+    details: string;
+    /** The button that opens a row: `(name) => "Show details of " + name`. */
+    expandRow: (name: string) => string;
+    /** The button of a group's row: `(value, count) => value + ", " + count + " rows"`. */
+    group: (value: string, count: number) => string;
+    /** The handle that resizes a column: `(header) => "Resize " + header`. */
+    resize: (header: string) => string;
+    /** The count of results under the filters: `(count) => count + " rows"`. */
+    results: (count: number) => string;
+    /** The accessible name of the filters' bar ("Filter the table"). */
+    filters: string;
+    /** "Clear filters". */
+    clearFilters: string;
+    /** A filter's chip remove button: `(label) => "Remove " + label`. */
+    removeFilter: (label: string) => string;
+    /** The words of a filter in force: `(header, value) => header + ": " + value`. */
+    activeFilter: (header: string, value: string) => string;
+    /** A `text` filter's field: `(header) => "Search " + header`. */
+    search: (header: string) => string;
+    /** The lower bound of a `range` filter: `(header) => header + " from"`. */
+    rangeFrom: (header: string) => string;
+    /** The upper bound of a `range` filter: `(header) => header + " to"`. */
+    rangeTo: (header: string) => string;
+    /** The button of the columns menu ("Columns"). */
+    columns: string;
+    /** The export button ("Export CSV"). */
+    export: string;
+    /** The words of the pagination under the table. */
+    pagination?: Partial<PaginationLabels>;
 };
 declare const dataTableLabels: DataTableLabels;
 type DataTableProps<T> = {
-    /** The rows, in the order the server gave (sorted here unless `manualSort`). */
+    /** The rows (stable: module scope, state or a query's data). Sorted, filtered and paginated here unless `manual`. */
     rows: readonly T[];
-    /** The columns, in order. */
+    /** The columns, in order (stable: module scope or `useMemo`). */
     columns: readonly DataTableColumn<T>[];
-    /** A stable id per row: the React key and the selection's value. */
+    /** A stable id per row: the React key, the selection's value, the expansion's key. */
     getRowId: (row: T) => string;
     /** What the table lists ("Jobs", "Your videos"): its `<caption>`, hidden unless `showCaption`. */
     caption: string;
@@ -203,8 +350,12 @@ type DataTableProps<T> = {
     defaultSort?: DataTableSort;
     /** Called when a header asks for a new sort. */
     onSortChange?: (sort: DataTableSort) => void;
-    /** The server sorts (`onSortChange` fetches): the rows are shown as given. */
-    manualSort?: boolean;
+    /** The filters in force (controlled), by column id — what `DataTableFilters` edits. */
+    filters?: DataTableFilterState;
+    /** The filters at first, uncontrolled. */
+    defaultFilters?: DataTableFilterState;
+    /** Called with the new filters. */
+    onFiltersChange?: (filters: DataTableFilterState) => void;
     /** Adds a checkbox per row and one in the header. */
     selectable?: boolean;
     /** The ids selected (controlled). */
@@ -213,8 +364,61 @@ type DataTableProps<T> = {
     defaultSelected?: readonly string[];
     /** Called with the new selection. */
     onSelectedChange?: (selected: string[]) => void;
-    /** The name of a row in its checkbox's label (default: its id). */
+    /** The name of a row in its labels (checkbox, expand button). Default: its id. */
     rowLabel?: (row: T) => string;
+    /** The columns the rows are grouped by, in order (controlled) — each `groupable`. */
+    groupBy?: readonly string[];
+    /** The grouping at first, uncontrolled. */
+    defaultGroupBy?: readonly string[];
+    /** Called with the new grouping. */
+    onGroupByChange?: (groupBy: string[]) => void;
+    /** Visible (`true`) or hidden (`false`) columns, by id (controlled); a column not listed is visible. */
+    columnVisibility?: Readonly<Record<string, boolean>>;
+    /** The visibility at first, uncontrolled. */
+    defaultColumnVisibility?: Readonly<Record<string, boolean>>;
+    /** Called with the new visibility (`DataTableColumnsMenu`). */
+    onColumnVisibilityChange?: (visibility: Record<string, boolean>) => void;
+    /** Columns that stay in view while the table scrolls sideways: at the start (a name) or the end (actions). */
+    pinning?: {
+        start?: readonly string[];
+        end?: readonly string[];
+    };
+    /** Columns can be resized (pointer drag, or the arrow keys on the focused handle). */
+    resizing?: boolean;
+    /** The children of a row (a tree): each row with children gets a button that shows them. */
+    getSubRows?: (row: T) => readonly T[] | undefined;
+    /** A panel under an opened row (the details of a job): each row gets a button that opens it. */
+    renderDetail?: (row: T) => React.ReactNode;
+    /** The opened rows and groups (controlled), by id. */
+    expanded?: Readonly<Record<string, boolean>>;
+    /** The opened rows at first, uncontrolled. */
+    defaultExpanded?: Readonly<Record<string, boolean>>;
+    /** Called with the opened rows. */
+    onExpandedChange?: (expanded: Record<string, boolean>) => void;
+    /** Rows per page (controlled): turns on the pagination under the table. */
+    pageSize?: number;
+    /** Rows per page at first, uncontrolled: turns on the pagination under the table. */
+    defaultPageSize?: number;
+    /** Called with the size chosen in the pagination's select (`pageSizeOptions`). */
+    onPageSizeChange?: (pageSize: number) => void;
+    /** The sizes the pagination offers (`[10, 25, 50]`). */
+    pageSizeOptions?: readonly number[];
+    /** The page, from 1 (controlled). */
+    page?: number;
+    /** The page at first, uncontrolled. Default 1. */
+    defaultPage?: number;
+    /** Called with the page asked for. */
+    onPageChange?: (page: number) => void;
+    /** The server does the work: the rows are shown as given (sorted, filtered, a single page) — fetch in `onStateChange`. */
+    manual?: {
+        sorting?: boolean;
+        filtering?: boolean;
+        pagination?: boolean;
+    };
+    /** The number of rows on the server (`manual.pagination`): the page count and the results' count. */
+    rowCount?: number;
+    /** Called with the sort, the filters and the page after each change: the query key of a server table. */
+    onStateChange?: (query: DataTableQuery) => void;
     /** Rows are loading: skeleton rows (`loadingRows` of them) and `aria-busy`. */
     loading?: boolean;
     /** How many skeleton rows while loading. Default 5. */
@@ -227,20 +431,76 @@ type DataTableProps<T> = {
     layout?: "auto" | "table" | "cards";
     /** comfortable (default) · compact. */
     density?: "comfortable" | "compact";
-    /** Renders only the rows in view (fixed `rowHeight`, a scrolling body of `height` px). Forces the table layout. */
-    virtualize?: {
-        rowHeight: number;
+    /** Renders only the rows in view, in a scrolling body of `height` px; rows are measured (`estimateRowHeight` is a guess). Forces the table layout. */
+    virtualized?: {
         height: number;
+        estimateRowHeight?: number;
         overscan?: number;
     };
-    /** Under the table: a `Pagination`, a total. */
+    /** Above the table, inside its frame: `DataTableFilters`, `DataTableColumnsMenu`, `DataTableExport`, actions. */
+    toolbar?: React.ReactNode;
+    /** Under the table (after the pagination): a total, a note. */
     footer?: React.ReactNode;
     /** The words, passed translated; English by default. */
     labels?: Partial<DataTableLabels>;
     /** Classes merged on the root. */
     className?: string;
 };
-/** A table of records: sort, selection, loading / empty / error, cards on a phone, windowing for long lists. */
-declare function DataTable<T>({ rows, columns, getRowId, caption, showCaption, sort: sortProp, defaultSort, onSortChange, manualSort, selectable, selected: selectedProp, defaultSelected, onSelectedChange, rowLabel, loading, loadingRows, error, empty, layout, density, virtualize, footer, labels: given, className, }: DataTableProps<T>): React.JSX.Element;
+type Context = {
+    table: DataTableInstance<object>;
+    columns: readonly DataTableColumn<object>[];
+    labels: DataTableLabels;
+    filters: DataTableFilterState;
+    setFilters: (filters: DataTableFilterState) => void;
+    /** The rows after the filters (all pages), or the server's count. */
+    resultCount: number;
+    /** The rows to export: filtered and sorted, every page, without the group rows. */
+    exportRows: () => readonly unknown[];
+    manualFiltering: boolean;
+};
+/**
+ * The table a component sits in (`toolbar`, or anything under it): the TanStack Table instance (`table` — the escape
+ * hatch for what the props do not cover), the columns, the words, the filters and their setter.
+ */
+declare function useDataTable<T extends RowData = object>(): Omit<Context, "table" | "columns" | "exportRows"> & {
+    table: DataTableInstance<T>;
+    columns: readonly DataTableColumn<T>[];
+    exportRows: () => readonly T[];
+};
+/** A table of records — sort, filters and facets, groups, details, pages, selection, visibility, pinning, resizing — on the client or the server, cards on a phone, windowing for long lists. */
+declare function DataTable<T extends RowData>({ rows, columns, getRowId, caption, showCaption, sort: sortProp, defaultSort, onSortChange, filters: filtersProp, defaultFilters, onFiltersChange, selectable, selected: selectedProp, defaultSelected, onSelectedChange, rowLabel, groupBy: groupByProp, defaultGroupBy, onGroupByChange, columnVisibility: visibilityProp, defaultColumnVisibility, onColumnVisibilityChange, pinning, resizing, getSubRows, renderDetail, expanded: expandedProp, defaultExpanded, onExpandedChange, pageSize: pageSizeProp, defaultPageSize, onPageSizeChange, pageSizeOptions, page: pageProp, defaultPage, onPageChange, manual, rowCount, onStateChange, loading, loadingRows, error, empty, layout, density, virtualized, toolbar, footer, labels: given, className, }: DataTableProps<T>): React.JSX.Element;
+
+type DataTableFiltersProps = {
+    /** The search's wait after the last key, in ms, before the filter applies (a request, in server mode). Default 250. */
+    debounce?: number;
+    /** More controls in the bar (a date range picker, a toggle). */
+    children?: React.ReactNode;
+    /** Classes merged on the bar. */
+    className?: string;
+};
+/**
+ * The filters of the table, from its columns: a search per `text` column, a menu of values (with their counts) per
+ * `facet` column, two bounds per `range` column; the filters in force as removable chips, "clear all", and the count
+ * of results, announced.
+ */
+declare function DataTableFilters({ debounce, children, className }: DataTableFiltersProps): React.JSX.Element;
+type DataTableColumnsMenuProps = {
+    /** Opens the menu at first (a story, a test). */
+    defaultOpen?: boolean;
+    /** Classes merged on the button. */
+    className?: string;
+};
+/** A menu of the `hideable` columns, each a checkbox: the person chooses what the table shows. */
+declare function DataTableColumnsMenu({ defaultOpen, className }: DataTableColumnsMenuProps): React.JSX.Element;
+type DataTableExportProps = {
+    /** The file's name. Default `"export.csv"`. */
+    filename?: string;
+    /** Receives the CSV instead of downloading it (send it to the server, a test). */
+    onExport?: (csv: string) => void;
+    /** Classes merged on the button. */
+    className?: string;
+};
+/** Downloads what the table shows — the filtered and sorted rows of every page, the visible columns — as CSV. */
+declare function DataTableExport({ filename, onExport, className }: DataTableExportProps): React.JSX.Element;
 
-export { DataTable, type DataTableColumn, type DataTableLabels, type DataTableProps, type DataTableSort, type SortDirection, dataTable, dataTableLabels };
+export { type CellValue, DataTable, type DataTableColumn, DataTableColumnsMenu, type DataTableColumnsMenuProps, DataTableExport, type DataTableExportProps, type DataTableFilterState, DataTableFilters, type DataTableFiltersProps, type DataTableInstance, type DataTableLabels, type DataTableProps, type DataTableQuery, type DataTableSort, type FilterValue, type SortDirection, compareValues, dataTable, dataTableCsv, dataTableLabels, useDataTable };