@allxsmith/bestax-bulma 5.54.0 → 5.55.0

package/dist/index.esm.js

@@ -33,6 +33,7 @@ export { Reveal } from './esm/components/Reveal.js';
 export { TreeView, TreeViewItem } from './esm/components/TreeView.js';
 export { ScrollArea } from './esm/components/ScrollArea.js';
 export { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList } from './esm/components/Command.js';
+export { DataTable } from './esm/components/DataTable.js';
 export { Block } from './esm/elements/Block.js';
 export { Box } from './esm/elements/Box.js';
 export { Button } from './esm/elements/Button.js';
@@ -40,6 +41,7 @@ export { Buttons } from './esm/elements/Buttons.js';
 export { LinkButton } from './esm/elements/LinkButton.js';
 export { ToggleButton } from './esm/elements/ToggleButton.js';
 export { Code } from './esm/elements/Code.js';
+export { ColorSwatch } from './esm/elements/ColorSwatch.js';
 export { Content } from './esm/elements/Content.js';
 export { Delete } from './esm/elements/Delete.js';
 export { DescriptionList, DescriptionListItem, DescriptionListLabel, DescriptionListValue } from './esm/elements/DescriptionList.js';
@@ -78,6 +80,7 @@ export { Checkbox, checkboxColors, checkboxSizes } from './esm/form/Checkbox.js'
 export { CheckboxCard } from './esm/form/CheckboxCard.js';
 export { Checkboxes } from './esm/form/Checkboxes.js';
 export { Control } from './esm/form/Control.js';
+export { Dropzone } from './esm/form/Dropzone.js';
 export { Field, FieldBody, FieldLabel } from './esm/form/Field.js';
 export { Fieldset } from './esm/form/Fieldset.js';
 export { File } from './esm/form/File.js';
@@ -92,6 +95,7 @@ export { Rate } from './esm/form/Rate.js';
 export { Autocomplete } from './esm/form/Autocomplete.js';
 export { Combobox, ComboboxEmpty, ComboboxGroup, ComboboxInput, ComboboxItem, ComboboxList, ComboboxMenu } from './esm/form/Combobox.js';
 export { TagInput, Taginput } from './esm/form/Taginput.js';
+export { ColorPicker, ColorPickerAlphaSlider, ColorPickerArea, ColorPickerHueSlider, ColorPickerInput, ColorPickerSwatches } from './esm/form/ColorPicker.js';
 export { InputBase } from './esm/form/InputBase.js';
 export { SelectBase } from './esm/form/SelectBase.js';
 export { TextAreaBase } from './esm/form/TextAreaBase.js';
@@ -127,6 +131,7 @@ export { Media, MediaContent, MediaLeft, MediaRight } from './esm/layout/Media.j
 export { Section } from './esm/layout/Section.js';
 export { Splitter, SplitterPane } from './esm/layout/Splitter.js';
 export { useColorClasses, useColorStyles } from './esm/helpers/useColorClasses.js';
+export { useDataTable } from './esm/components/useDataTable.js';
 export { useFlexboxClasses } from './esm/helpers/useFlexboxClasses.js';
 export { useOtherClasses } from './esm/helpers/useOtherClasses.js';
 export { useSpacingClasses } from './esm/helpers/useSpacingClasses.js';

package/dist/index.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/types/components/DataTable.d.ts

