@karni/ui 0.3.1 → 0.4.0

package/dist/src/components/resource/table/ResourceTable.d.ts

@@ -1,16 +1,24 @@
 import { ColumnDef, SortingState } from '@tanstack/react-table';
-import { KarniQueryValue } from '../../../schema/client';
 import { ExportFormat } from '../../../hooks/useResourceImport';
-import { BulkAction } from './BulkActionsBar';
+import { KarniQueryValue } from '../../../schema/client';
+import { BulkAction, BulkResult } from './BulkActionsBar';
 import { ResourceColumn } from './derive-columns';
+import { ResourceTableDensity } from './preferences';
+import { ResourceTableSlots } from './slots';
+import { ResourceTableKeyboardNavigation } from './TableView';
+import { ResourceTableStateStore } from './url-state';
 import * as React from "react";
-export type { BulkAction, ResourceColumn };
+export type { BulkAction, BulkResult, ResourceColumn, ResourceTableDensity, ResourceTableKeyboardNavigation, };
 export declare const DEFAULT_PAGE_SIZE = 25;
+/** The page sizes offered by default (`pageSizeOptions`). */
+export declare const DEFAULT_PAGE_SIZE_OPTIONS: readonly number[];
+/** Below this container width (px) rows render as cards (`cardBreakpoint`). */
+export declare const DEFAULT_CARD_BREAKPOINT = 640;
 export interface ResourceTableProps<T = Record<string, unknown>> {
     resource: string;
     /**
      * Per-field overrides. Naming a default-hidden field (an audit field such
-     * as `created_at`, or a json/file field) shows it; `hidden: true` hides one.
+     * as `created_at`, or a json/file field) shows it. `hidden: true` hides one.
      */
     columns?: ReadonlyArray<ResourceColumn<T>>;
     /**
@@ -26,46 +34,103 @@ export interface ResourceTableProps<T = Record<string, unknown>> {
     rowActions?: (row: T) => React.ReactNode;
     /** Passing this enables the default edit row action. */
     onEdit?: (row: T) => void;
-    /** Enables the default delete row action (uses useResourceMutations). */
+    /** Enables the default delete row action (confirms in a dialog, uses useResourceMutations). */
     enableDelete?: boolean;
     bulkActions?: ReadonlyArray<BulkAction>;
+    /**
+     * Opens a row. The whole row is clickable, and its first cell is a button,
+     * so the row opens from the keyboard too (Enter on any cell of the grid).
+     */
     onRowClick?: (row: T) => void;
     /**
      * `expand` query values. Default: single-relation field names ∩ the list
-     * operation's expand enum — never guessed beyond the schema (D5).
+     * operation's expand enum, never guessed beyond the schema (D5).
      */
     expand?: readonly string[];
+    /** The ordering when the URL names none. */
     initialSorting?: SortingState;
     /** Sent as `page_size`. Default 25. */
     pageSize?: number;
+    /** The page sizes a user can choose. Default `[10, 25, 50, 100]`. `pageSize` is always offered. */
+    pageSizeOptions?: readonly number[];
     /**
-     * Field names to build the filter bar from; `false` disables it. Default:
+     * Field names to build the filter bar from. `false` disables it. Default:
      * (enum/boolean/relation fields) ∩ declared list query params, domain
      * fields first, audit fields only with `showAuditFields`, cap 4 (D5).
      * Only enum, boolean and relation fields get controls.
      */
     filters?: readonly string[] | false;
     /**
-     * Fixed filters sent with every request and hidden from the filter bar —
+     * Fixed filters sent with every request and hidden from the filter bar,
      * e.g. `{ event: eventId }` for "the bookings of this event". A user filter
-     * on the same field never overrides them.
+     * on the same field never overrides them. Never written to the URL.
      */
     params?: Readonly<Record<string, KarniQueryValue>>;
     /**
      * Export buttons (one per format) when the resource serves
-     * `GET /<resource>/export/` — every Karni BaseViewSet does. The file carries
-     * the table's current filters, search and ordering; the backend applies the
-     * row scope and field visibility. Default `["csv", "xlsx"]`; `false` hides them.
+     * `GET /<resource>/export/`, as every Karni BaseViewSet does. The file
+     * carries the table's current filters, search and ordering. The backend
+     * applies the row scope and field visibility. Default `["csv", "xlsx"]`.
+     * `false` hides them.
      */
     exportFormats?: readonly ExportFormat[] | false;
     /** Extra toolbar content, rendered to the right of the search/filter row. */
     toolbar?: React.ReactNode;
-    /** Replaces the default EmptyState when the list has no results. */
+    /**
+     * Replaces both empty screens. Prefer `slots.NoRecords` and
+     * `slots.NoResults`, which tell "nothing yet" from "nothing matches".
+     */
     empty?: React.ReactNode;
     /** Rendered under the pagination row. */
     footer?: React.ReactNode;
-    /** Overrides displayLabel() for relation cells (and the delete confirm). */
+    /** Overrides displayLabel() for relation cells, row names (checkboxes, cards, the delete question). */
     getRowLabel?: (row: Record<string, unknown>) => string;
+    /** Replace any state screen or part (see ResourceTableSlots). */
+    slots?: Partial<ResourceTableSlots>;
+    /** The resource in sentences, plural ("events"). Default: from the resource name. */
+    resourceLabel?: string;
+    /** One of them ("event"). Default: a singular of `resourceLabel`. */
+    itemLabel?: string;
+    /** Names the table for assistive technology. Default: `resourceLabel`, capitalised. */
+    caption?: string;
+    /** Offers a create button (toolbar and the "no records yet" screen). */
+    onCreate?: () => void;
+    /** Default "New <itemLabel>". */
+    createLabel?: string;
+    /**
+     * Whether the role may create. Default: the schema documents a create
+     * operation and its access rule does not refuse this user.
+     */
+    canCreate?: boolean;
+    /** Whether a row's edit action shows. Default: the update operation's access rule for this user and row. */
+    canEdit?: boolean | ((row: T) => boolean);
+    /** Whether a row's delete action shows. Default: the delete operation's access rule for this user and row. */
+    canDelete?: boolean | ((row: T) => boolean);
+    /** Keep page, page size, sort, search and filters in the URL. Default true. */
+    syncUrl?: boolean;
+    /** Prefix of this table's URL keys (`events.page=2`). Default: the resource name, `""` for none. */
+    urlNamespace?: string;
+    /** Where URL state lives. Default `window.history`. Plug a router in here. */
+    stateStore?: ResourceTableStateStore;
+    /** Row density, controlled. Uncontrolled, the user's choice is remembered per user. */
+    density?: ResourceTableDensity;
+    /** The density before the user chooses. Default "comfortable". */
+    defaultDensity?: ResourceTableDensity;
+    onDensityChange?: (density: ResourceTableDensity) => void;
+    /** The "View" menu (density, column visibility). Default true. */
+    viewOptions?: boolean;
+    /** Below this container width (px) rows render as cards. Default 640, and 0 means never. */
+    cardBreakpoint?: number;
+    /**
+     * How the keyboard moves through the table layout. Default `"grid"`, the
+     * WAI-ARIA grid pattern: the whole table is one Tab stop, the arrow keys
+     * move between rows and cells (each control of a cell is a stop of its
+     * own), Home and End go to the ends of a row, Ctrl+Home and Ctrl+End to
+     * the first and last cell, Enter on a cell opens the row (`onRowClick`) and
+     * Space on a cell selects it (`bulkActions`). `"native"` is a plain table
+     * where every checkbox, button and link is its own Tab stop, as before.
+     */
+    keyboardNavigation?: ResourceTableKeyboardNavigation;
     className?: string;
 }
 /** Schema-driven data table for one resource: columns, sorting, filters, search, pagination, row actions and bulk select, all derived from the OpenAPI schema. */

