@optimum-intelligence/opti-ui 0.2.0 → 0.4.0

package/dist/components/data-table/types.d.ts

@@ -0,0 +1,335 @@
+import type * as React from 'react';
+import type { DateRange } from '../calendar/date-utils';
+import type { DateRangePreset } from '../date-picker/DateRangePicker';
+import type { InputProps } from '../input/Input';
+import type { PaginationLabels } from '../pagination/Pagination';
+export interface DataTableFilterOption {
+    value: string;
+    label: React.ReactNode;
+}
+interface FilterBase {
+    /** Key of this filter in `filterValues`. */
+    id: string;
+    /** Text on the control. */
+    label: string;
+}
+/** Dropdown that keeps the rows with one chosen value. */
+export interface DataTableSelectFilter<T> extends FilterBase {
+    type: 'select';
+    /** Value compared with the chosen option; an array matches on any of its items. Defaults to `row[id]`. */
+    value?: (row: T) => unknown;
+    /** Options to offer. Left out, they are collected from the rows. */
+    options?: DataTableFilterOption[];
+}
+/** On/off chip that keeps the matching rows while it is on. */
+export interface DataTableToggleFilter<T> extends FilterBase {
+    type: 'toggle';
+    /** Rows kept while the toggle is on. Defaults to rows where `row[id]` is truthy. */
+    match?: (row: T) => boolean;
+}
+/** Date range picker that keeps the rows dated inside the range, both days included. */
+export interface DataTableDateRangeFilter<T> extends FilterBase {
+    type: 'dateRange';
+    /** Date of the row: an ISO string, a `Date` or a timestamp. Defaults to `row[id]`. */
+    value?: (row: T) => string | number | Date | null | undefined;
+    presets?: DateRangePreset[];
+    min?: string;
+    max?: string;
+}
+export type DataTableFilter<T> = DataTableSelectFilter<T> | DataTableToggleFilter<T> | DataTableDateRangeFilter<T>;
+type ColumnFilterConfig<F> = F extends FilterBase ? Omit<F, 'id' | 'label'> & {
+    label?: string;
+} : never;
+/** A filter declared on a column: its type, or its definition without the `id` (the column's). */
+export type DataTableColumnFilter<T> = DataTableFilter<T>['type'] | ColumnFilterConfig<DataTableFilter<T>>;
+/** A select filter holds the option value, a toggle `true`, a date range `{ start, end }`. */
+export type DataTableFilterValue = string | true | DateRange;
+/** Values of the active filters by filter id. An inactive filter has no key. */
+export type DataTableFilterValues = Record<string, DataTableFilterValue>;
+/** A filter as the table uses it: column shorthand expanded, options collected. */
+export interface DataTableResolvedFilter<T> {
+    id: string;
+    type: DataTableFilter<T>['type'];
+    label: string;
+    /** Select filters only; empty for the other types. */
+    options: DataTableFilterOption[];
+    presets?: DateRangePreset[];
+    min?: string;
+    max?: string;
+    /** Whether `row` passes the filter at `value`. */
+    test: (row: T, value: DataTableFilterValue) => boolean;
+}
+export interface DataTableEditorContext<T> {
+    row: T;
+    /** Current value of the edited field. */
+    value: unknown;
+    setValue: (value: unknown) => void;
+    /** True while the row is being saved. */
+    disabled: boolean;
+}
+export interface DataTableColumnEdit<T> {
+    /** Built-in editor (default `text`). */
+    type?: 'text' | 'checkbox' | 'select';
+    /** Row property the editor writes. Defaults to the column id. */
+    field?: Extract<keyof T, string>;
+    /** Options of a `select` editor. */
+    options?: DataTableFilterOption[];
+    /** Props for the `text` editor's input (`inputMode`, `placeholder`, `type`…). */
+    inputProps?: Omit<InputProps, 'value' | 'defaultValue' | 'onValueChange' | 'size'>;
+    /** Replaces the built-in editor. */
+    render?: (context: DataTableEditorContext<T>) => React.ReactNode;
+}
+export interface DataTableColumn<T> {
+    /** Unique key. Also the property read from the row when there is no `accessor`. */
+    id: string;
+    header: React.ReactNode;
+    /** Plain-text name, used for the column's filter when `header` is not a string. */
+    label?: string;
+    /** Value used for sorting, searching, filtering and the default cell. Defaults to `row[id]`. */
+    accessor?: (row: T) => unknown;
+    /** Custom cell content. */
+    cell?: (row: T) => React.ReactNode;
+    /** Defaults to `true`, or `false` for columns that only define `cell` (actions, icons). */
+    sortable?: boolean;
+    /** Include this column in the built-in search. Same default as `sortable`. */
+    searchable?: boolean;
+    /** `contains` (default) matches anywhere in the value; `exact` only whole words, for ids and codes. */
+    searchMode?: 'contains' | 'exact';
+    /** Custom ascending comparison. */
+    compare?: (a: T, b: T) => number;
+    /** Adds a filter on this column to the toolbar. */
+    filter?: DataTableColumnFilter<T>;
+    /** Makes the cell editable once `onRowSave` is set. */
+    edit?: NonNullable<DataTableColumnEdit<T>['type']> | DataTableColumnEdit<T>;
+    /** Leaves the column out of the grid; it still takes part in search, filters and sorting. */
+    hidden?: boolean;
+    align?: 'start' | 'center' | 'end';
+    /** Right-align with tabular figures. */
+    numeric?: boolean;
+    /** Monospace text, for ids, codes and timestamps. */
+    mono?: boolean;
+    /** Quieter text colour, for secondary values. */
+    muted?: boolean;
+    /** Cuts long text with an ellipsis instead of wrapping it. The column takes its `width`, not the text's. */
+    truncate?: boolean;
+    /** Preferred width. The table measures its columns once and then holds them, so this is a starting point. */
+    width?: number | string;
+    /** Floor for the measured width, for columns whose content gets longer on later pages. */
+    minWidth?: number | string;
+    /** Extra class on the column's body cells. */
+    cellClassName?: string | ((row: T) => string | undefined);
+}
+export interface DataTableSort {
+    id: string;
+    direction: 'asc' | 'desc';
+}
+export interface DataTableRowAction {
+    /** Tooltip and accessible name. */
+    label: string;
+    icon: React.ReactNode;
+    onClick: () => void;
+    disabled?: boolean;
+    /** Colours the button red on hover. */
+    danger?: boolean;
+}
+export type DataTableRowTone = 'accent' | 'info' | 'success' | 'warning' | 'danger';
+export interface DataTableEntry<T> {
+    id: string;
+    row: T;
+}
+export interface DataTableLabels extends PaginationLabels {
+    search: string;
+    clearSearch: string;
+    selectAll: string;
+    selectRow: (label: string) => string;
+    count: (count: number) => React.ReactNode;
+    /** Summary while a search or filter narrows the rows. Defaults to `count` of the total, prefixed with the match count. */
+    filteredCount: (count: number, total: number) => React.ReactNode;
+    selected: (count: number) => React.ReactNode;
+    emptyTitle: React.ReactNode;
+    emptyDescription: React.ReactNode;
+    noMatchTitle: React.ReactNode;
+    noMatchDescription: React.ReactNode;
+    /** Shown instead of `noMatchDescription` when filters leave no rows. Defaults to it. */
+    noFilterMatchDescription: React.ReactNode;
+    loading: string;
+    errorTitle: React.ReactNode;
+    retry: string;
+    /** Accessible name of the filter group. */
+    filters: string;
+    /** The "no filter" option of a select filter. */
+    filterAll: string;
+    clearFilters: string;
+    /** Accessible name of the row actions column. */
+    actions: string;
+    edit: string;
+    save: string;
+    cancel: string;
+    delete: string;
+}
+/** Labels with the defaults filled in. Pagination texts stay partial: `Pagination` has its own defaults. */
+export type DataTableResolvedLabels = Omit<DataTableLabels, keyof PaginationLabels> & Partial<PaginationLabels>;
+export interface UseDataTableOptions<T> {
+    /** All rows, or in server mode the rows of the current page. */
+    data: T[];
+    /** Column definitions: id, header, cell renderer, sorting, filter and layout options. */
+    columns: DataTableColumn<T>[];
+    /**
+     * `server` renders `data` as it is: search, filtering, sorting and pagination are
+     * left to the API, driven by the `search` / `filterValues` / `sort` / `page` callbacks.
+     */
+    mode?: 'client' | 'server';
+    /** Server mode: number of rows across all pages. */
+    total?: number;
+    /** Shows placeholder rows when there is no data yet, and dims the rows during a refetch. */
+    loading?: boolean;
+    /** Error message shown in place of the rows. */
+    error?: React.ReactNode;
+    /** Adds a retry button to the error message. */
+    onRetry?: () => void;
+    /** Stable id per row, needed for selection and editing. Defaults to `row.id`, then the index. */
+    getRowId?: (row: T, index: number) => string;
+    /** Language whose alphabet orders sorted text and filter options (`"hu"`). Defaults to the browser's. */
+    locale?: string;
+    /** Show the search box (default `true`). */
+    searchable?: boolean;
+    /** Search text (controlled). */
+    search?: string;
+    /** Initial search text when uncontrolled. */
+    defaultSearch?: string;
+    /** Called when the search text changes (after `searchDebounce`). */
+    onSearchChange?: (search: string) => void;
+    /** Milliseconds of typing pause before the search applies. Defaults to 300 in server mode, 0 otherwise. */
+    searchDebounce?: number;
+    /** Replaces the built-in search, which matches every term against the searchable columns. */
+    filter?: (row: T, search: string) => boolean;
+    /** Toolbar filters that are not tied to a column. Columns add theirs with `filter`. */
+    filters?: DataTableFilter<T>[];
+    /** Filter values by filter id (controlled). */
+    filterValues?: DataTableFilterValues;
+    /** Initial filter values when uncontrolled. */
+    defaultFilterValues?: DataTableFilterValues;
+    /** Called with all filter values when one changes or they are cleared. */
+    onFilterValuesChange?: (values: DataTableFilterValues) => void;
+    /** Column sort (controlled); `null` for none. */
+    sort?: DataTableSort | null;
+    /** Initial sort when uncontrolled. */
+    defaultSort?: DataTableSort | null;
+    /** Called when the user sorts a column. */
+    onSortChange?: (sort: DataTableSort | null) => void;
+    /** Paginate rows (default `true`). */
+    paginated?: boolean;
+    /** Current page, starting at 1 (controlled). */
+    page?: number;
+    /** Called when the page changes. */
+    onPageChange?: (page: number) => void;
+    /** Rows per page (controlled). */
+    pageSize?: number;
+    /** Initial rows per page when uncontrolled. */
+    defaultPageSize?: number;
+    /** Called when the rows per page change. */
+    onPageSizeChange?: (pageSize: number) => void;
+    /**
+     * Selected row ids. Passing `onSelectionChange` adds the checkbox column.
+     * Select-all covers every filtered row, or in server mode the current page.
+     */
+    selection?: string[];
+    /** Called with the selected row ids. */
+    onSelectionChange?: (selection: string[]) => void;
+    /** Makes rows clickable and keyboard-activatable (Enter). */
+    onRowClick?: (row: T) => void;
+    /** Accessible name of a row, used by row selection and clickable rows. */
+    rowLabel?: (row: T) => string;
+    /** Trailing cell of each row: icon buttons, or any content (a menu, a link). */
+    rowActions?: (row: T) => DataTableRowAction[] | React.ReactNode;
+    /** Tints a row to flag its state. */
+    rowTone?: (row: T) => DataTableRowTone | null | undefined;
+    /** Extra props for a row's `<tr>` (`className`, `style`, `data-*`). */
+    rowProps?: (row: T) => React.HTMLAttributes<HTMLTableRowElement> & Record<`data-${string}`, unknown>;
+    /**
+     * Adds an edit action to each row; columns with `edit` turn into inputs. Called
+     * with the edited row. Return a promise to keep the row open while it saves; a
+     * rejected one leaves it open for another try.
+     */
+    onRowSave?: (row: T, original: T) => void | Promise<void>;
+    /** Adds a delete action, shown while a row is edited, or on every row without `onRowSave`. */
+    onRowDelete?: (row: T) => void;
+    /** Override texts for localisation. */
+    labels?: Partial<DataTableLabels>;
+}
+/** State and derived rows of a table, returned by `useDataTable` and read by the `DataTable` parts. */
+export interface DataTableInstance<T> {
+    mode: 'client' | 'server';
+    /** Every column, hidden ones included. */
+    columns: DataTableColumn<T>[];
+    visibleColumns: DataTableColumn<T>[];
+    labels: DataTableResolvedLabels;
+    locale?: string;
+    /** Every row of `data`, before search and filters. */
+    allRows: DataTableEntry<T>[];
+    /** Rows after filters, search and sorting, across all pages. In server mode: the current page. */
+    rows: DataTableEntry<T>[];
+    /** Rows of the current page. */
+    pageRows: DataTableEntry<T>[];
+    /** Number of matching rows across all pages. */
+    count: number;
+    /** Number of rows before search and filters; in server mode the same as `count`. */
+    totalCount: number;
+    /** A search or filter is narrowing the rows. */
+    filtered: boolean;
+    /** Clears the search and every filter. */
+    reset: () => void;
+    loading: boolean;
+    /** Loading with no rows to show yet. */
+    pending: boolean;
+    error?: React.ReactNode;
+    onRetry?: () => void;
+    searchable: boolean;
+    search: string;
+    setSearch: (search: string) => void;
+    searchDebounce: number;
+    filters: DataTableResolvedFilter<T>[];
+    filterValues: DataTableFilterValues;
+    /** Sets one filter; `undefined` clears it. */
+    setFilterValue: (id: string, value: DataTableFilterValue | undefined) => void;
+    clearFilters: () => void;
+    activeFilterCount: number;
+    sort: DataTableSort | null;
+    setSort: (sort: DataTableSort | null) => void;
+    /** Cycles a column through ascending, descending and unsorted. */
+    toggleSort: (id: string) => void;
+    isSortable: (column: DataTableColumn<T>) => boolean;
+    paginated: boolean;
+    page: number;
+    pageCount: number;
+    pageSize: number;
+    setPage: (page: number) => void;
+    setPageSize: (pageSize: number) => void;
+    selectable: boolean;
+    /** Ids of the selected rows. */
+    selection: string[];
+    isSelected: (id: string) => boolean;
+    toggleRow: (id: string, selected: boolean) => void;
+    toggleAll: (selected: boolean) => void;
+    allSelected: boolean;
+    someSelected: boolean;
+    editable: boolean;
+    deletable: boolean;
+    /** Id of the row being edited. */
+    editingId: string | null;
+    /** True while `onRowSave` is pending. */
+    saving: boolean;
+    startEdit: (id: string) => void;
+    cancelEdit: () => void;
+    /** Value of a field of the row being edited, with its unsaved changes. */
+    editValue: (row: T, field: string) => unknown;
+    setEditValue: (field: string, value: unknown) => void;
+    saveEdit: () => void;
+    deleteRow: (row: T) => void;
+    onRowClick?: (row: T) => void;
+    rowLabel?: (row: T) => string;
+    rowActions?: (row: T) => DataTableRowAction[] | React.ReactNode;
+    rowTone?: (row: T) => DataTableRowTone | null | undefined;
+    rowProps?: (row: T) => React.HTMLAttributes<HTMLTableRowElement>;
+}
+export {};

package/dist/components/data-table/useDataTable.d.ts

@@ -0,0 +1,9 @@
+import type { DataTableColumn, DataTableInstance, UseDataTableOptions } from './types';
+/** The value a column sorts, searches and filters by. */
+export declare function getColumnValue<T>(column: DataTableColumn<T>, row: T): unknown;
+/**
+ * State and row processing of a `DataTable`, without any markup. Pass the
+ * result to `DataTable.Root` to lay the parts out yourself, or read `rows`,
+ * `filterValues` and the rest to drive something else (an export, a chart).
+ */
+export declare function useDataTable<T>({ data, columns, mode, total, loading, error, onRetry, getRowId, locale, searchable, search: searchProp, defaultSearch, onSearchChange, searchDebounce, filter, filters: filtersProp, filterValues: filterValuesProp, defaultFilterValues, onFilterValuesChange, sort: sortProp, defaultSort, onSortChange, paginated, page: pageProp, onPageChange, pageSize: pageSizeProp, defaultPageSize, onPageSizeChange, selection: selectionProp, onSelectionChange, onRowClick, rowLabel, rowActions, rowTone, rowProps, onRowSave, onRowDelete, labels, }: UseDataTableOptions<T>): DataTableInstance<T>;