@@ -0,0 +1,120 @@
+import React from 'react';
+import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
+import { TrProps } from '../elements/Tr.js';
+import { type DataTableColumn, type DataTableModel, type DataTableStateOptions } from './useDataTable.js';
+export { useDataTable } from './useDataTable.js';
+export type { DataTableCellContext, DataTableCellProps, DataTableCheckboxProps, DataTableColumn, DataTableColumnMeta, DataTableFilters, DataTableHeaderCellProps, DataTableLabels, DataTableModel, DataTablePaginationProps, DataTableResolvedLabels, DataTableRowScope, DataTableSearchProps, DataTableSelectionMode, DataTableSort, DataTableSortButtonProps, DataTableSortDirection, DataTableState, DataTableStateOptions, UseDataTableOptions, } from './useDataTable.js';
+/**
+ * Props for the DataTable component. The helper props, `className`, the
+ * `ref` and the other attributes go on the wrapper `<div>`, which holds the
+ * toolbar, the table and the pager. `aria-label` and `aria-labelledby` name
+ * the `<table>` itself.
+ *
+ * @extraProp {string} [aria-label] - Names the table, in place of a `caption`. A table needs a name, so pass a `caption`, this or `aria-labelledby`, and a development build warns when it has none.
+ * @extraProp {string} [aria-labelledby] - The id of a visible heading that names the table, in place of a `caption`.
+ * @extraProp {React.Ref<HTMLDivElement>} [ref] - Ref forwarded to the wrapper `<div>`.
+ */
+export interface DataTableProps<TRow> extends DataTableStateOptions<TRow>, Omit<React.HTMLAttributes<HTMLDivElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * The columns, in the order they're shown. Required unless `table` is
+     * given. Keep the array the same from one render to the next, defined
+     * outside the component or in `useMemo`: a new one has every cell's text
+     * worked out again.
+     */
+    columns?: DataTableColumn<TRow>[];
+    /** The rows, as records of your own. Required unless `table` is given. */
+    data?: TRow[];
+    /**
+     * A table made by `useDataTable`, rendered in place of one made from
+     * `columns`, `data` and the state props, which are then left unread. Use
+     * it to put a toolbar, a count or an export button elsewhere on the page.
+     */
+    table?: DataTableModel<TRow>;
+    /**
+     * Names the table, as a visible `<caption>`. A table needs a name: this,
+     * `aria-label` or `aria-labelledby`.
+     */
+    caption?: React.ReactNode;
+    /** Adds borders to all cells. */
+    isBordered?: boolean;
+    /** Adds zebra-striping to rows. */
+    isStriped?: boolean;
+    /** Makes the table more compact by cutting cell padding in half. */
+    isNarrow?: boolean;
+    /** Adds a hover effect on rows. */
+    isHoverable?: boolean;
+    /** Makes the table span the full width of its wrapper. */
+    isFullwidth?: boolean;
+    /**
+     * Scrolls a table wider than its wrapper sideways, in a `ScrollArea`
+     * named after the table, which can be scrolled from the keyboard while it
+     * overflows.
+     */
+    isResponsive?: boolean;
+    /** Shows a search field in the toolbar, labelled by `labels.search`. */
+    hasSearch?: boolean;
+    /**
+     * More of the toolbar, after the search field: buttons for the selected
+     * rows, a filter, a download. Given the table.
+     */
+    toolbar?: (table: DataTableModel<TRow>) => React.ReactNode;
+    /**
+     * Shows a page of skeleton rows under the header in place of the rows,
+     * and marks the table busy. For data on its way, as from a server with
+     * `manual`.
+     */
+    loading?: boolean;
+    /**
+     * What the table shows when it has no rows at all, in one cell across
+     * every column. A small `EmptyState` saying `labels.empty` by default. A
+     * title of your own sits under the heading the table does, so give it the
+     * next level down with `titleAs`.
+     */
+    empty?: React.ReactNode;
+    /**
+     * What the table shows when the search and filters let no row through, in
+     * one cell across every column. A small `EmptyState` saying
+     * `labels.noResults` by default. A button that clears the search goes
+     * away with it, so send focus back to the search field when it's pressed.
+     */
+    noResults?: React.ReactNode;
+    /**
+     * Props of your own for a row's `Tr`, such as a handler or a class. The
+     * table's own (`isSelected`) win. To wrap a row in a `ContextMenu`, build
+     * the table from `useDataTable`'s props instead.
+     */
+    rowProps?: (row: TRow) => DataTableRowProps;
+    /** Additional CSS classes, on the wrapper `<div>`. */
+    className?: string;
+}
+/** What `rowProps` gives a row's `Tr`: any of its props but the ones the table sets. */
+export type DataTableRowProps = Omit<TrProps, 'isSelected' | 'children'>;
+/** The type of `DataTable`, generic in the row. */
+export type DataTableComponent = (<TRow>(props: DataTableProps<TRow> & React.RefAttributes<HTMLDivElement>) => React.ReactElement | null) & {
+    displayName?: string;
+};
+/**
+ * The `DataTable` component is a table of records that people can sort,
+ * search, page through and select rows from, rendered with bestax's own
+ * `Table` parts, `Checkbox` and `Pagination`.
+ *
+ * It's a native table, as in the WAI-ARIA Authoring Practices' sortable
+ * table: a sortable header holds a button, the sorted one carries
+ * `aria-sort`, and each row's checkbox is named for the row. It runs on
+ * `useDataTable`, which custom markup can use too.
+ *
+ * @example
+ * <DataTable
+ *   caption="Users"
+ *   columns={[
+ *     { id: 'name', header: 'Name', sortable: true, isRowHeader: true },
+ *     { id: 'role', header: 'Role', sortable: true },
+ *   ]}
+ *   data={users}
+ *   selectionMode="multiple"
+ *   pageSize={10}
+ *   hasSearch
+ * />
+ */
+export declare const DataTable: DataTableComponent;
+export default DataTable;