package/dist/src/components/resource/table/RowCard.d.ts

@@ -0,0 +1,31 @@
+import { ResourceTableDensity } from './preferences';
+/**
+ * One row as a card, for containers narrower than ResourceTable's
+ * `cardBreakpoint`: the title (the first column, or `getRowLabel`), then a
+ * label: value pair per visible column, with the row's checkbox and actions.
+ * The default of ResourceTable's `RowCard` slot.
+ */
+import * as React from "react";
+export interface ResourceTableCardField {
+    id: string;
+    label: React.ReactNode;
+    value: React.ReactNode;
+}
+export interface ResourceTableRowCardProps<T = Record<string, unknown>> {
+    row: T;
+    /** The card's heading: the first column's cell, or `getRowLabel(row)`. */
+    title: React.ReactNode;
+    /** The other visible columns, as label: value pairs. */
+    fields: readonly ResourceTableCardField[];
+    /** The row's checkbox, when the table has bulk actions. */
+    selection?: React.ReactNode;
+    /** The row's actions (edit, delete, `rowActions`). */
+    actions?: React.ReactNode;
+    /** Opens the row (`onRowClick`). The title becomes a button. */
+    onOpen?: () => void;
+    selected: boolean;
+    /** Why the last bulk action failed for this row. */
+    failure?: string;
+    density: ResourceTableDensity;
+}
+export declare function RowCard<T>(props: ResourceTableRowCardProps<T>): React.ReactElement;

