prime-ui-kit 0.15.0 → 0.16.0

package/dist/hooks/useLoadMore.d.ts

@@ -0,0 +1,28 @@
+import * as React from "react";
+import type { AsyncHandler } from "../internal/usePendingChanges";
+type LoadMoreOptions = {
+    /** More can be requested now: `hasMore`, a handler, nothing loading, no load error. */
+    enabled: boolean;
+    onLoadMore: AsyncHandler | undefined;
+    /** The list's own scroller: the observer root. */
+    scrollRef: React.RefObject<HTMLElement | null>;
+    /** Changes when the list changes (a batch arrived): a new round may ask again. */
+    round: unknown;
+    /**
+     * How far past the scroller's end the sentinel counts as reached (`IntersectionObserver`
+     * `rootMargin`). A list of rows asks 48 px early; a long table asks earlier.
+     */
+    rootMargin?: string;
+};
+/**
+ * Load more at the end of a list (Select, CommandMenu, a DataTable that scrolls forever): a
+ * sentinel after the last item asks once per round when it scrolls into the list's own scroller;
+ * `request` asks the same way from the keyboard (the highlight reached the last item). A disabled
+ * round (loading, an error) asks again once it is enabled. Without `IntersectionObserver` (jsdom,
+ * old engines) only `request` asks.
+ */
+export declare function useLoadMore<E extends HTMLElement = HTMLDivElement>({ enabled, onLoadMore, scrollRef, round, rootMargin, }: LoadMoreOptions): {
+    sentinelRef: React.RefObject<E | null>;
+    request: () => void;
+};
+export {};

package/dist/hooks/useMediaQuery.d.ts

@@ -1,7 +1,5 @@
-/** Viewport below the first breakpoint (foundation §9): overlays become bottom sheets. */
-export declare const COMPACT_QUERY = "(max-width: 639px)";
 /**
- * Whether a media query matches, kept in sync with the viewport. `false` on the server, while
+ * Whether a media query matches (the constants of `./breakpoints`), kept in sync with the viewport. `false` on the server, while
  * `enabled` is off, and where `matchMedia` is missing.
  */
 export declare function useMediaQuery(query: string, enabled?: boolean): boolean;

package/dist/hooks/useMergedRefs.d.ts

@@ -1,7 +1,13 @@
 import * as React from "react";
+type MaybeRef<T> = React.Ref<T> | undefined;
 /**
- * One stable callback ref that writes to every given ref (callback or object). The identity changes
- * only when one of the refs does, so the node is not detached and reattached on every render. The
- * single way to merge refs in components; the number of refs at a call site must not change.
+ * One stable callback ref that writes to every given ref (callback or object): an internal ref and
+ * the consumer's, up to three. The identity changes only when one of the refs does, so the node is
+ * not detached and reattached on every render. A single ref turns into a callback ref, which fits
+ * whichever tag a part renders. The single way to merge refs in components.
+ *
+ * A node that unmounts after its successor mounted (the leaving layer of a `RegionSwap`) does not
+ * clear an object ref that holds the successor.
  */
-export declare function useMergedRefs<T>(...refs: Array<React.Ref<T> | undefined>): React.RefCallback<T>;
+export declare function useMergedRefs<T>(a: MaybeRef<T>, b?: MaybeRef<T>, c?: MaybeRef<T>): React.RefCallback<T>;
+export {};

package/dist/hooks/useModalLayer.d.ts

@@ -1,24 +1,30 @@
 import * as React from "react";
 import { type DismissReason, type LayerEntry } from "../internal/overlay/layerStack";
