prime-ui-kit 0.14.0 → 0.16.0

package/dist/internal/selectionIndicator.d.ts

@@ -0,0 +1,27 @@
+import type * as React from "react";
+/**
+ * The sliding indicator of a switcher (`selectionIndicator.module.css`): join it on the element
+ * the host draws as its folder, thumb or capsule, first in the row so it paints under the items.
+ */
+export declare const selectionIndicatorClass: string;
+/**
+ * Writes a boolean `data-*` flag only when it changes: a layout pass that runs on every frame of
+ * a container resize must not restyle the row when nothing changed.
+ */
+export declare function setFlag(element: HTMLElement, name: `data-${string}`, on: boolean): void;
+/**
+ * Places the indicator over `target` — its offset box in the parent they share — straight in the
+ * DOM, so a resize or a font swap never re-renders the host. With `animate` (a person's choice) a
+ * move of a visible indicator glides; every other placement snaps. Without a target the
+ * indicator fades out.
+ */
+export declare function placeIndicator(indicator: HTMLElement, target: HTMLElement | null, animate: boolean): void;
+/** `onTransitionEnd` of the indicator: the glide is over, so the next layout change snaps. */
+export declare function endIndicatorGlide(event: Pick<React.TransitionEvent<HTMLElement>, "target" | "currentTarget" | "propertyName">): void;
+/**
+ * Scrolls a sideways scroller (never the page: `scrollIntoView` would scroll it too) so `item` is
+ * in view and clear of the edge fade (`--scroll-fade-depth` on the scroller); near an end it
+ * scrolls all the way, where the fade melts to nothing. Smooth only after a person's choice.
+ * Returns the offset the scroller goes to, or `null` when the item is already in view.
+ */
+export declare function revealInScroller(scroller: HTMLElement, item: HTMLElement, smooth: boolean): number | null;

package/dist/internal/slot.d.ts

@@ -1,9 +1,19 @@
 import * as React from "react";
 type AnyProps = Record<string, unknown>;
