@karni/ui 0.3.1 → 0.4.0

package/dist/src/components/resource/query-state.d.ts

@@ -0,0 +1,20 @@
+/** A 4xx answer is the server's decision (not found, forbidden, invalid): asking again gives the same answer. */
+export declare function isClientError(error: unknown): boolean;
+/**
+ * The query client's own retry policy, except that a 4xx is never retried:
+ * TanStack's default (three retries with backoff) would hold a "Couldn't
+ * find this event" back for seven seconds.
+ */
+export declare function useRetryUnlessClientError(): (failureCount: number, error: unknown) => boolean;
+/**
+ * Stands for "the request is waiting for a connection": TanStack Query
+ * pauses queries while the browser is offline instead of failing them, and
+ * this is what the Error slot receives then (describeError words it as
+ * "You're offline").
+ */
+export declare function offlineError(): TypeError;
+/**
+ * Calls `retry` when the connection comes back while `error` is a network
+ * failure, so an offline error clears itself without a click.
+ */
+export declare function useRetryWhenOnline(error: unknown, retry: () => void): void;

package/dist/src/components/resource/resource-names.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How a resource is named in a sentence: "No venues yet", "You can't edit
+ * this event". The router prefix is plural ("events", "loose-slots"). The
+ * singular is derived with English rules that cover the common cases, and a
+ * component's `resourceLabel` prop is the escape hatch for the rest
+ * ("people" / "person").
+ *
+ * Internal to @karni/ui.
+ */
+/** The words a resource takes in a sentence, both lower case. */
+export interface ResourceNames {
+    /** "event", "loose slot". */
+    singular: string;
+    /** "events", "loose slots". */
+    plural: string;
+}
+/** What a component's `resourceLabel` prop accepts: either word, or both. */
+export interface ResourceLabel {
+    singular?: string;
+    plural?: string;
+}
+/** "loose-slots" → { singular: "loose slot", plural: "loose slots" }, unless `label` says otherwise. */
+export declare function resourceNames(resource: string, label?: ResourceLabel): ResourceNames;

package/dist/src/components/resource/select/ResourceSelect.d.ts

