@eifi1/ui-kit 0.33.0 → 0.34.0

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

@@ -1,15 +1,603 @@
-import 'react';
-export { a as DEFAULT_DATA_TABLE_SORT_LABELS, b as DataTable, G as DataTableCellProps, c as DataTableChrome, d as DataTableColumn, e as DataTableDensity, H as DataTableHeadProps, g as DataTableProps, h as DataTableRowAction, i as DataTableSortLabels, F as FilterState, M as MobileSwipeActions, S as ServerPagination } from '../data-table-labels-BJ5JE_X2.js';
-export { SortState } from './data-table-sort.js';
-import './swipeable-row.js';
-import './status-dot.js';
-import './progress-bar.js';
-import './signed-amount.js';
-import './stat-tile.js';
-import './chip.js';
-import 'lucide-react';
-import './field-parts.js';
-import './tooltip.js';
-import '../hooks/use-anchored-rect.js';
-import '../lib/clipping.js';
-import './write-lock.js';
+import type { ReactNode, TdHTMLAttributes, ThHTMLAttributes } from "react";
+import type { ColumnFilter, FilterValue } from "./data-table-filters.js";
+import type { SortCycle, SortDir, SortState } from "./data-table-sort.js";
+import type { SwipeAction } from "./swipeable-row.js";
+import { type DataTableLabels } from "./data-table-labels.js";
+import { type LabelOverride } from "../i18n/kit-labels.js";
+export interface DataTableColumn<T> {
+    key: string;
+    header: ReactNode;
+    cell: (row: T) => ReactNode;
+    sortBy?: (row: T) => string | number | null | undefined;
+    filter?: ColumnFilter<T>;
+    filterBy?: (row: T) => string;
+    className?: string;
+    headClassName?: string;
+    mobilePrimary?: boolean;
+    mobileHidden?: boolean;
+    /**
+     * Set on a column whose cell renders its own `<a>` (or anything else that must
+     * keep its own click): the row anchor of `rowHref` then skips it and lands on
+     * the next column that allows wrapping (Keksdose feedback #451). Without it the
+     * fallback can wrap such a cell the moment the headline column is hidden from
+     * the settings panel — `<a>` inside `<a>`, which React warns about and which
+     * kills the inner link outright, since RowLink cancels the click on the capture
+     * phase and the cell's own `stopPropagation` then blocks the row handler too.
+     * The rejected alternative was sniffing the rendered output for an anchor: a
+     * cell that renders a link is a fact its author knows and the renderer cannot
+     * see without reaching into React elements it deliberately treats as opaque.
+     */
+    noRowLink?: boolean;
+    /**
+     * The direction this column sorts in on its FIRST click. `"desc"` for money and
+     * count columns, where the rows worth reading are the large ones and an ascending
+     * first click opens on the zero rows (keksdose's aggregated report tables). The
+     * rest of the cycle follows from it — see {@link DataTableProps.sortCycle}.
+     * Default `"asc"`.
+     */
+    firstSort?: SortDir;
+    /**
+     * The column's name as plain text, for the places a ReactNode `header` cannot go:
+     * the phone sort control's options ({@link DataTableProps.mobileSort}), the spoken
+     * "Sorted by …" and the column-settings checklist. Only needed when `header` is not
+     * a string (an icon, a unit suffix); without it those places fall back to the
+     * header string, then to `key`.
+     */
+    headerText?: string;
+    /**
+     * Extra attributes for this column's `<td>` in a given row — a `data-*` hook, a
+     * `title`, an `aria-describedby`, a class. keksdose's accounts page
+     * (accounts-page.tsx, the name and IBAN columns) is why it exists: its demo mode
+     * blurs everything marked `data-private`, and with nowhere to put the marker on the
+     * cell it wrapped every value in an inner `<span data-private>` — which blurs the
+     * text but not the cell, and has to be remembered in every `cell` renderer.
+     *
+     * MERGED under the kit's own, which win: `className` is joined before the column's
+     * `className` (so the column's alignment is still the alignment), `style` is laid
+     * under a resized column's pinned width, and `data-col` and a `role` stay the
+     * table's — `data-col` is how a resize finds the column's cells, and a `<td>` that
+     * claims another role leaves its row's cell count wrong for a screen reader.
+     *
+     * On a phone the card field (`<dd>`, or the primary line) gets the `data-*`
+     * attributes only: the rest — padding classes, `colSpan`, a width — describe a
+     * table cell and would mean something else, or nothing, on a card.
+     */
+    cellProps?: (row: T) => DataTableCellProps | undefined;
+    /** The same for the column's `<th>`, once. `scope`, `aria-sort`, `data-col` and the
+     *  width a resize pins stay the table's, and the class list goes before
+     *  `headClassName` for the same reason as in {@link cellProps}. */
+    headProps?: DataTableHeadProps;
+    /**
+     * This column's cell in the table's totals row — a `<tfoot>` on a wide screen, a
+     * labelled summary card under the list on a phone. kastlan's trial balance is why
+     * it exists: it hand-built a debit/credit/balance strip in a `div` UNDER the table,
+     * which lined up with no column, dropped out of the table's semantics, and stayed
+     * put when the user hid or resized the columns it was summing.
+     *
+     * `rows` is every row that passes the current filters (in the current sort order),
+     * NOT just the page on screen: a total that changes when the user pages is not a
+     * total, and the trial balance has to balance on page 1 as much as on page 7. The
+     * page is the second argument for the rare "subtotal of this page" footer.
+     *
+     * Under `serverPagination` the table only ever holds one page, so both arguments are
+     * that page — a server-side table computes its totals on the server and returns
+     * them here (`footer: () => fmt(response.totalDebit)`), ignoring the arguments.
+     *
+     * The cell takes the column's `className` (so a `text-end` amount column totals
+     * end-aligned), its resized width, and drops out with the column when it is hidden.
+     */
+    footer?: (rows: T[], page: T[]) => ReactNode;
+}
+/** A `data-*` attribute, typed so `{ "data-private": "" }` needs no cast. */
+type DataAttributes = {
+    [key: `data-${string}`]: string | number | boolean | undefined;
+};
+/** What {@link DataTableColumn.cellProps} may return. */
+export type DataTableCellProps = TdHTMLAttributes<HTMLTableCellElement> & DataAttributes;
+/** What {@link DataTableColumn.headProps} takes. */
+export type DataTableHeadProps = ThHTMLAttributes<HTMLTableCellElement> & DataAttributes;
+export interface ServerPagination {
+    page: number;
+    pageSize: number;
+    total: number;
+    onPageChange: (page: number) => void;
+    /** Without it the page size is the server's to choose, and the pager shows no
+     *  page-size select at all — one that changed nothing was a control that lied. */
+    onPageSizeChange?: (pageSize: number) => void;
+    /**
+     * A page is being fetched. The table marks itself `aria-busy`, dims the rows it is
+     * still showing (they are the PREVIOUS page's, and about to go), and replaces the
+     * empty state with a loading row when there is nothing to show yet — "no results"
+     * while the first page is still in flight is a claim the table cannot make.
+     *
+     * The pager stays usable. Disabling it would drop focus from the very button the
+     * user just pressed (a disabled button cannot hold focus), and a second click
+     * during a fetch is a request the owner already has to handle for a slow network.
+     */
+    isLoading?: boolean;
+}
+export interface DataTableProps<T> {
+    rows: T[];
+    columns: DataTableColumn<T>[];
+    rowKey: (row: T) => string | number;
+    defaultPageSize?: number;
+    onRowClick?: (row: T) => void;
+    /**
+     * The URL that shows this row, when one exists — the table then renders a REAL
+     * anchor for it (Keksdose feedback #451, "to be able to middle click with the
+     * mouse and open in a new tab"). A row that opens through `onRowClick` alone is
+     * invisible to the browser: no middle click, no ⌘/Ctrl-click, no "copy link
+     * address", no status-bar preview, no long-press menu on a phone. The
+     * alternative was an `onAuxClick` that calls `window.open` — it buys back only
+     * the middle click and loses the other four, none of which JavaScript can fake.
+     *
+     * Return `undefined` for a row that has no address of its own. Only wire this up
+     * where the OPEN row is genuinely in the URL (a `?row=` param, a detail route);
+     * a row whose expansion lives in local component state has no link to hand out,
+     * and a link the target page cannot honour is worse than no link.
+     *
+     * The anchor covers the row's primary cell, not the whole `<tr>`: an `<a>` may
+     * not wrap table cells, and the absolutely-positioned row overlay that is the
+     * usual workaround would sit on top of the per-cell controls these rows carry
+     * (status toggles, the selection checkbox, nested links) and swallow them.
+     */
+    rowHref?: (row: T) => string | undefined;
+    expandedRow?: (row: T) => ReactNode | null;
+    isExpanded?: (row: T) => boolean;
+    /**
+     * Extra classes for a row — the `<tr>` on desktop, the card on mobile. Merged last,
+     * so a `hover:` fill here replaces the row's own `hover:bg-hover`.
+     *
+     * **A row you paint has to pick its own hover** (0.33, docs/colour-roles-harmonization.md
+     * §12.2): the kit cannot see your rest colour, and `--bg-hover` is mixed against the
+     * card. The rule: a hover differs from its rest by 1.08:1 or more, and every text role
+     * on it keeps 4.5:1.
+     * - A row that rests on the well (`bg-surface-2`) hovers to the CARD,
+     *   `hover:bg-surface`: in light the well is the page, and `--bg-hover` sits 1.04:1
+     *   from it.
+     * - A row whose well MARKS A STATE (selected) keeps its fill and draws a 1 px inside
+     *   line instead, since the card would read as "not selected":
+     *   `bg-surface-2 hover:bg-surface-2 hover:outline hover:-outline-offset-1 hover:outline-strong`.
+     *   An outline, not a shadow: a shadow on a `<tr>` is not painted by every engine.
+     * - Not `--bg-active` for a selected row: its muted and money text fall to 3.8–4.7:1.
+     */
+    rowClassName?: (row: T) => string | undefined;
+    /**
+     * Extra DOM attributes for a row's container — the `<tr>` on desktop, the
+     * `<li>` on mobile. For hooks that have to sit on the row itself rather than
+     * inside a cell: guided-tour anchors, analytics ids, e2e selectors. Undefined
+     * values are dropped, so a per-row conditional needs no filtering at the call
+     * site. Not a styling escape hatch — that is `rowClassName`.
+     */
+    rowAttributes?: (row: T) => Record<string, string | undefined> | undefined;
+    /**
+     * Set false for a table that is short by construction — an invoice's line
+     * items, a wizard's picks — where the pager is chrome around a list that can
+     * never need one. Renders every row and drops the footer entirely. Ignored in
+     * `serverPagination` mode, where the pager is the only way to reach the rest
+     * of the data.
+     */
+    paginated?: boolean;
+    empty?: ReactNode;
+    /**
+     * If set, the table persists filter / sort / page-size state to localStorage under this key.
+     * Use a stable, unique key per table (e.g. "transactions-table").
+     */
+    storageKey?: string;
+    /**
+     * When true, mirror filter/sort/page state into URL search params so views are
+     * shareable and bookmarkable. URL params used: `f.<column>`, `sort`, `p`, `ps`.
+     * URL state takes precedence over localStorage on initial load. Requires the
+     * consuming app to render inside a react-router Router.
+     *
+     * `{ prefix }` namespaces them, for two URL-synced tables on one page:
+     * `urlSync={{ prefix: "inv." }}` uses `inv.f.<column>`, `inv.sort`, `inv.p`, `inv.ps`.
+     */
+    urlSync?: TableUrlSync;
+    /**
+     * When true, the table fills its parent's height and scrolls INTERNALLY, with the
+     * header pinned — so the page itself doesn't add a second, outer scrollbar. On a
+     * phone the card list is the scroller instead, with the filter button pinned above
+     * it; an unbounded parent simply lets either layout grow to its content. The parent must give it a bounded height (e.g. a flex
+     * column inside the viewport-locked app shell). See feedback #207.
+     *
+     * The cure for TWO SCROLLBARS (round 0.34 C14, kastlan feedback 55): the default
+     * `maxBodyHeight` scrolls the body inside a page that scrolls too. How a page fills
+     * the height is in {@link DataTableProps.maxBodyHeight}'s note.
+     */
+    fillHeight?: boolean;
+    /** How tall the scrolling body may get before it scrolls, as a CSS length.
+     *
+     *  Default `calc(100dvh - 12rem)`, which is what every caller had before this
+     *  existed: a bound is what makes the sticky header work, because a header
+     *  can only stick to a wrapper that actually scrolls. The cap assumes the
+     *  table has page chrome above and below it, and a table that is the last
+     *  thing on its page can afford more — ASPICE Atlas report #12, "for the 25
+     *  elements there should in best case be no scrolling necessary".
+     *
+     *  Ignored under `fillHeight`, which bounds the body by its flex parent
+     *  instead and is the stronger statement of the same intent.
+     *
+     *  **Two scrollbars** (round 0.34 C14, kastlan feedback 55). The cap scrolls the
+     *  body INSIDE a page that, in most shells, scrolls itself: a table taller than
+     *  the cap on a page with anything else on it shows two scrollbars side by side,
+     *  and the wheel moves whichever is under the pointer. For a list page whose table
+     *  is the point, fill the height instead, from `md` up (a phone scrolls the page
+     *  and its card list as one):
+     *
+     *  1. the shell's content column becomes a flex column of the main area's height
+     *     when the page asks — kastlan's
+     *     `md:has-[>[data-fill-height]]:flex md:has-[>[data-fill-height]]:h-full md:has-[>[data-fill-height]]:flex-col`;
+     *  2. the page's root asks, and is a flex column that may shrink:
+     *     `data-fill-height` and `md:flex md:min-h-0 md:flex-1 md:flex-col`;
+     *  3. the table takes the rest: `<DataTable fillHeight>`.
+     *
+     *  Only the body then scrolls, under its pinned header, and every other page grows
+     *  with its content as before (kastlan e3985c9, its leases list). A short table that
+     *  is the last thing on its page can instead drop the cap: `maxBodyHeight="none"`. */
+    maxBodyHeight?: string;
+    /**
+     * When provided, the table renders the supplied rows as-is (no client-side
+     * filtering/sorting/slicing) and the pagination footer is driven by these
+     * server-controlled values. Column-level filters and sorting are hidden
+     * UNLESS the caller takes them over via `onFiltersChange`/`onSortsChange` —
+     * the caller is then expected to translate the state into the server query
+     * that produces `rows`.
+     */
+    serverPagination?: ServerPagination;
+    /**
+     * Controlled filter/sort state. When the `on*Change` callback is provided
+     * the table stops owning that piece of state: it renders `filters`/`sorts`
+     * as given and reports user interactions through the callback (including
+     * in serverPagination mode, where the UI is otherwise disabled).
+     *
+     * Page reset: on a client-side table, a change in the VALUE of `filters` or
+     * `sorts` sends the table back to page 1 — whoever made the change, the user
+     * through the header or the owner from outside (a saved view, a chip). Compared
+     * by value, so passing a fresh but equal object on every render does not reset
+     * anything. In `serverPagination` mode the owner's `page` is the page, and
+     * resetting it on a filter change stays the owner's job.
+     */
+    filters?: FilterState;
+    onFiltersChange?: (next: FilterState) => void;
+    sorts?: SortState[];
+    onSortsChange?: (next: SortState[]) => void;
+    /**
+     * Opt-in multi-row selection (desktop table only). When provided, a leading
+     * checkbox column is rendered with a select-all box in the header; the owner
+     * holds the selected set and reacts via the callbacks. Rows for which
+     * `isSelectable` returns false render no checkbox and are excluded from
+     * select-all. See feedback #285 (bulk edit).
+     */
+    selection?: {
+        isSelectable?: (row: T) => boolean;
+        isSelected: (row: T) => boolean;
+        onToggle: (row: T, checked: boolean) => void;
+        /**
+         * Commit a whole Shift+click range in ONE call (audit 2026-09-22).
+         *
+         * Optional and purely additive: without it the range is still walked row by
+         * row, exactly as before. With it, an owner holding a `Set` copies that Set
+         * once instead of once per row — a 400-row range was 400 `onToggle` calls,
+         * 400 Set copies and 400 renders of this table, all to reach a state the
+         * owner could have reached in one.
+         *
+         * `rows` is already filtered by `isSelectable` and is in the order the table
+         * is showing, so it can be applied as-is.
+         */
+        onToggleMany?: (rows: T[], checked: boolean) => void;
+        allSelected: boolean;
+        someSelected: boolean;
+        onToggleAll: (checked: boolean) => void;
+    };
+    /** User-facing strings (English defaults); pass translated overrides. Merged over
+     *  `dataTable` from `<UiKitProvider labels>`, so a call site only states what
+     *  differs for THIS table — typically `table`, its accessible name. */
+    labels?: LabelOverride<DataTableLabels>;
+    /** BCP-47 locale for the date filter's calendar and the pager's numbers. Falls
+     *  back to `<UiKitProvider locale>`, then to the runtime's default. */
+    locale?: string;
+    /** localStorage namespace prefix for `storageKey` persistence: the stored key is this
+     *  plus `storageKey`. Falls back to `<UiKitProvider tableStorageKeyPrefix>` (0.34, set
+     *  your app's prefix there once), then to "hbui-table:". This prop wins over both. */
+    storageKeyPrefix?: string;
+    /**
+     * On phones, surface the expanded row's detail in a full-screen dialog instead
+     * of unfolding it inline (feedback #204). Desktop always uses inline expansion.
+     */
+    mobileExpandAsDialog?: boolean;
+    /**
+     * Show the `mobileHidden` columns in the OPENED row on the phone layout — inline
+     * under the card, or in the `mobileExpandAsDialog` dialog — so a column dropped from
+     * the card to keep it short is not lost (0.32, docs/text-size-harmonization.md §4:
+     * "a new `mobileDetailsInRow` puts the `mobileHidden` columns into the opened row, so
+     * nothing is lost"). At Large a card holds fewer facts per screen, and dropping one
+     * from the card must not drop it from the phone.
+     *
+     * Each column is a label above its value, BEFORE what `expandedRow` renders: the
+     * row's own facts first, then the app's detail or editor. A row opens as it always
+     * does (`onRowClick` toggling `isExpanded`); with this set it may open without an
+     * `expandedRow` at all. `rowActions`' column is one of them — the actions, which the
+     * card otherwise offers only as swipes, reachable by a tap. Desktop is unaffected.
+     */
+    mobileDetailsInRow?: boolean;
+    /**
+     * The row's name, as plain text — for the "⋯" menu its `rowActions` collapse into at
+     * Large ("Actions for Ada Example", §10.8). Without it every row's menu button is
+     * named "Actions", which a screen reader cannot tell apart down the list.
+     */
+    rowName?: (row: T) => string | undefined;
+    /**
+     * The phone row dialog's `backCloses` ({@link FullBleedDialog}): whether it pushes
+     * its own history entry so Back dismisses it. On by default — right for a row whose
+     * expansion is component state, where nothing else would answer Back.
+     *
+     * **Set it `false` when the open row is in the URL** and opening it PUSHES (a
+     * `?row=` written with `useSearchParamState(…, { history: "replace-on-clear" })` or
+     * `"push"`): Back already closes the row through the router, and a second entry on
+     * top of the page's is two owners of one Back press (keksdose dev #584). Keep it on
+     * when opening the row REPLACES the URL — then nothing was pushed, and the dialog's
+     * own entry is the only thing Back can pop.
+     *
+     * The table cannot decide this for you: `isExpanded` is a predicate, and neither it
+     * nor `rowHref` says whether opening pushed or replaced (keksdose's feedback page
+     * has `rowHref` with a REPLACING `?row=`, and needs the entry). Ignored unless
+     * `mobileExpandAsDialog`.
+     */
+    mobileDialogBackCloses?: boolean;
+    /**
+     * Group the mobile card list into sections, each with a sticky header — the
+     * "assistance"-style list (like the transactions list grouped by date, but by
+     * whatever key you return, e.g. a name's first letter). The returned string is
+     * the section a row belongs to; rows must already be ordered so equal keys are
+     * contiguous (pair with a matching default sort). `mobileGroupLabel` formats
+     * the header. Desktop is unaffected. Feedback #317.
+     */
+    mobileGroupBy?: (row: T) => string;
+    mobileGroupLabel?: (key: string) => ReactNode;
+    /**
+     * Fully replace the default mobile card body (bold primary + labelled
+     * key/value rows) with a compact custom layout, while keeping the shared
+     * clickable/expandable row wrapper. Use when the stacked label/value grid
+     * wastes space (feedback #317). Desktop is unaffected.
+     *
+     * It replaces the WHOLE body, `mobilePrimary` included: a column's
+     * `mobilePrimary` cell is not drawn when `mobileCard` is set, so anything that
+     * cell carried (keksdose's environment and rework chips, 0.27) must be drawn by
+     * the card itself — as `FeedbackMobileCard` does.
+     */
+    mobileCard?: (row: T) => ReactNode;
+    /**
+     * A "Sort by" select and a direction button above the phone card list (keksdose
+     * K10). The card list has no header row, so without it a phone user is stuck with
+     * whatever order the table opened in. It drives the same sort state as the column
+     * headers — `sorts`/`onSortsChange` when controlled, the URL and `storageKey` when
+     * not — and offers the columns a header click could sort (those with a `sortBy`).
+     * Each option is named by the column's `headerText`, else its string `header`.
+     *
+     * Off by default, so no existing phone layout gains a row. Strings:
+     * {@link DataTableSortLabels}. Phones only; the desktop table is unchanged.
+     */
+    mobileSort?: boolean;
+    /**
+     * Swipe actions for a mobile row, revealed by dragging it horizontally. Return
+     * `null` (or empty sides) for rows that should not move — a locked row, one whose
+     * mutation is in flight, one the user has expanded.
+     *
+     * Prefer `start`/`end`: actions committed by dragging the row toward the reading
+     * START or END of the line. In a left-to-right layout `end` is a drag to the
+     * right, and in a right-to-left one it is a drag to the left — so a "drag forward
+     * to archive" row stays forward in Arabic or Hebrew without a second definition.
+     * `left`/`right` are the physical directions and keep meaning exactly that; each
+     * is used only where the logical side for that direction is not given.
+     *
+     * Mobile only, and deliberately so: the desktop table already has room for an
+     * actions column, and a drag gesture on a pointer device is a worse version of a
+     * button. Wraps only the row body, so an expansion panel below stays put while the
+     * row above it slides.
+     */
+    mobileSwipeActions?: (row: T) => MobileSwipeActions | null;
+    /**
+     * Renders as a full-width row above the data rows in the desktop table
+     * (mobile has no equivalent list-row slot, so it's desktop-only). For a
+     * toggle that shows/hides a slice of rows, style it as an expand/collapse
+     * disclosure (chevron + label) so it reads as part of the table rather
+     * than a floating control above it. See feedback #10/#11 (transactions'
+     * "hide upcoming/scheduled" toggle).
+     */
+    leadingRow?: ReactNode;
+    /**
+     * Row height. `"compact"` is lenkbank's in-card tables: five `text-xs` tables with
+     * `px-2 py-1` cells sitting inside cards, which at the default padding came out at
+     * twice their height and pushed the card's own content below the fold — the whole
+     * reason they were still hand-rolled `<table>`s. It tightens the header, the cells,
+     * the selection checkboxes, the pager and the phone cards together, so a compact
+     * table is compact everywhere rather than a dense body under a roomy header.
+     *
+     * Defaults to `"comfortable"`, which is the table every caller has today.
+     */
+    density?: DataTableDensity;
+    /**
+     * What a repeated click on a sorted header does. `"tri"` (the default, and the only
+     * behaviour before 0.8.0): first direction → the other → unsorted. `"toggle"`: first
+     * direction ⇄ the other, never unsorted — for a report table that is always ranked
+     * by something. Each column's first direction is its own `firstSort`. `aria-sort`
+     * and the spoken "Sorted by …" follow whatever the click produced, so they are
+     * right under either cycle.
+     */
+    sortCycle?: SortCycle;
+    /**
+     * The desktop table's power-user chrome, as one switch. `"full"` (default) is the
+     * table as it has always been. `"minimal"` is a compact report table in a half-width
+     * card: no column-settings rail, no resize handles, no multi-sort (and so no
+     * "Shift-click to add a sort" tooltip) — the three pieces that cost width and
+     * attention and that a ten-row summary never needs. Each can still be set on its
+     * own below; an explicit boolean wins over the preset.
+     */
+    chrome?: DataTableChrome;
+    /**
+     * The vertical "Columns (n/m)" rail and its show/hide + auto-size panel. Default:
+     * on, unless `chrome="minimal"`. With it off, every column is shown and a hidden
+     * set persisted under `storageKey` is ignored — there would be no way to get a
+     * column back.
+     */
+    columnSettings?: boolean;
+    /**
+     * The drag handles on the header's trailing edges. Default: on, unless
+     * `chrome="minimal"`. With it off, widths persisted under `storageKey` are ignored
+     * for the same reason as above: nothing could reset them.
+     */
+    resizable?: boolean;
+    /**
+     * Shift-click adds a secondary sort criterion. Default: on, unless
+     * `chrome="minimal"`. With it off, a shift-click sorts like a plain click and the
+     * header drops the tooltip that advertises the gesture.
+     */
+    multiSort?: boolean;
+    /**
+     * The card around the table — border, surface, radius, shadow. Set false to sit the
+     * table inside the app's own card, under its own caption and CSV button, without a
+     * frame inside a frame. The table's layout is unchanged; only the chrome goes.
+     * Default true.
+     */
+    frame?: boolean;
+    /**
+     * Fade out an edge of the desktop table's scroller while columns are hidden behind
+     * it (0.25) — the kit {@link Table}'s `edgeFade`, on the scroller this table draws
+     * itself (DataTable renders its own `<table>`, not through Table, so the prop is
+     * its own too). Measured: nothing is drawn while every column fits; the end with
+     * columns behind it fades, both ends once scrolled into the middle, the reading
+     * direction's ends in RTL. A `mask-image`, so no layout moves and no colour is
+     * assumed; never animated. The scroller's own scrollbars stay out of it — its
+     * vertical one sits at the inline end, in the very band that fades. Focus landing
+     * in a cell behind the fade (a row action, a link, the selection box) is scrolled
+     * clear of it. The scroller carries `data-overflow` (`"start"`, `"end"`, `"both"`).
+     *
+     * The phone layout is a card list that never scrolls sideways; it is unaffected.
+     *
+     * Off by default. It is visual only, but not neutral: on the bump it would change
+     * how every overflowing desktop table in an app looks, and the mask covers
+     * everything the scroller paints — the sticky header and totals rows, an app's own
+     * marks at the scroller's edges. Opt in per table, or app-wide from your own wrapper.
+     */
+    edgeFade?: boolean;
+    /** Extra classes for the table's root element (the card, or with `frame={false}`
+     *  the plain wrapper). Merged last, so a caller's margin or width wins. */
+    className?: string;
+    /**
+     * Per-row actions: an actions column of icon buttons at the row's end on desktop,
+     * and the same actions as swipe actions on a phone card (where the column is not
+     * shown; with `mobileDetailsInRow` also as buttons in the opened row). At Large and
+     * Extra large two or more collapse into one "⋯" menu with each action's words
+     * (0.32, §10.8, `RowActions`) — name the rows with `rowName` so each menu button is
+     * "Actions for …". kastlan's `ResourceListPage` appended this column by hand to every CRUD
+     * list — the edit pencil, the delete bin, a `useConfirm` before the delete, and a
+     * `stopPropagation` on each so a press did not also open the row.
+     *
+     * `kind: "edit"` / `"delete"` bring the icon, the label (`labels.edit` /
+     * `labels.delete`), the tone and the swipe side; any other action states its own
+     * `label` and `icon`. `confirm` is the hook-in for a confirmation: pass the kit's
+     * `useConfirm()` (or anything answering a boolean) and the action runs only on a yes.
+     *
+     *     const confirm = useConfirm();
+     *     rowActions={[
+     *       { kind: "edit", onAction: openEditor },
+     *       { kind: "delete", onAction: (r) => remove(r.id),
+     *         confirm: (r) => confirm({ title: t("delete", { name: r.name }), tone: "danger" }) },
+     *     ]}
+     *
+     * A function receives the row, for actions that differ per row. An explicit
+     * `mobileSwipeActions` wins over the swipes derived from here.
+     */
+    rowActions?: DataTableRowAction<T>[] | ((row: T) => DataTableRowAction<T>[]);
+    /**
+     * The bar above the table — a search field, filter chips, a create button. Inside
+     * the table's frame, above the header, on desktop and phone alike (resource-list
+     * pages set a search box in a `div` above the card, outside the frame it filters).
+     */
+    toolbar?: ReactNode;
+    /**
+     * The totals row's name — "Total", "Summe", "Totals as of 30 June". It is the row's
+     * header: rendered as a `<th scope="row">` in the first visible column that has no
+     * `footer` of its own (falling back to the first visible column if every one has a
+     * value), so a screen reader reads "Total, Debit, 12 400.00" for the cell beside it.
+     * On a phone it heads the summary card, which is also named by it.
+     *
+     * There is no built-in default word: a new kit label key is a silent English string
+     * in every translated app (see `missingDataTableLabels`), and the caller has the
+     * word in its own catalogue already. Without it the row is unlabelled on screen —
+     * pass one.
+     */
+    footerLabel?: ReactNode;
+    /**
+     * Show the totals row. Default: shown when any column declares a `footer`. Set
+     * false to drop it without touching the column definitions (a "show totals"
+     * switch). The row is also left out while there are no rows to total — a row of
+     * zeroes under "No results" says nothing the empty state has not.
+     */
+    footer?: boolean;
+}
+/** One entry of {@link DataTableProps.rowActions}. */
+export interface DataTableRowAction<T> {
+    /** A preset: `"edit"` (pencil, `labels.edit`, swipes toward the END) or `"delete"`
+     *  (bin, `labels.delete`, danger tone, swipes toward the START). */
+    kind?: "edit" | "delete";
+    /** The action's name — its tooltip, accessible name and swipe label. Required
+     *  without a `kind`. */
+    label?: string;
+    /** The glyph. Required without a `kind`. */
+    icon?: ReactNode;
+    /** Runs after `confirm` (when given) has said yes. */
+    onAction: (row: T) => void;
+    /** Asked before `onAction`; a `false` (or a promise of one) cancels. */
+    confirm?: (row: T) => boolean | Promise<boolean>;
+    /** Default: `"danger"` for `kind: "delete"`, else `"default"`. */
+    tone?: "default" | "danger";
+    /** Leave the action out for this row. */
+    hidden?: (row: T) => boolean;
+    /** Why the action is locked for this row — the button stays focusable and says so,
+     *  and the row gets no swipe for it. See `IconButton`'s `disabledReason`. */
+    disabledReason?: (row: T) => ReactNode;
+    /** Which way the phone card is dragged to commit it, or `false` for no swipe.
+     *  Default: `"start"` for a danger action, `"end"` otherwise. */
+    swipe?: "start" | "end" | false;
+}
+/** See {@link DataTableProps.chrome}. */
+export type DataTableChrome = "full" | "minimal";
+/** See {@link DataTableProps.density}. */
+export type DataTableDensity = "comfortable" | "compact";
+export type FilterState = Record<string, FilterValue>;
+export type { SortState };
+/** What {@link DataTableProps.mobileSwipeActions} returns for one row. */
+export interface MobileSwipeActions {
+    /** Committed by dragging toward the reading start (left in LTR, right in RTL). */
+    start?: SwipeAction[];
+    /** Committed by dragging toward the reading end (right in LTR, left in RTL). */
+    end?: SwipeAction[];
+    /** Committed by dragging physically LEFT, whatever the direction. */
+    left?: SwipeAction[];
+    /** Committed by dragging physically RIGHT, whatever the direction. */
+    right?: SwipeAction[];
+}
+/**
+ * The phone sort control's strings (keksdose K10). They are `dataTable` strings —
+ * read from the table's resolved labels, so the `labels` prop and the provider's
+ * `dataTable` namespace reach them — and are declared here, with the table's other
+ * public types (the control itself, `MobileSort`, is in data-table-mobile.tsx), with
+ * English defaults until `DataTableLabels` declares them itself.
+ */
+export interface DataTableSortLabels {
+    /** The control's visible label: "Sort by". */
+    sortBy: string;
+    /** The "no sort" option — the rows in the order they were given: "Default order". */
+    sortDefault: string;
+    /** The direction button's name while the sort ascends: "Ascending". */
+    sortAscending: string;
+    /** …and while it descends: "Descending". */
+    sortDescending: string;
+}
+/** The phone sort control's words, as they sit in {@link DEFAULT_DATA_TABLE_LABELS}
+ *  (DataTableLabels extends DataTableSortLabels; one source for the English). */
+export declare const DEFAULT_DATA_TABLE_SORT_LABELS: DataTableSortLabels;
+import { type TableUrlSync } from "./use-table-state.js";
+export declare function DataTable<T>({ rows, columns: columnsProp, rowKey, defaultPageSize, onRowClick, rowHref, expandedRow, isExpanded, rowClassName, rowAttributes, paginated, empty, storageKey, urlSync, fillHeight, maxBodyHeight, serverPagination, filters: filtersProp, onFiltersChange, sorts: sortsProp, onSortsChange, selection, labels: labelsProp, locale: localeProp, storageKeyPrefix: storageKeyPrefixProp, mobileExpandAsDialog, mobileDetailsInRow, rowName, mobileDialogBackCloses, mobileGroupBy, mobileGroupLabel, mobileCard, mobileSort, mobileSwipeActions, leadingRow, density, sortCycle, chrome, columnSettings: columnSettingsProp, resizable: resizableProp, multiSort: multiSortProp, frame, edgeFade, className, rowActions, toolbar, footerLabel, footer: footerProp, }: DataTableProps<T>): import("react").JSX.Element;