prime-ui-kit 0.14.0 → 0.16.0

package/dist/internal/mediaDisk.d.ts

@@ -1,14 +1,17 @@
 /**
  * The still disk over media: the look of `Button shape="circle" variant="shade"` (`l`) for a disk
- * that is not a control. A host positions it; it may shrink it to a small frame (the glyph follows
- * at half the diameter).
+ * that is not a control. Join it with `data-size="l"` (the control tier it takes its diameter
+ * from). A host positions it; it may shrink it to a small frame (the glyph follows at half the
+ * diameter).
  */
 export declare const mediaDiskClass: string;
 /**
  * The play mark of a video frame: the still media disk with the play glyph — the same size, ground
  * and glyph as the play and transfer disks over media. Decorative: the tile around it is the
- * button and says what it opens.
+ * button and says what it opens. Always mounted: `shown={false}` fades and shrinks it away (the
+ * frame plays, a transfer takes the middle) and it comes back the same way.
  */
-export declare function MediaPlayMark({ className }: {
+export declare function MediaPlayMark({ shown, className, }: {
+    shown?: boolean;
     className?: string;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/internal/mediaPlayer.d.ts

@@ -8,26 +8,40 @@ import { type TransferDiskProps } from "./transferDisk";
  * sound at a time on the page (`internal/mediaSession`), the keyboard seek, the transcript
  * (`internal/transcript`) and the transfer (`internal/transfer`, drawn by `internal/transferDisk`).
  * A player adds only what its media really has of its own (the voice waveform and rate, the
- * circle's poster) and keeps its own media logic.
+ * circle's poster); the playback itself is `useMediaPlayer`. Each prop is described in
+ * `mediaPlayer.api.ts`.
  */
 export type MediaPlayerProps = TranscriptProps & TransferProps & {
-    /** The media file; loaded with `preload="metadata"`. */
+    /**
+     * Audio URL, loaded with `preload="metadata"`: nothing plays before a press.
+     */
     src: string;
-    /** Length in seconds, shown until the media reports its own. */
+    /**
+     * Length in seconds, shown until the media reports its own.
+     */
     duration?: number;
-    /** Nobody has played it yet: an accent dot after the time. Clear it on `onPlayingChange(true)`. */
+    /**
+     * Nobody has played it yet: an accent dot after the time and `labels.unplayed` for screen readers. Clear it when `onPlayingChange(true)` comes; the dot fades out and the row closes up in place.
+     */
     unplayed?: boolean;
-    /** Playing with sound (controlled). One sound plays at a time on the page. */
+    /**
+     * Playing with sound (controlled): `true` plays it (from the start or on from a pause), `false` pauses it. One sound plays on the page at a time.
+     */
     playing?: boolean;
-    /** Initial playing state (uncontrolled). Default `false`. */
+    /**
+     * Initial playing state (uncontrolled).
+     */
     defaultPlaying?: boolean;
-    /** Playback with sound started or stopped: a press, another sound taking over, the end. */
+    /**
+     * Playback with sound started or stopped: the play disk, Enter / Space, another sound taking over, the end (then `onEnded` too); a drag on the waveform that pauses for the seek does not count.
+     */
     onPlayingChange?: (playing: boolean) => void;
-    /** Playback reached the end; the player is back at the start. */
+    /**
+     * Playback reached the end; the player is back at the start, paused.
+     */
     onEnded?: () => void;
     /**
-     * Nothing can be played: the play control, the seek, the transcript button and the transfer
-     * actions are off. A disabled `Fieldset` around the player disables it too.
+     * Nothing can be played: the play disk, the waveform slider and the rate chip, the transcript button and the transfer actions are off (native `disabled`). A disabled `Fieldset` around it disables it too.
      */
     disabled?: boolean;
 };
@@ -70,20 +84,38 @@ export declare const MEDIA_PLAYER_LABELS: {
 };
 /** Where a player's playback is: at the start, playing, or stopped past the start. */
 export type PlaybackState = "idle" | "playing" | "paused";
-/**
- * The keyboard seek of every player (on the voice waveform, on the circle): ArrowRight / ArrowUp
- * 5 s forward, ArrowLeft / ArrowDown 5 s back (mirrored in RTL), PageUp / PageDown a tenth, Home
- * / End the edges. The next position in seconds, or `null` for any other key.
- */
-export declare function seekByKey(event: React.KeyboardEvent<HTMLElement>, current: number, total: number): number | null;
 /** Splits a player's props: the shared player ones, and the rest (its own and the DOM's). */
 export declare function splitMediaPlayerProps<P extends MediaPlayerProps>(props: P): [MediaPlayerProps, Omit<P, keyof MediaPlayerProps>];
 /** The transfer disk's props a player hands on (it adds its own `look` and `className`). */
-export type PlayerTransferDisk = Pick<TransferDiskProps, "state" | "progress" | "labels" | "onCancel" | "onRetry" | "onDownload" | "disabled">;
-export type MediaPlayer = {
-    /** The triad: what the owner (or the player's last act) wants — it may lead the media. */
-    wanted: boolean;
-    setWanted: (playing: boolean) => void;
+type PlayerTransferDisk = Pick<TransferDiskProps, "state" | "progress" | "labels" | "onCancel" | "onRetry" | "onDownload" | "disabled">;
+type MediaPlayerOptions = {
+    /** Playback speed of the media. Default `1`. */
+    rate?: number;
+    /**
+     * The element whose `progressProperty` carries the played share (0…1): written every frame while
+     * playing and on every seek, never through a render.
+     */
+    progressRef?: React.RefObject<HTMLElement | SVGSVGElement | null>;
+    /** The custom property the share is written to. Default `--ring-value` (a live `Ring`). */
+    progressProperty?: string;
+};
+/** The media element's events the player listens to: spread them on the `<audio>` / `<video>`. */
+type MediaEvents = {
+    onPlay: () => void;
+    onPause: () => void;
+    onEnded: () => void;
+    onLoadedMetadata: () => void;
+    onDurationChange: () => void;
+};
+type MediaPlayer = {
+    /** Where the playback is: `idle` at the start, `playing`, `paused` past the start. */
+    state: PlaybackState;
+    /** The position in seconds: exact at rest, the whole second while playing. */
+    position: number;
+    /** The length the player knows (the media's own, else `duration`), `null` while unknown. */
+    duration: number | null;
+    /** A drag of the seek holds the playback (`scrub`). */
+    seeking: boolean;
     transcript: Transcript | null;
     /** Its own `disabled` or a disabled `Fieldset` around it. */
     disabled: boolean;
@@ -93,13 +125,43 @@ export type MediaPlayer = {
     inactive: boolean;
     /** The transfer disk to draw, or `null` without a transfer. */
     transferDisk: PlayerTransferDisk | null;
+    /** Plays (from the start out of `idle`, on from a pause) or pauses — inside the press. */
+    toggle: () => void;
+    /** Moves the position to `seconds` (clamped); out of `idle` it leaves the player paused there. */
+    seek: (seconds: number) => void;
+    /** The keyboard seek (`seekByKey`) on the element that has it; `true` when the key moved it. */
+    seekWithKey: (event: React.KeyboardEvent<HTMLElement>) => boolean;
+    /** A drag of the seek starts (`true`: a playing media holds) or ends (`false`: it resumes). */
+    scrub: (active: boolean) => void;
+    mediaEvents: MediaEvents;
 };
 /**
- * The shared half of a chat player: registers `mediaRef` with the one-sound session, holds the
- * `playing` triad, the transcript and the transfer. The player drives its media from `wanted`
- * and reports what the media does through `setWanted`.
+ * The one playback engine of the chat players. It registers `mediaRef` with the one-sound
+ * session, holds the `playing` triad and syncs the media to it, keeps the playback state
+ * (`idle` → `playing` ⇄ `paused` → the end rewinds to `idle`), starts with a rewind when the media
+ * stands elsewhere, applies the rate, follows the position with one animation-frame loop that
+ * writes the played share to `progressRef` (a render only when the second changes), and holds a
+ * playing media through a drag of the seek. The transcript and the transfer come with it. A player
+ * draws its media from this and spreads `mediaEvents` on the element.
+ */
+export declare function useMediaPlayer(mediaRef: React.RefObject<HTMLMediaElement | null>, props: MediaPlayerProps, labels: MediaPlayerLabels, { rate, progressRef, progressProperty }?: MediaPlayerOptions): MediaPlayer;
+/**
+ * The root of every player: a `role="group"` named by `labels.player`, with the player's state on
+ * it (`data-playing`, `data-seeking`, `data-disabled`, `data-transfer`).
+ */
+export declare function MediaPlayerRoot({ label, player, className, children, ...rest }: Omit<MediaPlayerRootProps, "children"> & {
+    label: string;
+    player: MediaPlayer;
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * The accent dot of a player nobody has played yet (after the voice message's time, in the video
+ * circle's duration pill): it rises in when `unplayed` turns on and closes up in place when it
+ * clears. Decorative; the player reads `labels.unplayed` itself.
  */
-export declare function useMediaPlayer(mediaRef: React.RefObject<HTMLMediaElement | null>, props: MediaPlayerProps, labels: MediaPlayerLabels): MediaPlayer;
+export declare function UnplayedDot({ shown }: {
+    shown: boolean;
+}): import("react/jsx-runtime").JSX.Element | null;
 /**
  * The play disk of every player: one `Button shape="circle"` (control `l`) for every state — play
  * ⇄ pause, and while the media is on its way, failed or not fetched, the transfer's ×, retry or
@@ -125,11 +187,13 @@ export declare function PlayDisk({ look, state, labels, disabled, covered, trans
 }): import("react/jsx-runtime").JSX.Element;
 /**
  * The transcript button of every player, so a voice message and a circle never drift: a soft `xs`
- * icon Button with the transcript mark («→A») that cross-fades into a chevron up while the text is
- * open, spinning (`loading`) while it is asked for. The player places it at its top end.
+ * icon Button with the transcript mark («→A») that cross-fades (`Button.Icon`) into a chevron up
+ * while the text is open, spinning (`loading`) while it is asked for. The player places it at its
+ * top end.
  */
 export declare function TranscriptButton({ transcript, disabled, className, }: {
     transcript: Transcript;
     disabled?: boolean;
     className?: string;
 }): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/internal/mediaSession.d.ts

@@ -1,10 +1,4 @@
 import * as React from "react";
-/** `media` started playing (or got its sound back while playing): it takes the session. */
-export declare function claimPlayback(media: HTMLMediaElement): void;
-/** `media` paused, ended or went away: the session is free. */
-export declare function releasePlayback(media: HTMLMediaElement): void;
-/** The media element now holding the session (tests and diagnostics). */
-export declare function activePlayback(): HTMLMediaElement | null;
 /**
  * Registers a media element with the session: playing it with sound pauses whatever else plays.
  * Listens to the element itself, so native controls, `play()` from code and the kit's own buttons

package/dist/internal/messageList.d.ts

@@ -19,7 +19,7 @@ export type Selection = readonly string[] | null;
  * The selection of a list, outside React state: each message subscribes to its own state in it
  * (`useMessageSelection`), so a toggle re-renders the messages whose state changed, not the list.
  */
-export type SelectionStore = {
+type SelectionStore = {
     get: () => Selection;
     /** `0` — not selecting, `1` — selecting, not selected, `2` — selected. */
     stateOf: (value: string) => 0 | 1 | 2;
@@ -84,7 +84,7 @@ export declare function useMessageSelection(value: string): {
 /** The whole selection of the list. */
 export declare function useListSelection(): Selection;
 /** What a message row says about itself from its props alone, before it renders. */
-export type MessageRowDescription = {
+type MessageRowDescription = {
     value: string | undefined;
     direction: MessageDirection;
     /** The row's height before it is measured (px). */
@@ -98,7 +98,7 @@ export type MessageRowDescription = {
  * typing, the selection bar). A `message` row describes itself; a `sticky` row is a date that
  * sticks while its day scrolls.
  */
-export type RowKind = {
+type RowKind = {
     tail?: boolean;
     sticky?: boolean;
     message?: (props: Record<string, unknown>) => MessageRowDescription;
@@ -119,3 +119,4 @@ export type MessageRowInfo = {
 /** The list wraps every row in it. */
 export declare const MessageRowProvider: React.Provider<MessageRowInfo | null>;
 export declare function useMessageRow(): MessageRowInfo | null;
+export {};

package/dist/internal/motionTiming.d.ts

@@ -0,0 +1,34 @@
+import { TOKEN_DEFAULTS } from "./tokenDefaults";
+/**
+ * Motion timing for code: the motion tokens read from the document, so theme, app overrides and
+ * reduced motion (which zeroes the movement clocks, foundation §7) apply to JS motion as they do
+ * to CSS. WAAPI and timers cannot take `var()`; everything that times a motion in JS reads here.
+ */
+export type MotionDurationToken = "xfast" | "fast" | "base" | "slow";
+type MotionCurve = "standard" | "enter" | "exit" | "emphasized";
+/** A custom property of the document root as written (`""` when the CSS cannot be read). */
+export declare function motionToken(name: `--prime-motion-${string}`): string;
+/**
+ * A duration token in ms, read from the document (respects theme and reduced-motion overrides);
+ * its token default when the CSS cannot be read.
+ */
+export declare function readCssDurationMs(name: keyof typeof TOKEN_DEFAULTS): number;
+/**
+ * A duration custom property in ms as it applies to `element` (a component clock such as
+ * `--prime-message-morph-duration`, which a theme or reduced motion may set); 0 when unset.
+ */
+export declare function readElementDurationMs(element: Element, name: `--${string}`): number;
+/** `--prime-motion-duration-<token>` in ms. */
+export declare function motionDurationMs(token: MotionDurationToken): number;
+/** When a motion of `ms` has surely ended: the timeout of a fallback that cleans up after it. */
+export declare function afterMotionMs(ms: number): number;
+/** Timeout fallback for an exit of `token` length: the token duration plus slack. */
+export declare function exitTimeoutMs(token: MotionDurationToken): number;
+/**
+ * WAAPI timing from the motion tokens (`--prime-motion-duration-<token>`,
+ * `--prime-motion-easing-<curve>`), read at animation time. Read once per frame: a computed style
+ * read of the root forces a style pass, and each list of a board would otherwise force its own
+ * after the previous list's glides.
+ */
+export declare function motionTiming(duration: MotionDurationToken, curve?: MotionCurve): KeyframeAnimationOptions;
+export {};

package/dist/internal/namedRole.d.ts

@@ -0,0 +1,13 @@
+import type * as React from "react";
+type NamedProps = {
+    role?: React.AriaRole;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+};
+/**
+ * The role of a generic element (`<div>`, `<span>`) that the consumer may name: a name on an
+ * element without a role is ignored by assistive tech, so a named element takes `role` (`group`
+ * for a panel, `img` for a mark). An explicit `role` wins; an unnamed element keeps none.
+ */
+export declare function namedRole(props: NamedProps, role: React.AriaRole): React.AriaRole | undefined;
+export {};

package/dist/internal/nodeText.d.ts

@@ -0,0 +1,6 @@
+import * as React from "react";
+/**
+ * The plain text of a node tree: a label made of nodes (an icon and a word, a highlighted match)
+ * still has a name to search, announce or show in a trigger. Booleans and empty nodes add nothing.
+ */
+export declare function nodeText(node: React.ReactNode): string;

package/dist/{components/modal → internal/overlay}/DialogGuard.d.ts

@@ -1,17 +1,15 @@
 export type DialogGuardProps = {
     /**
-     * A request runs: Escape, a press outside, a swipe, the close button and `Close` do nothing; the
-     * close button and the `Close` child stay in place, disabled.
+     * A request runs: Escape, a press outside, a swipe, the close button and `Close` do nothing; the close button and the `Close` child stay in place, disabled. The grab handle stays and takes no drag.
      */
     busy?: boolean;
     /**
-     * Unsaved changes: any of those dismisses first asks «Не сохранять изменения?» (a ConfirmDialog
-     * with the Root's `labels.discard*`); confirming closes the dialog.
+     * Unsaved changes: any of those dismisses (a swipe glides back first) asks «Не сохранять изменения?» (a ConfirmDialog with `labels.discard*`); confirming closes the dialog.
      */
     dirty?: boolean;
 };
 /**
- * Holds a Modal or Drawer from inside its content, where the form state lives: put it anywhere in
+ * Holds a Modal, Drawer or Sheet from inside its content, where the form state lives: put it anywhere in
  * `Content`. Renders nothing but the «discard changes?» confirm when it is asked. Closing from code
  * (`open={false}`) is never held.
  */

package/dist/{components/modal → internal/overlay}/DialogParts.d.ts

@@ -1,12 +1,16 @@
 /**
- * Shared header / body / footer parts of Modal, Drawer and Sheet. Not exported from the package
- * root: consumers use them as `Modal.*`, `Drawer.*` and `Sheet.*`. The owning content component
- * provides the shell context (ids, close handler, labels, default footer layout).
+ * The dialog of Modal, Drawer and Sheet: one root state, one panel mechanic (`DialogPanel`: the
+ * portal, the scrim and the panel as siblings, the modal layer, the swipe of a sheet, the shell
+ * context) and the shared header / body / footer parts. Not exported from the package root:
+ * consumers use them as `Modal.*`, `Drawer.*` and `Sheet.*`.
  */
 import * as React from "react";
-import type { Tone } from "../../internal/states";
-/** System strings of the built-in «discard changes?» confirm (`Modal.Guard` / `Drawer.Guard dirty`). */
-export type DialogDiscardLabels = {
+import { type SlotPartProps } from "../slot";
+import type { ControlSize, Tone } from "../states";
+/** System strings of a dialog: its close button and the built-in «discard changes?» confirm. */
+export type DialogLabels = {
+    /** `aria-label` of the header close button. */
+    close: string;
     /** Title of the confirm a dismiss of a `dirty` dialog opens. */
     discardTitle: string;
     /** Its description. */
@@ -16,27 +20,44 @@ export type DialogDiscardLabels = {
     /** Its cancel button: back to the form. */
     discardCancel: string;
 };
-export declare const DIALOG_DISCARD_LABELS: DialogDiscardLabels;
+export declare const DIALOG_LABELS: DialogLabels;
 export type DialogRootOptions = {
+    /**
+     * Controlled visibility; together with `onOpenChange`.
+     */
     open?: boolean;
+    /**
+     * Initial visibility, uncontrolled.
+     */
     defaultOpen?: boolean;
+    /**
+     * Called on every open and close: trigger, close button, `Close`, Escape, scrim click, code. A `Guard` holds the dismisses (not code).
+     */
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Escape closes the dialog.
+     */
     closeOnEscape?: boolean;
+    /**
+     * A click on the scrim (and a swipe down, which draws the grab handle) closes the dialog. A destructive action is confirmed in a ConfirmDialog; unsaved changes are held by `Guard`.
+     */
     closeOnOutsideClick?: boolean;
-    closeLabel: string;
-    discardLabels: DialogDiscardLabels;
+    labels?: Partial<DialogLabels>;
     /** Modal only: Enter clicks `Modal.Confirm`. */
     confirmOnEnter?: boolean;
+    /**
+     * Replaces the default Enter confirm (the `Modal.Confirm` click).
+     */
     onEnterConfirm?: (event: KeyboardEvent) => void;
 };
 /** What a `Guard` inside the content holds the dialog to. */
-export type DialogGuardState = {
+type DialogGuardState = {
     /** A request runs: no way to dismiss; the close button is disabled. */
     busy: boolean;
     /** Unsaved changes: a dismiss asks first. */
     dirty: boolean;
 };
-export type DialogRootState = {
+type DialogRootState = {
     open: boolean;
     setOpen: (open: boolean) => void;
     /**
@@ -53,82 +74,64 @@ export type DialogRootState = {
     setConfirmingClose: (open: boolean) => void;
     closeOnEscape: boolean;
     closeOnOutsideClick: boolean;
-    closeLabel: string;
-    discardLabels: DialogDiscardLabels;
+    labels: DialogLabels;
     confirmOnEnter: boolean;
     onEnterConfirm?: (event: KeyboardEvent) => void;
 };
-declare const DialogRootProvider: React.Provider<DialogRootState | null>, useDialogRootContext: () => DialogRootState;
-export { DialogRootProvider, useDialogRootContext };
-/** State of Modal.Root / Drawer.Root: open (controlled or not), the dismiss policy and the guard. */
-export declare function useDialogRoot({ open, defaultOpen, onOpenChange, closeOnEscape, closeOnOutsideClick, closeLabel, discardLabels, confirmOnEnter, onEnterConfirm, }: DialogRootOptions): DialogRootState;
+declare const DialogRootProvider: React.Provider<DialogRootState | null>;
+export { DialogRootProvider };
+/**
+ * State of Modal.Root / Drawer.Root / Sheet.Root: open (controlled or not), the dismiss policy, the
+ * labels and the guard.
+ */
+export declare function useDialogRoot({ open, defaultOpen, onOpenChange, closeOnEscape, closeOnOutsideClick, labels: labelsProp, confirmOnEnter, onEnterConfirm, }: DialogRootOptions): DialogRootState;
 /**
- * Registers a guard from inside the content (`Modal.Guard`, `Drawer.Guard`, ConfirmDialog while it
- * runs); it is lifted when the part unmounts.
+ * Registers a guard from inside the content (`Modal.Guard`, `Drawer.Guard`, `Sheet.Guard`,
+ * ConfirmDialog while it runs); it is lifted when the part unmounts.
  */
 export declare function useDialogGuard({ busy, dirty }: DialogGuardState): DialogRootState;
+/** Footer actions: `fill` — equal-width buttons in one row; `end` — auto-width, right-aligned. */
+type DialogFooterLayout = "fill" | "end";
 /**
- * The modal layer of a Modal / Drawer panel: Escape and scrim clicks ask to close per the Root's
- * `closeOnEscape` / `closeOnOutsideClick` (and its guard); focus returns to the opener
- * (foundation §8).
+ * When the panel is a bottom sheet that swipes down to close: `never` (Drawer, a Modal near the
+ * top), `compact` (a centred Modal on a viewport below 640px), `always` (Sheet).
  */
-export declare function useDialogLayer<T extends HTMLElement>({ open, requestClose, closeOnEscape, closeOnOutsideClick, }: DialogRootState): {
-    onClose: () => void;
-    ref: React.RefObject<T | null>;
-    layer: import("../../internal/overlay/layerStack").LayerEntry;
-};
+type DialogSwipe = "never" | "compact" | "always";
 /**
- * The content of a closing dialog: while the exit motion plays it keeps showing the last children
- * it had open, so a record cleared together with `open` does not empty the panel mid-motion.
+ * Which dialog the panel is: it picks the side padding of the zones (`--prime-<kind>-padding`) and
+ * the enter / exit motion while the panel is not a bottom sheet (a drawer slides from its side).
  */
-export declare function useExitSnapshot<T>(open: boolean, children: T): T;
-/** Class for the `role="dialog"` element: hairline tokens and the `prime-dialog` container. */
-export declare const dialogShellClassName: string;
-/** Footer actions: `fill` — equal-width buttons in one row; `end` — auto-width, right-aligned. */
-export type DialogFooterLayout = "fill" | "end";
-type DialogShellContextValue = {
-    titleId: string;
-    descriptionId: string;
-    hasDescription: boolean;
-    registerTitle: (present: boolean) => void;
-    registerDescription: (present: boolean) => void;
-    onClose: () => void;
-    closeLabel: string;
-    /** The guard is busy: the close button stays in place, disabled. */
-    busy: boolean;
+type DialogKind = "modal" | "drawer" | "sheet";
+type DialogPanelProps = React.HTMLAttributes<HTMLDivElement> & {
+    kind: DialogKind;
+    /** The component's own panel class: its geometry and width tiers. */
+    panelClassName: string;
+    swipe: DialogSwipe;
     footerLayout: DialogFooterLayout;
-    /** Enter-confirm target (Modal only). */
-    confirmRef?: React.MutableRefObject<HTMLElement | null>;
-};
-type UseDialogShellOptions = {
-    ariaLabel?: string;
-    ariaLabelledBy?: string;
-    ariaDescribedBy?: string;
-    onClose: () => void;
-    closeLabel: string;
-    busy: boolean;
-    footerLayout: DialogFooterLayout;
-    confirmRef?: React.MutableRefObject<HTMLElement | null>;
-};
-/** Builds the shell context and the resolved `aria-*` for the `role="dialog"` element. */
-export declare function useDialogShellValue({ ariaLabel, ariaLabelledBy, ariaDescribedBy, onClose, closeLabel, busy, footerLayout, confirmRef, }: UseDialogShellOptions): {
-    value: DialogShellContextValue;
-    aria: {
-        "aria-label": string | undefined;
-        "aria-labelledby": string | undefined;
-        "aria-describedby": string | undefined;
-    };
+    /** Portal target. Default `document.body`. */
+    container?: HTMLElement | null;
+    /** Class on the full-screen scrim. */
+    overlayClassName?: string;
+    /** Enter clicks the action in `Confirm` (Modal: per the Root's `confirmOnEnter`). */
+    enterConfirm?: boolean;
+    /** The tier of the controls inside (Modal: `m`); without it they keep the surrounding tier. */
+    controlSize?: ControlSize;
+    ref?: React.Ref<HTMLDivElement>;
 };
-export declare function DialogShellProvider({ value, children, }: {
-    value: DialogShellContextValue;
-    children: React.ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+/**
+ * The panel of a dialog: portaled while open and during its exit motion (showing the children it
+ * had open), the scrim and the `role="dialog"` panel side by side, the modal layer (Escape and the
+ * scrim ask the Root to close through its guard; focus returns to the opener, foundation §8), and
+ * on a bottom sheet the grab handle and the swipe down — a guarded swipe asks first.
+ */
+export declare function DialogPanel({ container, children, ...props }: DialogPanelProps): import("react/jsx-runtime").JSX.Element | null;
 export type DialogIconProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
-    /** Soft fill + text color of the role. Default `neutral`. Not used around a picture. */
+    /**
+     * Soft fill and icon color; not used around a picture.
+     */
     tone?: Tone;
     /**
-     * An `Icon` in a filled box of the role, or the record's picture — an `Avatar.Root` (sized to
-     * the box) or a `Thumbnail.Root` — with no box of its own.
+     * An `Icon` (sized to the m icon), or the record's picture: an `Avatar.Root` (sized to the tile) or a `Thumbnail.Root`.
      */
     children: React.ReactNode;
     ref?: React.Ref<HTMLSpanElement>;
@@ -153,8 +156,7 @@ export declare namespace DialogDescription {
 }
 export type DialogHeaderProps = React.HTMLAttributes<HTMLElement> & {
     /**
-     * Built-in close button (square ghost `s`, `labels.close`). Default `true`. While a `Guard` is
-     * `busy` it stays in place, disabled.
+     * Built-in square ghost `s` close button named by `labels.close`; disabled in place while a `Guard` is `busy`.
      */
     showClose?: boolean;
     ref?: React.Ref<HTMLElement>;
@@ -187,7 +189,9 @@ export declare namespace DialogBody {
     var displayName: string;
 }
 export type DialogFooterProps = React.HTMLAttributes<HTMLElement> & {
-    /** `fill` — equal-width buttons; `end` — auto width, right-aligned. Default depends on the container. */
+    /**
+     * `fill`: equal-width buttons in one row; `end`: auto width, at the end. Stacked on phones (viewport below 640 px) and in a dialog narrower than 360 px.
+     */
     layout?: DialogFooterLayout;
     ref?: React.Ref<HTMLElement>;
 };
@@ -207,21 +211,13 @@ export declare function DialogMeta({ className, ...rest }: DialogMetaProps): imp
 export declare namespace DialogMeta {
     var displayName: string;
 }
-type SlotChild = React.ReactElement<{
-    onClick?: React.MouseEventHandler;
-    ref?: React.Ref<HTMLElement>;
-}>;
-export type DialogTriggerProps = {
-    children: SlotChild;
-};
+export type DialogTriggerProps = SlotPartProps;
 /** Adds "open the dialog" to the child's click (unless the child prevents default). */
 export declare function DialogTrigger({ children }: DialogTriggerProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace DialogTrigger {
     var displayName: string;
 }
-export type DialogCloseProps = {
-    children: SlotChild;
-};
+export type DialogCloseProps = SlotPartProps;
 /**
  * Adds "close the dialog" to the child's click (unless the child prevents default); the close
  * goes through the guard, and the child is `disabled` while the guard is busy.
@@ -230,10 +226,11 @@ export declare function DialogClose({ children }: DialogCloseProps): import("rea
 export declare namespace DialogClose {
     var displayName: string;
 }
-export type DialogConfirmProps = {
-    children: SlotChild;
-};
-/** Marks the primary action: Enter inside the dialog clicks it (`confirmOnEnter`). */
+export type DialogConfirmProps = SlotPartProps;
+/**
+ * Marks the primary action as the Enter target (`confirmOnEnter`): Enter inside the dialog clicks
+ * it. It adds no handler of its own; the child's `onClick` (or its `type="submit"`) is the action.
+ */
 export declare function DialogConfirm({ children }: DialogConfirmProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace DialogConfirm {
     var displayName: string;

package/dist/internal/overlay/FloatingPanel.d.ts

@@ -1,7 +1,22 @@
 import type * as React from "react";
+import { type SwipeDismiss } from "../../hooks/useSwipeDismiss";
 import type { ControlSize } from "../states";
 import type { FloatingLayer } from "./useFloatingLayer";
-export type FloatingPanelProps = Omit<React.HTMLAttributes<HTMLElement>, "onAnimationEnd"> & {
+/**
+ * The grab bar of a bottom sheet (Sheet, a Modal or a floating layer as a phone sheet): drawn only
+ * while the swipe exists, `aria-hidden` (the gesture is an extra way out next to Escape and the
+ * scrim). The drag starts on it or on the header right after it.
+ */
+export declare function SheetHandle({ swipe }: {
+    swipe: Pick<SwipeDismiss, "enabled">;
+}): import("react/jsx-runtime").JSX.Element | null;
+/** How wide an anchored panel is (`data-width` on the floating surface). */
+export type FloatingWidth = "auto" | "trigger" | "content";
+/**
+ * The panel is a `<div>`; `E` is the element type its consumer holds it as (a menu, a listbox:
+ * `HTMLElement`), so the consumer ref needs no cast.
+ */
+type FloatingPanelProps<E extends HTMLElement = HTMLDivElement> = Omit<React.HTMLAttributes<HTMLDivElement>, "onAnimationEnd"> & {
     floating: FloatingLayer;
     /** Tier of the panel (`data-size`) and of the controls inside. */
     size: ControlSize;
@@ -9,7 +24,13 @@ export type FloatingPanelProps = Omit<React.HTMLAttributes<HTMLElement>, "onAnim
     scroll?: boolean;
     /** The raised floating surface (radius, shadow, fill). Default `true`. */
     surface?: boolean;
-    ref?: React.Ref<HTMLElement>;
+    /**
+     * `auto` — the content's width between the panel minimum (or the trigger's width) and twice the
+     * minimum; `trigger` — exactly the trigger's width; `content` — what the content needs, within
+     * the viewport. A bottom sheet is always full width.
+     */
+    width?: FloatingWidth;
+    ref?: React.Ref<E>;
 };
 /**
  * The panel of a floating layer: portaled to `<body>` when it opens (so it stacks above every
@@ -17,10 +38,10 @@ export type FloatingPanelProps = Omit<React.HTMLAttributes<HTMLElement>, "onAnim
  * `data-side` (foundation §8), a size context for the controls inside, and a layer context so
  * layers opened inside stack above it in the layer stack. Renders nothing while closed. A layer in
  * sheet mode (`floating.sheet`) renders a scrim and a bottom sheet with a grab handle around the
- * same panel element; the consumer ref stays on the panel.
+ * same panel element, which then carries `data-sheet`; the consumer ref stays on the panel.
  */
-export declare function FloatingPanel({ floating, size, scroll, surface, className, onKeyDown, children, ref, ...rest }: FloatingPanelProps): import("react/jsx-runtime").JSX.Element | null;
-export type FloatingTriggerProps = {
+export declare function FloatingPanel<E extends HTMLElement = HTMLDivElement>({ floating, size, scroll, surface, width, className, onKeyDown, children, ref, ...rest }: FloatingPanelProps<E>): import("react/jsx-runtime").JSX.Element | null;
+type FloatingTriggerProps = {
     /** Props of the layer for its trigger: `ref`, ARIA, handlers, `data-state`. */
     triggerProps: Record<string, unknown> & {
         ref?: React.Ref<HTMLElement>;
@@ -34,3 +55,4 @@ export type FloatingTriggerProps = {
  * `aria-describedby` ids join, the child's own props win.
  */
 export declare function FloatingTrigger({ triggerProps, children, ...forwarded }: FloatingTriggerProps): import("react/jsx-runtime").JSX.Element;
+export {};