API index

Absent

A value that is not there: null or undefined.

type Absent = null | undefined;

AggregateColumn<Z>

A column that carries an aggregate, as the pipeline needs it.

AggregateFor<W, Z>

What a column accepts as aggregate: sums and averages for numbers, the extremes for numbers and points in time, the range for points in time, counts for every value with a text form - or a function of one's own.

type AggregateFor<W, Z> =
  | ([Present<W>] extends [number] ? "sum" | "avg" | "min" | "max" : never)
  | ([Present<W>] extends [Date] ? "min" | "max" | "range" : never)
  | (IsDisplayable<W> extends true ? "count" | "distinct" : never)
  | AggregateFunction<W, Z>;

AggregateFunction<W, Z>

An aggregate of one's own: the values present and the rows of the group - or of the filtered set, in the footer. Its result runs through the column's presentation; undefined means there is none.

type AggregateFunction<W, Z> = (values: readonly Present<NoInfer<W>>[], rows: readonly Z[]) => Present<NoInfer<W>> | undefined;

AggregateKind

The built-in aggregates. range is for points in time: the earliest and the latest.

type AggregateKind = "sum" | "avg" | "min" | "max" | "range" | "count" | "distinct";

CellEdit<Z>

An edit the user committed - reported, not applied.

CellEditorProps<W, Z>

What an editor of one's own receives. The table holds the draft; Enter, Escape and Tab stay the table's, bubbling up from the field.

Events

ColumnComponent<Z>

The Column of a table, typed at its row: a field column names a field in value, a computed column a function and an id. What it accepts as aggregate, filter, format and edit follows from the type of its value.

interface ColumnComponent<Z> {
  <W extends number | Absent>(
    props: Computed<Z, W> & { footer: "sum" | "avg"; aggregate?: never; format?: NumberFormat; children?: Presentation<W, Z>; share?: boolean },
  ): ReactNode;
  <W extends number | Absent>(
    props: Computed<Z, W> & {
      aggregate: "sum" | "avg" | "min" | "max" | "count" | "distinct";
      footer?: never;
      share?: boolean;
      format?: NumberFormat;
      children?: Presentation<W, Z>;
    },
  ): ReactNode;
  <W extends Date | Absent>(
    props: Computed<Z, W> & {
      aggregate: "min" | "max" | "range" | "count" | "distinct";
      footer?: never;
      format?: DateFormat;
      group?: DatePeriod;
      children?: Presentation<W, Z>;
    },
  ): ReactNode;
  <W extends Date | Absent>(
    props: Computed<Z, W> & {
      group: DatePeriod;
      aggregate?: "min" | "max" | "range" | "count" | "distinct";
      footer?: never;
      format?: DateFormat;
      children?: Presentation<W, Z>;
    },
  ): ReactNode;
  <W extends number | Absent>(
    props: Computed<Z, W> & { format: NumberFormat; aggregate?: AggregateFunction<W, Z>; share?: boolean; children?: Presentation<W, Z> },
  ): ReactNode;
  <W extends Date | Absent>(
    props: Computed<Z, W> & { format: DateFormat; group?: DatePeriod; aggregate?: AggregateFunction<W, Z>; children?: Presentation<W, Z> },
  ): ReactNode;
  <W>(
    props: Computed<Z, W> & {
      footer?: never;
      format?: never;
      aggregate?: AggregateFunction<W, Z>;
      children: Presentation<W, Z>;
    },
  ): ReactNode;
  <W extends Displayable | Absent>(
    props: Computed<Z, W> & { footer?: never; format?: never; aggregate?: "count" | "distinct" | AggregateFunction<W, Z>; children?: never },
  ): ReactNode;
  <K extends Field<Z>>(props: FieldColumn<Z, K>): ReactNode;
}

ColumnPreset<P, K extends Field<P> = Field<P>>

The properties of a column, as column() supplies them.

type ColumnPreset<P, K extends Field<P> = Field<P>> = FieldColumn<P, K>;

Computed<Z, W>

A computed column's props: its value is a function of the row, so it needs an id.