package/dist/src/components/resource/table/TableView.d.ts

@@ -0,0 +1,29 @@
+import { Header, Table } from '@tanstack/react-table';
+import { ResourceTableDensity } from './preferences';
+import * as React from "react";
+/** How the keyboard moves through the table's rows (ResourceTable's `keyboardNavigation`). */
+export type ResourceTableKeyboardNavigation = "grid" | "native";
+export interface TableViewProps<T> {
+    table: Table<T>;
+    /** Names the table for assistive technology ("Events"). */
+    caption: string;
+    density: ResourceTableDensity;
+    /** A sort or page change is loading: sort buttons ignore clicks. */
+    busy: boolean;
+    /** The column whose header was clicked last, for its progress spinner. */
+    sortTarget: string | null;
+    /** Work has run for 500ms: show progress. */
+    slow: boolean;
+    onSort: (header: Header<T, unknown>, event: React.MouseEvent) => void;
+    onRowClick?: (row: T) => void;
+    /** Why the last bulk action failed, by row id. */
+    failures: Readonly<Record<string, string>>;
+    /** 1-based position of the first row in the whole list, for aria-rowindex. */
+    firstRowIndex: number;
+    totalCount?: number;
+    /** The rows are stale (a later request failed or is slow): dim them. */
+    dimmed: boolean;
+    scrollRef: React.RefObject<HTMLDivElement>;
+    keyboardNavigation: ResourceTableKeyboardNavigation;
+}
+export declare function TableView<T>(props: TableViewProps<T>): React.ReactElement;

package/dist/src/components/resource/table/ViewOptions.d.ts

@@ -0,0 +1,19 @@
+import { ResourceTableDensity } from './preferences';
+/**
+ * ResourceTable's "View" menu: compact rows on or off, and which columns
+ * show. Both are remembered per user (see ./preferences). A Radix dropdown,
+ * so it is operable by keyboard (arrows, Space to toggle, Escape to close).
+ * Internal to @karni/ui. ResourceTable's `viewOptions={false}` hides it.
+ */
+import * as React from "react";
+export interface ViewOptionsProps {
+    density: ResourceTableDensity;
+    onDensityChange: (density: ResourceTableDensity) => void;
+    columns: ReadonlyArray<{
+        id: string;
+        label: string;
+        visible: boolean;
+    }>;
+    onColumnVisibilityChange: (id: string, visible: boolean) => void;
+}
+export declare function ViewOptions(props: ViewOptionsProps): React.ReactElement;

package/dist/src/components/resource/table/access.d.ts

