prime-ui-kit 0.15.0 → 0.17.0

package/dist/components/tooltip/Tooltip.d.ts

@@ -1,6 +1,7 @@
 import * as React from "react";
 import { type PositionAlign, type PositionSide } from "../../hooks/usePosition";
-import type { ControlSize } from "../../internal/states";
+import type { SlotPartProps } from "../../internal/slot";
+import { type ControlSize } from "../../internal/states";
 export type TooltipSide = PositionSide;
 /**
  * The anchored-layer vocabulary. A tooltip centres on its trigger by default (foundation §8);
@@ -8,10 +9,17 @@ export type TooltipSide = PositionSide;
  */
 export type TooltipAlign = PositionAlign;
 export type TooltipProviderProps = {
-    /** Show delay in ms for every Tooltip.Root inside. */
+    /**
+     * Show delay in ms for every Tooltip.Root inside.
+     */
     delayDuration?: number;
-    /** Window in ms after a tooltip closes during which the next one opens instantly. */
+    /**
+     * Window in ms after a tooltip closes during which the next one opens instantly.
+     */
     skipDelayDuration?: number;
+    /**
+     * Subtree.
+     */
     children: React.ReactNode;
 };
 declare function TooltipProvider({ delayDuration, skipDelayDuration, children, }: TooltipProviderProps): import("react/jsx-runtime").JSX.Element;
