prime-ui-kit 0.9.0 → 0.9.1

package/dist/components/textarea/Textarea.d.ts

@@ -7,13 +7,14 @@ export type TextareaLabels = {
     counter: string;
 };
 export type TextareaRootProps = Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "size" | "children"> & {
+    /** Tier. Default: the tier of the surrounding control (a form, a panel), else `m`. */
     size?: ControlSize;
     /** Invalid state: danger ring and `aria-invalid`. A non-empty `error` implies it. */
     invalid?: boolean;
     /**
      * Draws the focus ring on the field box (default). `false` hides only the visual ring — focus,
      * keyboard and ARIA are unchanged, the error ring still shows. Turn it off only where focus is
-     * otherwise obvious (a single search field with a caret, e.g. a command palette); WCAG 2.4.7.
+     * otherwise obvious (a single composer field with a caret); WCAG 2.4.7.
      */
     focusRing?: boolean;
     label?: React.ReactNode;
@@ -31,45 +32,29 @@ export type TextareaRootProps = Omit<React.TextareaHTMLAttributes<HTMLTextAreaEl
     /** Called with the new string value; native `onChange` still fires. */
     onValueChange?: (value: string) => void;
     labels?: Partial<TextareaLabels>;
+    /** The native `<textarea>`. */
+    ref?: React.Ref<HTMLTextAreaElement>;
 };
