themelia-ui 2.0.0 → 3.0.0

package/dist/components/base/typography/text/text.d.ts

@@ -14,27 +14,35 @@ export interface TextProps extends Omit<React.HTMLAttributes<HTMLElement>, "chil
     content?: string;
     /**
      * Semantic role, which selects the colour token. `main` for primary copy, `secondary`
-     * for supporting copy (descriptions, captions, metadata); `inherit` takes the parent's.
+     * for supporting copy (descriptions, captions, metadata). `inherit` selects none and takes
+     * the parent's, for text inside a surface that already sets its own — a solid tab, a
+     * tooltip, a coloured chip. Without it those places would drop Text and hand-roll a span,
+     * which is how a kit ends up with two ways to set type.
      */
     type?: TextType;
     /**
-     * Step on the type scale. Omit it on primary content so the Typography provider
-     * default flows; reserve `xs` for support text and metadata.
+     * Step on the type scale. Omit it on primary content so the provider default flows;
+     * `UIProvider`'s `typography.defaultTextSize` changes it. Reserve `xs` for support text
+     * and metadata. `xxs` renders as `xs`; use `xs`.
+     * @default "sm"
      */
     size?: TextSize;
     /** Horizontal alignment. */
     align?: TextAlign;
     /**
-     * Leading, on the shared tier. `tight` and `none` suit dense rows and single-line
-     * values; `relaxed` suits prose.
+     * Leading, on the shared tier. Unset, each size step carries the leading paired with it
+     * (`--text-<step>--line-height`); a value here overrides that. `tight` and `none` suit
+     * dense rows and single-line values; `relaxed` suits prose.
+     * @default paired
      */
     lineHeight?: TextLineHeight;
     /** Tabular figures, so digits align in a column. Use for any value in a table. */
     numeric?: boolean;
     /**
-     * Ellipsises the text at one line. Makes the element a block with `min-width: 0`;
-     * every flex box between it and the constrained width also needs `min-width: 0`
-     * (`Stack` and `Grid` set it; a hand-rolled flex div does not).
+     * Ellipsises the text at one line rather than wrapping. Makes the element a block with
+     * `min-width: 0`, for the same reason `align` does; every flex box between it and the
+     * constrained width also needs `min-width: 0` (`Stack` and `Grid` set it; a hand-rolled
+     * flex div does not). `Heading` and every `primitives` value take it too.
      */
     truncate?: boolean;
     /** Font weight. */

package/dist/components/base/upload/dropzone.d.ts

@@ -22,4 +22,10 @@ export interface DropzoneProps extends Omit<ComponentProps<"div">, "onDrop" | "c
     /** Controls rendered below the label, not inside it, where clicks would open the file dialog. */
     footer?: ReactNode;
 }
+/**
+ * The drop target on its own, for a surface that wants the drag behaviour without
+ * FileUpload's list and validation around it. It reports dropped or picked files and owns
+ * no state; the box is a `<label>` for a real file input, so it is keyboard-reachable and
+ * submits in a plain form.
+ */
 export declare function Dropzone({ onDrop, accept, multiple, disabled, invalid, compact, icon, inputProps, strings, label, hint, footer, className, ...props }: DropzoneProps): import("react").JSX.Element;

package/dist/components/base/upload/file-picker-input.d.ts

@@ -14,4 +14,9 @@ export interface FilePickerInputProps extends Omit<ComponentProps<"div">, "onCha
     name?: string;
     strings?: StringsProp<FilePickerStrings>;
 }
+/**
+ * A file field shaped like an Input, showing the chosen file's name, for a form row. The
+ * file input covers the whole control, so any part of it opens the dialog, and the `accept`
+ * wiring and the re-validation come with it. `FileUpload` is the drop-zone alternative.
+ */
 export declare function FilePickerInput({ value, onValueChange, onRejectedFiles, constraints, disabled, invalid, name, strings, className, ...props }: FilePickerInputProps): import("react").JSX.Element;

package/dist/components/base/upload/file-upload.d.ts