package/dist/types/components/useDataTable.d.ts

@@ -0,0 +1,445 @@
+import React from 'react';
+import type { TableAlignment } from '../elements/tableAlignment.js';
+/**
+ * Carries a row type and adds nothing, so `DataTableColumnMeta` can take the
+ * row type for the fields an add-on merges in while it has none of its own.
+ */
+type CarriesRow<TRow> = {
+    [K in never]?: TRow;
+};
+/**
+ * Options of its own an add-on gives a column, read from the column's
+ * `meta`. Empty in bestax: an add-on, such as a spreadsheet exporter, adds
+ * its fields by declaration merging, and every column then takes them. Every
+ * declaration of it names the row type the same way, `TRow`.
+ *
+ * @example
+ * declare module '@allxsmith/bestax-bulma' {
+ *   interface DataTableColumnMeta<TRow> {
+ *     exportValue?: (row: TRow) => string | number;
+ *   }
+ * }
+ */
+export interface DataTableColumnMeta<TRow = unknown> extends CarriesRow<TRow> {
+}
+/** What a column's `cell` is given beside the row. */
+export interface DataTableCellContext {
+    /** The column's raw value for the row, from its `accessor`. */
+    value: unknown;
+    /** The column's text for the row, from its `format`. */
+    text: string;
+    /** The row's id, from `getRowId`. */
+    rowId: string;
+}
+/**
+ * One column of a DataTable. A column keeps three things apart: its raw
+ * value (`accessor`), which sorting and `filterFn` read; its text
+ * (`format`), which the cell shows, the search matches and an export
+ * writes; and its rich content (`cell`), which only the screen sees.
+ */
+export interface DataTableColumn<TRow> {
+    /**
+     * Names the column for good: the sort, the filters and an export refer to
+     * it by this id. Unique within the table, and stable across renders.
+     */
+    id: string;
+    /**
+     * The column's name, as text: the header, the sort button's name, the
+     * row checkboxes' names when it's the row header, and the header an
+     * export writes.
+     */
+    header: string;
+    /**
+     * The raw value, for sorting and filtering: a key of the row, or a
+     * function of it. Left out, it's the row's property named `id`.
+     */
+    accessor?: keyof TRow | ((row: TRow) => unknown);
+    /**
+     * The text for the value: what the cell shows when there's no `cell`, what
+     * the search matches, and what an export writes. Left out, it's the value
+     * as a string, and nothing for `null` or `undefined`. Give one for
+     * numbers and dates you want written a certain way.
+     */
+    format?: (value: unknown, row: TRow) => string;
+    /**
+     * Rich content for the cell, such as a tag or a link. Only the screen
+     * reads it: sorting, the search and an export use the value and its text.
+     */
+    cell?: (row: TRow, context: DataTableCellContext) => React.ReactNode;
+    /**
+     * Makes the header a button that sorts by this column: ascending, then
+     * descending, then unsorted.
+     */
+    sortable?: boolean;
+    /** Sorts descending on the first press, for a column read from the top, such as a score. */
+    sortDescFirst?: boolean;
+    /**
+     * Compares two rows for an ascending sort, returning a negative number,
+     * zero or a positive one. Descending reverses it. Without it, numbers,
+     * dates and booleans compare by value, anything else by its text in the
+     * `LocaleProvider`'s locale with numbers inside it read as numbers ("Item
+     * 9" before "Item 10"), and an empty value goes last either way.
+     */
+    sortFn?: (a: TRow, b: TRow) => number;
+    /**
+     * Whether the column takes part in filtering: the search matches its
+     * text, and `filters` can hold a value for it. `false` leaves it out of
+     * both, as for a column of actions.
+     */
+    filterable?: boolean;
+    /**
+     * Decides whether a row passes this column's value in `filters`. Without
+     * it, the column's text has to contain the value's text, compared as the
+     * search compares.
+     */
+    filterFn?: (row: TRow, filterValue: unknown) => boolean;
+    /** Aligns the header and the cells (`isAligned` on `Th` and `Td`). */
+    align?: TableAlignment;
+    /** The column's width, on its header cell: a number is pixels, a string any CSS length. */
+    width?: string | number;
+    /**
+     * Renders this column's cells as row headers (`th scope="row"`), which a
+     * screen reader reads out with the other cells of the row. The row's
+     * checkbox is named from it. Mark one column, usually the first.
+     */
+    isRowHeader?: boolean;
+    /** Options of an add-on's own, as `DataTableColumnMeta` declares them. */
+    meta?: DataTableColumnMeta<TRow>;
+}
+/** The direction of a sort, in `aria-sort`'s words. */
+export type DataTableSortDirection = 'ascending' | 'descending';
+/** One column a DataTable sorts by. */
+export interface DataTableSort {
+    /** The column's `id`. */
+    id: string;
+    /** Which way it sorts. */
+    direction: DataTableSortDirection;
+}
+/** The values per column `filters` holds, keyed by column `id`. */
+export type DataTableFilters = Record<string, unknown>;
+/**
+ * Which of a table's rows to read: `all` of `data`, `filtered` (the ones the
+ * search and the filters let through, from every page), the `page` shown,
+ * or the `selected` ones the filters let through. Each comes in the order
+ * the table shows them.
+ */
+export type DataTableRowScope = 'all' | 'filtered' | 'page' | 'selected';
+/** Whether a DataTable has row checkboxes. */
+export type DataTableSelectionMode = 'none' | 'multiple';
+/**
+ * The words a DataTable writes. Each is English unless you give your own,
+ * and the numbers in the default messages are written in the
+ * `LocaleProvider`'s locale.
+ */
+export interface DataTableLabels {
+    /**
+     * The header checkbox's name. "Select all rows", or "Select all rows on
+     * this page" when there's more than one page, since it then covers the
+     * page shown.
+     */
+    selectAll?: string;
+    /** A row checkbox's name, from the row's label (`label => 'Select ' + label`). */
+    selectRow?: (rowLabel: string) => string;
+    /**
+     * Says that headers with buttons sort: hidden at the end of the caption,
+     * after a comma, or as a hidden caption of its own. "column headers with
+     * buttons are sortable".
+     */
+    sortHint?: string;
+    /** The search field's label. "Search". */
+    search?: string;
+    /** Announced after the search or a filter changes ("12 rows match"). */
+    results?: (count: number) => string;
+    /** Announced after the page changes ("Showing 11 to 20 of 57"). */
+    pageRange?: (first: number, last: number, total: number) => string;
+    /** Announced while `loading`, once the search, a filter or the page has changed. "Loading". */
+    loading?: string;
+    /**
+     * The pager's name. "{the table's name} pages" when the table is named by
+     * `aria-label` or a text `caption`, so two tables' pagers have different
+     * names, else `Pagination`'s own.
+     */
+    pagination?: string;
+    /** What the table shows with no rows at all. "No rows to show." */
+    empty?: string;
+    /** What the table shows when the search and filters let no row through. "No rows match." */
+    noResults?: string;
+}
+/** The words a DataTable writes, with every default filled in. */
+export interface DataTableResolvedLabels extends Required<Omit<DataTableLabels, 'pagination'>> {
+    /** The pager's name, when one was given. */
+    pagination?: string;
+}
+/**
+ * The options `useDataTable` and `DataTable` share, beside the columns and
+ * the data. Each piece of state is yours when you pass its value (and its
+ * `on…Change`), or the table's own, starting from its `default…`.
+ */
+export interface DataTableStateOptions<TRow> {
+    /**
+     * A row's id, unique and stable, which the selection is a list of. Left
+     * out, it's the row's `id` property as a string. A development build
+     * warns about a missing or repeated id, and a row with none falls back to
+     * its index, which doesn't survive the data changing.
+     */
+    getRowId?: (row: TRow, index: number) => string;
+    /**
+     * The sort when you hold it: an array of `{ id, direction }`, the first
+     * deciding and each next one breaking ties. The headers set one at a time.
+     */
+    sort?: DataTableSort[];
+    /**
+     * The sort to start with when the table holds it. Text sorts in the
+     * `LocaleProvider`'s locale, or the runtime's own outside one, which can
+     * differ between a server and the browser, so put a table rendered on the
+     * server sorted inside a `LocaleProvider`.
+     */
+    defaultSort?: DataTableSort[];
+    /** Called with the new sort when a header is pressed. */
+    onSortChange?: (sort: DataTableSort[]) => void;
+    /**
+     * `multiple` adds a checkbox to each row and a "select all" checkbox to the header.
+     *
+     * @defaultValue 'none'
+     */
+    selectionMode?: DataTableSelectionMode;
+    /**
+     * The selected rows' ids when you hold them. They stay selected while the
+     * search, a filter or the page hides them.
+     */
+    selected?: string[];
+    /** The rows selected to begin with, by id, when the table holds them. */
+    defaultSelected?: string[];
+    /** Called with every selected id after a checkbox changes. */
+    onSelectedChange?: (selected: string[]) => void;
+    /** Rows per page. Set, the table pages through `Pagination`; left out, it shows every row. */
+    pageSize?: number;
+    /**
+     * The page shown when you hold it, counting from 1. A page past the end
+     * shows the last.
+     */
+    page?: number;
+    /**
+     * The page to start on when the table holds it.
+     *
+     * @defaultValue 1
+     */
+    defaultPage?: number;
+    /**
+     * Called with the page chosen in the pager, and with 1 when the search or
+     * a filter changes through the table while the page held isn't 1, even
+     * when a page past the end shows as the last.
+     */
+    onPageChange?: (page: number) => void;
+    /**
+     * The search when you hold it, matched against every filterable column's
+     * text: in the `LocaleProvider`'s locale, ignoring case and the accents
+     * the language ignores, or a case-insensitive substring outside one.
+     */
+    search?: string;
+    /** The search to start with when the table holds it. */
+    defaultSearch?: string;
+    /** Called with the search as it changes through the table. */
+    onSearchChange?: (search: string) => void;
+    /**
+     * A value per column, by `id`, when you hold them. A row passes when every
+     * column with a value passes it: the column's `filterFn` if it has one,
+     * given the value as it is, or else the column's text has to contain the
+     * value's text, compared as the search compares. An array is a choice of
+     * values, as a multiple-choice filter gives, and passes a row whose text
+     * contains any of them. A value of `undefined`, `null`, `''` or an empty
+     * array is no filter.
+     */
+    filters?: DataTableFilters;
+    /** The filters to start with when the table holds them. */
+    defaultFilters?: DataTableFilters;
+    /** Called with every filter value after one changes through the table. */
+    onFiltersChange?: (filters: DataTableFilters) => void;
+    /**
+     * Hands sorting, filtering and paging to a server: the table shows `data`
+     * as given, as the current page, and only reports the state as it
+     * changes.
+     */
+    manual?: boolean;
+    /**
+     * With `manual`, how many rows match in all, which sets the page count and
+     * the announced count. Without it, the table counts the rows in `data`,
+     * which with a `pageSize` is one page and no pager, and a development
+     * build warns.
+     */
+    rowCount?: number;
+    /** The words the table writes, in your app's language. */
+    labels?: DataTableLabels;
+}
+/** What `useDataTable` takes. */
+export interface UseDataTableOptions<TRow> extends DataTableStateOptions<TRow> {
+    /**
+     * The columns, in the order they're shown. Keep the array the same from
+     * one render to the next, defined outside the component or in `useMemo`:
+     * a new one has every cell's text worked out again.
+     */
+    columns: DataTableColumn<TRow>[];
+    /** The rows, as records of your own. */
+    data: TRow[];
+}
+/** The table's state, as it stands. */
+export interface DataTableState {
+    /** The sort, the first entry deciding. */
+    sort: DataTableSort[];
+    /** The selected rows' ids. */
+    selected: string[];
+    /** The page shown, counting from 1. */
+    page: number;
+    /** Rows per page, or `undefined` when it doesn't page. */
+    pageSize: number | undefined;
+    /** The search. */
+    search: string;
+    /** The filter values, by column id. */
+    filters: DataTableFilters;
+}
+/** The props `getSortButtonProps` gives a header's `<button>`. */
+export interface DataTableSortButtonProps {
+    type: 'button';
+    className: string;
+    onClick: () => void;
+}
+/** The props `getSearchProps` gives a search `<input>` or bestax `Input`. */
+export interface DataTableSearchProps {
+    type: 'search';
+    value: string;
+    onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+}
+/** The props `getHeaderCellProps` gives a column's `Th`. */
+export interface DataTableHeaderCellProps {
+    scope: 'col';
+    'aria-sort'?: DataTableSortDirection;
+    isAligned?: TableAlignment;
+    width?: string | number;
+}
+/** The props `getCellProps` gives a row's `Td`, or its `Th` for the row header. */
+export interface DataTableCellProps {
+    scope?: 'row';
+    isAligned?: TableAlignment;
+}
+/** The props `getSelectAllProps` and `getSelectRowProps` give a `Checkbox`. */
+export interface DataTableCheckboxProps {
+    'aria-label': string;
+    checked: boolean;
+    indeterminate?: boolean;
+    disabled?: boolean;
+    onChange: () => void;
+}
+/** The props `getPaginationProps` gives `Pagination`. */
+export interface DataTablePaginationProps {
+    total: number;
+    current: number;
+    onPageChange: (page: number) => void;
+}
+/**
+ * A table: what `useDataTable` returns, what `DataTable`'s `toolbar` is
+ * given, and what its `table` takes. It reads the rows and the state, changes
+ * the state, and hands out props for bestax's own `Th`, `Tr`, `Td`,
+ * `Checkbox` and `Pagination`, so markup of your own behaves as DataTable's
+ * does.
+ */
+export interface DataTableModel<TRow> {
+    /** The columns, in the order they're shown. */
+    columns: DataTableColumn<TRow>[];
+    /** The state as it stands. */
+    state: DataTableState;
+    /** Whether rows have checkboxes. */
+    selectionMode: DataTableSelectionMode;
+    /** Whether a server sorts, filters and pages (`manual`). */
+    manual: boolean;
+    /** How many rows the search and filters let through, or `rowCount` with `manual`. */
+    rowCount: number;
+    /** How many pages there are, at least 1. */
+    pageCount: number;
+    /** The words the table writes, with the defaults filled in. */
+    labels: DataTableResolvedLabels;
+    /** The rows in `scope` (`filtered` by default), in the order the table shows them. */
+    getRows: (scope?: DataTableRowScope) => TRow[];
+    /** A row's id. */
+    getRowId: (row: TRow) => string;
+    /** A column's raw value for a row, or `undefined` for a column it doesn't have. */
+    getValue: (row: TRow, columnId: string) => unknown;
+    /** A column's text for a row, or `''` for a column it doesn't have. */
+    getText: (row: TRow, columnId: string) => string;
+    /** What names a row: its row header's text, or its first column's. */
+    getRowLabel: (row: TRow) => string;
+    /** Whether a row is selected. */
+    isSelected: (row: TRow) => boolean;
+    /** Sets the sort. */
+    setSort: (sort: DataTableSort[]) => void;
+    /** Moves a column through its sort, as its header button does. */
+    toggleSort: (columnId: string) => void;
+    /** Sets the selected ids. */
+    setSelected: (selected: string[]) => void;
+    /**
+     * Selects a row, or clears it, or with no `selected` flips it. Called
+     * twice in one handler, the second call builds on the first while the
+     * table holds the selection. While you hold it, each call builds on the
+     * selection as rendered, so make several changes at once with
+     * `setSelected`.
+     */
+    toggleRowSelected: (row: TRow, selected?: boolean) => void;
+    /**
+     * Selects every row on the page, or clears them, or with no `selected`
+     * does what the header checkbox does. It builds on earlier calls as
+     * `toggleRowSelected` does.
+     */
+    togglePageSelected: (selected?: boolean) => void;
+    /** Goes to a page, counting from 1. */
+    setPage: (page: number) => void;
+    /**
+     * Sets the search, and goes back to page 1, calling `onPageChange` with 1
+     * unless the page held is 1 already.
+     */
+    setSearch: (search: string) => void;
+    /**
+     * Sets one column's filter value, and goes back to page 1. Called twice in
+     * one handler, the second call builds on the first while the table holds
+     * the filters. While you hold them, each call builds on the filters as
+     * rendered, so set several at once with `setFilters`.
+     */
+    setFilter: (columnId: string, value: unknown) => void;
+    /** Sets every filter value, and goes back to page 1, as `setSearch` does. */
+    setFilters: (filters: DataTableFilters) => void;
+    /** Props for a column's `Th`: its scope, its `aria-sort` while sorted, its alignment and width. */
+    getHeaderCellProps: (column: DataTableColumn<TRow>) => DataTableHeaderCellProps;
+    /** Props for the `<button>` in a sortable column's header. */
+    getSortButtonProps: (column: DataTableColumn<TRow>) => DataTableSortButtonProps;
+    /** Props for a row's `Tr`: Bulma's selected look while it's selected. */
+    getRowProps: (row: TRow) => {
+        isSelected: boolean;
+    };
+    /** Props for a row's cell in a column: its alignment, and `scope="row"` for the row header. */
+    getCellProps: (row: TRow, column: DataTableColumn<TRow>) => DataTableCellProps;
+    /** Props for the header's "select all" `Checkbox`, which covers the page shown. */
+    getSelectAllProps: () => DataTableCheckboxProps;
+    /** Props for a row's `Checkbox`, named for the row. */
+    getSelectRowProps: (row: TRow) => DataTableCheckboxProps;
+    /** Props for `Pagination`: the page count, the page and the handler. */
+    getPaginationProps: () => DataTablePaginationProps;
+    /** Props for a search field, bound to the search. */
+    getSearchProps: () => DataTableSearchProps;
+}
+/**
+ * Whether a search or a filter value is narrowing the rows. Used by
+ * DataTable to tell an empty table from one with no matches.
+ */
+export declare function isFiltering(search: string, filters: DataTableFilters): boolean;
+/**
+ * `useDataTable` holds a table's sort, selection, page, search and filters,
+ * works out its rows, and hands out props for bestax's own table parts, so
+ * custom markup behaves as `DataTable` does. Pass its result to
+ * `<DataTable table={table} />` to render it with DataTable's own markup,
+ * with a toolbar or an export button elsewhere on the page.
+ *
+ * @example
+ * const table = useDataTable({ columns, data: users, pageSize: 10 });
+ *
+ * <DataTable table={table} caption="Users" hasSearch />
+ */
+export declare function useDataTable<TRow>(options: UseDataTableOptions<TRow>): DataTableModel<TRow>;
+export {};