-export type UseModalLayerOptions = {
+type UseModalLayerOptions = {
     open: boolean;
-    /** Escape (`escape`) or a click on the scrim (`scrim`); the owner applies its `closeOn*` props. */
+    /** Escape asks the layer to close (the owner's `closeOnEscape`). */
+    closeOnEscape: boolean;
+    /** A click on the scrim asks the layer to close (the owner's `closeOnOutsideClick`). */
+    closeOnOutsideClick: boolean;
+    /** A dismiss the options allow: Escape (`escape`) or a click on the scrim (`scrim`). */
     onDismiss: (reason: DismissReason) => void;
 };
-export type ModalLayer<T extends HTMLElement> = {
+type ModalLayer<T extends HTMLElement> = {
     /** Attach to the panel (`role="dialog"`): the trap container and the inside of the layer. */
     ref: React.RefObject<T | null>;
     /** Pass to `<LayerProvider value={layer}>` around the content: nested layers stack above. */
     layer: LayerEntry;
 };
 /**
- * The mechanics of a modal layer — Modal, Drawer, CommandMenu, the off-canvas Sidebar — in one
- * fixed order: the rest of the page becomes inert, focus moves in and Tab is trapped, document
- * scroll locks, and the layer joins the stack with scrim (`click`) dismissal. On close the page is
+ * The mechanics of a modal layer — Modal, Drawer, Sheet, ConfirmDialog, CommandMenu, MediaViewer,
+ * the off-canvas Sidebar — in one fixed order: the rest of the page becomes inert, focus moves in
+ * and Tab is trapped, document scroll locks, and the layer joins the stack with scrim (`click`)
+ * dismissal, filtered by `closeOnEscape` / `closeOnOutsideClick` before `onDismiss` hears of it. On close the page is
  * restored first, then focus returns to the opener, captured at the open transition — the control
  * that was pressed (Safari does not focus a clicked button), else the focused element; a layer a
  * pointer opened returns focus without the focus ring. Focus always returns, also after a scrim
  * click: the page behind was inert, so the opener is the only place to continue from (foundation
  * §8).
  */
-export declare function useModalLayer<T extends HTMLElement = HTMLElement>({ open, onDismiss, }: UseModalLayerOptions): ModalLayer<T>;
+export declare function useModalLayer<T extends HTMLElement = HTMLElement>({ open, closeOnEscape, closeOnOutsideClick, onDismiss, }: UseModalLayerOptions): ModalLayer<T>;
+export {};

package/dist/hooks/usePosition.d.ts

@@ -11,51 +11,13 @@ export type PositionAlign = "auto" | "start" | "center" | "end";
 export declare const DEFAULT_SIDE: PositionSide;
 export declare const DEFAULT_ALIGN: PositionAlign;
 /**
- * Computed length of a CSS custom property on `:root` in px (rem/px values).
- * Falls back when there is no DOM / stylesheet (SSR, jsdom).
+ * Computed length of a CSS custom property in px (rem/px values): on `element` when given (a value
+ * a component or its tier sets on it), else on `:root`. Falls back when there is no DOM /
+ * stylesheet (SSR, jsdom).
  */
-export declare function readCssLengthPx(name: string, fallbackPx: number): number;
+export declare function readCssLengthPx(name: string, fallbackPx: number, element?: Element | null): number;
 /** Minimum distance from a floating panel to the viewport edge: `--prime-space-2`. */
 export declare function getViewportPadPx(): number;
-export type ComputeFloatingOptions = {
-    side: PositionSide;
-    align: PositionAlign;
-    /** Gap between the anchor and the layer (px). */
-    offset: number;
-    /** Minimum distance from the viewport edge (px); 8 by default. */
-    viewportPad?: number;
-    /** Flip to the opposite side (and edge) when the layer does not fit. */
-    flip: boolean;
-    matchAnchorWidth: boolean;
-    /** Closest the arrow centre may come to a layer corner; computes `arrow` when set. */
-    arrowInset?: number;
-    /**
-     * The box the layer must stay in (viewport px), intersected with the viewport: a scroll region
-     * whose sticky parts the layer must not cover. Flipping, the cross-axis clamp and the size limits
-     * use it instead of the viewport.
-     */
-    boundary?: Pick<DOMRectReadOnly, "top" | "left" | "right" | "bottom">;
-};
-export type ComputedFloatPosition = {
-    top: number;
-    left: number;
-    /** The side after flipping. */
-    side: PositionSide;
-    minWidth?: number;
-    /** Room across: the viewport minus gutters (top / bottom) or the room on the side (left / right). */
-    maxWidth: number;
-    /** Room along the side the layer opened on (px). */
-    maxHeight: number;
-    /** Arrow centre along the edge facing the anchor (px from the layer's start). */
-    arrow?: number;
-};
-/**
- * Places a layer on `side` of the anchor: flips to the opposite side when it does not fit there
- * and does on the other (or has more room), aligns it along the cross axis (flipping the edge when
- * it overflows), keeps it inside the viewport and, with `arrowInset`, points an arrow at the
- * anchor's centre without leaving the layer's straight edge.
- */
-export declare function computeFloatingPosition(anchor: Pick<DOMRectReadOnly, "top" | "left" | "right" | "bottom" | "width" | "height">, contentW: number, contentH: number, vw: number, vh: number, opts: ComputeFloatingOptions): ComputedFloatPosition;
 export type PositionOptions = {
     side?: PositionSide;
     align?: PositionAlign;

package/dist/hooks/usePresence.d.ts

@@ -1,12 +1,8 @@
 import * as React from "react";
+import { type MotionDurationToken } from "../internal/motionTiming";
 export type PresenceState = "open" | "closed";
-export type MotionDurationToken = "xfast" | "fast" | "base" | "slow";
 export declare function prefersReducedMotion(): boolean;
-/** `--prime-motion-duration-<token>` in ms, read from the document (respects theme overrides). */
-export declare function motionDurationMs(token: MotionDurationToken): number;
-/** Timeout fallback for an exit animation of `token` length: the token duration plus slack. */
-export declare function exitTimeoutMs(token: MotionDurationToken): number;
-export type UsePresenceOptions = {
+type UsePresenceOptions = {
     /** Longest exit duration of the layer — the timeout fallback when no `animationend` arrives. */
     exitDuration?: MotionDurationToken;
 };
@@ -25,6 +21,7 @@ export type Presence = {
  * Keeps an overlay mounted until its exit animation ends. Open → mounted at once with
  * `state="open"`; close → `state="closed"` stays mounted until `animationend` / `transitionend`
  * on the layer element, or the token-duration timeout; unmounts immediately under
- * `prefers-reduced-motion: reduce`. Shared by every floating layer (foundation §7 "Overlay contract").
+ * `prefers-reduced-motion: reduce`. Shared by every floating layer (foundation §8 "Overlay contract").
  */
 export declare function usePresence(open: boolean, options?: UsePresenceOptions): Presence;
+export {};

package/dist/hooks/useScrollRegion.d.ts

@@ -0,0 +1,28 @@
+import * as React from "react";
+/**
+ * What a ScrollContainer lets its content ask for (`useScrollRegion`): a chat list asks to go to
+ * the end after its own message, to bring a message into view, and follows whether the reader is
+ * at the end. The region scrolls only itself.
+ */
+export type ScrollRegion = {
+    /** The scrolling element: the root of an IntersectionObserver or a measure inside it. */
+    element: () => HTMLElement | null;
+    /** The reader is at the end (`anchor="end"`, within 4 px). */
+    atEnd: () => boolean;
+    /** Follows `atEnd`; returns the unsubscribe. */
+    subscribe: (listener: () => void) => () => void;
+    /** Scrolls to the end; `smooth` glides there (instant under reduced motion). */
+    scrollToEnd: (behavior?: ScrollBehavior) => void;
+    /** Scrolls the region (only) so `element` stands in its middle. */
+    scrollToElement: (element: Element, behavior?: ScrollBehavior) => void;
+    /**
+     * Content is about to change size in place on the motion clock `clock` (a duration custom
+     * property, read on the region: `--prime-message-morph-duration`): until that motion has played,
+     * what the reader sees stays still — even at the end of `anchor="end"`, so the change grows past
+     * the edge instead of pushing everything up. Call it right before the change.
+     */
+    hold: (clock: `--${string}`) => void;
+};
+export declare const ScrollRegionContext: React.Context<ScrollRegion | null>;
+/** The ScrollContainer around this component, or `null` outside one. */
+export declare function useScrollRegion(): ScrollRegion | null;

package/dist/hooks/useStableValue.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The value, kept as the same reference while it stays equal to the last one: an inline object or
+ * array of the owner (new on every render) becomes a dependency that changes only with its content.
+ * `isEqual` defaults to `shallowEqual`; pass one that compares what matters (rows by key).
+ */
+export declare function useStableValue<T>(value: T, isEqual?: (previous: T, next: T) => boolean): T;

package/dist/hooks/useSwipeDismiss.d.ts

@@ -1,26 +1,47 @@
 import * as React from "react";
-export type UseSwipeDismissOptions = {
+/** What holds a panel that could otherwise swipe away (a dialog `Guard`). */
+type SwipeGuard = "busy" | "dirty" | null;
+type UseSwipeDismissOptions = {
+    /**
+     * The gesture exists: the panel draws a grab handle and a drag can dismiss it. Off where the
+     * panel takes no swipe at all (a wide viewport, `closeOnOutsideClick={false}`).
+     */
     enabled: boolean;
+    /**
+     * `busy` — no drag starts (the panel carries `data-swipe-disabled`: no grab cursor, the browser
+     * pans again); `dirty` — a drag past the threshold glides back and asks through `onDismiss` (the
+     * host opens its «discard changes?» confirm) instead of leaving.
+     */
+    guard?: SwipeGuard;
+    /** A drag released past the threshold, or a flick: the host's dismiss request. */
     onDismiss: () => void;
-    /** Selector of the zones a drag starts from: the grab handle, the header. */
-    handle: string;
     /**
-     * How far down the panel is, 0 (at rest) … 1 (off the bottom edge), on every move and on release
-     * (0 back, 1 out) — for parts that follow the drag, such as the scrim's opacity.
+     * The scrim under the panel: it follows the drag through `--swipe-progress` (0 at rest … 1 off
+     * the edge) and mirrors `data-swiping` / `data-swipe-dismissed`, so its CSS fades with the panel.
      */
-    onProgress?: (progress: number) => void;
+    scrimRef?: React.RefObject<HTMLElement | null>;
 };
-/** The custom property the panel CSS maps onto its own axis (`transform`). */
-export declare const SWIPE_OFFSET_VAR = "--swipe-offset";
+export type SwipeDismiss = {
+    /** The gesture exists: render the grab handle (`SheetHandle`). */
+    enabled: boolean;
+    /** Attach to the panel. */
+    onPointerDown: (event: React.PointerEvent<HTMLElement>) => void;
+    /** Spread on the panel: `data-swipe-disabled` while the guard is busy. */
+    panelProps: {
+        "data-swipe-disabled"?: "";
+    };
+};
+/** The attribute of the grab handle: a drag starts on it, or on the header right after it. */
+export declare const SWIPE_HANDLE_ATTRIBUTE = "data-swipe-handle";
 /**
  * Swipe-down-to-close for a panel at the bottom edge (Sheet, Modal and floating layers as phone
- * sheets). Attach `onPointerDown` to the panel: a drag down from `handle` moves the panel with the
- * pointer through `--swipe-offset` and `data-swiping`, which its CSS maps onto `transform`. On
- * release the panel closes past 30% of its height or on a flick — gliding the rest of the way out
- * from the release point (`data-swipe-dismissed`) — otherwise it glides back; `onProgress` follows
- * along. A sideways drag is left to scrolling. The gesture is an extra way out: the panel keeps
- * Escape and the scrim (WCAG 2.5.7).
+ * sheets). Attach `onPointerDown` to the panel: a drag down from the grab handle (or the header
+ * right under it) moves the panel with the pointer through `--swipe-offset` and `data-swiping`,
+ * which its CSS maps onto `transform`. On release the panel closes past 30% of its height or on a
+ * flick — gliding the rest of the way out from the release point (`data-swipe-dismissed`) —
+ * otherwise it glides back; the scrim follows along. A `dirty` panel glides back and asks instead.
+ * A sideways drag is left to scrolling. The gesture is an extra way out: the panel keeps Escape
+ * and the scrim (WCAG 2.5.7).
  */
-export declare function useSwipeDismiss({ enabled, onDismiss, handle, onProgress, }: UseSwipeDismissOptions): {
-    onPointerDown: (event: React.PointerEvent<HTMLElement>) => void;
-};
+export declare function useSwipeDismiss({ enabled, guard, onDismiss, scrimRef, }: UseSwipeDismissOptions): SwipeDismiss;
+export {};

package/dist/hooks/useVirtualRows.d.ts

@@ -1,11 +1,11 @@
 import * as React from "react";
 /** A row to render: its index, top offset and height in px. */
-export type VirtualRow = {
+type VirtualRow = {
     index: number;
     start: number;
     size: number;
 };
-export type UseVirtualRowsOptions = {
+type UseVirtualRowsOptions = {
     /** Number of rows. */
     count: number;
     /** The scroll container the rows scroll in (vertically). */
@@ -41,7 +41,7 @@ export type UseVirtualRowsOptions = {
      */
     sticky?: readonly number[];
 };
-export type VirtualRows = {
+type VirtualRows = {
     /** Rows to render, by index: the visible range, the overscan and the pinned rows. */
     rows: VirtualRow[];
     /** Height of all rows, px: the size of the scrolled content. */
@@ -50,6 +50,11 @@ export type VirtualRows = {
     startOf: (index: number) => number;
     /** Callback ref for the element of row `index`: measures it and follows its size. */
     measure: (index: number) => (node: HTMLElement | null) => void;
+    /**
+     * Every rendered row has its own measured size: the offsets of the window are exact, so a host
+     * may scroll to a row by its offset (a chat opening at its end).
+     */
+    measured: boolean;
 };
 /**
  * Vertical row virtualization inside a component's own scroller: renders the rows that intersect
@@ -72,3 +77,4 @@ export declare function rowGaps({ rows, totalSize }: Pick<VirtualRows, "rows" |
     })[];
     end: number;
 };
+export {};

package/dist/icon-set.js

@@ -410,7 +410,7 @@ import {
   Youtube,
   Zap,
   ZapOff
-} from "./chunks/chunk-6TI4DSM5.js";
+} from "./chunks/chunk-A7OQWH6R.js";
 import {
   Activity,
   ArrowDown,
@@ -527,7 +527,7 @@ import {
   X,
   ZoomIn,
   ZoomOut
-} from "./chunks/chunk-Q3BFRQHZ.js";
+} from "./chunks/chunk-U3Q2I3MY.js";
 export {
   AArrowDown as AArrowDownIcon,
   AArrowUp as AArrowUpIcon,

package/dist/icons/Icon.d.ts

@@ -18,6 +18,6 @@ export declare function Icon({ name, ...rest }: IconProps): import("react/jsx-ru
  * whole drawing. Call it once at module level.
  */
 export declare function createIcon(glyph: SvgGlyph): {
-    ({ className, size, tone, color, label, animated, strokeWidth, ...rest }: DomainIconProps): import("react/jsx-runtime").JSX.Element;
+    ({ className, size, tone, color, label, animated, drawn, strokeWidth, ...rest }: DomainIconProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

package/dist/icons/glyph.d.ts

@@ -28,6 +28,12 @@ export type DomainIconProps = Omit<React.ComponentPropsWithoutRef<"svg">, "color
      * it still.
      */
     animated?: boolean;
+    /**
+     * A mark that follows a state instead of playing a gesture: `true` draws the glyph's stroke in
+     * (its `draw` parts), `false` draws it out, both ways eased — a check that appears when a row is
+     * ticked. Undefined: the usual one-shot gesture. A drawn icon plays no hover gesture.
+     */
+    drawn?: boolean;
     ref?: React.Ref<SVGSVGElement>;
 };
 /** A kit glyph component: an animated icon drawn on the 24-unit grid. */
@@ -36,17 +42,18 @@ export type Glyph = React.ComponentType<DomainIconProps> & {
     source: string;
 };
 /** Shared class names and attributes of every kit icon root. */
-export declare function useIconRoot({ className, size, tone, color, label, animated, motion, }: Pick<DomainIconProps, "className" | "size" | "tone" | "color" | "label" | "animated"> & {
+export declare function useIconRoot({ className, size, tone, color, label, animated, drawn, motion, }: Pick<DomainIconProps, "className" | "size" | "tone" | "color" | "label" | "animated" | "drawn"> & {
     /** `glyph` — parts carry their own `data-motion`; `generic` — the whole drawing pops. */
     motion: "glyph" | "generic";
 }): {
     readonly className: string;
-    readonly "data-tone": "accent" | "success" | "warning" | "danger" | "secondary" | "muted" | undefined;
+    readonly "data-tone": "accent" | "success" | "warning" | "danger" | "muted" | "secondary" | undefined;
     readonly "data-color": "gray" | "blue" | "green" | "orange" | "red" | "yellow" | "purple" | "sky" | "pink" | "teal" | undefined;
     readonly role: "img" | undefined;
     readonly "aria-label": string | undefined;
     readonly "aria-hidden": true | undefined;
     readonly "data-icon-motion": "glyph" | "generic" | undefined;
+    readonly "data-drawn": string | undefined;
 };
 /**
  * Defines a kit glyph from its SVG body (paths copied from Lucide, parts annotated with