type Computed<Z, W> = ColumnBase &
  ValuePaths<W> & {
    /** The id is required where the value is a function. */
    id: string;
    value: (row: Z) => W;
    /* The two names stand here without a condition on the value type, unlike on
       a field column: the value of a computed column is derived from `value`,
       and a condition over this W is not yet resolved when the overload is
       chosen - `filter="range"` would then leave the whole column untyped. A
       filter of one's own is still checked against the value. */
    /** A filter in the column header: `"list"` offers the values that occur,
        `"range"` two bounds (meaningful only for numbers and points in time), a
        filter from `columnFilter` asks whatever it asks itself. */
    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the condition belongs to the filter
    filter?: "list" | "range" | ColumnFilter<Present<W>, any>;
    /** Edits the column's cells in place in grid mode - see a field column's `edit`. */
    edit?: "text" | "number" | "select" | "date" | ((editor: CellEditorProps<W, Z>) => ReactNode);
    /** What `edit="select"` offers.
      @default the values that occur */
    editOptions?: readonly Present<W>[];
    /** Checks a draft before it is reported; a message keeps the editor open. */
    validate?: (value: W | null, row: Z) => string | null | undefined;
  };

DateFormat

The names of the standard presentations of a point in time.

type DateFormat = "date" | "time" | "dateTime";

DatePeriod

The span a point in time is grouped by.

type DatePeriod = "day" | "week" | "month" | "year";

Displayable

What can appear as text without children.

type Displayable = string | number | boolean | Date;

EditFor<W, Z>

What a column accepts as edit: the core field for its value - "text" for text, "number" for numbers, "date" for points in time, "select" for text and numbers - or an editor of one's own.

type EditFor<W, Z> =
  | ([Present<W>] extends [string] ? "text" | "select" : never)
  | ([Present<W>] extends [number] ? "number" | "select" : never)
  | ([Present<W>] extends [Date] ? "date" : never)
  | ((editor: CellEditorProps<W, Z>) => ReactNode);

EditOptions<W, Z>

The props a column carries for editing in grid mode (<Table grid>).

Field<Z>

The field names of a row.

type Field<Z> = Extract<keyof Z, string>;

FieldCondition<W>

What can be set as a condition on a field: a list of its values, and for numbers and points in time a range as well.

type FieldCondition<W> =
  | ListCondition<W>
  | ([Present<W>] extends [number] ? RangeCondition<number> : [Present<W>] extends [Date] ? RangeCondition<Date> : never);

FilterFor<W>

What a column accepts as filter: "list" for every value with a text form, "range" for numbers and points in time, a filter from columnFilter only where its value type fits.

type FilterFor<W> =
  | (IsDisplayable<W> extends true ? "list" : never)
  | ([Present<W>] extends [number] ? "range" : [Present<W>] extends [Date] ? "range" : never)
  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the condition belongs to the filter; at the column only the value counts
  | ColumnFilter<Present<W>, any>;

FormatFor<W>

What a column accepts as format: a number format for numbers, a date format for points in time, nothing for every other value.

type FormatFor<W> = [Present<W>] extends [number]
  ? NumberFormat
  : [Present<W>] extends [Date]
    ? DateFormat
    : never;

GroupByComponent<Z>

A value the table can be grouped by without being a column: no cell, no export, no entry among the columns - only where a grouping is chosen.

interface GroupByComponent<Z> {
  <W extends string | number | boolean | Date | Absent>(
    props: GroupByBase & {
      /** The id is required where the value is a function. */
      id: string;
      value: (row: Z) => W;
      groupValue?: (value: Present<W>) => string | number | boolean | Date | Absent;
      group?: GroupFor<W>;
    },
  ): ReactNode;
  <K extends Field<Z>>(
    props: GroupByBase & {
      /** A field of the row; supplies the id at the same time. */
      value: K;
      id?: string;
      groupValue?: (value: Present<Z[K]>) => string | number | boolean | Date | Absent;
      group?: GroupFor<Z[K]>;
    },
  ): ReactNode;
}

GroupFor<W>

group on a point in time: its rows are grouped by day, ISO week, month or year.

type GroupFor<W> = [Present<W>] extends [Date] ? DatePeriod : never;

GroupingId<Z>

A column or group key the table can be grouped by. The columns stand in the JSX, which the hook does not see: a field name is suggested, any id is taken, and one that nothing carries falls out.

type GroupingId<Z> = Field<Z> | (string & {});

GroupLevel<Z>

One level of the grouping: what a row is grouped by on it.

IsDisplayable<W>

true where the value present can appear as text without children (Displayable), false otherwise - what decides the filters and aggregates a column offers.

type IsDisplayable<W> = [Present<W>] extends [never]
  ? false
  : [Present<W>] extends [Displayable]
    ? true
    : false;

ListCondition<W>

The condition of a list filter: the chosen values, an absent one as null.