package/dist/types/elements/ColorSwatch.d.ts

@@ -0,0 +1,54 @@
+import React from 'react';
+import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses.js';
+declare const validColorSwatchSizes: readonly ["small", "medium", "large"];
+/**
+ * Props for the ColorSwatch component. The helper props, the other
+ * attributes and the `ref` land on its `<span>`.
+ *
+ * @extraProp {React.Ref<HTMLSpanElement>} [ref] - Ref forwarded to the `<span>`.
+ * @extraProp {string} [aria-label] - Names the swatch in place of `label`.
+ * @extraProp {boolean} [aria-hidden] - Hides the swatch from assistive tech, for one beside text that already names the color.
+ */
+export interface ColorSwatchProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'color' | 'role'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * The color it shows: any CSS color, such as `#1e6b99`,
+     * `hsl(202, 67%, 36%)` or `var(--bulma-primary)`. A see-through color
+     * shows a checkerboard behind it.
+     */
+    color: string;
+    /**
+     * What the color is called, such as "Brand blue", read as the swatch's
+     * name in place of `color` as written. A `var()` reads as nothing useful,
+     * so a development build warns when one has no name.
+     */
+    label?: string;
+    /** The swatch's size. */
+    size?: (typeof validColorSwatchSizes)[number];
+    /** Draws a circle in place of a rounded square. */
+    isRounded?: boolean;
+    /**
+     * Drawn on the swatch, such as an icon. It's hidden from assistive tech,
+     * since the swatch is an image named by its label.
+     */
+    children?: React.ReactNode;
+    /** Text color helper, the color of anything drawn on the swatch. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * The `ColorSwatch` component shows a color as a small chip, named by its label or by the color itself.
+ *
+ * It's an image to assistive tech, so the color is always there in words.
+ * In forced colors it keeps its color, edged in the system's text color.
+ *
+ * @function
+ * @param {ColorSwatchProps} props - Props for the ColorSwatch component.
+ * @param {React.Ref<HTMLSpanElement>} ref - Forwarded ref to the `<span>`.
+ * @returns {JSX.Element} The rendered swatch.
+ *
+ * @example
+ * <ColorSwatch color="#1e6b99" label="Brand blue" />
+ */
+export declare const ColorSwatch: React.ForwardRefExoticComponent<ColorSwatchProps & React.RefAttributes<HTMLSpanElement>>;
+export default ColorSwatch;