@@ -4,29 +4,48 @@ import { FileConstraints, FileRejection } from './upload.types.js';
 export interface FileUploadProps extends FileConstraints {
     /** Applied to the file input itself, so a `FormField` label can address it. */
     id?: string;
-    /** Controlled selection. */
+    /** The chosen files, controlled. */
     value?: File[];
     defaultValue?: File[];
+    /** Called with the next selection, after validation. */
     onValueChange?: (files: File[]) => void;
-    /** Receives what was refused. Rejected files never reach `onValueChange`. */
+    /**
+     * Receives the files that failed validation, each with a reason code. Rejected files never
+     * reach `onValueChange`.
+     */
     onRejectedFiles?: (rejections: FileRejection[]) => void;
+    /** Accepts more than one file. */
     multiple?: boolean;
     /** Cap on the selection. Defaults to 1 for single, unlimited for multiple. */
     maxFiles?: number;
-    /** Whether a new selection adds to the list or replaces it. */
+    /**
+     * Whether a second drop adds to the set or replaces it. Defaults to `append` with
+     * `multiple`, else `replace`.
+     */
     selectionMode?: "append" | "replace";
     disabled?: boolean;
+    /** Applies the invalid treatment to the zone. The message stays with FormField. */
     invalid?: boolean;
-    /** A compact single row, for a zone that sits inside a form rather than owning a page. */
+    /**
+     * A single row rather than a panel, for a zone that sits inside a form rather than owning
+     * a page.
+     */
     compact?: boolean;
     /** Shorthand for `strings.instruction`. */
     label?: ReactNode;
     /** Overrides this control's own copy, the rejection sentences included. */
     strings?: Partial<FileUploadStrings>;
+    /** The line under the zone: the constraint text a reader needs before they choose. */
     hint?: ReactNode;
-    /** Hides the built-in list, for a caller rendering their own. */
+    /**
+     * Shows the chosen files under the zone. Turn it off only when something else on the page
+     * shows them — a caller rendering its own list.
+     */
     showList?: boolean;
-    /** Shows the refusals under the zone. */
+    /**
+     * Shows the refused files under the zone, each with its reason. Turn it off only when
+     * something else on the page shows them.
+     */
     showRejections?: boolean;
     /** Per-file transfer progress, 0–100, keyed by file name. */
     progress?: Record<string, number>;

package/dist/components/base/upload/media-gallery.d.ts

@@ -15,6 +15,10 @@ export interface MediaGalleryProps extends FileConstraints {
     strings?: Partial<MediaGalleryStrings>;
     className?: string;
 }
+/**
+ * Chosen images as reorderable tiles, for a gallery rather than a queue. The order is part of
+ * the value: the first tile is the cover.
+ */
 export declare function MediaGallery({ value, defaultValue, onValueChange, onRejectedFiles, maxFiles, disabled, invalid, showCover, strings, accept, ...constraints }: MediaGalleryProps & {
     className?: string;
 }): import("react").JSX.Element;

package/dist/components/base/upload/media-upload.d.ts

@@ -5,11 +5,19 @@ interface MediaUploadProps extends FileConstraints {
     id?: string;
     /** Overrides this control's own copy — the empty frame, the overlay, and remove. */
     strings?: Partial<MediaUploadStrings>;
-    /** Controlled file. */
+    /** The chosen file, controlled. */
     value?: File | null;
+    /** Called with the chosen file, or `undefined` when it is removed. */
     onValueChange?: (file: File | undefined) => void;
+    /**
+     * Receives the refused files. Report them through FormField's `error` prop: the error and
+     * helper text are associated with the native input.
+     */
     onRejectedFiles?: (rejections: FileRejection[]) => void;
-    /** An already-stored image. In controlled mode, clear this alongside value to remove it. */
+    /**
+     * An already-stored image. Uncontrolled, removing it clears its preview; when `value` is
+     * controlled, clear both `value` and `previewUrl` in `onValueChange` to remove it.
+     */
     previewUrl?: string;
     disabled?: boolean;
     invalid?: boolean;
@@ -24,6 +32,11 @@ interface MediaUploadProps extends FileConstraints {
 }
 export type AvatarUploadProps = MediaUploadProps;
 export type ImageUploadProps = MediaUploadProps;
+/** The round variant, sized for a profile image. */
 export declare function AvatarUpload({ strings, ...props }: AvatarUploadProps): import("react").JSX.Element;
+/**
+ * A single image, where the picker is the preview in the shape it will have in the
+ * product — a cover, a banner. Add an image, replace it, or remove it.
+ */
 export declare function ImageUpload({ strings, ...props }: ImageUploadProps): import("react").JSX.Element;
 export {};

package/dist/components/base/upload/preview-image.d.ts

@@ -6,4 +6,8 @@ export interface PreviewImageProps {
     fallback: ReactNode;
     className?: string;
 }
+/**
+ * A thumbnail for a file that has not been uploaded yet, or any image, that falls back to a
+ * glyph rather than the browser's broken-image mark when it fails to load.
+ */
 export declare function PreviewImage({ src, alt, fallback, className }: PreviewImageProps): import("react").JSX.Element;

package/dist/components/base/upload/upload-queue.d.ts

@@ -1,6 +1,7 @@
 import { FileUploadProps } from './file-upload.js';
 import { UploadProgressListStrings, UploadTrayStrings } from './upload.strings.js';
 export type UploadStatus = "queued" | "uploading" | "done" | "error" | "cancelled";
+/** One file on its way. The caller creates it, sends the file, and feeds status and progress back. */
 export interface UploadItem {
     /** Stable identity. The caller's, not a file name — two files may share one. */
     id: string;
@@ -9,6 +10,7 @@ export interface UploadItem {
     size?: number;
     /** 0–100. Ignored unless the status is `uploading`. */
     progress?: number;
+    /** Drives the row's icon, bar and trailing control. */
     status: UploadStatus;
     /** Shown under the row when the status is `error`. */
     error?: string;
@@ -16,33 +18,48 @@ export interface UploadItem {
     preview?: string;
 }
 export interface UploadProgressListProps {
+    /** The rows: id, name, size, status, and progress or error. Entirely caller-owned. */
     items: UploadItem[];
     /** Overrides this list's own copy — the five status words and the row controls. */
     strings?: Partial<UploadProgressListStrings>;
     /** Offered while a row is queued or uploading. */
     onCancel?: (id: string) => void;
-    /** Offered when a row has failed. */
+    /** Offered when a row has failed. Supplying it renders the retry control. */
     onRetry?: (id: string) => void;
     /**
      * Offered once a row is done, cancelled or failed, and on a queued row without
-     * `onCancel`. Never on a transfer in flight (that is cancel).
+     * `onCancel`. Never on a transfer in flight (that is cancel). Supplying it renders the
+     * dismiss control.
      */
     onRemove?: (id: string) => void;
     className?: string;
 }
 export declare function UploadProgressList({ items, onCancel, onRetry, onRemove, strings, className, }: UploadProgressListProps): import("react").JSX.Element | null;
 export interface UploadTrayProps extends Omit<FileUploadProps, "value" | "onValueChange" | "showList"> {
-    /** Everything in the tray, at whatever stage. */
+    /**
+     * Everything in the tray, at whatever stage: id, name, size, status, and progress or
+     * error. Entirely caller-owned.
+     */
     items: UploadItem[];
     /** Fires when files are dropped or browsed; the caller adds them to `items` and starts the transfer. */
     onAddFiles: (files: File[]) => void;
+    /** Stops one transfer. Supplying it renders the cancel control on a row in flight. */
     onCancel?: (id: string) => void;
+    /** Supplying it renders the retry control on a failed row. */
     onRetry?: (id: string) => void;
+    /** Supplying it renders the dismiss control on a finished row. */
     onRemove?: (id: string) => void;
+    /** Empties the tray. Supplying it renders the clear-all control. */
     onClearAll?: () => void;
-    /** Overrides this tray's own copy — the clear-all control. */
+    /** Overrides this tray's own copy, which names its controls — clear-all among them. */
     strings?: Partial<UploadTrayStrings>;
-    /** Hides the counts row. */
+    /** Shows the counts row above the list — "Uploading 1, Uploaded 1, Failed 1". */
     showSummary?: boolean;
 }
+/**
+ * The same list docked as a tray, with a drop target above it and a summary beneath — for
+ * uploads that outlive the page they started on. Adding files does not write to `items`:
+ * the tray reports the drop through `onAddFiles`, and the caller starts the transfer and
+ * reports back.
+ */
 export declare function UploadTray({ items, onAddFiles, onCancel, onRetry, onRemove, onClearAll, strings, showSummary, className, ...uploadProps }: UploadTrayProps): import("react").JSX.Element;

package/dist/components/base/upload/upload.types.d.ts

@@ -18,9 +18,14 @@ export interface FileRejection {
 /** Return `true` to accept, `false` for the default message, or a message of your own. */
 export type FileValidator = (file: File) => boolean | string;
 export interface FileConstraints {
-    /** Native accept filter, e.g. `.pdf,image/*`. Enforced here as well as by the dialog. */
+    /**
+     * Native accept filter, e.g. `.pdf,image/*`. Enforced here as well as by the dialog, and
+     * checked before `onValueChange` rather than after, like every constraint.
+     */
     accept?: string;
+    /** Smallest file accepted, in bytes. */
     minSizeBytes?: number;
+    /** Largest file accepted, in bytes. */
     maxSizeBytes?: number;
     /** Runs after the type and size checks. */
     validateFile?: FileValidator;

package/dist/components/base/upload/use-file-drop-target.d.ts

@@ -6,8 +6,9 @@ export interface FileDropTargetProps {
     onDrop: DragEventHandler<HTMLElement>;
 }
 /**
- * Drag state that survives descendants: `dragleave` fires on entering a child, so enters
- * and leaves are counted and dragging clears only at zero.
+ * The drop behaviour on its own, for a custom target. Its drag state survives descendants:
+ * `dragleave` fires on entering a child, so enters and leaves are counted and dragging
+ * clears only at zero.
  */
 export declare function useFileDropTarget({ disabled, onFiles, }: {
     disabled?: boolean;

package/dist/components/base/upload/validate-files.d.ts

@@ -11,5 +11,8 @@ export interface ValidationResult {
     nextFiles: File[];
     rejections: FileRejection[];
 }
-/** Validates a selection; each file gets its own verdict, so one rejection does not stop the rest. */
+/**
+ * The validation FileUpload runs, as a plain call, so a caller can pre-check. Each file gets
+ * its own verdict, so one rejection does not stop the rest.
+ */
 export declare function validateFileSelection({ incoming, current, maxFiles, append, ...constraints }: ValidateOptions): ValidationResult;

package/dist/components/base/value-inputs/color-input.d.ts

@@ -6,14 +6,33 @@ import { ColorInputStrings } from './value-inputs.strings.js';
  */
 import * as React from "react";
 export interface ColorInputProps extends Omit<InputProps, "type"> {
-    /** What the swatch shows. Defaults to the current value. */
+    /**
+     * What the swatch shows, when it differs from the value — a resolved token, say. Defaults
+     * to the current value.
+     */
     previewValue?: string;
+    /**
+     * Called with the colour as a string. Typed text is any CSS colour and is not normalised —
+     * what is typed is what is stored; the picker's value arrives in `format`.
+     */
     onValueChange?: (value: string) => void;
-    /** Overrides this field's own copy — the swatch's name. */
+    /**
+     * Overrides this field's own copy — the swatch's name. The swatch is a control, with the
+     * native picker under it, so it needs one.
+     */
     strings?: Partial<ColorInputStrings>;
-    /** The notation the picker emits. Defaults to `oklch` (or `hex` with the deprecated `emitHex`). */
+    /**
+     * The notation the picker emits — typed text is never rewritten. The kit's own palette is
+     * OKLCH, which is why that is the default; a consumer whose tokens are hex, rgb or hsl
+     * gets their own notation back. The conversion is culori's. With the deprecated `emitHex`
+     * and no `format`, it is `hex`.
+     * @default "oklch"
+     */
     format?: "oklch" | "hex" | "rgb" | "hsl";
-    /** @deprecated Use `format="hex"`. */
+    /**
+     * Makes the picker emit hex. `format` wins where both are given.
+     * @deprecated Use `format="hex"`; this spelling stays because it is published API.
+     */
     emitHex?: boolean;
 }
 export declare const ColorInput: React.ForwardRefExoticComponent<Omit<ColorInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/components/base/value-inputs/date-time-input.d.ts

@@ -18,4 +18,8 @@ export interface DateTimeInputProps {
     "aria-invalid"?: boolean | "true" | "false";
     "aria-required"?: boolean | "true" | "false";
 }
+/**
+ * A date and a time in one field: a date picker and time segments editing one value, stored
+ * as an ISO string.
+ */
 export declare const DateTimeInput: import('react').ForwardRefExoticComponent<DateTimeInputProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/base/value-inputs/phone-input.d.ts

@@ -2,21 +2,40 @@ import { InputProps } from '../text-inputs/index.js';
 import { CountryPrefixInput } from './country-prefixes.js';
 import { PhoneInputStrings } from './value-inputs.strings.js';
 export interface PhoneInputProps extends Omit<InputProps, "type" | "prefix"> {
-    /** Applies the invalid treatment to both the picker and the number field. */
+    /**
+     * Applies the invalid treatment to both the picker and the number field. The message
+     * stays on the FormField.
+     */
     invalid?: boolean;
-    /** Controlled dial code, e.g. "+1", or an ISO code that is resolved to one. */
+    /**
+     * Controlled dial code, e.g. "+1", or an ISO code that is resolved to one — the dial code
+     * as its own channel, apart from the number.
+     */
     prefix?: string;
+    /** The dial code the field starts with, when uncontrolled. */
     defaultPrefix?: string;
+    /** Called with the dial code the reader picks. */
     onPrefixChange?: (prefix: string) => void;
-    /** The list offered. ISO codes are looked up; unknown countries take a full object. */
+    /**
+     * Which dial codes the picker offers. ISO codes are looked up; unknown countries take a
+     * full object. `DEFAULT_COUNTRY_PREFIXES` is the built-in set.
+     */
     prefixes?: CountryPrefixInput[];
-    /** Hides the picker, for a form that captures the country elsewhere. */
+    /**
+     * Hides the picker, so the code cannot be changed — a form scoped to one country should
+     * not offer the list, and one that captures the country elsewhere need not.
+     */
     disablePrefixSelector?: boolean;
-    /** Overrides this field's own copy — the dial-code lane. */
+    /** Overrides this field's own copy — the dial-code lane's placeholder and its accessible name. */
     strings?: Partial<PhoneInputStrings>;
-    /** Tidies the number when the field loses focus. */
+    /** Tidies the number when focus leaves, rather than fighting the reader mid-entry. */
     normalizeOnBlur?: boolean;
     /** Shows the country name beside the dial code in the list. */
     showCountryName?: boolean;
 }
+/**
+ * A dial-code picker and a national number, kept apart so the prefix is always known and
+ * the number always national. `value` is the national number, without the prefix; read
+ * `event.target.value` in `onChange`.
+ */
 export declare const PhoneInput: import('react').ForwardRefExoticComponent<Omit<PhoneInputProps, "ref"> & import('react').RefAttributes<HTMLInputElement>>;

package/dist/components/base/value-inputs/slider.d.ts

@@ -16,13 +16,24 @@ export interface SliderFieldProps<TValue extends number | number[] = number | nu
      */
     value?: TValue;
     defaultValue?: TValue;
+    /** The lower bound. */
     min?: number;
+    /** The upper bound. */
     max?: number;
+    /** The increment between values. */
     step?: number;
     disabled?: boolean;
+    /** Applies the invalid treatment. The message stays on the FormField. */
     invalid?: boolean;
+    /**
+     * The track's direction. A vertical slider takes its height from
+     * `--slider-vertical-min-h`, because a slider has no content to size it.
+     */
     orientation?: "horizontal" | "vertical";
-    /** Track and thumb size: `md` is a larger drag target (touch, media controls). */
+    /**
+     * Track and thumb size: `md` is a larger drag target (touch, media controls). A slider is
+     * dragged, which is why this one keeps a size prop.
+     */
     size?: "sm" | "md";
     /** Native-shaped handler, for form libraries. */
     onChange?: (event: SliderChangeEvent<TValue extends number ? number : TValue>) => void;
@@ -32,7 +43,10 @@ export interface SliderFieldProps<TValue extends number | number[] = number | nu
     onValueCommitted?: (value: TValue extends number ? number : TValue) => void;
     /** Shows the current value beside the track. */
     showValue?: boolean;
-    /** Formats ONE value. A range formats each end and joins them. */
+    /**
+     * How the readout writes ONE value. A range formats each end and joins them with an en
+     * dash.
+     */
     formatValue?: (value: number) => string;
     /** Suffix on the displayed value — "px", "%", "mm". Ignored when `formatValue` is given. */
     unit?: string;
@@ -41,10 +55,24 @@ export interface SliderFieldProps<TValue extends number | number[] = number | nu
     "aria-labelledby"?: string;
     "aria-describedby"?: string;
     "aria-invalid"?: boolean | "true" | "false" | "grammar" | "spelling";
-    /** Overrides this slider's own copy: each range thumb's name ("Minimum", "Maximum") and the fallback name. */
+    /**
+     * Overrides this slider's own copy: each range thumb's name and the fallback name.
+     * `thumb` is a function of the thumb's index, defaulting to "Minimum" and "Maximum" — two
+     * handles called the same thing are two handles a screen reader cannot tell apart, and a
+     * range may have more than two.
+     */
     strings?: Partial<SliderStrings>;
 }
+/**
+ * One number on a track, or a range when the value is an array. It emits both a bare value
+ * and a native-shaped change event, because a form library registers a field by handing it
+ * an `onChange` and reading `event.target.value`.
+ */
 export declare const SliderField: <TValue extends number | number[] = number>(props: SliderFieldProps<TValue> & RefAttributes<HTMLDivElement>) => ReactElement | null;
-/** `SliderField` without the readout (`showValue`, `unit`) — for a toolbar or a canvas control. */
+/**
+ * The bare control: `SliderField` without the value readout (`showValue`, `unit`) — for a
+ * slider inside a toolbar, a popover or a canvas control, where the surrounding surface
+ * already says what it adjusts.
+ */
 export declare const Slider: <TValue extends number | number[] = number>(props: SliderProps<TValue> & RefAttributes<HTMLDivElement>) => ReactElement | null;
 export type SliderProps<TValue extends number | number[] = number | number[]> = Omit<SliderFieldProps<TValue>, "showValue" | "unit">;

package/dist/components/base/value-inputs/tags-input.d.ts

@@ -1,12 +1,14 @@
 import { ReactNode } from 'react';
 import { TagsInputStrings } from './value-inputs.strings.js';
 export interface TagsInputProps {
-    /** Controlled value. */
+    /** The chips, controlled. */
     value?: string[];
     defaultValue?: string[];
+    /** Called with the next list of tags. */
     onValueChange?: (value: string[]) => void;
     placeholder?: string;
     disabled?: boolean;
+    /** Applies the invalid treatment. The message stays with FormField. */
     invalid?: boolean;
     name?: string;
     /** Cap on the number of tags. Entry is refused once it is reached. */
@@ -15,22 +17,34 @@ export interface TagsInputProps {
     showCount?: boolean;
     /** Shows a clear-all control under the field. */
     showClearAll?: boolean;
-    /** Overrides this field's own copy — clear-all, and each tag's remove. */
+    /**
+     * Overrides this field's own copy — clear-all, and each tag's remove, named after the tag
+     * it removes.
+     */
     strings?: Partial<TagsInputStrings>;
+    /** Lets the same string appear twice. */
     allowDuplicates?: boolean;
     /** Duplicate detection is case-insensitive unless this is set. */
     caseSensitive?: boolean;
     /** Keeps the list sorted as tags are added. */
     sortTags?: boolean;
+    /** The shortest tag accepted. */
     minLength?: number;
+    /** The longest tag accepted. */
     maxLength?: number;
-    /** Rejects a tag when this returns false. Runs after the length checks. */
+    /**
+     * Rejects a tag when this returns false. Runs after the length checks — the field refuses
+     * the tag rather than accepting a bad one and reporting it later.
+     */
     validate?: (value: string) => boolean;
-    /** Splits pasted and typed input into several tags. Defaults to a comma or a newline. */
+    /**
+     * Splits pasted and typed input into several tags — which is what a column copied out of
+     * a spreadsheet looks like. Defaults to a comma or a newline.
+     */
     delimiter?: string | RegExp;
     /** Commits whatever is typed when the field loses focus. */
     addOnBlur?: boolean;
-    /** Replaces the chip. */
+    /** Replaces the chip, for a tag that carries an avatar or a colour. */
     renderTag?: (tag: string, index: number, remove: (index: number) => void) => ReactNode;
     className?: string;
     /** Goes on the text input, not the wrapper, so a `FormField` label names it. */

package/dist/components/features/actions/action-adapters.d.ts

@@ -5,6 +5,11 @@ export interface ActionHttpErrorOptions {
     body: unknown;
     response: Response;
 }
+/**
+ * The `Error` createHttpActionRunner throws for a failed response, carrying `status`,
+ * `statusText`, `body` and the `Response`, plus the body's own `errors` when it has them. What
+ * `parseErrors` receives for an HTTP failure.
+ */
 export declare class ActionHttpError extends Error {
     status: number;
     statusText: string;
@@ -19,13 +24,23 @@ export interface CreateHttpActionRunnerOptions {
     parseResponse?: (response: Response) => Promise<unknown>;
 }
 export declare function createHttpActionRunner<TResult = unknown>({ baseUrl, fetcher, parseResponse, }?: CreateHttpActionRunnerOptions): ActionRequestRunner<TResult>;
+/** Identity helper that keeps the generics inferred. */
 export declare function defineAction<TPayload = unknown, TValues = unknown, TResult = unknown>(definition: ActionDefinition<TPayload, TValues, TResult>): ActionDefinition<TPayload, TValues, TResult>;
+/**
+ * `defineAction` for a destructive action: its tone defaults to `"destructive"`, and its
+ * modality to a destructive `"alert"`.
+ */
 export declare function defineDeleteAction<TPayload = unknown, TResult = unknown>(definition: Omit<ActionDefinition<TPayload, undefined, TResult>, 'modality'> & {
     modality: Omit<ActionModalityConfig<TPayload, undefined, TResult>, 'type' | 'tone'> & Partial<Pick<ActionModalityConfig<TPayload, undefined, TResult>, 'type' | 'tone'>>;
 }): ActionDefinition<TPayload, undefined, TResult>;
+/**
+ * `defineAction` for an action that asks through a form: the modality's `type` defaults to
+ * `"dialog"`.
+ */
 export declare function defineFormAction<TPayload = unknown, TValues = unknown, TResult = unknown>(definition: Omit<ActionDefinition<TPayload, TValues, TResult>, 'modality'> & {
     modality: Omit<ActionModalityConfig<TPayload, TValues, TResult>, 'type'> & Partial<Pick<ActionModalityConfig<TPayload, TValues, TResult>, 'type'>>;
 }): ActionDefinition<TPayload, TValues, TResult>;
+/** `defineAction` for an action that runs without asking: its modality is `"none"`. */
 export declare function defineSilentAction<TPayload = unknown, TValues = unknown, TResult = unknown>(definition: Omit<ActionDefinition<TPayload, TValues, TResult>, 'modality'>): ActionDefinition<TPayload, TValues, TResult>;
 export declare function toPageAction<TPayload = unknown, TValues = unknown, TResult = unknown>(action: ResolvedAction<TPayload, TValues, TResult>): {
     id: string;

package/dist/components/features/actions/action-overlay-outlet.d.ts

@@ -1,2 +1,6 @@
 import { ActionOverlayOutletProps } from './actions.types.js';
+/**
+ * Renders the active action's modality — alert, dialog, or drawer. Mount one inside the
+ * `ActionProvider`; every surface that runs an action with a `modality` then shares it.
+ */
 export declare function ActionOverlayOutlet({ strings }?: ActionOverlayOutletProps): import("react").JSX.Element | null;

package/dist/components/features/actions/action-provider.d.ts

@@ -1,3 +1,4 @@
 import { ReactNode } from 'react';
 import { ActionProviderProps } from './actions.types.js';
+/** Owns the action registry and the run state. Mount one near the app shell. */
 export declare function ActionProvider<TPayload = unknown, TValues = unknown, TResult = unknown>({ actions, runtime, feedback, guards, parseErrors, requestRunner, onOverlayOpenChange, onRunningChange, children, }: ActionProviderProps<TPayload, TValues, TResult>): ReactNode;

package/dist/components/features/actions/action-scope.d.ts

@@ -1,3 +1,7 @@
 import { ReactNode } from 'react';
 import { ActionScopeProps } from './actions.types.js';
+/**
+ * Declarative registration, for actions that belong to a subtree rather than a component.
+ * Registers `actions` under `scope` while mounted, and surfaces inside it resolve in that scope.
+ */
 export declare function ActionScope<TPayload = unknown, TValues = unknown, TResult = unknown>({ scope, actions, children, }: ActionScopeProps<TPayload, TValues, TResult>): ReactNode;

package/dist/components/features/actions/action-store.d.ts

@@ -55,4 +55,8 @@ export declare class ActionStore {
 export declare function createActionStore(): ActionStore;
 export declare const ActionStoreContext: import('react').Context<ActionStore | null>;
 export declare const ActionScopeContext: import('react').Context<string | null>;
+/**
+ * The store itself, for logic the hooks do not cover. Throws outside an `ActionProvider` rather
+ * than returning null.
+ */
 export declare function useActionStore(): ActionStore;

package/dist/components/features/actions/actions.types.d.ts

@@ -138,6 +138,10 @@ export interface ActionModalityConfig<TPayload = unknown, TValues = unknown, TRe
 export type ActionPredicate<TPayload = unknown> = boolean | BivariantCallback<[context: ActionContext<TPayload>], boolean>;
 export type ActionPermission = string | readonly string[];
 export type ActionRoles = string | readonly string[];
+/**
+ * One action, defined once and read from every surface: what it is called, where it appears, how
+ * it asks, and what it runs.
+ */
 export interface ActionDefinition<TPayload = unknown, TValues = unknown, TResult = unknown> extends Omit<ActionPresentation, 'visible' | 'disabled'> {
     id: string;
     label: ReactNode;
@@ -153,12 +157,18 @@ export interface ActionDefinition<TPayload = unknown, TValues = unknown, TResult
     disabled?: ActionPredicate<TPayload>;
     permission?: ActionPermission;
     roles?: ActionRoles;
+    /**
+     * How the action asks. The outlet renders it; no surface needs its own dialog. `"none"`, or no
+     * modality, runs the action at once.
+     */
     modality?: 'none' | ActionModalityConfig<TPayload, TValues, TResult>;
+    /** A declarative request, run by `requestRunner` — for apps whose actions are mostly HTTP. */
     request?: ActionRequestConfig<TPayload, TValues>;
     requestRunner?: ActionRequestRunner<TResult>;
     run?: BivariantCallback<[
         context: ActionRunContext<TPayload, TValues>
     ], TResult | Promise<TResult>>;
+    /** Turns a failure into field errors, so a form modality can show them inline. */
     parseErrors?: ActionErrorParser;
     successMessage?: ActionMessage<TPayload, TValues, TResult>;
     errorMessage?: ActionMessage<TPayload, TValues, TResult>;