-export type SlotProps = {
+type SlotProps<E extends HTMLElement = HTMLElement> = {
     children?: React.ReactNode;
-    ref?: React.Ref<HTMLElement>;
+    ref?: React.Ref<E>;
 } & AnyProps;
+/**
+ * The props of a slot part (`Trigger`, `Close`, `Confirm`, `Anchor`): exactly one element, which
+ * takes the part's behaviour. A slot part renders no DOM of its own, so it has no `className`.
+ */
+export type SlotPartProps = {
+    /**
+     * One element: a control, a disabled control or a non-interactive element such as a Badge.
+     */
+    children: React.ReactElement;
+};
 /**
  * Merges its own props onto the single React child element.
  * The basis of the `asChild` polymorphism pattern (same idea as Radix UI `Slot`).
@@ -15,11 +25,49 @@ export type SlotProps = {
  * - `on*` handlers — both fire, child first; a child `preventDefault()` skips the slot handler
  * - All other props — a defined child prop overrides the slot prop
  * - `ref` — merged with the child's ref
- * - `aria-disabled` on the slot — clicks (pointer and keyboard-activated) are stopped in the capture
- *   phase, so the child's own `onClick` never runs and a link does not navigate
+ * - `aria-disabled` on the slot — the child leaves the Tab order (`tabIndex -1`), a link loses its
+ *   `href` (it stays a `link` by role), and clicks (pointer and keyboard-activated) are stopped in
+ *   the capture phase, so the child's own `onClick` never runs and nothing navigates
  */
-export declare function Slot({ children, ref, ...slotProps }: SlotProps): import("react/jsx-runtime").JSX.Element;
+export declare function Slot<E extends HTMLElement = HTMLElement>({ children, ref, ...slotProps }: SlotProps<E>): import("react/jsx-runtime").JSX.Element;
 export declare namespace Slot {
     var displayName: string;
 }
+/** One part moved into an outlet: its id (a key for the outlet) and what it renders. */
+type OutletEntry = {
+    id: string;
+    node: React.ReactNode;
+};
+/**
+ * The place in a host that renders parts written elsewhere in its subtree: a page's own
+ * `AppHeader.Root` in the app shell's header row, page tools wrapped in a page component in the
+ * header's second row. The host owns one store (`useOutletStore`) and renders its entries
+ * (`useOutletEntries`); a part moves in with `useMovedToOutlet`. The store is external to React
+ * state, so a part that updates re-renders the outlet only — never the host, never the part's own
+ * tree.
+ */
+export type OutletStore = {
+    /** Adds or replaces the part `id` (it keeps the place it first took); `null` takes it out. */
+    set: (id: string, node: React.ReactNode | null) => void;
+    subscribe: (listener: () => void) => () => void;
+    entries: () => readonly OutletEntry[];
+};
+/** The outlet store of a host, created once. */
+export declare function useOutletStore(): OutletStore;
+/** The parts moved into `store`, in the order they first arrived (none on the server). */
+export declare function useOutletEntries(store: OutletStore): readonly OutletEntry[];
+/**
+ * Moves `node` into the outlet `store` (`null` — no outlet: the part stays where it is written).
+ * Returns `true` once the part has moved: render nothing then. Until then — on the server and in
+ * the first client render — the part renders in place, so the server HTML has it; the move happens
+ * before the browser paints. The part leaves the outlet when it unmounts.
+ */
+export declare function useMovedToOutlet(store: OutletStore | null, node: React.ReactNode): boolean;
+/**
+ * The one element child of an `asChild` part, whose own children the part wraps
+ * (`React.cloneElement(child, undefined, …child.props.children)`). Throws a named error otherwise.
+ */
+export declare function slotChild(children: React.ReactNode, part: string): React.ReactElement<{
+    children?: React.ReactNode;
+}>;
 export {};

package/dist/internal/states.d.ts

@@ -5,8 +5,67 @@
 /** Control size tiers: xs 28 · s 32 · m 36 · l 40 · xl 48. Default is always `m`. */
 export declare const controlSizes: readonly ["xs", "s", "m", "l", "xl"];
 export type ControlSize = (typeof controlSizes)[number];
+/**
+ * The default `size` of an overlay's `Content` (Modal, Drawer, Popover, Dropdown, Tooltip): a width
+ * tier of its own that never follows the host's tier (foundation §10), so it does not resolve
+ * through `useHostTier`.
+ */
+export declare const OVERLAY_CONTENT_SIZE = "m";
 /** The tier `n` steps smaller, never below `xs`: a control nested in another (foundation §6 pairing). */
 export declare function stepDown(size: ControlSize, n?: number): ControlSize;
+/**
+ * The tier of a fixed small control inside a host (a corner close, a row toggle, a tile check, a
+ * close on a tab): `xs` up to `m`, `s` for `l` and `xl`. Not a step down: in an `m` host a step
+ * down would give `s`, and the control would read as one of the host's own actions.
+ */
+export declare function compactTier(size: ControlSize): ControlSize;
+/**
+ * Named tier mappings: one per metric a host must match, each with the reason it is not a step.
+ * A component never declares its own `Record<ControlSize, ControlSize>`.
+ */
+export declare const tierMappings: {
+    /** An Avatar or Thumbnail leading a Select row: the media stays inside the row height. */
+    readonly rowMedia: {
+        readonly xs: "xs";
+        readonly s: "xs";
+        readonly m: "s";
+        readonly l: "s";
+        readonly xl: "m";
+    };
+    /**
+     * The Skeleton tier whose line height equals the legend row of a label tier
+     * (16 · 16 · 20 · 20 · 20), so a loading legend keeps the height of the loaded one.
+     */
+    readonly legendSkeleton: {
+        readonly xs: "xs";
+        readonly s: "xs";
+        readonly m: "m";
+        readonly l: "m";
+        readonly xl: "m";
+    };
+    /**
+     * The label tier of a legend's text (ProgressBar, ProgressCircle): a legend is secondary to its
+     * indicator, so s and xl read the label of the tier below (xs · xs · m · l · l).
+     */
+    readonly legendText: {
+        readonly xs: "xs";
+        readonly s: "xs";
+        readonly m: "m";
+        readonly l: "l";
+        readonly xl: "l";
+    };
+    /**
+     * The account Avatar of a Sidebar row: the avatar of the tier, capped so it still fits the
+     * compact rail with even air around it (32 at `l`, 40 at `xl`).
+     */
+    readonly railAvatar: {
+        readonly xs: "xs";
+        readonly s: "s";
+        readonly m: "m";
+        readonly l: "m";
+        readonly xl: "l";
+    };
+};
 /** Visual treatment. */
 export declare const variants: readonly ["solid", "soft", "outline", "ghost"];
 export type Variant = (typeof variants)[number];
@@ -19,6 +78,8 @@ export type PaletteColor = (typeof paletteColors)[number];
 /** Values of `data-state`. */
 export declare const dataStates: readonly ["open", "closed", "checked", "unchecked", "indeterminate", "active", "inactive"];
 export type DataState = (typeof dataStates)[number];
+/** The state of a check: a checkbox box, a check mark, a choice row. */
+export type CheckState = Extract<DataState, "checked" | "unchecked" | "indeterminate">;
 /**
  * Text color (Typography, Icon). `default` is primary text, `secondary` and `muted` are the
  * two quieter steps; the rest map to the semantic `*-text` colors.

package/dist/internal/sticky.d.ts

@@ -1,2 +1,6 @@
-/** Covers the sub-pixel seam above a block-start sticky surface in WebKit (`sticky.module.css`). */
+/**
+ * A surface that sticks to the start edge of its scroller (`sticky.module.css`): it sticks at
+ * `top: 0`, covers the sub-pixel seam above it in WebKit, and stops sticking on a screen lower than
+ * 480px (foundation §9). The host sets only its stacking (`z-index`) and fill (`--sticky-bg`).
+ */
 export declare const stickySurfaceClass: string;

package/dist/internal/swallowNextClick.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A gesture that ends with the pointer released over the page (a drag, a dragged scroll) is
+ * followed by a click on whatever the pointer was released over. That click is not a press: it is
+ * taken here, once, and only when it lands inside `source` or `scope` (the list an item was dropped
+ * into renders it anew, so the click lands on a new element there). The next press or key ends the
+ * watch, so a later click (a keyboard activation among them) is never taken. Returns a function
+ * that ends the watch early.
+ */
+export declare function swallowNextClick(source: Element, scope?: Element | null): () => void;

package/dist/internal/swatch.d.ts

@@ -1,4 +1,5 @@
 import * as React from "react";
+import type { PaletteColor } from "./states";
 export type ColorPreset = {
     /** CSS color stored as the value (`onValueChange` returns it as is). */
     value: string;
@@ -11,35 +12,72 @@ export type ColorPreset = {
  * Take `COLOR_PRESETS.slice(0, 8)` for a single row of eight.
  */
 export declare const COLOR_PRESETS: readonly ColorPreset[];
-/** One selectable swatch: `null` is «no color». */
+/** Names of the palette hues, in the order a palette picker shows them. */
+export declare const PALETTE_COLOR_NAMES: Record<PaletteColor, string>;
+/** Every palette hue in the picker order (the keys of `PALETTE_COLOR_NAMES`). */
+export declare const PALETTE_ORDER: PaletteColor[];
+/**
+ * One selectable swatch: `null` is «no color». `contrast` picks the check mark: `light` / `dark`
+ * by the color's luminance; `surface` (the «no color» checkerboard, drawn from the surface's own
+ * fills) follows the theme with the primary text color; `hue` — a palette hue (`value` is its
+ * name), drawn from its solid step with its own foreground.
+ */
 export type SwatchOption = {
     value: string | null;
     label: string;
-    contrast: "light" | "dark";
+    contrast: "light" | "dark" | "surface" | "hue";
 };
 /** The presets as swatch options, plus the «no color» option at the end when `allowEmpty`. */
 export declare function useSwatchOptions(presets: readonly ColorPreset[], allowEmpty: boolean, emptyLabel: string): SwatchOption[];
-/** Class of a selectable swatch (button or option) sized by `--swatch-size` / `--swatch-radius`. */
+/** The palette hues as swatch options (`value` is the hue), plus «no color» when `allowEmpty`. */
+export declare function usePaletteOptions(palette: readonly PaletteColor[], allowEmpty: boolean, emptyLabel: string, names: Record<PaletteColor, string>): SwatchOption[];
+/**
+ * Class of a selectable swatch (button or option) sized by `--swatch-size` / `--swatch-radius`,
+ * with the press feedback; the donor owns its hover, focus and disabled look.
+ */
 export declare const swatchClass: string;
 /**
- * Tier of a swatch grid, from `data-size` on the same element: `--swatch-radius`, `--swatch-gap`
- * and `--swatch-size` = `--swatch-base` − 8. The host picks the base: `--swatch-base-control`
- * (control height) or `--swatch-base-item` (menu item height).
+ * The square swatch button of a trigger (ColorPresets): the field height of the tier on the same
+ * element (`fieldTierClass` + `data-size`), the inner edge that darkens on hover and while open
+ * (`data-state`), the press feedback and the shared disabled look.
+ */
+export declare const swatchTriggerClass: string;
+/**
+ * Tier of a swatch grid, on the grid element with `data-size`: the field tier plus
+ * `--swatch-radius`, the gap between swatches and `--swatch-size` = base − 8, where the base is the
+ * control height, or the menu item height with `data-base="item"`; on a coarse pointer at least the
+ * touch target.
  */
 export declare const swatchTierClass: string;
-/** Color layer of a swatch; `null` draws the "no color" checkerboard. */
-export declare function SwatchFill({ value }: {
+/**
+ * A grid of swatches, joined next to `swatchTierClass`: one row of `--swatch-count` swatches (the
+ * host sets it) while the width allows, then `--swatch-columns` (`useBalancedColumns`) balanced
+ * rows. `data-stretch` makes the swatches share the whole width, each across its column.
+ */
+export declare const swatchGridClass: string;
+/**
+ * Defines `--swatch-checker`, the kit's transparency checkerboard as a background layer, for a host
+ * that lays a translucent color over it (ColorPicker's alpha track).
+ */
+export declare const checkerboardClass: string;
+/**
+ * Color layer of a swatch; `null` draws the "no color" checkerboard; `hue` — the value is a palette
+ * hue on a swatch that carries `palette.hue` + `data-color`.
+ */
+export declare function SwatchFill({ value, hue }: {
     value: string | null;
+    hue?: boolean;
 }): import("react/jsx-runtime").JSX.Element;
 /**
  * Inside a selectable swatch: the color layer and the contrasting check, which draws in when the
  * swatch is selected and retracts when it is not (`CheckMark`, the same mark as Checkbox).
  */
-export declare function SwatchContent({ value, selected }: {
+export declare function SwatchContent({ value, selected, hue, }: {
     value: string | null;
     selected: boolean;
+    hue?: boolean;
 }): import("react/jsx-runtime").JSX.Element;
-export type SwatchChipProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
+type SwatchChipProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
     value: string | null;
     ref?: React.Ref<HTMLSpanElement>;
 };
@@ -51,9 +89,19 @@ export declare function SwatchChip({ value, className, ...rest }: SwatchChipProp
 /** Case- and space-insensitive color comparison; `null` means "no color". */
 export declare function sameColor(a: string | null, b: string | null): boolean;
 /**
- * sRGB channels (0–255) of a hex, `rgb()` or `hsl()` color; `null` for anything else (named colors,
- * other spaces). Kept dependency-free so the swatches stay out of the ColorPicker entry.
+ * `--swatch-columns` of a swatch grid: balanced rows at its current width (none before the first
+ * measure). `cellSelector` finds a swatch, whose height is the tier size (ColorSwatches, ColorPresets).
  */
-export declare function colorToRgb(value: string): [number, number, number] | null;
-/** `dark` when a dark mark contrasts better with the color than a light one (WCAG luminance). */
-export declare function markContrast(value: string): "light" | "dark";
+export declare function useBalancedColumns(gridRef: React.RefObject<HTMLElement | null>, count: number, cellSelector: string): number | undefined;
+/**
+ * Roving focus over a grid of `count` swatches (ColorSwatches, ColorPresets): `itemRef(index)` on
+ * each swatch; `move(event, from, columns?)` takes the arrows, Home and End from the focused swatch
+ * (else `from`), focuses the swatch they reach and returns its index — `null` for any other key.
+ * Without `columns` the rows are the visual ones (a grid that wraps to its width).
+ */
+export declare function useSwatchGrid(count: number): {
+    itemRef: (index: number) => (node: HTMLElement | null) => void;
+    move: (event: React.KeyboardEvent, from: number, columns?: number) => number | null;
+    focus: (index: number) => void;
+};
+export {};

package/dist/internal/textFormatting.d.ts

@@ -14,7 +14,7 @@ export declare const TEXT_FORMATTING_LABELS: TextFormattingLabels;
 /** Every format in toolbar order. */
 export declare const TEXT_FORMATS: readonly TextFormat[];
 /** Text with its selection, `start <= end` (a caret when equal). */
-export type TextSelection = {
+type TextSelection = {
     text: string;
     start: number;
     end: number;
@@ -50,3 +50,4 @@ export declare const FORMAT_SHORTCUTS: Record<TextFormat, {
 }>;
 /** `⌘⇧X` on Apple systems, `Ctrl+Shift+X` elsewhere. */
 export declare function shortcutText(format: TextFormat, apple: boolean): string;
+export {};

package/dist/internal/textFormattingToolbar.d.ts

@@ -1,7 +1,7 @@
 import * as React from "react";
 import { type ControlSize } from "./states";
 import { type TextFormattingLabels } from "./textFormatting";
-export type TextFormattingOptions = {
+type TextFormattingOptions = {
     textareaRef: React.RefObject<HTMLTextAreaElement | null>;
     /** The hotkeys and the toolbar. */
     enabled: boolean;
@@ -13,7 +13,7 @@ export type TextFormattingOptions = {
     /** Id of the textarea (`aria-controls` of the toolbar). */
     controlsId?: string;
 };
-export type TextFormatting = {
+type TextFormatting = {
     /** On the textarea's `onSelect`. */
     onSelect: () => void;
     /** Call first in the textarea's `onKeyDown`; `true` when the key was a formatting one and is used. */
@@ -24,3 +24,4 @@ export type TextFormatting = {
     toolbar: React.ReactNode;
 };
 export declare function useTextFormatting({ textareaRef, enabled, toolbar: toolbarAllowed, labels, size, controlsId, }: TextFormattingOptions): TextFormatting;
+export {};

package/dist/internal/tokenDefaults.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Token values as numbers at the default root size (16px): px for lengths, ms for durations. For
+ * JS that needs a token before the CSS can be read (server render, a test without the styles) or
+ * where a number must agree with the CSS (an off-screen estimate, a gesture clock). Live values
+ * come from the CSS (`readCssLengthPx`, `readCssDurationMs`), with these as their defaults.
+ */
+export declare const TOKEN_DEFAULTS: {
+    readonly "--prime-gallery-max-size": 360;
+    readonly "--prime-message-video-note-box": 268;
+    readonly "--prime-motion-duration-base": 380;
+    readonly "--prime-motion-duration-fast": 230;
+    readonly "--prime-motion-duration-slow": 570;
+    readonly "--prime-motion-duration-xfast": 150;
+    readonly "--prime-motion-hold-confirm": 1200;
+    readonly "--prime-motion-stagger": 80;
+    readonly "--prime-panel-offset": 4;
+    readonly "--prime-space-2": 8;
+    readonly "--prime-space-6": 24;
+    readonly "--prime-space-8": 32;
+    readonly "--prime-space-20": 80;
+};

package/dist/internal/touchTarget.d.ts

@@ -2,3 +2,8 @@
 export declare const touchTargetClass: string;
 /** The same hit area grown in height only: a segment beside other content of its host. */
 export declare const touchTargetBlockClass: string;
+/**
+ * A row of a stacked list (a list item, a menu row, a timeline entry): on coarse pointers the row
+ * itself grows to the touch target height, since a hit area outside it would cover its neighbours.
+ */
+export declare const touchTargetRowClass: string;

package/dist/internal/transcript.d.ts

@@ -1,23 +1,32 @@
 import * as React from "react";
 import type { SurfaceDepth } from "./surfaceDepth";
+import { type AsyncHandler } from "./usePendingChanges";
 /**
- * The transcript of a voice or video message (VoicePlayer, VideoNote): a button that
- * opens the text under the media, the text itself, and its request when the text is not known yet.
+ * The transcript of a voice or video message (VoicePlayer, VideoNote): a button that opens the
+ * text under the media, the text itself, and its request when the text is not known yet (each
+ * prop is described in `transcript.api.ts`). An `onTranscribe` that returns nothing keeps the
+ * button spinning until the owner passes `transcript`.
  */
 export type TranscriptProps = {
-    /** The text of the recording, when it is known. With it or `onTranscribe` the button shows. */
+    /**
+     * The text of the recording, when it is known. With it or `onTranscribe` a «→A» button opens and closes the text: the button ends the waveform, the text opens under the player.
+     */
     transcript?: string;
     /**
-     * Asks for the text when `transcript` is not known yet, on the first open. Return a Promise of the
-     * text: only the button spins and the area stays closed until it resolves, then it opens with the
-     * text; a rejection announces `transcribeFailed`. Returning nothing keeps the button spinning
-     * until the owner passes `transcript`.
+     * Asks for the text on the first open while `transcript` is not known; return a Promise of the text. The button spins, then the text opens; a rejection announces `labels.transcribeFailed`.
+     */
+    onTranscribe?: AsyncHandler<[], string>;
+    /**
+     * The transcript is open (controlled). Opening it without a text calls `onTranscribe`.
      */
-    onTranscribe?: () => Promise<string> | void;
-    /** The transcript is open (controlled). */
     transcriptExpanded?: boolean;
-    /** Initially open (uncontrolled). Default `false`. */
+    /**
+     * Initially open (uncontrolled). In `Chat.Messages` the open state and a resolved text survive a row scrolled away and back.
+     */
     defaultTranscriptExpanded?: boolean;
+    /**
+     * The transcript button was pressed, or a rejected `onTranscribe` closed the transcript.
+     */
     onTranscriptExpandedChange?: (expanded: boolean) => void;
 };
 export type TranscriptLabels = {
@@ -62,12 +71,4 @@ export type Transcript = {
  * that would change the bubble twice.
  */
 export declare function useTranscript({ transcript, onTranscribe, transcriptExpanded, defaultTranscriptExpanded, onTranscriptExpandedChange, }: TranscriptProps, labels: TranscriptLabels): Transcript | null;
-/**
- * The button's glyph: the transcript mark («→A») while closed, a chevron up while open; they
- * cross-fade. The request's spinner is the Button's own `loading` (`internal/mediaPlayer`
- * `TranscriptButton`).
- */
-export declare function TranscriptGlyph({ expanded }: {
-    expanded: boolean;
-}): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/internal/transfer.d.ts

@@ -1,3 +1,4 @@
+import type { AsyncHandler } from "./usePendingChanges";
 /**
  * Where a transfer of a file or a recording is, in either direction: `remote` — not fetched yet
  * (the download arrow fetches it); `queued` — waiting its turn; `loading` — in flight; `failed` —
@@ -11,23 +12,36 @@ export type TransferState = "remote" | "queued" | "loading" | "failed" | "done";
  */
 export type TransferDirection = "upload" | "download";
 /** A cancel, a retry or a download: a returned promise keeps the disk pending until it settles. */
-export type TransferHandler = () => void | Promise<void>;
+export type TransferHandler = AsyncHandler;
 /**
  * The transfer props of every part that sends or receives its content (VoicePlayer, VideoNote,
- * Message.File; Message.Media per item, its handlers per index).
+ * Message.File; Message.Media per item, its handlers per index). Each prop is described in
+ * `transfer.api.ts`.
  */
 export type TransferProps = {
-    /** Where the transfer is; without it the content is simply there. */
+    /**
+     * The transfer of the recording, drawn on the play disk itself, either way (`TransferState`): `queued` / `loading` — the cancel cross and the share ring; `failed` — retry; `remote` — download; `done` — the disk fades out.
+     */
     transfer?: TransferState;
-    /** Share transferred, 0…1; without it a transfer in flight turns an indeterminate arc. */
+    /**
+     * Share transferred, 0…1 (`UploadItem.progress`): the ring along the disk's inner edge, gliding (`base`) while it turns. Without it a transfer in flight turns a quarter arc.
+     */
     transferProgress?: number;
-    /** Which way it goes: the words only. Default `upload`. */
+    /**
+     * Which way it goes: sending (`upload`) or receiving (`download`). Changes only the words — the names of the cross and the retry, the share and the failure — never the look.
+     */
     transferDirection?: TransferDirection;
-    /** Cancel the transfer in flight (the disk's cross). */
+    /**
+     * Cancel the transfer in flight: the disk's cross. A returned promise keeps the disk pending (a spinner, `aria-busy`, no second press); a rejection leaves the transfer as it was and announces `cancelFailed`.
+     */
     onCancel?: TransferHandler;
-    /** Transfer it again after a failure (the danger disk). */
+    /**
+     * Transfer it again after a failure: the danger disk's retry; a promise works the same (`retryFailed` on a rejection).
+     */
     onRetry?: TransferHandler;
-    /** Fetch a `remote` content (the download arrow). */
+    /**
+     * Fetch a `remote` content: the download arrow; set `transfer` to `loading` with `transferDirection="download"` as it starts. A promise works the same (`downloadFailed` on a rejection).
+     */
     onDownload?: TransferHandler;
 };
 /** The strings of a transfer, one shape for every part that transfers its content. */

package/dist/internal/transferDisk.d.ts

@@ -29,7 +29,7 @@ export type TransferDiskProps = {
     className?: string;
 };
 type Action = "cancel" | "retry" | "download";
-export type TransferDiskModel = {
+type TransferDiskModel = {
     /** What a press does now, or `null` when the disk only shows the state. */
     action: Action | null;
     /** The handler of `action` was given. */
@@ -66,11 +66,10 @@ export declare function useTransferDisk({ state, progress, labels, onCancel, onR
  * named `progressbar` while in flight.
  */
 export declare function TransferDisk({ look, size, className, ...props }: TransferDiskProps): import("react/jsx-runtime").JSX.Element;
-export type TransferOverlayProps = TransferDiskProps;
 /**
  * The transfer disk centred over a box (an attachment tile, a picture in a chat message, a video
  * circle). The host positions it (`position: absolute; inset: 0`) and dims its content while the
  * transfer is not done; only the disk takes the pointer.
  */
-export declare function TransferOverlay({ className, ...props }: TransferOverlayProps): import("react/jsx-runtime").JSX.Element;
+export declare function TransferOverlay({ className, ...props }: TransferDiskProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/internal/useFlipList.d.ts

@@ -0,0 +1,44 @@
+/** A box in viewport coordinates. */
+type LayoutBox = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+};
+/**
+ * Where an element sits in the layout with any animation transform taken back out — its glide and
+ * its growth (a tile growing into the cover cell is drawn smaller until it gets there). A decision
+ * that depends on where things stand (a drop position) is measured against this: reading the drawn
+ * box makes each answer depend on the glide the previous answer started.
+ */
+export declare function layoutRect(element: Element): LayoutBox;
+type FlipListOptions = {
+    /** The element the items move inside; positions are kept relative to it. */
+    container: HTMLElement | null;
+    /** The items that glide, in the container (read on every layout change). */
+    nodes: (container: HTMLElement) => Iterable<HTMLElement>;
+    /** The stable key of an item; an item without one does not glide. */
+    keyOf: (node: HTMLElement) => string | undefined;
+    /**
+     * Changes when the items may have moved. While `enabled`, every change glides; the first one
+     * after `enabled` turns on only takes the baseline (the frame a drag starts is no layout change).
+     */
+    layoutKey?: string;
+    enabled?: boolean;
+    /** A new value glides this layout change while not `enabled` (a keyboard move, a rollback). */
+    settle?: number;
+};
+/**
+ * Animates layout changes of a list's items from the position currently on screen (FLIP): the
+ * items of a sortable list and its drop gap, a list whose order changed, cards a refused move
+ * puts back. `capture()` reads where the items stand now; the next commit glides every item that
+ * moved from there — a host calls it right before it changes the order itself. A glide reversed
+ * midway starts from where the item is drawn, so offsets never compound. Reduced motion: nothing
+ * glides.
+ */
+export declare function useFlipList({ container, nodes, keyOf, layoutKey, enabled, settle, }: FlipListOptions): {
+    capture: () => void;
+};
+export {};

package/dist/internal/useNearView.d.ts

@@ -1,7 +1,8 @@
 import * as React from "react";
 /**
- * `true` once the element has come near the view of its scroller (half a viewport ahead) and from
- * then on: heavy media (a video's first frame) mounts only then. Without IntersectionObserver it is
- * `true` at once.
+ * `true` once the element has come near the view of its scroller (half a view ahead) and from
+ * then on: heavy media (a video's first frame) mounts only then. Inside a `ScrollContainer` the
+ * scroller is the observer's root, so a tile below the fold of a chat waits for the chat's scroll,
+ * not the page's; elsewhere the viewport. Without IntersectionObserver it is `true` at once.
  */
 export declare function useNearView(ref: React.RefObject<Element | null>): boolean;

package/dist/internal/usePendingChanges.d.ts

@@ -1,3 +1,8 @@
+/**
+ * The kit's async event: a handler that returns nothing is a sync event; one that returns a
+ * Promise keeps the change pending until it settles (resolve — done, reject — nothing changes).
+ */
+export type AsyncHandler<A extends unknown[] = [], R = void> = (...args: A) => void | Promise<R>;
 /** Whether an event handler answered with a promise: the change it made is pending until it settles. */
 export declare function isPromiseLike(value: unknown): value is PromiseLike<unknown>;
 /**
@@ -16,3 +21,21 @@ export declare function usePendingChanges<T, Change>(value: T, apply: (value: T,
         onReject?: (reason: unknown) => void;
     }) => void;
 };
+/**
+ * The keys whose async event is still running (a row being moved, an option being deleted).
+ * `track(key, outcome)` holds the key while a returned promise is pending and returns the outcome
+ * unchanged, so the caller can chain on it; a sync outcome holds nothing.
+ */
+export declare function usePendingKeys<K>(): {
+    pending: ReadonlySet<K>;
+    track: <T>(key: K, outcome: T) => T;
+};
+/**
+ * One async action that runs once at a time (a retry, a reload): `run` calls the latest handler and
+ * ignores calls while its promise is pending; `pending` is `true` until it settles. `run` is
+ * `undefined` without a handler, so the host can hide the action.
+ */
+export declare function usePendingAction<A extends unknown[]>(handler: AsyncHandler<A, unknown> | undefined): {
+    pending: boolean;
+    run: ((...args: A) => void) | undefined;
+};

package/dist/internal/useRangeSelection.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
-export type RangeSelectionOptions<K> = {
+type RangeSelectionOptions<K> = {
     /**
      * The items in their visual order: ranges and drags run over them. A function is read at the
      * moment of the press (items whose order lives in the DOM).
@@ -39,3 +39,4 @@ export declare function useRangeSelection<K>(options: RangeSelectionOptions<K>):
     handlers: RangeSelectionHandlers;
     dragging: boolean;
 };
+export {};