@@ -1,3 +1,5 @@
+import { ResourceLabel } from '../resource-names';
+import { ResourceSelectSlots } from './select-states';
 import * as React from "react";
 export interface ResourceSelectProps {
     resource: string;
@@ -12,7 +14,7 @@ export interface ResourceSelectProps {
     filter?: Record<string, string | number | boolean>;
     id?: string;
     className?: string;
-    /** Page size for the option request (only the first page is fetched, D8). */
+    /** Rows per options request. Default: the API's own page size. More load as the list scrolls. */
     pageSize?: number;
     /** Set false to hide the clear affordance (which emits null). Default true. */
     clearable?: boolean;
@@ -20,17 +22,46 @@ export interface ResourceSelectProps {
     searchDebounceMs?: number;
     "aria-label"?: string;
     "aria-labelledby"?: string;
+    /** Ids of the help text and error message that describe the field. */
+    "aria-describedby"?: string;
+    /** Marks the field invalid (destructive border). */
+    "aria-invalid"?: boolean | "true" | "false";
+    "aria-required"?: boolean | "true" | "false";
+    /** Called when focus leaves the select (not when it moves into its own list). */
+    onBlur?: () => void;
+    /** Replaces parts of the picker: Option, Chip, Loading, Empty, Error. */
+    slots?: Partial<ResourceSelectSlots>;
+    /**
+     * Whether typing searches the server (`?search=`). Default: what the
+     * schema says (a list without `search_fields` documents no `search`
+     * parameter). Without search, typing narrows the rows already loaded and
+     * the list says so.
+     */
+    searchable?: boolean;
+    /**
+     * The list filter that takes several ids at once, used to label
+     * preselected values in one request. Default `"id__in"` when the schema
+     * documents it. Otherwise (or with `false`) each id loads from its detail
+     * endpoint.
+     */
+    idsFilter?: string | false;
+    /** How the related resource is named in messages. Default: derived from `resource`. */
+    resourceLabel?: ResourceLabel;
 }
 /**
  * Searchable picker for a related row, querying the related resource as you type.
  *
  * Contract D8.
  *
- * A text input drives a debounced `?search=` list request; options render in
- * a NON-MODAL Radix Popover whose auto-focus is prevented so keyboard focus
- * never leaves the input. The input implements the ARIA 1.2 combobox pattern
- * (combobox → listbox with aria-activedescendant). Pre-selected ids that were
- * never seen in a result page are resolved through detail fetches, and the
- * clear affordance emits `null`.
+ * A text input drives a debounced `?search=` request (or, when the API cannot
+ * search, narrows the loaded rows and says so). Options render in a
+ * NON-MODAL Radix Popover that never takes focus from the input. Options load
+ * a page at a time as the list scrolls or the keyboard reaches its end, never
+ * all at once, and long lists render only the rows in view. The input
+ * implements the ARIA 1.2 combobox pattern (aria-expanded, aria-controls,
+ * aria-activedescendant). Arrows, Home/End and PageUp/PageDown move through
+ * every loaded page. Preselected ids are labelled in one request where the
+ * API has an id-list filter, else per id. An id that cannot be loaded says
+ * so instead of showing a bare id. The clear affordance emits `null`.
  */
-export declare function ResourceSelect(props: ResourceSelectProps): React.ReactElement;
+export declare const ResourceSelect: React.ForwardRefExoticComponent<ResourceSelectProps & React.RefAttributes<HTMLInputElement>>;

package/dist/src/components/resource/select/select-states.d.ts

@@ -0,0 +1,68 @@
+import { ErrorSlotProps } from '../../../states/ErrorState';
+import { ResourceNames } from '../resource-names';
+/**
+ * ResourceSelect's replaceable parts (`slots`) and their defaults, exported
+ * as `defaultResourceSelectSlots` so a project can wrap them.
+ */
+import * as React from "react";
+export interface ResourceSelectOptionProps {
+    /** The row behind the option. */
+    item: Record<string, unknown>;
+    /** Its label (`getOptionLabel`, else displayLabel). */
+    label: React.ReactNode;
+    selected: boolean;
+    /** Highlighted by the keyboard or the pointer. */
+    active: boolean;
+}
+export interface ResourceSelectChipProps {
+    /** The selected row's label, or what to say when it could not be loaded. */
+    label: React.ReactNode;
+    /** "loading" while the row behind a preselected id loads, "failed" when it could not. */
+    state: "loaded" | "loading" | "failed";
+    /** Removes the value. Absent when the select is disabled. */
+    onRemove?: () => void;
+    /** The accessible name of the remove button: "Remove Aurora Hall". */
+    removeLabel: string;
+}
+export interface ResourceSelectEmptyProps {
+    /**
+     * "none": the resource has no rows yet. "no-match": the search found
+     * nothing. "no-loaded-match": search is not available and none of the
+     * loaded rows match the typed text.
+     */
+    reason: "none" | "no-match" | "no-loaded-match";
+    /** The typed text. */
+    search: string;
+    /** How the resource is named ("venue" / "venues"). */
+    names: ResourceNames;
+    /** How many rows are loaded (for "no-loaded-match"). */
+    loaded: number;
+}
+export interface ResourceSelectLoadingProps {
+    /** How many placeholder rows to show. */
+    rows: number;
+}
+/** The replaceable parts of ResourceSelect (`slots`). */
+export interface ResourceSelectSlots {
+    /** One option's content (the row around it carries the listbox semantics). */
+    Option: React.ComponentType<ResourceSelectOptionProps>;
+    /** One selected value in `multiple` mode. */
+    Chip: React.ComponentType<ResourceSelectChipProps>;
+    /** While the first page of options loads. */
+    Loading: React.ComponentType<ResourceSelectLoadingProps>;
+    /** No options to show, and why. */
+    Empty: React.ComponentType<ResourceSelectEmptyProps>;
+    /** The options could not be loaded (forbidden, offline, server), with retry when it can help. */
+    Error: React.ComponentType<ErrorSlotProps>;
+}
+export declare function ResourceSelectOption({ label, selected, }: ResourceSelectOptionProps): React.ReactElement;
+declare function XIcon(props: React.SVGAttributes<SVGSVGElement>): React.ReactElement;
+export { XIcon as ResourceSelectClearIcon };
+export declare function ResourceSelectChip({ label, state, onRemove, removeLabel, }: ResourceSelectChipProps): React.ReactElement;
+export declare function ResourceSelectLoading({ rows }: ResourceSelectLoadingProps): React.ReactElement;
+/** "No venues yet" and "No venues match “ber”" are different situations, said differently. */
+export declare function emptyText({ reason, search, names, loaded }: ResourceSelectEmptyProps): string;
+export declare function ResourceSelectEmpty(props: ResourceSelectEmptyProps): React.ReactElement;
+export declare function ResourceSelectError(props: ErrorSlotProps): React.ReactElement;
+/** ResourceSelect's own slot components, for wrapping rather than rewriting. */
+export declare const defaultResourceSelectSlots: ResourceSelectSlots;

package/dist/src/components/resource/select/use-option-pages.d.ts

@@ -0,0 +1,37 @@
+import { UseInfiniteQueryResult, InfiniteData } from '@tanstack/react-query';
+export type OptionRow = Record<string, unknown>;
+/** The query string of one page request. */
+type PageQuery = Record<string, string | readonly string[]>;
+export interface OptionPage {
+    /** Undefined when the API does not count (cursor pagination). */
+    count?: number;
+    next: string | null;
+    results: OptionRow[];
+}
+/** `next` → its query string (`?page=2&search=x`, `?cursor=...`). */
+export declare function pageQueryOf(next: string): PageQuery;
+export interface OptionPagesInput {
+    resource: string;
+    /** The (debounced) search term, "" for none. */
+    search: string;
+    filter?: Record<string, string | number | boolean>;
+    pageSize?: number;
+    enabled: boolean;
+}
+export type OptionPagesResult = UseInfiniteQueryResult<InfiniteData<OptionPage, PageQuery | null>>;
+/** Option pages, each fetched on demand. The previous term's rows stay while a new search loads. */
+export declare function useOptionPages({ resource, search, filter, pageSize, enabled, }: OptionPagesInput): OptionPagesResult;
+export interface SelectedRows {
+    /** Rows found for the requested ids, by String(id). */
+    rows: Record<string, OptionRow>;
+    /** Ids that could not be loaded (deleted, hidden from the role, or the request failed). */
+    failed: ReadonlySet<string>;
+    /** Ids still loading. */
+    loading: ReadonlySet<string>;
+}
+/** Loads the rows behind ids the options have not shown yet. */
+export declare function useSelectedRows(resource: string, ids: ReadonlyArray<string | number>, options: {
+    idsFilter?: string;
+    enabled: boolean;
+}): SelectedRows;
+export {};

package/dist/src/components/resource/select/venue-backend.d.ts

@@ -0,0 +1,144 @@
+import { RequestHandler } from 'msw';
+export interface VenueRow {
+    id: number;
+    name: string;
+    city: string;
+}
+/** `count` venues: twelve named ones, then "Venue 00013", "Venue 00014", ... */
+export declare function makeVenues(count?: number): VenueRow[];
+export type Failure = number | "offline";
+export type Delay = number | "infinite";
+export interface VenueBackendOptions {
+    /** How many venues exist. Default 12. */
+    count?: number;
+    /** Whether the list documents and honours `?search=`. Default true. */
+    search?: boolean;
+    /** Whether the list documents and honours `?id__in=1,2`. Default false (Karni's default). */
+    idsFilter?: boolean;
+    /** The server's page size when the request names none. Default 50. */
+    pageSize?: number;
+    /** Fail every list request (a status, or "offline" for a dropped connection). */
+    listFailure?: Failure;
+    /** Fail list requests for pages after the first. */
+    nextPageFailure?: Failure;
+    /** Fail every detail request. */
+    detailFailure?: Failure;
+    /** Delay every list request. */
+    listDelay?: Delay;
+    /** Delay list requests that carry a search term (the "Searching…" state). */
+    searchDelay?: Delay;
+    /** Delay every detail request. */
+    detailDelay?: Delay;
+}
+export interface VenueBackend {
+    handlers: RequestHandler[];
+    /** Every venues request, in order. */
+    requests: URL[];
+    rows: VenueRow[];
+    /** The list requests only. */
+    listRequests: () => URL[];
+}
+/** The OpenAPI document of the simulated backend (drf-spectacular dialect). */
+export declare function venueOpenApi(options?: Pick<VenueBackendOptions, "search" | "idsFilter">): {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+    };
+    "x-karni-auth-mode": string;
+    paths: {
+        "/api/venues/": {
+            get: {
+                operationId: string;
+                "x-karni-resource": string;
+                parameters: Record<string, unknown>[];
+                responses: {
+                    "200": {
+                        description: string;
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    $ref: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        "/api/venues/{id}/": {
+            get: {
+                operationId: string;
+                parameters: {
+                    in: string;
+                    name: string;
+                    required: boolean;
+                    schema: {
+                        type: string;
+                    };
+                }[];
+                responses: {
+                    "200": {
+                        description: string;
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    $ref: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+    components: {
+        schemas: {
+            Venue: {
+                type: string;
+                required: string[];
+                properties: {
+                    id: {
+                        type: string;
+                        readOnly: boolean;
+                    };
+                    name: {
+                        type: string;
+                        maxLength: number;
+                    };
+                    city: {
+                        type: string;
+                        maxLength: number;
+                    };
+                };
+            };
+            PaginatedVenueList: {
+                type: string;
+                required: string[];
+                properties: {
+                    count: {
+                        type: string;
+                    };
+                    next: {
+                        type: string;
+                        nullable: boolean;
+                        format: string;
+                    };
+                    previous: {
+                        type: string;
+                        nullable: boolean;
+                        format: string;
+                    };
+                    results: {
+                        type: string;
+                        items: {
+                            $ref: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+/** Handlers for the schema and the venues endpoints, plus the request log. */
+export declare function venueBackend(options?: VenueBackendOptions): VenueBackend;

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

@@ -1,20 +1,77 @@
 /**
- * Selected-count toolbar for ResourceTable's bulk select (D5): shows how many
- * rows are selected (selection persists across pages), a clear affordance and
- * one button per configured bulk action.
- * Internal to @karni/ui — the public surface is ResourceTable's props.
+ * Selected-count toolbar for ResourceTable's bulk select (D5): how many rows
+ * are selected (selection persists across pages) and what "all" covers, a
+ * clear affordance, one button per bulk action, and what happened last time
+ * (a failure in plain words, or which rows failed). The table runs the
+ * actions (confirming destructive ones first). This bar only presents them.
+ * The default of ResourceTable's `BulkActions` slot.
  */
 import * as React from "react";
+/** What a bulk action may report back: the rows it could not handle, and why. */
+export interface BulkResult {
+    /** Each failed row's id (String(row.id)) and the reason to show on that row. */
+    failed?: ReadonlyArray<{
+        id: string;
+        reason: string;
+    }>;
+}
+/**
+ * What `BulkAction.onClick` returns: nothing (the 0.3 contract, kept), or a
+ * promise of nothing or a `BulkResult`.
+ */
+export type BulkActionReturn = void | Promise<void | BulkResult>;
 export interface BulkAction {
     label: React.ReactNode;
-    onClick: (selectedIds: string[]) => void;
+    /**
+     * Runs the action on the selected ids. Return a promise to have the table
+     * show progress, report failures and deselect the rows that succeeded.
+     * Resolve a `BulkResult` to mark the rows that failed. A plain `void`
+     * return leaves the selection as it is.
+     */
+    onClick: (selectedIds: string[]) => BulkActionReturn;
     destructive?: boolean;
+    /**
+     * Ask before running. Default: true for destructive actions. An object
+     * words the question ("Archive 3 events?" by default).
+     */
+    confirm?: boolean | {
+        title?: React.ReactNode;
+        description?: React.ReactNode;
+        confirmLabel?: string;
+    };
+    /** Announced while the action runs ("Archiving…"). */
+    pendingLabel?: string;
 }
+/** What the last bulk action came to, for the bar to report. */
+export type BulkOutcome = {
+    kind: "failed";
+    actionLabel: string;
+    error: unknown;
+    count: number;
+} | {
+    kind: "partial";
+    actionLabel: string;
+    failed: number;
+    total: number;
+};
 export interface BulkActionsBarProps {
     /** Row ids (String(row.id), D5) currently selected, across all pages. */
     selectedIds: readonly string[];
     bulkActions: ReadonlyArray<BulkAction>;
     onClear: () => void;
+    /** Runs (or asks to confirm) the action at `index`. `trigger` gets focus back after a dialog. */
+    onAction?: (index: number, trigger: HTMLButtonElement | null) => void;
+    /** The action running now, by index. */
+    runningIndex?: number | null;
+    /** The last action's failure or partial failure, reported until the next one. */
+    outcome?: BulkOutcome | null;
+    /** Rows on the current page, and whether all of them are selected. */
+    pageRowCount?: number;
+    allPageRowsSelected?: boolean;
+    /** Everything matching the current search and filters (DRF `count`). */
+    totalCount?: number;
+    /** The resource, plural ("events"). */
+    resourceLabel?: string;
     className?: string;
 }
 export declare function BulkActionsBar(props: BulkActionsBarProps): React.ReactElement;

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

@@ -0,0 +1,31 @@
+import { Table } from '@tanstack/react-table';
+import { ResourceTableDensity } from './preferences';
+import { ResourceTableRowCardProps } from './RowCard';
+import * as React from "react";
+export interface CardListProps<T> {
+    table: Table<T>;
+    caption: string;
+    resourceLabel: string;
+    density: ResourceTableDensity;
+    Card: React.ComponentType<ResourceTableRowCardProps<unknown>>;
+    rowLabel: (row: T) => string;
+    /** Overrides the first column as each card's title. */
+    useRowLabelAsTitle: boolean;
+    onRowClick?: (row: T) => void;
+    failures: Readonly<Record<string, string>>;
+    /** Plain-text column names, for the sort choice. */
+    columnLabel: (columnId: string) => string;
+    /** The current ordering and a way to change it ("" is the default order). */
+    ordering: string;
+    onOrderingChange: (ordering: string) => void;
+    /** A sort or page change is loading: the list announces busy. */
+    busy: boolean;
+    dimmed: boolean;
+    /**
+     * The list element. Focusable by script only (tabIndex -1): where focus
+     * lands when the control that had it is gone (a deleted row, the bulk
+     * toolbar after its action), as the table layout's scroll region is.
+     */
+    listRef?: React.Ref<HTMLUListElement>;
+}
+export declare function CardList<T>(props: CardListProps<T>): React.ReactElement;

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

@@ -0,0 +1,28 @@
+import { KarniErrorContext } from '../../../states/describe-error';
+/**
+ * The question ResourceTable asks before destructive work (a row delete, a
+ * destructive bulk action): a Modal (Radix dialog, so focus is trapped and
+ * Escape cancels) naming the action and how many rows it touches. While the
+ * work runs the confirm button shows progress. A failure is reported inside
+ * the dialog in plain words, with the button kept for another try when
+ * trying again can help. Focus returns to the control that opened it.
+ * Internal to @karni/ui.
+ */
+import * as React from "react";
+export interface ConfirmDialogProps {
+    open: boolean;
+    title: React.ReactNode;
+    description?: React.ReactNode;
+    confirmLabel: string;
+    pendingLabel?: string;
+    destructive?: boolean;
+    pending: boolean;
+    /** The last attempt's failure, shown in the dialog. */
+    error?: unknown;
+    errorContext?: KarniErrorContext;
+    onConfirm: () => void;
+    onCancel: () => void;
+    /** Where focus goes when the dialog closes (the control that opened it, or a fallback). */
+    returnFocus: () => HTMLElement | null;
+}
+export declare function ConfirmDialog(props: ConfirmDialogProps): React.ReactElement;

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

@@ -3,10 +3,10 @@ import { ExportFormat } from '../../../hooks/useResourceImport';
 /**
  * ResourceTable's export buttons (karni.transfer, ADR 0002 P6): one per
  * format, each downloading `GET /<resource>/export/` with the table's current
- * filters, search and ordering — the backend applies the row scope and the
+ * filters, search and ordering. The backend applies the row scope and the
  * role's field visibility, so the file is exactly what the table may show.
  *
- * Internal to @karni/ui — the public surface is ResourceTable's `exportFormats`.
+ * Internal to @karni/ui. The public surface is ResourceTable's `exportFormats`.
  */
 import * as React from "react";
 export interface ExportButtonsProps {

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

@@ -4,13 +4,13 @@ import { FieldDef } from '../../../schema/types';
  * ResourceTable's search box + declared-params-derived filter bar (D5).
  *
  * The parent decides WHICH fields filter (enum/boolean/relation fields ∩ the
- * list operation's declared query params, cap 4, `filters` prop overrides);
- * this component only renders the controls:
+ * list operation's declared query params, cap 4, `filters` prop overrides).
+ * This component only renders the controls:
  * - enum   → clearable <Select> ("All" clears),
  * - boolean → clearable Yes/No <Select>,
  * - relation → <ResourceSelect> (multiple for many-relations).
  *
- * Internal to @karni/ui — the public surface is ResourceTable's props.
+ * Internal to @karni/ui. The public surface is ResourceTable's props.
  */
 import * as React from "react";
 export interface FilterBarProps {

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

@@ -1,7 +1,13 @@
 /**
  * ResourceTable's server-mode pagination row (DRF PageNumberPagination:
- * `{count, next, previous, results}` with `page` / `page_size` params).
- * Internal to @karni/ui — the public surface is ResourceTable's props.
+ * `{count, next, previous, results}` with `page` / `page_size` params):
+ * "Page X of Y · N items", a page size choice, first / previous / next /
+ * last, and a page number to jump to. Only one page is ever fetched.
+ *
+ * While a page is on its way (`busy`) the buttons stay focusable but ignore
+ * clicks (`aria-disabled`), so a double click never skips a page and a
+ * keyboard user's focus stays put. After 500ms the clicked button shows
+ * progress. The default of ResourceTable's `Pagination` slot.
  */
 import * as React from "react";
 export interface PaginationControlsProps {
@@ -10,10 +16,16 @@ export interface PaginationControlsProps {
     pageCount: number;
     /** Total item count across all pages (DRF `count`). */
     totalCount: number;
-    /** From DRF `previous` / `next` — the server is the authority. */
+    /** From DRF `previous` / `next`. The server is the authority. */
     hasPrevious: boolean;
     hasNext: boolean;
     onPageChange: (page: number) => void;
+    /** Rows per page. With `onPageSizeChange` and `pageSizeOptions` it renders the size choice. */
+    pageSize?: number;
+    pageSizeOptions?: readonly number[];
+    onPageSizeChange?: (pageSize: number) => void;
+    /** A page is loading: controls announce busy and ignore clicks. */
+    busy?: boolean;
     className?: string;
 }
 export declare function PaginationControls(props: PaginationControlsProps): React.ReactElement;