@@ -0,0 +1,12 @@
+import { KarniUser } from '../../../auth/types';
+import { KarniAccessRule } from '../../../schema/types';
+/** Who is asking. `null` when the table renders outside an AuthProvider. */
+export interface AccessIdentity {
+    status: "loading" | "authenticated" | "anonymous";
+    user: KarniUser | null;
+}
+/**
+ * `true` when the rule allows the operation for this identity (and row),
+ * `false` when it refuses, `undefined` when only the server can tell.
+ */
+export declare function evaluateAccess(rule: KarniAccessRule | undefined, identity: AccessIdentity | null, row?: unknown): boolean | undefined;

package/dist/src/components/resource/table/derive-columns.d.ts

@@ -25,9 +25,9 @@ export interface DeriveColumnsArgs<T> {
 /**
  * Builds the derived column set: domain columns (schema order), then any
  * shown audit columns (AUDIT_FIELDS order), then `columns` entries naming
- * fields the schema does not declare — plain accessor columns (escape hatch
+ * fields the schema does not declare, as plain accessor columns (escape hatch
  * for computed or server-extra keys). `columns` overrides merge onto their
- * fields; naming a default-skipped field (json, audit, ...) shows it.
+ * fields, and naming a default-skipped field (json, audit, ...) shows it.
  */
 export declare function deriveColumns<T>(args: DeriveColumnsArgs<T>): Array<ColumnDef<T>>;
 export {};

package/dist/src/components/resource/table/grid-navigation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ResourceTable's keyboard model in the table layout: the WAI-ARIA grid
+ * pattern with a roving tabindex. The whole table is one Tab stop. The arrow
+ * keys move between rows and cells, Home and End to the ends of a row, and
+ * Ctrl+Home and Ctrl+End to the first and last cell of the grid.
+ *
+ * The stops are read from the DOM, so any cell content works: a cell that
+ * holds controls (a checkbox, the row's button, links, the row actions, a
+ * menu trigger) puts each control in the row's arrow order, and a cell
+ * without one is a stop itself. Exactly one stop has tabindex 0 (the last
+ * one focused). Every other stop has -1, and a MutationObserver keeps it so
+ * when rows, pages or cell content change. Internal to @karni/ui.
+ */
+import * as React from "react";
+export interface GridNavigation {
+    onKeyDown: (event: React.KeyboardEvent<HTMLTableElement>) => void;
+    onFocus: (event: React.FocusEvent<HTMLTableElement>) => void;
+}
+/**
+ * The roving tabindex of a table. Returns the handlers for the <table>. When
+ * `enabled` is false they do nothing and the table is left as rendered.
+ */
+export declare function useGridNavigation(tableRef: React.RefObject<HTMLTableElement>, enabled: boolean): GridNavigation;

package/dist/src/components/resource/table/layout.d.ts

@@ -0,0 +1,37 @@
+import { ResourceTableDensity } from './preferences';
+/** Row and header geometry per density. Every value is a spacing token. */
+export declare const DENSITY_CLASSES: Record<ResourceTableDensity, {
+    head: string;
+    cell: string;
+    action: string;
+    card: string;
+}>;
+/**
+ * The scrolling box: both directions scroll inside it, so 50 columns never
+ * push the page sideways and the header can stick. Its height is capped by
+ * the `--karni-table-max-height` token (70vh). Set it to `none` to let the
+ * page scroll instead.
+ */
+export declare const SCROLL_BOX = "group/scroll relative w-full max-h-[var(--karni-table-max-height)] overflow-auto rounded-md border border-border bg-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring";
+/**
+ * The scroll box of a grid: a cell or control the keyboard focuses scrolls
+ * into view below the sticky header, not under it.
+ */
+export declare const GRID_SCROLL_BOX = "scroll-pt-10";
+/** A grid cell without a control takes focus itself, and shows it inside its edges. */
+export declare const GRID_CELL = "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring";
+export declare const TABLE = "w-full border-separate border-spacing-0 text-sm";
+/** Sticky on vertical scroll, above the frozen body cells. */
+export declare const THEAD = "sticky top-0 z-raised";
+export declare const HEAD_CELL = "whitespace-nowrap border-b border-border bg-muted text-left align-middle text-xs font-medium text-muted-foreground";
+/** Opaque backgrounds on every cell, so frozen cells hide what scrolls beneath them. */
+export declare const BODY_CELL = "whitespace-nowrap border-b border-border bg-background align-middle group-hover/row:bg-muted group-data-[state=selected]/row:bg-muted";
+export declare const LAST_ROW = "[&>tr:last-child>td]:border-b-0";
+/** The checkbox column: a fixed width, so the frozen first column can sit after it. */
+export declare const SELECT_CELL = "sticky left-0 w-10 min-w-10 px-3";
+/** The frozen first data column, with an edge once the table scrolls sideways. */
+export declare const FROZEN_CELL = "sticky border-r border-r-transparent group-data-[scrolled=true]/scroll:border-r-border";
+export declare const FROZEN_AT_START = "left-0";
+export declare const FROZEN_AFTER_SELECT = "left-10";
+/** The frozen column's content is capped, so it never takes the whole width. */
+export declare const FROZEN_CONTENT = "max-w-72 truncate";

package/dist/src/components/resource/table/preferences.d.ts

@@ -0,0 +1,12 @@
+export type ResourceTableDensity = "comfortable" | "compact";
+export declare function densityKey(userId: string | number | undefined): string;
+export declare function hiddenColumnsKey(namespace: string, userId: string | number | undefined): string;
+/**
+ * A value remembered under `key`, re-read when the key changes (another user
+ * signs in). `parse` returns undefined for anything it does not recognise.
+ */
+export declare function useStoredPreference<V>(key: string, fallback: V, parse: (raw: string) => V | undefined, serialize: (value: V) => string): [V, (value: V) => void];
+export declare function parseDensity(raw: string): ResourceTableDensity | undefined;
+export declare function parseColumnList(raw: string): readonly string[] | undefined;
+export declare const asString: (value: string) => string;
+export declare const serializeColumnList: (value: readonly string[]) => string;

package/dist/src/components/resource/table/slots.d.ts

@@ -0,0 +1,41 @@
+import { ErrorSlotProps } from '../../../states/ErrorState';
+import { BulkActionsBarProps } from './BulkActionsBar';
+import { PaginationControlsProps } from './PaginationControls';
+import { ResourceTableRowCardProps } from './RowCard';
+import { ResourceTableForbiddenProps, ResourceTableLoadingProps, ResourceTableNoRecordsProps, ResourceTableNoResultsProps, ResourceTableOfflineProps } from './states';
+/**
+ * ResourceTable's slots: every state screen and structural part a project
+ * can replace with its own component, `slots={{ NoRecords: OurEmpty }}`.
+ * Each slot receives the props type exported next to it. The defaults are
+ * exported as `defaultResourceTableSlots`, so a replacement can wrap one
+ * (`(props) => <defaultResourceTableSlots.Error {...props} />`).
+ */
+import type * as React from "react";
+/** The pagination row's props (the `Pagination` slot). */
+export type ResourceTablePaginationProps = PaginationControlsProps;
+/** The bulk actions bar's props (the `BulkActions` slot). */
+export type ResourceTableBulkActionsProps = BulkActionsBarProps;
+export interface ResourceTableSlots {
+    /** The first load: the layout in outline. */
+    Loading: React.ComponentType<ResourceTableLoadingProps>;
+    /** The resource has no rows at all yet. */
+    NoRecords: React.ComponentType<ResourceTableNoRecordsProps>;
+    /** Rows exist, but none match the search and filters. */
+    NoResults: React.ComponentType<ResourceTableNoResultsProps>;
+    /** The list (or the schema) failed to load and there is nothing to show. */
+    Error: React.ComponentType<ErrorSlotProps>;
+    /** A refresh failed while rows were already on screen: the rows stay. */
+    RefetchError: React.ComponentType<ErrorSlotProps>;
+    /** The role may not view this resource (the list answered 403). */
+    Forbidden: React.ComponentType<ResourceTableForbiddenProps>;
+    /** The browser is offline. */
+    Offline: React.ComponentType<ResourceTableOfflineProps>;
+    /** The pagination row. */
+    Pagination: React.ComponentType<ResourceTablePaginationProps>;
+    /** The selected-rows bar. */
+    BulkActions: React.ComponentType<ResourceTableBulkActionsProps>;
+    /** One row as a card, below `cardBreakpoint`. */
+    RowCard: React.ComponentType<ResourceTableRowCardProps<unknown>>;
+}
+export declare const defaultResourceTableSlots: ResourceTableSlots;
+export type { ResourceTableForbiddenProps, ResourceTableLoadingProps, ResourceTableNoRecordsProps, ResourceTableNoResultsProps, ResourceTableOfflineProps, ResourceTableRowCardProps, };

package/dist/src/components/resource/table/states.d.ts

@@ -0,0 +1,91 @@
+import { ErrorSlotProps } from '../../../states/ErrorState';
+import { ResourceTableDensity } from './preferences';
+/**
+ * ResourceTable's state screens, each the default of one slot: the loading
+ * skeleton, the two empty screens (nothing yet / nothing matches), the error
+ * panels, the permission screen and the offline notice. A project replaces
+ * any of them with `slots={{ NoRecords: OurEmpty }}`, and each receives the
+ * props documented here.
+ */
+import * as React from "react";
+/** What the Loading slot receives: enough to draw the real layout's outline. */
+export interface ResourceTableLoadingProps {
+    /** Columns of the real table, the checkbox and actions columns included (a guess until the schema loads). */
+    columnCount: number;
+    /** Rows of a full page: the page size. */
+    rowCount: number;
+    density: ResourceTableDensity;
+    /** Draw the toolbar's outline too (until the schema says what the toolbar holds). */
+    toolbar: boolean;
+    /** "cards" below the container breakpoint, else "table". */
+    layout: "table" | "cards";
+    /** A checkbox column leads (the table has bulk actions). */
+    selectable: boolean;
+    /** An actions column ends each row (edit, delete, `rowActions`). */
+    actions: boolean;
+}
+/**
+ * The default Loading slot: the real layout in outline (toolbar, header row
+ * with the real column count, a full page of rows at the current density,
+ * the pagination row), so nothing moves when the data arrives. Hidden from
+ * screen readers: the table's live region says "Loading…" instead.
+ */
+export declare function TableSkeleton(props: ResourceTableLoadingProps): React.ReactElement;
+/** What the NoRecords slot receives: the resource has no rows at all yet. */
+export interface ResourceTableNoRecordsProps {
+    /** The resource as a sentence names it, plural ("events"). */
+    resourceLabel: string;
+    /** One of them ("event"). */
+    itemLabel: string;
+    /** Set when the table knows how to create one and the role may: offer it. */
+    onCreate?: () => void;
+    createLabel: string;
+}
+/** "No events yet": explains, and offers the create action when there is one. */
+export declare function NoRecords(props: ResourceTableNoRecordsProps): React.ReactElement;
+/** One active filter, in words ("Status: Draft"). */
+export interface ResourceTableActiveFilter {
+    field: string;
+    label: string;
+    value: string;
+}
+/** What the NoResults slot receives: rows exist, but none match the search or filters. */
+export interface ResourceTableNoResultsProps {
+    resourceLabel: string;
+    /** The search term, or "" when the search box is empty. */
+    search: string;
+    /** The filters narrowing the list, in words. */
+    filters: readonly ResourceTableActiveFilter[];
+    /** Resets the search and every filter (pinned `params` stay). */
+    onClearFilters: () => void;
+}
+/** "No events match": says what is narrowing the list and offers to clear it. */
+export declare function NoResults(props: ResourceTableNoResultsProps): React.ReactElement;
+/** The default Error slot: what failed, in plain words, with "Try again" when it can help. */
+export declare function TableError(props: ErrorSlotProps): React.ReactElement;
+/**
+ * The default RefetchError slot: a failed refresh over rows already shown.
+ * The rows stay, and this one line says the list may be out of date.
+ */
+export declare function RefetchError(props: ErrorSlotProps): React.ReactElement;
+/** What the Forbidden slot receives: the list itself answered 403. */
+export interface ResourceTableForbiddenProps {
+    resourceLabel: string;
+    /** The server's refusal (its own explanation, when it gave one, is in `data.detail`). */
+    error: unknown;
+}
+/** "You can't view events": no retry, since asking again changes nothing. */
+export declare function Forbidden(props: ResourceTableForbiddenProps): React.ReactElement;
+/** What the Offline slot receives while the browser has no connection. */
+export interface ResourceTableOfflineProps {
+    resourceLabel: string;
+    /** Rows loaded before the connection dropped are still on screen. */
+    hasRows: boolean;
+    onRetry: () => void;
+}
+/**
+ * The default Offline slot. With rows on screen it is one line above them.
+ * Without rows it is the offline error panel. The table reloads by itself
+ * once the connection is back.
+ */
+export declare function OfflineNotice(props: ResourceTableOfflineProps): React.ReactElement;

package/dist/src/components/resource/table/story-fixtures.d.ts

@@ -0,0 +1,25 @@
+import { RequestHandler } from 'msw';
+import { ResourceTableStateStore } from './url-state';
+export declare const WIDE_COLUMN_COUNT = 50;
+/** Field names of the wide resource: `name`, then 49 metrics. */
+export declare const WIDE_FIELDS: readonly string[];
+export declare const wideOpenApi: Record<string, unknown>;
+export declare function wideHandlers(total?: number): RequestHandler[];
+export declare const LARGE_EVENT_COUNT = 100000;
+/** `/api/events/` with `total` rows. Only the requested page is ever built. */
+export declare function largeHandlers(total?: number): RequestHandler[];
+/**
+ * The events schema as a backend with `Access(write=Owned("organizer") |
+ * HasRole("staff"), create=HasRole("staff"))` and deletes for admins only
+ * publishes it.
+ */
+export declare const accessOpenApi: Record<string, unknown>;
+/**
+ * `accessOpenApi` as a role that may not read `capacity` (`Karni.field_roles`):
+ * the per-role schema leaves the field out, so the column is absent.
+ */
+export declare const partialOpenApi: Record<string, unknown>;
+/** A ResourceTableStateStore over a plain object: what a router adapter looks like. */
+export declare function memoryStateStore(initial?: Record<string, string>): ResourceTableStateStore & {
+    values: Record<string, string>;
+};

package/dist/src/components/resource/table/structural-columns.d.ts

@@ -0,0 +1,25 @@
+import { ColumnDef } from '@tanstack/react-table';
+import * as React from "react";
+export declare const SELECT_COLUMN = "__select__";
+export declare const ACTIONS_COLUMN = "__actions__";
+export declare function isStructural(columnId: string): boolean;
+export declare function selectionColumn<T>(options: {
+    rowLabel: (row: T) => string;
+    resourceLabel: string;
+}): ColumnDef<T>;
+export interface RowActionsOptions<T> {
+    rowActions?: (row: T) => React.ReactNode;
+    onEdit?: (row: T) => void;
+    /** Whether this row's edit action is offered (the role may change it). */
+    canEdit: (row: T) => boolean;
+    /** Present when deletes are enabled. Asks to confirm, then deletes. */
+    onDelete?: (row: T, trigger: HTMLButtonElement) => void;
+    canDelete: (row: T) => boolean;
+    /** Button geometry for the current density. */
+    buttonClassName: string;
+}
+/** The actions of one row, in the order a row reads: edit, custom, delete. */
+export declare function RowActions<T>(props: RowActionsOptions<T> & {
+    row: T;
+}): React.ReactElement;
+export declare function actionsColumn<T>(options: RowActionsOptions<T>): ColumnDef<T>;

package/dist/src/components/resource/table/table-icons.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ResourceTable's own icons (pagination arrows, create, view options). Inline
+ * SVG with `currentColor` strokes, like the primitives' icons.
+ * Internal to @karni/ui.
+ */
+import * as React from "react";
+type IconProps = React.SVGAttributes<SVGSVGElement>;
+export declare function ChevronLeftIcon(props: IconProps): React.ReactElement;
+export declare function ChevronRightIcon(props: IconProps): React.ReactElement;
+export declare function FirstPageIcon(props: IconProps): React.ReactElement;
+export declare function LastPageIcon(props: IconProps): React.ReactElement;
+export declare function PlusIcon(props: IconProps): React.ReactElement;
+export declare function SlidersIcon(props: IconProps): React.ReactElement;
+export declare function FilterOffIcon(props: IconProps): React.ReactElement;
+export declare function InboxIcon(props: IconProps): React.ReactElement;
+export {};

package/dist/src/components/resource/table/table-utils.d.ts

@@ -1,16 +1,40 @@
+import { DefaultError, DefaultOptions } from '@tanstack/react-query';
 import { SortingState } from '@tanstack/react-table';
 /**
  * Maps TanStack sorting state to the DRF `ordering` query parameter.
- * Column ids equal schema field names verbatim — that IS the ordering
- * contract (D5) — so `[{id: "title", desc: true}]` becomes `-title`.
+ * Column ids equal schema field names verbatim (that IS the ordering
+ * contract, D5), so `[{id: "title", desc: true}]` becomes `-title`.
  */
 export declare function sortingToOrdering(sorting: SortingState): string | undefined;
+/** `"-title,starts_at"` → TanStack sorting state (the inverse of sortingToOrdering). */
+export declare function orderingToSorting(ordering: string): SortingState;
+/** The HTTP status of a KarniApiError-shaped error, if it has one. */
+export declare function statusOf(error: unknown): number | undefined;
 /**
  * Duck-typed 404 check (works with KarniApiError or any error exposing a
  * numeric `status`), used for the D5 page-clamp: a list 404 with page > 1
  * decrements the page and refetches as loading, never as an error.
  */
 export declare function isNotFoundError(error: unknown): boolean;
+/** The `retry` default of the app's QueryClient (`undefined`: TanStack's own). */
+export type RetryDefault = NonNullable<DefaultOptions["queries"]>["retry"];
+/**
+ * The list query's retry rule, under the app's own. A request the server
+ * refused (4xx) fails the same way again, so it is never retried, except a
+ * timeout (408) or a rate limit (429). Anything else (5xx, the network)
+ * retries as the app's QueryClient `retry` default says: three tries when it
+ * sets none, and none at all with `retry: false`, which shows the error at once.
+ */
+export declare function listRetry(appDefault: RetryDefault): (failureCount: number, error: DefaultError) => boolean;
+/** "loose-slots" → "loose slots": the resource as a sentence names it. */
+export declare function resourceWords(resource: string): string;
+/**
+ * A conservative English singular ("events" → "event", "categories" →
+ * "category", "addresses" → "address"). ResourceTable's `itemLabel` prop
+ * replaces it where it guesses wrong.
+ */
+export declare function singular(plural: string): string;
+export declare function capitalised(text: string): string;
 export declare function pageCountFor(count: number | undefined, pageSize: number): number;
 /** Safe record view of an unknown row (rows are plain JSON objects). */
 export declare function asRecord(value: unknown): Record<string, unknown>;
@@ -18,7 +42,7 @@ export declare function asRecord(value: unknown): Record<string, unknown>;
 export declare function errorMessage(error: unknown): string;
 /**
  * Display label for an enum member: ALL_CAPS and lower_snake constants are
- * prettified ("DRAFT" → "Draft", "in_progress" → "In progress"); mixed-case
+ * prettified ("DRAFT" → "Draft", "in_progress" → "In progress"). Mixed-case
  * values ("iOS") pass through untouched.
  */
 export declare function enumLabel(value: string | number, labels?: Readonly<Record<string, string>>): string;