prime-ui-kit 0.15.0 → 0.17.0

package/dist/components/dnd/Dnd.d.ts

@@ -1,82 +1,127 @@
 import * as React from "react";
+import type { AsyncHandler } from "../../internal/usePendingChanges";
 import { type DragItem, type DragOutcome } from "./dragSession";
 import { type Point, type Rect } from "./geometry";
 import { type DndLabels } from "./labels";
 export type { DragItem, DragOutcome } from "./dragSession";
 export type { DndLabels } from "./labels";
+/** Applies a reorder to an array; hosts of `Dnd.Sortable` (FieldList) take it from this module. */
+export { moveBefore } from "./useSortableList";
+/**
+ * Set on a `Dnd.Sortable` while an item of its kind is carried: the list may take it. A host scopes
+ * its drag-time look to it (no hover-only actions, no snapping in the scroller around the list).
+ */
+export declare const DND_CARRYING_ATTRIBUTE = "data-dnd-carrying";
 export type DndRootProps = {
-    /** Built-in strings (live region, handle, role description). Russian defaults. */
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<DndLabels>;
+    /**
+     * The app or the screen that drags.
+     */
     children?: React.ReactNode;
 };
 /**
  * Owns the one drag session the app shares, the overlay that follows the pointer and the live
- * region. Mount once above every screen that drags: a drag crosses component boundaries.
+ * region. Mount once above every screen that drags: a drag crosses component boundaries. A root
+ * inside another one is its children: the outer session stays the one session.
  */
-declare function DndRoot({ labels, children }: DndRootProps): import("react/jsx-runtime").JSX.Element;
+declare function DndRoot(props: DndRootProps): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
 declare namespace DndRoot {
     var displayName: string;
 }
+/**
+ * The live region of the drag session above, for a host that announces its own changes of the same
+ * items (a FileUpload set of tiles): one region speaks them in order. `null` without a `Dnd.Root`.
+ */
+export declare function useDragAnnouncer(): ((message: string) => void) | null;
 export type DndHandleProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children"> & {
-    ref?: React.Ref<HTMLButtonElement>;
+    ref?: React.Ref<HTMLElement>;
 };