@@ -19,39 +27,61 @@ declare namespace TooltipProvider {
     var displayName: string;
 }
 export type TooltipRootProps = {
+    /**
+     * Tooltip.Trigger and Tooltip.Content.
+     */
     children: React.ReactNode;
+    /**
+     * Controlled visibility; together with `onOpenChange`.
+     */
     open?: boolean;
+    /**
+     * Initial visibility, uncontrolled.
+     */
     defaultOpen?: boolean;
+    /**
+     * Called on hover, focus, blur, pointer-leave, press, Escape, and when a neighbour in the group opens.
+     */
     onOpenChange?: (open: boolean) => void;
-    /** Show delay in ms for this tooltip; defaults to the Provider's (400). */
+    /**
+     * Show delay in ms for this tooltip (the Provider's when omitted); hiding never waits for it.
+     */
     delayDuration?: number;
 };
 declare function TooltipRoot({ children, open, defaultOpen, onOpenChange, delayDuration: delayProp, }: TooltipRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace TooltipRoot {
     var displayName: string;
 }
-export type TooltipTriggerProps = {
-    /**
-     * One element. A focusable one (Button, link) is the trigger as is; a disabled control is wrapped
-     * in a focusable host that takes hover and Tab for it; a non-interactive one (Badge, Avatar,
-     * ProgressCircle, an `Icon` with `label`) becomes a tab stop.
-     */
-    children: React.ReactElement;
-    ref?: React.Ref<HTMLElement>;
-} & Omit<React.HTMLAttributes<HTMLElement>, "children">;
+export type TooltipTriggerProps = SlotPartProps;
 /**
- * The tooltip id joins the child's own `aria-describedby`; the child's handlers run first. Other
- * props (handlers, ARIA, `ref`) are forwarded to the child.
+ * Wraps one element. A focusable one (Button, link) is the trigger as is; a disabled control — by
+ * its own `disabled` or a disabled `Fieldset` around it — is wrapped in a focusable host that takes
+ * hover and Tab for it (around a button the host is the button: `role="button"`, `aria-disabled`,
+ * named by the control); a non-interactive
+ * one (Badge, Avatar, ProgressCircle, an `Icon` with `label`) becomes a tab stop. The tooltip id
+ * joins the child's own `aria-describedby`; the child's handlers run first. Props a wrapping trigger
+ * adds pass on to the child.
  */
-declare function TooltipTrigger({ children, ...forwarded }: TooltipTriggerProps): import("react/jsx-runtime").JSX.Element;
+declare function TooltipTrigger(props: TooltipTriggerProps): import("react/jsx-runtime").JSX.Element;
 declare namespace TooltipTrigger {
     var displayName: string;
 }
 export type TooltipContentProps = Omit<React.HTMLAttributes<HTMLDivElement>, "id" | "role" | "onPointerEnter" | "onPointerLeave"> & {
+    /**
+     * Hint text, optionally with a Kbd.
+     */
     children: React.ReactNode;
-    /** Text and padding tier; also the size context of controls inside (a Kbd). */
+    /**
+     * Text and padding tier; also the size context of controls inside (a Kbd).
+     */
     size?: ControlSize;
+    /**
+     * Preferred side; flips to the opposite one when it does not fit, then shifts inside the viewport.
+     */
     side?: TooltipSide;
+    /**
+     * Alignment along the trigger: centred by default; `auto` lines the chip up with the trigger edge that has more room beyond it; `start` or `end` fix the edge. The arrow keeps pointing at the trigger.
+     */
     align?: TooltipAlign;
     ref?: React.Ref<HTMLDivElement>;
 };

package/dist/components/typography/Typography.d.ts

@@ -6,21 +6,47 @@ export type TypographyWeight = "regular" | "medium" | "semibold";
 export type TypographyTracking = "normal" | "tight" | "tighter" | "wide";
 export type TypographyAs = "p" | "span" | "div" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "small" | "blockquote" | "article" | "section" | "header" | "footer" | "aside" | "nav" | "main";
 export type TypographyProps = {
+    /**
+     * The element, by the page outline; the role keeps the look.
+     */
     as?: TypographyAs;
-    /** Text role (`--prime-text-<role>-*`). */
+    /**
+     * Text role: size, line height, weight and tracking.
+     */
     variant: TypographyRole;
-    /** Overrides the role's weight. Omit to use the role's own weight. */
+    /**
+     * Overrides the role's weight.
+     */
     weight?: TypographyWeight;
-    /** Overrides the role's tracking. Omit to use the role's own tracking. */
+    /**
+     * Overrides the role's tracking with a `--prime-font-tracking-*` step.
+     */
     tracking?: TypographyTracking;
-    /** Clamp to one line with an ellipsis (set `title` when the full text matters). */
+    /**
+     * `tabular` — every digit as wide as the others: amounts, times and counts line up in a column and keep their width.
+     */
+    numeric?: "proportional" | "tabular";
+    /**
+     * One line with an ellipsis; set `title` when the full text matters.
+     */
     truncate?: boolean;
+    /**
+     * Italic, for quotes and titles of works.
+     */
     italic?: boolean;
-    /** Text color. Default `default` (primary text). */
+    /**
+     * Text color by meaning; `default` is primary text.
+     */
     tone?: TextTone;
+    /**
+     * The text.
+     */
     children?: React.ReactNode;
+    /**
+     * Class on the element.
+     */
     className?: string;
     ref?: React.Ref<HTMLElement>;
 } & React.HTMLAttributes<HTMLElement>;
 /** Any text element styled by one text role; state goes to `data-*`. */
-export declare function Typography({ as: Tag, variant, weight, tracking, truncate, italic, tone, className, children, ref, ...rest }: TypographyProps): import("react/jsx-runtime").JSX.Element;
+export declare function Typography({ as: Tag, variant, weight, tracking, numeric, truncate, italic, tone, className, children, ref, ...rest }: TypographyProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/video-note/VideoNote.d.ts

@@ -7,14 +7,20 @@ export type VideoNoteLabels = MediaPlayerLabels & {
     /** The disk's description before playback: `{duration}`. */
     duration: string;
 };
+export declare const VIDEO_NOTE_LABELS: VideoNoteLabels;
 /**
  * The shared player props (`MediaPlayerProps`, the same as VoicePlayer's) and what only a video
  * has: a poster. No waveform (it shows a face, not levels) and no rate (a face is watched at its
  * own pace; a voice recording is the one listened to faster).
  */
 export type VideoNoteProps = MediaPlayerRootProps & MediaPlayerProps & {
-    /** A still to show before the video draws its first frame. */
+    /**
+     * A still shown before the first frame; without it the first frame is drawn. Video only.
+     */
     poster?: string;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<VideoNoteLabels>;
 };
 /**

package/dist/{internal → components/visually-hidden}/VisuallyHidden.d.ts

@@ -1,8 +1,7 @@
 import type * as React from "react";
-export type VisuallyHiddenProps = React.HTMLAttributes<HTMLSpanElement> & {
+export type VisuallyHiddenProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "role" | "aria-live" | "aria-atomic" | "aria-relevant"> & {
     /**
-     * An announcement region: `polite` — `role="status"`, read after what is being said; `assertive`
-     * — `role="alert"`, read at once. Both are atomic: the whole text is read on every change.
+     * An announcement region, read as a whole on every change: `polite` — `role="status"`, `assertive` — `role="alert"` (urgent only).
      */
     live?: "polite" | "assertive";
     ref?: React.Ref<HTMLSpanElement>;
@@ -11,8 +10,9 @@ export type VisuallyHiddenProps = React.HTMLAttributes<HTMLSpanElement> & {
 export declare const visuallyHiddenClass: string;
 /**
  * Text for screen readers only: spoken counters, live-region messages, names of icon-only parts.
- * Public as `VisuallyHidden` (docs in `src/components/visually-hidden/`); inside the kit it replaces
- * the per-component `.srOnly` / `.visuallyHidden` CSS copies.
+ * The one sr-only recipe and the one announcement region of the kit: a live region is
+ * `live="polite"` / `live="assertive"`, never a hand-set `role` / `aria-live` (the props type has
+ * none, and the region attributes win over the rest).
  */
 export declare function VisuallyHidden({ className, live, ...rest }: VisuallyHiddenProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace VisuallyHidden {

package/dist/components/voice-player/VoicePlayer.d.ts

@@ -9,19 +9,32 @@ export type VoicePlayerLabels = MediaPlayerLabels & {
     /** Name of the rate chip: `{rate}` as shown on it. */
     rate: string;
 };
+export declare const VOICE_PLAYER_LABELS: VoicePlayerLabels;
 /**
  * The shared player props (`MediaPlayerProps`, the same as VideoNote's) and what only a voice
  * message has: its waveform (the seek is drawn on it) and the speed chip (a recording of speech is
  * listened to faster; a round video is watched as a face at its own pace — VideoNote has no rate).
  */
 export type VoicePlayerProps = MediaPlayerRootProps & MediaPlayerProps & {
-    /** Levels 0…1 from data, resampled to the bars that fit the width. Without it: a calm flat row. */
+    /**
+     * Levels 0…1 from data, resampled to the bars that fit the width. Without it: a calm flat row. Voice only: a circle shows a face, not levels.
+     */
     waveform?: readonly number[];
-    /** Playback speed (controlled). */
+    /**
+     * Playback speed (controlled). Voice only: speech is listened to faster; a face is watched at its own pace.
+     */
     rate?: VoicePlayerRate;
-    /** Initial playback speed (uncontrolled). Default `1`. */
+    /**
+     * Initial playback speed (uncontrolled).
+     */
     defaultRate?: VoicePlayerRate;
+    /**
+     * The rate chip was pressed: 1× → 1.5× → 2× → 1×.
+     */
     onRateChange?: (rate: VoicePlayerRate) => void;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<VoicePlayerLabels>;
 };
 /**

package/dist/hooks/breakpoints.d.ts

@@ -0,0 +1,10 @@
+/** Viewport below the first breakpoint (640): overlays become bottom sheets. */
+export declare const COMPACT_QUERY = "(max-width: 639px)";
+/** Viewport below the tablet breakpoint (768): the side navigation leaves the page, off-canvas. */
+export declare const OFF_CANVAS_QUERY = "(max-width: 767px)";
+/** A touch screen: no hover and a coarse pointer (long press instead of hover, larger targets). */
+export declare const TOUCH_QUERY = "(hover: none) and (pointer: coarse)";
+/** A pointer that can hover: hover-only affordances (a reaction bar on a long hover). */
+export declare const HOVER_QUERY = "(hover: hover)";
+/** The person asked for less motion. */
+export declare const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";

package/dist/hooks/floatingPosition.d.ts

@@ -0,0 +1,42 @@
+import type { PositionAlign, PositionSide } from "./usePosition";
+type FloatingOptions = {
+    side: PositionSide;
+    align: PositionAlign;
+    /** Gap between the anchor and the layer (px). */
+    offset: number;
+    /** Minimum distance from the viewport edge (px); `--prime-space-2` 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">;
+};
+type FloatingPosition = {
+    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;
+};
+/**
+ * The geometry of `usePosition`, without the DOM. 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: FloatingOptions): FloatingPosition;
+export {};

package/dist/hooks/useDraft.d.ts

@@ -0,0 +1,12 @@
+import * as React from "react";
+/**
+ * The draft text of an input bound to a value: it follows `source` (the value as text) while the
+ * input is not focused, and is the person's own text while they edit. The host commits the draft
+ * on blur / Enter and puts the committed value back with `setDraft` (an unreadable draft reverts
+ * to `source`).
+ */
+export declare function useDraft<E extends HTMLElement = HTMLInputElement>(source: string): {
+    inputRef: React.RefObject<E | null>;
+    draft: string;
+    setDraft: React.Dispatch<React.SetStateAction<string>>;
+};

package/dist/hooks/useEdgeOverflow.d.ts

@@ -1,11 +1,11 @@
 import * as React from "react";
 /** The axes a region scrolls along: only those are measured. */
-export type EdgeOverflowAxis = "vertical" | "horizontal" | "both";
+type EdgeOverflowAxis = "vertical" | "horizontal" | "both";
 /**
  * Edges of a scroll region that hide content: `start` / `end` along the inline axis (logical,
  * RTL-aware), `top` / `bottom` along the block axis.
  */
-export type EdgeOverflow = {
+type EdgeOverflow = {
     start: boolean;
     end: boolean;
     top: boolean;
@@ -19,7 +19,9 @@ export type EdgeOverflow = {
  * With `depth` it also writes how far the hidden content reaches on each side to the region itself
  * (`--edge-top` / `--edge-bottom` / `--edge-start` / `--edge-end`, px), so a fade is as deep as
  * that distance at most: it grows as the region scrolls away from an edge and melts as it comes
- * back. A distance is written capped at `--prime-space-8` (the deepest fade) and only when it
+ * back. A distance is written capped at `--scroll-fade-depth` (the deepest fade, read on the
+ * region) and only when it
  * changes, so away from the edges a scroll frame writes nothing and restyles nothing.
  */
 export declare function useEdgeOverflow(ref: React.RefObject<HTMLElement | null>, axis: EdgeOverflowAxis | null, depth?: boolean): EdgeOverflow;
+export {};

package/dist/hooks/useElementSize.d.ts

@@ -0,0 +1,31 @@
+import * as React from "react";
+/** The border box of an element in px, rounded. */
+type ElementSize = {
+    width: number;
+    height: number;
+};
+type ObserveOptions = {
+    /** Observe nothing while `false` (the element is not needed yet). Default `true`. */
+    enabled?: boolean;
+};
+type ResizeOptions = ObserveOptions & {
+    /**
+     * Also observe the element's children, including ones added later: a row whose own box keeps
+     * its size while an item in it grows (a label, a count, fonts loading).
+     */
+    children?: boolean;
+};
+/**
+ * The size of the element `ref` holds, as state: measured before paint and again whenever it
+ * changes (ResizeObserver), `null` while there is no element. A host that only re-lays out its own
+ * DOM (an indicator, a fit check) takes `useResizeEffect` instead and never re-renders.
+ */
+export declare function useElementSize<E extends Element>(ref: React.RefObject<E | null>, { enabled }?: ObserveOptions): ElementSize | null;
+/**
+ * Calls `onResize` whenever the element `ref` holds changes size (and, with `children`, any of its
+ * children, also ones added later). The callback runs outside React: a host writes its DOM there
+ * (places an indicator, re-fits a row) and re-renders only if it decides to. The first layout is
+ * the host's own; this follows the changes after it.
+ */
+export declare function useResizeEffect<E extends Element>(ref: React.RefObject<E | null>, onResize: () => void, { enabled, children }?: ResizeOptions): void;
+export {};

package/dist/hooks/useEnterConfirm.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
-export type UseEnterConfirmOptions = {
+type UseEnterConfirmOptions = {
     enabled: boolean;
     containerRef: React.RefObject<HTMLElement | null>;
     /** Replaces the default (a `click()` on `confirmRef`). */
@@ -13,3 +13,4 @@ export type UseEnterConfirmOptions = {
  * the header (close button) is left alone.
  */
 export declare function useEnterConfirm({ enabled, containerRef, onEnterConfirm, confirmRef, }: UseEnterConfirmOptions): void;
+export {};

package/dist/hooks/useImageStatus.d.ts

@@ -4,16 +4,23 @@ export type ImageStatus = "idle" | "loading" | "loaded" | "error";
 type MediaHandlers<E extends Element> = {
     onLoad?: React.ReactEventHandler<E>;
     onError?: React.ReactEventHandler<E>;
+    /**
+     * An `<img>` counts as loaded only once it is decoded (`HTMLImageElement.decode()`), so it never
+     * paints half-ready or blank for a frame; a picture already in the cache counts at once (spread
+     * `ref` on the image). `onLoad` follows a load event once decoded. Default `false`.
+     */
+    decode?: boolean;
 };
 /**
- * Media side of an image-with-fallback component (Avatar, Thumbnail): tracks the `<img>` (or a
- * `<video>`'s first frame) and reports it to the root through `report`, so the root's Fallback
- * shows while loading and after an error. Key the element by `src`: a new source remounts it and
- * starts again at `loading`. Unmounting the media reports `idle`.
+ * Media side of an image-with-fallback component (Avatar, Thumbnail, a MediaViewer page): tracks
+ * the `<img>` (or a `<video>`'s first frame) and reports it to the root through `report`, so the
+ * root's Fallback shows while loading and after an error. Key the element by `src`: a new source
+ * remounts it and starts again at `loading`. Unmounting the media reports `idle`.
  */
-export declare function useImageStatus<E extends Element = HTMLImageElement>(report: (status: ImageStatus) => void, { onLoad, onError }?: MediaHandlers<E>): {
+export declare function useImageStatus<E extends Element = HTMLImageElement>(report: (status: ImageStatus) => void, { onLoad, onError, decode }?: MediaHandlers<E>): {
     status: "loading" | "error" | "loaded";
     onLoad: (event: React.SyntheticEvent<E>) => void;
     onError: (event: React.SyntheticEvent<E>) => void;
+    ref: (element: E | null) => void;
 };
 export {};

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;