type ListCondition<W> = readonly (Present<W> | null)[];

ModelColumn<Z, K extends string = string>

A column as the model reads it - what sorting, search, hiding and the export need of it, not its presentation.

NumberField<Z>

The field names whose value is a number or may be absent.

type NumberField<Z> = {
  [K in Field<Z>]: Z[K] extends number | Absent ? K : never;
}[Field<Z>];

NumberFormat

The names of the standard presentations of a number.

type NumberFormat = "percent" | "count" | { decimals: number };

OwnAggregate<Z = never>

An aggregate of one's own: the values present and the group's rows.

type OwnAggregate<Z = never> = (values: readonly unknown[], rows: readonly Z[]) => unknown;

Pin

Where a pinned column stands: in the block before or after the others.

type Pin = "start" | "end";

Present<W>

The value without the absence - that is what children gets.

type Present<W> = Exclude<W, Absent>;

Presentation<W, Z>

What a column draws in a cell: the value present and its row.

type Presentation<W, Z> = (value: Present<W>, row: Z) => ReactNode;

RangeCondition<W>

The condition of a range filter: both bounds inclusive, each may be absent.

RowAdd

A new row the user saved: every column that edits, by column id.

RowAttributes

What a row carries in classes and data attributes.

type RowAttributes = { className?: string } & {
  [data: `data-${string}`]: string | undefined;
};

RowDelete<Z>

A row the user asked to delete, and confirmed.

RowGroup<Z>

The rows of the filtered set that share one grouping value on one level.

RowSave<Z>

A Row draft the user saved (ADR-0036) - reported, not applied.

SetFilter<Z>

Sets a condition from outside. Typed at the field of the row, not at the column: the columns stand in the JSX, and the hook does not see that (ADR-0017). An id that is not a field name – a computed column or an id of one's own – takes any condition; through it the condition of a filter of one's own is set as well.

interface SetFilter<Z> {
  <B>(filter: RowFilter<Z, B>, condition: B | null): void;
  <K extends Field<Z>>(column: K, condition: FieldCondition<Z[K]> | null): void;
  <I extends string>(column: I & (I extends Field<Z> ? never : unknown), condition: unknown): void;
}

SortDirection

The direction of one sort level: asc puts the smallest value on top, desc the largest.

type SortDirection = "asc" | "desc";

SortLevel<K extends string = string>

One level of the sort. Several levels act in their order: the second decides only what the first leaves open.

Table<Z>

What useTable returns: the table's state, and its parts typed at the row. Pass it as of to a part that stands outside the table.

TableInput<Z = unknown, K extends string = string>

The view's state the model computes a table from, beside its rows and columns: search, filter, sort, page, hidden columns, order, grouping, tree.

TableRef

What a part without a row type needs from a table – for of.

type TableRef = Omit<TableSnapshot<unknown>, "setFilter" | "conditionOf"> & {
  readonly Table: unknown;
  /** Without a row kind: any id, any condition. */
  setFilter(column: string, condition: unknown): void;
};

TableRequest<K extends string = string>

The request server mode reports to onRequest: the parts of the view that decide the rows - search, conditions, sort, page and page size - and nothing else, each at its default as well. A server has no default of the table's to fall back on, and a request it has to complete is one it completes wrongly. A width, an order, a pin or a fold is no part of it.

type TableRequest<K extends string = string> = Required<Pick<TableView<K>, "search" | "conditions" | "sort" | "page" | "pageSize">>;

TableSelection<T extends string | number>

What useTableSelection returns: the selected keys and the gestures on them. Give it to useTable as selection when the application holds the selection.

TableView<K extends string = string>

Search, conditions, sort levels, page, page size, hidden columns, order, dragged widths, the grouping and the pinned columns. Whatever is at its default is absent. The pre-filter never belongs to it: it is a function of the application.

ToolbarSize

The size of a toolbar's controls.

type ToolbarSize = "sm" | "md";

TreeInput<Z>

Tree rows for the model: how a row is keyed, how its children are read, and which branches are open.

VerdictColumnComponent<Z>

The VerdictColumn of a table, typed at its row: a numeric field, or a function with an id, whose value is read against limits and shown with its verdict.

interface VerdictColumnComponent<Z> {
  (props: VerdictBase & { id: string; value: (row: Z) => number | Absent }): ReactNode;
  <K extends NumberField<Z>>(props: VerdictBase & { value: K; id?: string }): ReactNode;
}