+/**
+ * Whether the owner is still saving the move of the `Dnd.SortableItem` around (its `onReorder`
+ * promise): for a host that draws the busy state inside the item itself (a card's spinner).
+ */
+export declare function useSortableItemBusy(): boolean;
+export type DndLockProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children" | "role"> & {
+    ref?: React.Ref<HTMLSpanElement>;
+};
+/**
+ * The mark of a thing that holds its place (a pinned row, a system column): the lock a `Dnd.Handle`
+ * turns into in a `locked` item, and the same mark where a host shows a fixed row without a grip
+ * (FieldList). Named `labels.locked` unless the host names it.
+ */
+export declare function DndLock({ className, "aria-label": ariaLabel, ...rest }: DndLockProps): import("react/jsx-runtime").JSX.Element;
 /**
  * The grip of a `handle` item: a ghost icon-only Button (`xs`), so it is reachable by keyboard
- * (Alt+arrows reorder). In a `locked` item it is a lock (`labels.locked`) instead.
+ * (Alt+arrows reorder) and carries the item's key shortcuts and role description. In a `locked`
+ * item it is a `Dnd.Lock` instead; while the owner saves the item's move it is busy.
  */
 declare function DndHandle({ className, "aria-label": ariaLabel, ref, ...rest }: DndHandleProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DndHandle {
     var displayName: string;
 }
 export type DndSortableProps<T> = Omit<React.HTMLAttributes<HTMLElement>, "children"> & {
-    /** Items in their current order. */
+    /**
+     * Items in their current order.
+     */
     items: readonly T[];
-    /** Stable unique id of an item. */
+    /**
+     * Stable unique id; must match `Dnd.SortableItem id`.
+     */
     getId: (item: T) => string;
-    /** Spoken by the live region ("Задача 3: позиция 2 из 5"). Defaults to the id. */
+    /**
+     * Spoken by the live region.
+     */
     getLabel?: (item: T) => string;
     /**
-     * Called when an item lands in front of `beforeId` (`null` = last). A returned promise keeps the
-     * item drawn in its new place until it settles; a rejection glides it back.
+     * Item `id` lands in front of `beforeId` (`null` = last), maybe from a linked list. Apply it with `moveBefore`; a returned promise keeps the item still and busy until it settles, a rejection moves it back.
      */
-    onReorder: (id: string, beforeId: string | null) => void | Promise<void>;
+    onReorder: AsyncHandler<[id: string, beforeId: string | null]>;
     /**
-     * Renders one item; return a `Dnd.SortableItem`. During a drag `index` is the place the item will
-     * have on release. Parts marked `data-dnd-mirror` stay in step on the carried copy.
+     * Returns a `Dnd.SortableItem`. During a drag `index` is the place the item will have on release, so a shown position follows the gap; parts marked `data-dnd-mirror` stay in step on the carried copy.
      */
     renderItem: (item: T, index: number) => React.ReactNode;
-    /** Layout of the list: a column, a row, or a wrapping grid (reading order, Alt + ← / →). */
+    /**
+     * A column, a single row, or a wrapping grid (`display: grid`; the host sets the tracks and the cells' size, the gap takes a cell). Keyboard: Alt + ↑ / ↓ in a column, Alt + ← / → in a row and a grid.
+     */
     axis?: "x" | "y" | "grid";
-    /** Only `Dnd.Handle` starts a drag; the rest of the item stays free for clicks and text selection. */
+    /**
+     * Only `Dnd.Handle` starts a drag; the rest of the item stays free for clicks and text selection.
+     */
     handle?: boolean;
+    /**
+     * No drag, no keyboard reorder.
+     */
     disabled?: boolean;
     /**
-     * Drag kind. Lists sharing a `kind` exchange items: an item dropped from another list arrives in
-     * `onReorder` with an `id` that is not in `items` (move it into this list), and Alt + the arrows
-     * across the axis move an item to the neighbouring list of the kind (document order). Defaults to
-     * a unique value per list, so lists stay separate.
+     * Lists sharing a `kind` exchange items (a board): an item from another list arrives in `onReorder` with an `id` not in `items`. Alt + the arrows across the axis move it by keyboard. Name each list: it is spoken.
      */
     kind?: string;
     /**
-     * Refuses an item (by id) the list would otherwise take: `false`, or a string that says why — it
-     * is spoken and shown under the carried copy. The list turns `danger` before the release.
+     * Refuses an item by id: `false`, or a string that says why (spoken and shown under the carried copy). The list turns `danger` before the release.
      */
     canDrop?: (id: string) => boolean | string;
-    /** Shown while the list has no items; a gap opening in the list takes its place. */
+    /**
+     * Shown while the list has no items, inside a dashed drop slot while the list takes drops; fades out when a gap opens in the list, so the gap takes its place.
+     */
     empty?: React.ReactNode;
     /**
-     * Root element: `ul` / `ol` turn items into `li`; `tbody` turns them into table rows (`tr`), the
-     * gap into a row across every column, and the carried copy keeps every cell's width.
+     * Root element; `ul` / `ol` render items as `li`, `tbody` as table rows `tr` (the gap is a row across every column, the carried copy keeps every cell's width).
      */
     as?: "div" | "ul" | "ol" | "tbody";
-    /** Accessible name of the list. */
+    /**
+     * Accessible name of the list.
+     */
     "aria-label"?: string;
     /**
-     * Content in front of the items that never moves and takes no drop position (the heading row of
-     * a group of table rows).
+     * Content in front of the items that never moves and takes no drop position: the heading row of a group in a `tbody`.
      */
     header?: React.ReactNode;
-    /** Content after the items that never moves and takes no drop position (an add tile). */
+    /**
+     * Content after the items that never moves and takes no drop position: an add tile at the end of a grid. Inside `ul` / `ol` it must be `li`.
+     */
     children?: React.ReactNode;
     ref?: React.Ref<HTMLElement>;
 };
@@ -89,38 +134,80 @@ declare namespace DndSortable {
     var displayName: string;
 }
 export type DndSortableItemProps = {
-    /** Must match `getId` of the item. */
+    /**
+     * The item id (same as `getId`).
+     */
     id: string;
+    /**
+     * This item cannot be dragged or moved (others may still move past it).
+     */
     disabled?: boolean;
     /**
-     * Holds its place: it does not drag or move, and nothing is put where it would shift it (a
-     * pinned first row, a system column). Its `Dnd.Handle` shows a lock.
+     * Holds its place: it does not move and nothing is put where it would shift it. Its `Dnd.Handle` turns into a lock. A pinned first row, a system column.
      */
     locked?: boolean;
+    /**
+     * The row look: fill, radius, padding.
+     */
     className?: string;
+    /**
+     * The row content.
+     */
     children?: React.ReactNode;
     ref?: React.Ref<HTMLElement>;
 } & Omit<React.HTMLAttributes<HTMLElement>, "id">;
-/** One item of a `Dnd.Sortable`. Renders `li` inside `ul` / `ol`, `tr` inside `tbody`, `div` otherwise. */
+/**
+ * One item of a `Dnd.Sortable`. Renders `li` inside `ul` / `ol`, `tr` inside `tbody`, `div` otherwise.
+ * The item is the keyboard target (a `div` one is a named `button`), or with `handle` its grip is.
+ */
 declare function DndSortableItem({ id, disabled: itemDisabled, locked, className, children, onPointerDown, onKeyDown, onDragStart, ref, ...rest }: DndSortableItemProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DndSortableItem {
     var displayName: string;
 }
 export type DndDraggableProps<TData = unknown> = {
-    /** What is dragged; a `Dnd.DropZone` accepts it by kind. */
+    /**
+     * What it is; zones accept by kind.
+     */
     kind: string;
+    /**
+     * Unique within its kind.
+     */
     id: string;
-    /** Payload handed to the drop target. */
+    /**
+     * Payload handed to the zone's `onDrop`.
+     */
     data?: TData;
-    /** Spoken by the live region. Defaults to the id. */
+    /**
+     * Spoken by the live region.
+     */
     label?: string;
+    /**
+     * Not draggable.
+     */
     disabled?: boolean;
-    /** Only `Dnd.Handle` starts a drag. */
+    /**
+     * Only a `Dnd.Handle` inside starts the drag.
+     */
     handle?: boolean;
+    /**
+     * Element.
+     */
     as?: "div" | "li" | "span" | "article" | "section";
+    /**
+     * Fired once the press became a drag.
+     */
     onDragStart?: (item: DragItem<TData>, point: Point, origin: Rect) => void;
+    /**
+     * Always fired at the end.
+     */
     onDragEnd?: (item: DragItem<TData>, outcome: DragOutcome) => void;
+    /**
+     * Class on the item.
+     */
     className?: string;
+    /**
+     * The item content.
+     */
     children?: React.ReactNode;
     ref?: React.Ref<HTMLElement>;
 } & Omit<React.HTMLAttributes<HTMLElement>, "id" | "onDragStart" | "onDragEnd">;
@@ -130,26 +217,50 @@ declare namespace DndDraggable {
     var displayName: string;
 }
 export type DndDropZoneProps<TData = unknown> = {
-    /** Drag kinds this zone takes, or a predicate over the dragged item. */
+    /**
+     * Kinds it takes, or a predicate.
+     */
     accepts: string | readonly string[] | ((item: DragItem) => boolean);
+    /**
+     * An accepted item landed.
+     */
     onDrop: (item: DragItem<TData>) => void;
     /**
-     * Refuses an item the zone would otherwise take: `false`, or a string that says why (spoken and
-     * shown under the carried copy). The zone turns `danger` before the release.
+     * Refuses an item: `false`, or a string that says why (spoken, and shown under the carried copy); the zone turns `danger` before the release.
      */
     canDrop?: (item: DragItem<TData>) => boolean | string;
+    /**
+     * An accepted item came over / left.
+     */
     onEnter?: (item: DragItem<TData>) => void;
+    /**
+     * An accepted item came over / left.
+     */
     onLeave?: () => void;
-    /** Flashes the zone after a drop, so the eye can follow where the item went. */
+    /**
+     * Flashes the zone after a drop, so the eye can follow where the item went.
+     */
     flashOnDrop?: boolean;
+    /**
+     * Not a target.
+     */
     disabled?: boolean;
+    /**
+     * Element.
+     */
     as?: "div" | "section" | "li" | "ul" | "ol" | "span";
+    /**
+     * The zone look.
+     */
     className?: string;
+    /**
+     * The zone content.
+     */
     children?: React.ReactNode;
     ref?: React.Ref<HTMLElement>;
 } & Omit<React.HTMLAttributes<HTMLElement>, "onDrop">;
 /** A box that takes dropped items. `data-dnd-over` / `data-dnd-reject` / `data-dnd-flash` mirror its state. */
-declare function DndDropZone<TData = unknown>({ accepts, onDrop, canDrop, onEnter, onLeave, flashOnDrop, disabled, as: Tag, className, children, onAnimationEnd, ref: forwardedRef, ...rest }: DndDropZoneProps<TData>): import("react/jsx-runtime").JSX.Element;
+declare function DndDropZone<TData = unknown>({ accepts, onDrop, canDrop, onEnter, onLeave, flashOnDrop, disabled, as: Tag, className, children, ref: forwardedRef, ...rest }: DndDropZoneProps<TData>): import("react/jsx-runtime").JSX.Element;
 declare namespace DndDropZone {
     var displayName: string;
 }

package/dist/components/dnd/geometry.d.ts

@@ -13,14 +13,6 @@ export type Rect = {
 /** `grid`: items wrap into rows (reading order: row by row, start to end inside a row). */
 export type Axis = "x" | "y" | "grid";
 export declare function rectOf(element: Element): Rect;
-/**
- * Where an element sits in the layout with any animation transform taken back out — its glide and
- * its growth (a tile growing into the cover cell is drawn smaller until it gets there). Every drop
- * decision is measured against this: reading the drawn box makes each answer depend on the
- * animation the previous answer started, and the gap swings between cells under a pointer that
- * barely moves.
- */
-export declare function layoutRect(element: Element): Rect;
 export declare function rectContains(rect: Rect, point: Point): boolean;
 export declare function distanceBetween(a: Point, b: Point): number;
 /** Marks the gap a sortable list opens where the dragged item will land. */

package/dist/components/dnd/labels.d.ts

@@ -26,4 +26,4 @@ export type DndLabels = {
     /** Live region: a target refused the item and said why (`canDrop` answered a string). */
     refusedReason: string;
 };
-export declare const defaultDndLabels: DndLabels;
+export declare const DND_LABELS: DndLabels;

package/dist/components/dnd/useDropTarget.d.ts

@@ -28,8 +28,6 @@ export type DropTargetProps = {
     "data-dnd-over"?: true | undefined;
     "data-dnd-reject"?: true | undefined;
     "data-dnd-flash"?: true | undefined;
-    /** Ends the drop flash when its animation finishes. */
-    onAnimationEnd: (event: React.AnimationEvent<HTMLElement>) => void;
 };
 export type DropTargetHandle = {
     /** The id the target registered under; `DragSnapshot.overId` names it while the pointer is over. */

package/dist/components/dnd/useSortableList.d.ts

@@ -1,4 +1,5 @@
 import * as React from "react";
+import { type AsyncHandler } from "../../internal/usePendingChanges";
 import type { DropVerdict } from "./dragSession";
 import { type Axis } from "./geometry";
 import { type DragSourceProps } from "./useDragSource";
@@ -23,7 +24,7 @@ export type SortableListOptions = {
     items: readonly string[];
     labelOf: (id: string) => string;
     /** A returned promise keeps the move drawn until it settles; a rejection glides it back. */
-    onReorder: (id: string, beforeId: string | null) => void | Promise<void>;
+    onReorder: AsyncHandler<[id: string, beforeId: string | null]>;
     axis?: Axis | undefined;
     disabled?: boolean | undefined;
     /** Refuses an item of this kind (typically one from another list); a string says why. */
@@ -48,6 +49,10 @@ export type SortableListHandle = {
         radius: string | null;
     } | null;
     isOver: boolean;
+    /** A drag of the list's kind is in flight: the list may take the item. */
+    carrying: boolean;
+    /** Items whose move the owner is still saving (a promise from `onReorder`). */
+    pending: ReadonlySet<string>;
     /**
      * The order to DRAW: `items`, except right after a drop, when the owner answers a beat later and
      * drawing the old order until then would snap the item back and then jump again.

package/dist/components/drawer/Drawer.d.ts

@@ -1,40 +1,61 @@
-import * as React from "react";
-import { DialogGuard } from "../modal/DialogGuard";
-import { DialogActions, DialogBody, DialogClose, DialogDescription, type DialogDiscardLabels, DialogFooter, DialogHeader, DialogIcon, DialogMeta, DialogTitle, DialogTrigger } from "../modal/DialogParts";
-import type { ControlSize } from "../../internal/states";
-export type { DialogGuardProps as DrawerGuardProps } from "../modal/DialogGuard";
-export type { DialogActionsProps as DrawerActionsProps, DialogBodyProps as DrawerBodyProps, DialogCloseProps as DrawerCloseProps, DialogDescriptionProps as DrawerDescriptionProps, DialogFooterProps as DrawerFooterProps, DialogHeaderProps as DrawerHeaderProps, DialogIconProps as DrawerIconProps, DialogMetaProps as DrawerMetaProps, DialogTitleProps as DrawerTitleProps, DialogTriggerProps as DrawerTriggerProps, } from "../modal/DialogParts";
+import type * as React from "react";
+import { DialogGuard } from "../../internal/overlay/DialogGuard";
+import { DialogActions, DialogBody, DialogClose, DialogDescription, DialogFooter, DialogHeader, DialogIcon, type DialogLabels, DialogMeta, DialogTitle, DialogTrigger } from "../../internal/overlay/DialogParts";
+import { type ControlSize } from "../../internal/states";
+export type { DialogGuardProps as DrawerGuardProps } from "../../internal/overlay/DialogGuard";
+export type { DialogActionsProps as DrawerActionsProps, DialogBodyProps as DrawerBodyProps, DialogCloseProps as DrawerCloseProps, DialogDescriptionProps as DrawerDescriptionProps, DialogFooterProps as DrawerFooterProps, DialogHeaderProps as DrawerHeaderProps, DialogIconProps as DrawerIconProps, DialogMetaProps as DrawerMetaProps, DialogTitleProps as DrawerTitleProps, DialogTriggerProps as DrawerTriggerProps, } from "../../internal/overlay/DialogParts";
 export type DrawerSide = "left" | "right";
-export type DrawerLabels = DialogDiscardLabels & {
-    /** `aria-label` of the header close button. */
-    close: string;
-};
+export type DrawerLabels = DialogLabels;
 export type DrawerRootProps = {
+    /**
+     * 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 drawer. Default `true`. */
+    /**
+     * Escape closes the dialog.
+     */
     closeOnEscape?: boolean;
-    /** A click on the scrim closes the drawer. Default `true`. */
+    /**
+     * A click on the scrim closes the dialog. A destructive action is confirmed in a ConfirmDialog; unsaved changes are held by `Guard`.
+     */
     closeOnOutsideClick?: boolean;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<DrawerLabels>;
+    /**
+     * Trigger and Content.
+     */
     children?: React.ReactNode;
 };
-declare function DrawerRoot({ labels, children, ...options }: DrawerRootProps): import("react/jsx-runtime").JSX.Element;
+declare function DrawerRoot({ children, ...options }: DrawerRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DrawerRoot {
     var displayName: string;
 }
 export type DrawerContentProps = React.HTMLAttributes<HTMLDivElement> & {
-    /** Edge the panel slides from. Default `right`. */
+    /**
+     * Edge the panel slides from; rounded only on the edge facing the page. No swipe: the drawer closes by its buttons, Escape and the scrim. A panel from the bottom edge is a Sheet.
+     */
     side?: DrawerSide;
-    /** Panel width: `s` 360 · `m` 480 · `l` 640 · `xl` 800. Full width below 640px of viewport. */
+    /**
+     * Width: 360 · 480 · 640 · 800. Below 640 px of viewport — full width, without corners.
+     */
     size?: Exclude<ControlSize, "xs">;
-    /** Class on the full-screen scrim. */
+    /**
+     * Class on the scrim.
+     */
     overlayClassName?: string;
-    /** The `role="dialog"` panel. */
     ref?: React.Ref<HTMLDivElement>;
 };
-declare function DrawerContent({ children, ...props }: DrawerContentProps): import("react/jsx-runtime").JSX.Element | null;
+declare function DrawerContent({ side, size, ...props }: DrawerContentProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DrawerContent {
     var displayName: string;
 }

package/dist/components/dropdown/Dropdown.d.ts

@@ -1,37 +1,78 @@
 import * as React from "react";
-import { type PositionAlign, type PositionSide } from "../../hooks/usePosition";
+import { type AnchorPoint, type PositionAlign, type PositionSide } from "../../hooks/usePosition";
 import { type MenuGroupProps } from "../../internal/MenuGroup";
-import type { ControlSize, Tone } from "../../internal/states";
+import { type SlotPartProps } from "../../internal/slot";
+import { type ControlSize, type Tone } from "../../internal/states";
 export type DropdownRootProps = {
+    /**
+     * Controlled visibility; together with `onOpenChange`.
+     */
     open?: boolean;
+    /**
+     * Initial visibility, uncontrolled.
+     */
     defaultOpen?: boolean;
+    /**
+     * Called on every open and close: trigger, item pick, Escape, outside press, code.
+     */
     onOpenChange?: (open: boolean) => void;
-    /** A pointerdown outside the menu and its trigger closes it. Default `true`. */
+    /**
+     * A pointerdown outside the menu and its trigger closes it; focus follows the pointer.
+     */
     closeOnOutsideClick?: boolean;
-    /** Escape closes the menu. Default `true`. */
+    /**
+     * Escape closes the menu and returns focus to the trigger.
+     */
     closeOnEscape?: boolean;
+    /**
+     * A point inside the trigger or `Dropdown.Anchor` (px from its top-left corner) the menu opens at: a context menu at the pointer. It moves with the element on scroll.
+     */
+    anchorPoint?: AnchorPoint | null;
+    /**
+     * Trigger (or Anchor) and Content.
+     */
     children: React.ReactNode;
 };
-declare function DropdownRoot({ open, defaultOpen, onOpenChange, closeOnOutsideClick, closeOnEscape, children, }: DropdownRootProps): import("react/jsx-runtime").JSX.Element;
+declare function DropdownRoot({ open, defaultOpen, onOpenChange, closeOnOutsideClick, closeOnEscape, anchorPoint, children, }: DropdownRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DropdownRoot {
     var displayName: string;
 }
-export type DropdownTriggerProps = {
-    /** The element that opens the menu (usually a Button); it receives ref, ARIA and the click handler. */
-    children: React.ReactElement;
-    ref?: React.Ref<HTMLElement>;
-} & Omit<React.HTMLAttributes<HTMLElement>, "children">;
-/** Other props (handlers, ARIA, `ref`) are forwarded to the child, e.g. from a wrapping `Tooltip.Trigger`. */
-declare function DropdownTrigger({ children, ...forwarded }: DropdownTriggerProps): import("react/jsx-runtime").JSX.Element;
+export type DropdownTriggerProps = SlotPartProps;
+/**
+ * Wraps the element that opens the menu (usually a Button): it receives the ref, the ARIA, the
+ * click and the arrow keys (WAI-ARIA menu button). Props a wrapping trigger adds
+ * (`Tooltip.Trigger`) pass on to the child.
+ */
+declare function DropdownTrigger(props: DropdownTriggerProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DropdownTrigger {
     var displayName: string;
 }
+export type DropdownAnchorProps = SlotPartProps;
+/**
+ * An anchor that is not a trigger: the element a context menu opens against (a row, a list) with
+ * `Dropdown.Root anchorPoint`, the open state driven by `Dropdown.Root open`. It adds no click
+ * handler and no ARIA; presses on it do not close the menu, and focus returns to it on close.
+ */
+declare function DropdownAnchor({ children }: DropdownAnchorProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DropdownAnchor {
+    var displayName: string;
+}
 export type DropdownContentProps = Omit<React.HTMLAttributes<HTMLElement>, "role"> & {
+    /**
+     * Preferred side; flips to the opposite side when there is no room.
+     */
     side?: PositionSide;
+    /**
+     * Alignment along the trigger. `auto` lines the menu up with the trigger edge that has more room beyond it; `start`, `center` or `end` fix the edge.
+     */
     align?: PositionAlign;
-    /** Row tier: item height, text, icon. */
+    /**
+     * Row tier of the menu.
+     */
     size?: ControlSize;
-    /** The menu is at least as wide as the trigger. */
+    /**
+     * The menu is at least as wide as the trigger.
+     */
     matchTriggerWidth?: boolean;
     ref?: React.Ref<HTMLDivElement>;
 };
@@ -40,27 +81,50 @@ declare namespace DropdownContent {
     var displayName: string;
 }
 export type DropdownItemProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "role" | "onSelect"> & {
-    /** Runs the action; the menu closes after it. */
+    /**
+     * The action of the item.
+     */
     onSelect?: () => void;
+    /**
+     * Muted and `disabled` (a link item: `aria-disabled`), skipped by the arrow keys; no handler runs, the item's own `onClick` included.
+     */
     disabled?: boolean;
-    /** `danger` — destructive action (delete, revoke). */
+    /**
+     * `danger`: destructive action — danger text, icon and hover fill.
+     */
     tone?: Extract<Tone, "neutral" | "danger">;
     /**
-     * The item is its single child, a link (`<a href>`, a router `Link`): the item props merge onto
-     * it, so Cmd / Ctrl-click and «open in a new tab» work. Its children are the item content.
+     * The item is its single child link (`<a href>`, a router `Link`), so Cmd / Ctrl-click and «open in a new tab» work; the pick still closes the menu.
      */
     asChild?: boolean;
     /** The item element: `<button>`, or the `asChild` element. */
     ref?: React.Ref<HTMLButtonElement>;
 };
+/**
+ * An item is no tab stop (`tabIndex -1`): the menu moves focus between items with the arrow keys
+ * (roving focus), and Tab leaves the menu. A disabled item runs no handler at all, the consumer's
+ * `onClick` included (`InteractiveElement`).
+ */
 declare function DropdownItem({ onSelect, disabled, tone, asChild, className, onClick, children, ref, ...rest }: DropdownItemProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DropdownItem {
     var displayName: string;
 }
 export type DropdownCheckboxItemProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "role" | "onSelect" | "onChange" | "defaultChecked"> & {
+    /**
+     * Checked state (controlled).
+     */
     checked?: boolean;
+    /**
+     * Initial state (uncontrolled).
+     */
     defaultChecked?: boolean;
+    /**
+     * Called with the new state.
+     */
     onCheckedChange?: (checked: boolean) => void;
+    /**
+     * Muted and `disabled`, skipped by the arrow keys; no handler runs, the item's own `onClick` included.
+     */
     disabled?: boolean;
     ref?: React.Ref<HTMLButtonElement>;
 };
@@ -69,7 +133,7 @@ export type DropdownCheckboxItemProps = Omit<React.ButtonHTMLAttributes<HTMLButt
  * has it and a check mark at the end while checked, `role="menuitemcheckbox"`. Toggling keeps the
  * menu open, so several can be set in a row.
  */
-declare function DropdownCheckboxItem({ checked: checkedProp, defaultChecked, onCheckedChange, disabled, className, onClick, children, ...rest }: DropdownCheckboxItemProps): import("react/jsx-runtime").JSX.Element;
+declare function DropdownCheckboxItem({ checked: checkedProp, defaultChecked, onCheckedChange, disabled, className, onClick, children, ref, ...rest }: DropdownCheckboxItemProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DropdownCheckboxItem {
     var displayName: string;
 }
@@ -85,6 +149,9 @@ declare namespace DropdownItemIcon {
     var displayName: string;
 }
 export type DropdownItemShortcutProps = Omit<React.HTMLAttributes<HTMLElement>, "children"> & {
+    /**
+     * The keys («⌘D»).
+     */
     children: React.ReactNode;
     ref?: React.Ref<HTMLElement>;
 };
@@ -94,6 +161,9 @@ declare namespace DropdownItemShortcut {
     var displayName: string;
 }
 export type DropdownItemDescriptionProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "id"> & {
+    /**
+     * The sentence; it wraps inside the menu's width.
+     */
     children: React.ReactNode;
     ref?: React.Ref<HTMLSpanElement>;
 };
@@ -141,6 +211,7 @@ declare namespace DropdownHeader {
 export declare const Dropdown: {
     Root: typeof DropdownRoot;
     Trigger: typeof DropdownTrigger;
+    Anchor: typeof DropdownAnchor;
     Content: typeof DropdownContent;
     Header: typeof DropdownHeader;
     Title: typeof DropdownTitle;