-export type TextareaCounterProps = {
+/**
+ * A multi-line field. `className` goes to the field frame, `id`, `ref` and the native attributes
+ * to the `<textarea>` (it has no `Field` part).
+ */
+declare function TextareaRoot({ id, className, size: sizeProp, invalid, focusRing, label, required, optional, hint, error, counter, reserveSupportRow, autoResize, disabled, readOnly, value, onInput, onChange, onValueChange, labels: labelsProp, "aria-describedby": ariaDescribedBy, ref, ...rest }: TextareaRootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace TextareaRoot {
+    var displayName: string;
+}
+export type TextareaCounterProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
     current: number;
     max: number;
-    className?: string;
+    ref?: React.Ref<HTMLSpanElement>;
 };
 /** Character counter for the `counter` slot; turns danger when `current > max`. */
-declare function TextareaCounter({ current, max, className }: TextareaCounterProps): import("react/jsx-runtime").JSX.Element;
+declare function TextareaCounter(props: TextareaCounterProps): import("react/jsx-runtime").JSX.Element;
 declare namespace TextareaCounter {
     var displayName: string;
 }
 export declare const Textarea: {
-    Root: React.ForwardRefExoticComponent<Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "children" | "size"> & {
-        size?: ControlSize;
-        /** Invalid state: danger ring and `aria-invalid`. A non-empty `error` implies it. */
-        invalid?: boolean;
-        /**
-         * Draws the focus ring on the field box (default). `false` hides only the visual ring — focus,
-         * keyboard and ARIA are unchanged, the error ring still shows. Turn it off only where focus is
-         * otherwise obvious (a single search field with a caret, e.g. a command palette); WCAG 2.4.7.
-         */
-        focusRing?: boolean;
-        label?: React.ReactNode;
-        /** Shows the muted optional marker after the label text (`labels.optional`). */
-        optional?: boolean;
-        hint?: React.ReactNode;
-        /** Error message; replaces the hint in the same slot and implies `invalid`. */
-        error?: React.ReactNode;
-        /** Right-aligned slot of the support row, e.g. `<Textarea.Counter current={n} max={500} />`. */
-        counter?: React.ReactNode;
-        /** Always render the support row so an appearing error does not shift the layout. */
-        reserveSupportRow?: boolean;
-        /** Height follows the content. `false` → fixed height with native vertical resize. */
-        autoResize?: boolean;
-        /** Called with the new string value; native `onChange` still fires. */
-        onValueChange?: (value: string) => void;
-        labels?: Partial<TextareaLabels>;
-    } & React.RefAttributes<HTMLTextAreaElement>>;
+    Root: typeof TextareaRoot;
     Counter: typeof TextareaCounter;
 };
 export {};
-//# sourceMappingURL=Textarea.d.ts.map

package/dist/components/thumbnail/Thumbnail.d.ts

@@ -0,0 +1,41 @@
+import type * as React from "react";
+import { type ImageSlotFallbackProps, type ImageSlotImageProps } from "@/internal/imageSlot";
+import type { ControlSize, PaletteColor } from "@/internal/states";
+/** Width ÷ height. `1:1` square · `4:3` / `3:2` photo · `16:9` wide cover · `3:4` portrait. */
+export type ThumbnailRatio = "1:1" | "4:3" | "3:2" | "16:9" | "3:4";
+export type ThumbnailRootProps = React.HTMLAttributes<HTMLDivElement> & {
+    /** Height tier: 24 · 32 · 40 · 48 · 64; width follows `ratio`. Default `m`. */
+    size?: ControlSize;
+    /** Aspect ratio, width ÷ height. Default `1:1`. */
+    ratio?: ThumbnailRatio;
+    /** Fallback fill and icon color (`--prime-color-palette-<hue>-*`). Default `gray`. */
+    color?: PaletteColor;
+    /** Fallback fill: `soft` tint with a hue icon, or `solid` hue with a contrasting icon. */
+    variant?: "soft" | "solid";
+    /** Fills the container width (cards, galleries); the height follows `ratio`. */
+    fullWidth?: boolean;
+    /** A faint inner ring around the frame, for photos with a white background on a light surface. */
+    ring?: boolean;
+    ref?: React.Ref<HTMLDivElement>;
+};
+/** A preview of an object (product, vehicle, file, cover) at a fixed aspect ratio. People use Avatar. */
+declare function ThumbnailRoot({ size, ratio, color, variant, fullWidth, ring, className, children, ...rest }: ThumbnailRootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace ThumbnailRoot {
+    var displayName: string;
+}
+export type ThumbnailImageProps = ImageSlotImageProps & {
+    /** `cover` (default) crops to fill; `contain` shows the whole image on the fallback fill. */
+    fit?: "cover" | "contain";
+};
+/** The picture; while it loads or after an error the Fallback shows through. */
+declare function ThumbnailImage({ fit, ...rest }: ThumbnailImageProps): import("react/jsx-runtime").JSX.Element;
+declare namespace ThumbnailImage {
+    var displayName: string;
+}
+export type ThumbnailFallbackProps = ImageSlotFallbackProps;
+export declare const Thumbnail: {
+    Root: typeof ThumbnailRoot;
+    Image: typeof ThumbnailImage;
+    Fallback: (props: ImageSlotFallbackProps) => React.ReactElement;
+};
+export {};

package/dist/components/timeline/Timeline.d.ts

@@ -3,31 +3,33 @@ import type { ControlSize, PaletteColor, Tone } from "@/internal/states";
 export type TimelineRootProps = {
     /** Tier of text, dots and row rhythm. Default `m` (rows 64px). */
     size?: ControlSize;
-    /**
-     * Who gets the highlighted look (pill, accent title and dot):
-     * `selected` (default) — the `active` row keeps it; interactive rows get a faint hover wash.
-     * `hover` — the row under the pointer or with keyboard focus, transiently; `active` keeps only
-     * its semantics (`aria-current`), no persistent highlight.
-     */
-    highlight?: "selected" | "hover";
     /** `Timeline.Group` elements. */
     children: React.ReactNode;
     className?: string;
+    ref?: React.Ref<HTMLDivElement>;
 } & Omit<React.HTMLAttributes<HTMLDivElement>, "children">;
+declare function TimelineRoot({ size, children, className, ...rest }: TimelineRootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace TimelineRoot {
+    var displayName: string;
+}
 export type TimelineGroupProps = {
     /** Group heading (e.g. «Недавно»); labels the list via `aria-labelledby`. */
     label?: React.ReactNode;
     /** `Timeline.Item` and `Timeline.Gap` elements. */
     children: React.ReactNode;
     className?: string;
+    ref?: React.Ref<HTMLOListElement>;
 } & Omit<React.OlHTMLAttributes<HTMLOListElement>, "children">;
+/** One labelled `<ol>` of events. The connecting line runs from its first dot to its last. */
+declare function TimelineGroup({ label, children, className, ...rest }: TimelineGroupProps): import("react/jsx-runtime").JSX.Element;
+declare namespace TimelineGroup {
+    var displayName: string;
+}
 export type TimelineItemProps = {
     /** Decorative dot hue (categorization). Default `blue`, shown at reduced emphasis. */
     color?: PaletteColor;
     /** Semantic dot color (status). Wins over `color`; shown at full emphasis. */
     tone?: Tone;
-    /** Highlighted / selected row: soft pill, accent title and dot; `data-state="active"`, `aria-current`. */
-    active?: boolean;
     /** Renders the row as a link. */
     href?: string;
     /** Renders the row as the single child element (router link etc.); the dot is prepended to its children. */
@@ -37,12 +39,19 @@ export type TimelineItemProps = {
     /** `Timeline.Title`, `Timeline.Meta`, `Timeline.Value`. */
     children: React.ReactNode;
     className?: string;
+    /** The row element (`a`, `button`, `div` or the `asChild` element). */
+    ref?: React.Ref<HTMLElement>;
 } & Omit<React.HTMLAttributes<HTMLElement>, "children" | "color" | "onClick"> & Pick<React.AnchorHTMLAttributes<HTMLAnchorElement>, "target" | "rel" | "download">;
+declare function TimelineItem({ color, tone, href, asChild, onClick, children, className, ref, ...rest }: TimelineItemProps): import("react/jsx-runtime").JSX.Element;
+declare namespace TimelineItem {
+    var displayName: string;
+}
 export type TimelineTitleProps = {
     children: React.ReactNode;
     className?: string;
+    ref?: React.Ref<HTMLSpanElement>;
 } & Omit<React.HTMLAttributes<HTMLSpanElement>, "children">;
-/** First line: the event. Medium, primary (accent on the active row); wraps when narrow. */
+/** First line: the event. Medium, primary (accent on the highlighted row); wraps when narrow. */
 declare function TimelineTitle({ children, className, ...rest }: TimelineTitleProps): import("react/jsx-runtime").JSX.Element;
 declare namespace TimelineTitle {
     var displayName: string;
@@ -50,6 +59,7 @@ declare namespace TimelineTitle {
 export type TimelineMetaProps = {
     children: React.ReactNode;
     className?: string;
+    ref?: React.Ref<HTMLSpanElement>;
 } & Omit<React.HTMLAttributes<HTMLSpanElement>, "children">;
 /** Second line: date and relative time, muted, tabular numbers. Emphasize a part with `Timeline.MetaPrimary` or `<strong>`. */
 declare function TimelineMeta({ children, className, ...rest }: TimelineMetaProps): import("react/jsx-runtime").JSX.Element;
@@ -59,6 +69,7 @@ declare namespace TimelineMeta {
 export type TimelineMetaPrimaryProps = {
     children: React.ReactNode;
     className?: string;
+    ref?: React.Ref<HTMLSpanElement>;
 } & Omit<React.HTMLAttributes<HTMLSpanElement>, "children">;
 /** Emphasized part of the meta line (the date): primary, medium. */
 declare function TimelineMetaPrimary({ children, className, ...rest }: TimelineMetaPrimaryProps): import("react/jsx-runtime").JSX.Element;
@@ -70,6 +81,7 @@ export type TimelineValueProps = {
     tone?: Tone;
     children: React.ReactNode;
     className?: string;
+    ref?: React.Ref<HTMLSpanElement>;
 } & Omit<React.HTMLAttributes<HTMLSpanElement>, "children">;
 /**
  * Trailing amount: right-aligned, vertically centered, tabular numbers. Add `Timeline.ValueMeta` for a
@@ -82,74 +94,47 @@ declare namespace TimelineValue {
 export type TimelineValueMetaProps = {
     children: React.ReactNode;
     className?: string;
+    ref?: React.Ref<HTMLSpanElement>;
 } & Omit<React.HTMLAttributes<HTMLSpanElement>, "children">;
 /** Second line inside `Timeline.Value` (category, unit): meta size, muted, right-aligned under the value. */
 declare function TimelineValueMeta({ children, className, ...rest }: TimelineValueMetaProps): import("react/jsx-runtime").JSX.Element;
 declare namespace TimelineValueMeta {
     var displayName: string;
 }
+export type TimelineGapMetaProps = React.HTMLAttributes<HTMLSpanElement> & {
+    ref?: React.Ref<HTMLSpanElement>;
+};
+/** A caption on the right of a gap (e.g. «сейчас»). */
+declare function TimelineGapMeta({ className, ...rest }: TimelineGapMetaProps): import("react/jsx-runtime").JSX.Element;
+declare namespace TimelineGapMeta {
+    var displayName: string;
+}
 export type TimelineGapProps = {
     /** Caption color and hollow dot. Default `neutral` (muted); `warning` / `danger` flag a long interval. */
     tone?: Tone;
-    /** Optional trailing caption on the right (e.g. «сейчас»). */
-    trailing?: React.ReactNode;
-    /** Interval caption, e.g. «40 дней · 2 200 км без обслуживания». */
+    /** Interval caption, e.g. «40 дней · 2 200 км без обслуживания», and an optional `Timeline.GapMeta`. */
     children: React.ReactNode;
     className?: string;
+    ref?: React.Ref<HTMLDivElement>;
 } & Omit<React.HTMLAttributes<HTMLDivElement>, "children">;
+/**
+ * Interval between two events: a shorter row with a small hollow dot on a dashed segment and a
+ * muted caption. Renders an `li`, so it goes inside `Timeline.Group` between items.
+ */
+declare function TimelineGap({ tone, children, className, ...rest }: TimelineGapProps): import("react/jsx-runtime").JSX.Element;
+declare namespace TimelineGap {
+    var displayName: string;
+}
 export declare const Timeline: {
-    Root: React.ForwardRefExoticComponent<{
-        /** Tier of text, dots and row rhythm. Default `m` (rows 64px). */
-        size?: ControlSize;
-        /**
-         * Who gets the highlighted look (pill, accent title and dot):
-         * `selected` (default) — the `active` row keeps it; interactive rows get a faint hover wash.
-         * `hover` — the row under the pointer or with keyboard focus, transiently; `active` keeps only
-         * its semantics (`aria-current`), no persistent highlight.
-         */
-        highlight?: "selected" | "hover";
-        /** `Timeline.Group` elements. */
-        children: React.ReactNode;
-        className?: string;
-    } & Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & React.RefAttributes<HTMLDivElement>>;
-    Group: React.ForwardRefExoticComponent<{
-        /** Group heading (e.g. «Недавно»); labels the list via `aria-labelledby`. */
-        label?: React.ReactNode;
-        /** `Timeline.Item` and `Timeline.Gap` elements. */
-        children: React.ReactNode;
-        className?: string;
-    } & Omit<React.OlHTMLAttributes<HTMLOListElement>, "children"> & React.RefAttributes<HTMLOListElement>>;
-    Item: React.ForwardRefExoticComponent<{
-        /** Decorative dot hue (categorization). Default `blue`, shown at reduced emphasis. */
-        color?: PaletteColor;
-        /** Semantic dot color (status). Wins over `color`; shown at full emphasis. */
-        tone?: Tone;
-        /** Highlighted / selected row: soft pill, accent title and dot; `data-state="active"`, `aria-current`. */
-        active?: boolean;
-        /** Renders the row as a link. */
-        href?: string;
-        /** Renders the row as the single child element (router link etc.); the dot is prepended to its children. */
-        asChild?: boolean;
-        /** Renders the row as a `button` (unless `href` / `asChild`). */
-        onClick?: React.MouseEventHandler<HTMLElement>;
-        /** `Timeline.Title`, `Timeline.Meta`, `Timeline.Value`. */
-        children: React.ReactNode;
-        className?: string;
-    } & Omit<React.HTMLAttributes<HTMLElement>, "children" | "color" | "onClick"> & Pick<React.AnchorHTMLAttributes<HTMLAnchorElement>, "rel" | "target" | "download"> & React.RefAttributes<HTMLElement>>;
+    Root: typeof TimelineRoot;
+    Group: typeof TimelineGroup;
+    Item: typeof TimelineItem;
     Title: typeof TimelineTitle;
     Meta: typeof TimelineMeta;
     MetaPrimary: typeof TimelineMetaPrimary;
     Value: typeof TimelineValue;
     ValueMeta: typeof TimelineValueMeta;
-    Gap: React.ForwardRefExoticComponent<{
-        /** Caption color and hollow dot. Default `neutral` (muted); `warning` / `danger` flag a long interval. */
-        tone?: Tone;
-        /** Optional trailing caption on the right (e.g. «сейчас»). */
-        trailing?: React.ReactNode;
-        /** Interval caption, e.g. «40 дней · 2 200 км без обслуживания». */
-        children: React.ReactNode;
-        className?: string;
-    } & Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & React.RefAttributes<HTMLDivElement>>;
+    Gap: typeof TimelineGap;
+    GapMeta: typeof TimelineGapMeta;
 };
 export {};
-//# sourceMappingURL=Timeline.d.ts.map

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

@@ -1,11 +1,16 @@
 import * as React from "react";
+import { type PositionAlign, type PositionSide } from "@/hooks/usePosition";
 import type { ControlSize } from "@/internal/states";
-export type TooltipSide = "top" | "bottom" | "left" | "right";
+export type TooltipSide = PositionSide;
+export type TooltipAlign = PositionAlign;
 export type TooltipProviderProps = {
+    /** 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. */
+    skipDelayDuration?: number;
     children: React.ReactNode;
 };
-declare function TooltipProvider({ delayDuration, children }: TooltipProviderProps): import("react/jsx-runtime").JSX.Element;
+declare function TooltipProvider({ delayDuration, skipDelayDuration, children, }: TooltipProviderProps): import("react/jsx-runtime").JSX.Element;
 declare namespace TooltipProvider {
     var displayName: string;
 }
@@ -14,7 +19,7 @@ export type TooltipRootProps = {
     open?: boolean;
     defaultOpen?: boolean;
     onOpenChange?: (open: boolean) => void;
-    /** Задержка показа (мс) для этого тултипа; по умолчанию — из `Tooltip.Provider` (400). */
+    /** Show delay in ms for this tooltip; defaults to the Provider's (400). */
     delayDuration?: number;
 };
 declare function TooltipRoot({ children, open, defaultOpen, onOpenChange, delayDuration: delayProp, }: TooltipRootProps): import("react/jsx-runtime").JSX.Element;
@@ -22,27 +27,27 @@ declare namespace TooltipRoot {
     var displayName: string;
 }
 export type TooltipTriggerProps = {
+    /** One focusable element: a Button, or a `tabIndex={0}` wrapper around a disabled control. */
     children: React.ReactElement;
-    className?: string;
-};
-declare function TooltipTrigger({ children, className }: TooltipTriggerProps): React.ReactElement<React.HTMLAttributes<HTMLElement> & React.RefAttributes<HTMLElement>, string | React.JSXElementConstructor<any>>;
+    ref?: React.Ref<HTMLElement>;
+} & Omit<React.HTMLAttributes<HTMLElement>, "children">;
+/**
+ * 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.
+ */
+declare function TooltipTrigger({ children, ...forwarded }: TooltipTriggerProps): import("react/jsx-runtime").JSX.Element;
 declare namespace TooltipTrigger {
     var displayName: string;
 }
-type TooltipCoords = {
-    top: number;
-    left: number;
-    side: TooltipSide;
-};
-/** Позиция по стороне; если не влезает — противоположная сторона; затем сдвиг в пределах вьюпорта. */
-export declare function computeTooltipPosition(ar: Pick<DOMRectReadOnly, "top" | "left" | "right" | "bottom" | "width" | "height">, cw: number, ch: number, vw: number, vh: number, side: TooltipSide, offset: number, pad: number): TooltipCoords;
-export type TooltipContentProps = {
+export type TooltipContentProps = Omit<React.HTMLAttributes<HTMLDivElement>, "id" | "role" | "onPointerEnter" | "onPointerLeave"> & {
     children: React.ReactNode;
+    /** Text and padding tier; also the size context of controls inside (a Kbd). */
     size?: ControlSize;
     side?: TooltipSide;
-    className?: string;
+    align?: TooltipAlign;
+    ref?: React.Ref<HTMLDivElement>;
 };
-declare function TooltipContent({ children, size, side, className }: TooltipContentProps): import("react/jsx-runtime").JSX.Element | null;
+declare function TooltipContent({ children, size, side, align, className, ...rest }: TooltipContentProps): import("react/jsx-runtime").JSX.Element;
 declare namespace TooltipContent {
     var displayName: string;
 }
@@ -53,4 +58,3 @@ export declare const Tooltip: {
     Content: typeof TooltipContent;
 };
 export {};
-//# sourceMappingURL=Tooltip.d.ts.map

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

@@ -1,11 +1,11 @@
-import * as React from "react";
+import type * as React from "react";
 import type { TextTone } from "@/internal/states";
 /** Text roles from the foundation (`--prime-text-<role>-*`). */
 export type TypographyRole = "caption" | "body-s" | "body-m" | "body-l" | "title-s" | "title-m" | "title-l" | "heading-s" | "heading-m" | "heading-l" | "display-s" | "display-m" | "display-l" | "code";
 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 TypographyRootProps = {
+export type TypographyProps = {
     as?: TypographyAs;
     /** Text role (`--prime-text-<role>-*`). */
     variant: TypographyRole;
@@ -20,23 +20,7 @@ export type TypographyRootProps = {
     tone?: TextTone;
     children?: React.ReactNode;
     className?: string;
+    ref?: React.Ref<HTMLElement>;
 } & React.HTMLAttributes<HTMLElement>;
-export declare const Typography: {
-    Root: React.ForwardRefExoticComponent<{
-        as?: TypographyAs;
-        /** Text role (`--prime-text-<role>-*`). */
-        variant: TypographyRole;
-        /** Overrides the role's weight. Omit to use the role's own weight. */
-        weight?: TypographyWeight;
-        /** Overrides the role's tracking. Omit to use the role's own tracking. */
-        tracking?: TypographyTracking;
-        /** Clamp to one line with an ellipsis (set `title` when the full text matters). */
-        truncate?: boolean;
-        italic?: boolean;
-        /** Text color. Default `default` (primary text). */
-        tone?: TextTone;
-        children?: React.ReactNode;
-        className?: string;
-    } & React.HTMLAttributes<HTMLElement> & React.RefAttributes<HTMLElement>>;
-};
-//# sourceMappingURL=Typography.d.ts.map
+/** 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;

package/dist/hooks/useControllableState.d.ts

@@ -5,4 +5,3 @@ type UseControllableStateParams<T> = {
 };
 export declare function useControllableState<T>({ value, defaultValue, onChange, }: UseControllableStateParams<T>): readonly [T, (nextValue: T | ((prev: T) => T)) => void];
 export {};
-//# sourceMappingURL=useControllableState.d.ts.map

package/dist/hooks/useEnterConfirm.d.ts

@@ -0,0 +1,15 @@
+import * as React from "react";
+export type UseEnterConfirmOptions = {
+    enabled: boolean;
+    containerRef: React.RefObject<HTMLElement | null>;
+    /** Replaces the default (a `click()` on `confirmRef`). */
+    onEnterConfirm?: (event: KeyboardEvent) => void;
+    /** The confirm target (the primary button wrapped in `Modal.Confirm`). */
+    confirmRef: React.RefObject<HTMLElement | null>;
+};
+/**
+ * Enter inside a dialog clicks its confirm action — from a text field or the dialog itself. Enter on
+ * a button, link or `role="button"` activates that element instead (Enter on Cancel cancels), and
+ * the header (close button) is left alone.
+ */
+export declare function useEnterConfirm({ enabled, containerRef, onEnterConfirm, confirmRef, }: UseEnterConfirmOptions): void;

package/dist/hooks/useImageStatus.d.ts

@@ -0,0 +1,19 @@
+import * as React from "react";
+/** Load status of an image part as its root sees it; `idle` = no image part mounted. */
+export type ImageStatus = "idle" | "loading" | "loaded" | "error";
+type ImageHandlers = {
+    onLoad?: React.ReactEventHandler<HTMLImageElement>;
+    onError?: React.ReactEventHandler<HTMLImageElement>;
+};
+/**
+ * Image side of an image-with-fallback component (Avatar, Thumbnail): tracks the `<img>` load and
+ * reports it to the root through `report`, so the root's Fallback shows while loading and after an
+ * error. Key the image element by `src`: a new source remounts it and starts again at `loading`.
+ * Unmounting the image reports `idle`.
+ */
+export declare function useImageStatus(report: (status: ImageStatus) => void, { onLoad, onError }?: ImageHandlers): {
+    status: "loading" | "error" | "loaded";
+    onLoad: (event: React.SyntheticEvent<HTMLImageElement>) => void;
+    onError: (event: React.SyntheticEvent<HTMLImageElement>) => void;
+};
+export {};

package/dist/hooks/useInertSiblings.d.ts

@@ -0,0 +1,9 @@
+import * as React from "react";
+/** Body children that stay usable under a modal layer: live regions (the toast viewport). */
+export declare const LIVE_REGION_ATTR = "data-prime-live-region";
+/**
+ * While `enabled`, makes every `<body>` child inert except the one that holds `ref` (its portal)
+ * and live regions, then restores the previous values. `inert` already removes the content from
+ * the accessibility tree, so no `aria-hidden` is added. Part of `useModalLayer`.
+ */
+export declare function useInertSiblings(enabled: boolean, ref: React.RefObject<HTMLElement | null>): void;

package/dist/hooks/useMergedRefs.d.ts

@@ -1,3 +1,7 @@
 import * as React from "react";
-export declare function useMergedRefs<T>(...refs: Array<React.Ref<T> | undefined>): (value: T) => void;
-//# sourceMappingURL=useMergedRefs.d.ts.map
+/**
+ * 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.
+ */
+export declare function useMergedRefs<T>(...refs: Array<React.Ref<T> | undefined>): React.RefCallback<T>;

package/dist/hooks/useModalLayer.d.ts

@@ -0,0 +1,22 @@
+import * as React from "react";
+import { type DismissReason, type LayerEntry } from "@/internal/overlay/layerStack";
+export type UseModalLayerOptions = {
+    open: boolean;
+    /** Escape (`escape`) or a click on the scrim (`scrim`); the owner applies its `closeOn*` props. */
+    onDismiss: (reason: DismissReason) => void;
+};
+export 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
+ * restored first, then focus returns to the opener, captured at the open transition. 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>;

package/dist/hooks/usePosition.d.ts

@@ -1,62 +1,68 @@
 import * as React from "react";
-export type PositionSide = "bottom" | "top";
+export type PositionSide = "top" | "right" | "bottom" | "left";
 export type PositionAlign = "start" | "center" | "end";
-type UsePositionOptions = {
-    side?: PositionSide;
-    align?: PositionAlign;
-    offset?: number;
-    /** Отступ контента от краёв вьюпорта при расчёте flip/позиции (px). */
-    viewportPad?: number;
-    flip?: boolean;
-    matchTriggerMinWidth?: boolean;
-};
-/**
- * Private custom properties written by `usePosition` on the floating element. Panels combine them
- * with tokens, e.g. `max-height: min(var(--prime-panel-max-height), var(--float-max-h))`, so the
- * design limit and the room next to the anchor both apply.
- */
-export declare const FLOAT_MAX_HEIGHT_VAR = "--float-max-h";
-/** Trigger width (px) when the panel should be at least as wide as its anchor. */
-export declare const FLOAT_MIN_WIDTH_VAR = "--float-min-w";
-/** Viewport width minus gutters (px): a panel is never wider than the screen. */
-export declare const FLOAT_MAX_WIDTH_VAR = "--float-max-w";
-export type PositionUpdateMeta = {
-    resolvedSide: PositionSide;
-};
 /**
  * Computed length of a CSS custom property on `:root` in px (rem/px values).
  * Falls back when there is no DOM / stylesheet (SSR, jsdom).
  */
 export declare function readCssLengthPx(name: string, fallbackPx: number): number;
-/** Gap between anchor and floating panel: `--prime-panel-offset`. */
-export declare function getPanelOffsetPx(): number;
 /** Minimum distance from a floating panel to the viewport edge: `--prime-space-2`. */
 export declare function getViewportPadPx(): number;
 export type ComputeFloatingOptions = {
-    preferredSide: PositionSide;
+    side: PositionSide;
     align: PositionAlign;
+    /** Gap between the anchor and the layer (px). */
     offset: number;
-    /** Отступ от краёв вьюпорта (px); по умолчанию 8. */
+    /** 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;
-    matchTriggerMinWidth: boolean;
+    matchAnchorWidth: boolean;
+    /** Closest the arrow centre may come to a layer corner; computes `arrow` when set. */
+    arrowInset?: number;
 };
 export type ComputedFloatPosition = {
     top: number;
     left: number;
-    resolvedSide: PositionSide;
+    /** 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;
-    /** Доступная высота под контент (px), со стороны открытия. */
-    maxHeight?: 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;
 };
-/** Якорь + размеры слоя + вьюпорт; при flip — сторона с большим запасом / куда влезает контент. */
-export declare function computeFloatingPosition(anchorRect: DOMRectReadOnly, contentW: number, contentH: number, vw: number, vh: number, opts: ComputeFloatingOptions): ComputedFloatPosition;
-type UsePositionResult = {
-    resolvedSide: PositionSide;
-    update: () => PositionUpdateMeta | undefined;
+/**
+ * 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;
+    /** Write the anchor width to `--float-min-w` (the panel CSS decides min or exact width). */
+    matchAnchorWidth?: boolean;
+    /** Token of the gap between anchor and layer. Default `--prime-panel-offset`. */
+    offsetToken?: string;
+    /** Closest the arrow may come to a layer corner, read from the layer; writes `--float-arrow`. */
+    arrowInset?: (layer: HTMLElement) => number;
 };
-export declare function usePosition(anchorRef: React.RefObject<HTMLElement | null>, contentRef: React.RefObject<HTMLElement | null>, options?: UsePositionOptions): UsePositionResult;
-export {};
-//# sourceMappingURL=usePosition.d.ts.map
+export type Position = {
+    /** The side the layer opened on (after flipping). */
+    side: PositionSide;
+    /** Attach to the layer element (merge with other refs): positioning starts once it is in the DOM. */
+    attachLayer: (node: HTMLElement | null) => void;
+};
+/**
+ * Places a floating layer (`position: fixed`) next to its anchor and follows the anchor while
+ * `enabled`: before paint, again on the next frame (fonts), and on window resize, scroll of any
+ * scrolling ancestor of the anchor, visual-viewport changes and size changes of the layer or the
+ * anchor. Shared by every anchored layer (Popover, Dropdown, Select, TagSelect, Tooltip). A
+ * portaled layer reaches the DOM one commit after its owner, so the subscription waits for
+ * `attachLayer` instead of reading the ref too early.
+ */
+export declare function usePosition(enabled: boolean, anchorRef: React.RefObject<HTMLElement | null>, layerRef: React.RefObject<HTMLElement | null>, { side: preferredSide, align, matchAnchorWidth, offsetToken, arrowInset, }?: PositionOptions): Position;

package/dist/hooks/usePresence.d.ts

@@ -28,4 +28,3 @@ export type Presence = {
  * `prefers-reduced-motion: reduce`. Shared by every floating layer (foundation §7 "Overlay contract").
  */
 export declare function usePresence(open: boolean, options?: UsePresenceOptions): Presence;
-//# sourceMappingURL=usePresence.d.ts.map

package/dist/hooks/useScrollLock.d.ts

@@ -1,8 +1,6 @@
 /**
- * Locks body scroll when enabled. Supports multiple concurrent callers via
- * a reference-counted lock — the last caller to unmount restores scroll.
- * Compensates for scrollbar width to prevent layout shift.
- * Shared by modal/drawer overlays.
+ * Locks document scroll while enabled. Reference-counted: nested modal layers share one lock and
+ * the last one restores it. The scrollbar width is added to the body's right padding, so the page
+ * does not shift. Part of `useModalLayer`.
  */
 export declare function useScrollLock(enabled: boolean): void;
-//# sourceMappingURL=useScrollLock.d.ts.map