@mortenbrudvik/waveui 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -2345,6 +2345,13 @@ export declare interface ComboboxProps<M extends boolean = false> extends Omit<R
      * listbox keeps its size.
      */
     size?: CoreSize;
+    /**
+     * Advanced positioning of the popup (Fluent's `positioning`): `offset`, `fitViewport`,
+     * `matchReferenceWidth` and `fallbackPlacements` (tried in order when the requested side has no
+     * room). The popup opens below the field.
+     * @default `{ matchReferenceWidth: true, fitViewport: true }`
+     */
+    positioning?: PopupPositioningOptions;
     /**
      * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
      * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
@@ -3239,6 +3246,13 @@ export declare interface DatePickerProps extends Omit<React_2.HTMLAttributes<HTM
      * calendar keeps its size.
      */
     size?: CoreSize;
+    /**
+     * Advanced positioning of the popup (Fluent's `positioning`): `offset`, `fitViewport`,
+     * `matchReferenceWidth` and `fallbackPlacements` (tried in order when the requested side has no
+     * room). The popup opens below the field.
+     * @default `{}`: the calendar opens 4px below the field
+     */
+    positioning?: PopupPositioningOptions;
     /**
      * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
      * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
@@ -3799,6 +3813,23 @@ export declare interface DialogTriggerRenderProps extends React_2.HTMLAttributes
     ref: React_2.RefCallback<HTMLElement>;
 }
 
+/** Returned by {@link useDismiss}. */
+export declare interface DismissLayer {
+    /** The layer's id: pass it to `Portal layerId` or `DismissLayerProvider` around the surface. */
+    layerId: string;
+    /** Whether the layer is currently the topmost open layer (read at call time). */
+    isTopmost(): boolean;
+}
+
+/**
+ * Makes `layerId` the parent layer of everything rendered inside (`Portal layerId` does this for
+ * its children automatically).
+ */
+export declare function DismissLayerProvider(props: {
+    layerId: string;
+    children: React_2.ReactNode;
+}): React_2.ReactElement;
+
 /** Why a popup layer is dismissed: Escape, a press outside it, or focus moving outside it. */
 export declare type DismissReason = 'escape' | 'outside-press' | 'focus-outside';
 
@@ -4697,6 +4728,13 @@ export declare interface DropdownProps<M extends boolean = false> extends Omit<R
      * listbox keeps its size; the multi-select value text and clear button follow it.
      */
     size?: CoreSize;
+    /**
+     * Advanced positioning of the popup (Fluent's `positioning`): `offset`, `fitViewport`,
+     * `matchReferenceWidth` and `fallbackPlacements` (tried in order when the requested side has no
+     * room). The popup opens below the field.
+     * @default `{ matchReferenceWidth: true, fitViewport: true }`
+     */
+    positioning?: PopupPositioningOptions;
     /**
      * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
      * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
@@ -5190,12 +5228,54 @@ export declare interface FlexOwnProps {
  */
 export declare type FlexProps<C extends React_2.ElementType = 'div'> = PolymorphicProps<C, FlexOwnProps>;
 
+/** Props to spread onto the group element (compose its handlers with your own). */
+export declare interface FocusableGroupProps {
+    /** The group is itself focusable. */
+    tabIndex: 0;
+    onKeyDown: React_2.KeyboardEventHandler<HTMLElement>;
+    onFocusCapture: React_2.FocusEventHandler<HTMLElement>;
+    /** Marks the element as a group: nested groups own their own contents. */
+    'data-focusable-group': '';
+}
+
+/** How Tab and Enter treat the elements inside a focusable group. */
+export declare type FocusableGroupTabBehavior = 'unlimited' | 'limited' | 'limited-trap-focus';
+
 /**
  * How the keyboard reaches the items of a set: `'tab'`, every item is a Tab stop and the arrow
  * keys do nothing; `'arrow'`, the set is one Tab stop and the arrow keys move between its items.
  */
 export declare type FocusMode = 'tab' | 'arrow';
 
+/** Focus-visible ring for focusable controls (C-FOCUS). */
+export declare const focusRing = "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring";
+
+/** Focus-visible ring drawn inside the element: cells, rows, list and menu items. */
+export declare const focusRingInset = "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-ring";
+
+/** The first tabbable element inside `container`, or `null`. */
+export declare function getFirstTabbable(container: Element, options?: {
+    includeContainer?: boolean;
+}): HTMLElement | null;
+
+/** The last tabbable element inside `container`, or `null`. */
+export declare function getLastTabbable(container: Element, options?: {
+    includeContainer?: boolean;
+}): HTMLElement | null;
+
+/**
+ * The tabbable elements inside `container` in sequential focus order: positive `tabindex` first
+ * (ascending), then `tabindex=0` / natively tabbable elements in document order. Named radio
+ * groups follow {@link isTabbable}, so the result depends on where focus currently is: when focus
+ * is on a radio, the rest of its group is left out, which makes the focused radio the last entry
+ * when its group ends the container (the element a focus trap wraps from).
+ *
+ * @param options.includeContainer Also consider `container` itself.
+ */
+export declare function getTabbableElements(container: Element, options?: {
+    includeContainer?: boolean;
+}): HTMLElement[];
+
 /**
  * The classes that select a theme's tokens: `'wave-light'`, `'wave-dark dark'` or
  * `'wave-high-contrast high-contrast'`. Unknown values fall back to the light classes. Safe to call
@@ -5246,6 +5326,13 @@ export declare const gridClassNames: {
     readonly root: "wave-grid";
 };
 
+/** Handlers {@link useGridNavigation} needs on the grid element (compose them with the consumer's). */
+export declare interface GridNavigationHandlers {
+    onKeyDown: React_2.KeyboardEventHandler<HTMLTableElement>;
+    onFocus: React_2.FocusEventHandler<HTMLTableElement>;
+    onBlur: React_2.FocusEventHandler<HTMLTableElement>;
+}
+
 /**
  * The Grid's own props (the XOwnProps rule of `PolymorphicProps`: component-specific props only).
  * Every other prop comes from the rendered element (`as`).
@@ -5339,6 +5426,13 @@ export declare interface HamburgerProps extends React_2.ButtonHTMLAttributes<HTM
     ref?: React_2.Ref<HTMLButtonElement>;
 }
 
+/**
+ * Whether a modal surface is open now: a layer of kind `'modal'` (a Dialog, an overlay Drawer, an
+ * alert, the DatePicker's calendar, or your own `useDismiss({ kind: 'modal' })`). A non-modal
+ * surface is no modal. Server-safe: `false` when no layer is registered, as on the server.
+ */
+export declare function hasOpenModal(): boolean;
+
 /** Level of a heading element, `<h1>` … `<h6>`. */
 export declare type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 
@@ -5732,6 +5826,20 @@ export declare interface InputErrorMessageProps extends React_2.HTMLAttributes<H
     [dataAttribute: `data-${string}`]: unknown;
 }
 
+/**
+ * Focus indicator of text-entry controls: a 2px primary bottom border. `focus:outline-hidden`
+ * removes the outline while focused but — unlike `outline-none` — keeps a visible outline in
+ * forced-colors mode, where the border colour change is not perceivable. (Scoped to `:focus` so
+ * unfocused inputs do not show that outline in forced colors.)
+ */
+export declare const inputFocus = "focus:outline-hidden focus:border-b-2 focus:border-b-primary";
+
+/**
+ * Wrapper form of {@link inputFocus} for inputs rendered inside a styled wrapper (slots,
+ * SearchBox, TagPicker). Put `focus:outline-hidden` on the inner control.
+ */
+export declare const inputFocusWithin = "focus-within:border-b-2 focus-within:border-b-primary";
+
 /** Properties for the Input component. */
 export declare interface InputProps extends Omit<React_2.InputHTMLAttributes<HTMLInputElement>, 'size'> {
     /**
@@ -6035,6 +6143,16 @@ export declare interface LabelProps extends React_2.LabelHTMLAttributes<HTMLLabe
     ref?: React_2.Ref<HTMLLabelElement>;
 }
 
+/**
+ * What kind of surface a layer is. `modal` marks dialog-like surfaces (focus-restore validation and
+ * modal isolation look for them); a modal blocks presses and Escape for the layers below it only
+ * while its page isolation is active ({@link registerLayerIsolation}). `dialog` marks a non-modal
+ * Dialog or Drawer: it shields nothing (no isolation), takes Escape only from inside its tree
+ * (`escape: 'inside'`), and the Toaster moves out of its way; focus-restore validation and modal
+ * isolation do not count it.
+ */
+export declare type LayerKind = 'modal' | 'dialog' | 'popover' | 'menu' | 'listbox' | 'tooltip' | 'toast';
+
 /**
  * A hyperlink with Fluent link styling. Renders an `<a>` by default; `as` renders a router link
  * (`<Link as={RouterLink} to="/">`) or a `<button>` styled as a link (`type="button"` by default).
@@ -6834,7 +6952,7 @@ export declare const Menu: {
         displayName: string;
     };
     Popover: {
-        ({ side, align, offset, target, children, className, style, onKeyDown, onKeyDownCapture, onFocus, onPointerEnter, onPointerLeave, onPointerMove, onContextMenu, ref, ...rest }: MenuPopoverProps): JSX.Element | null;
+        ({ side, align, offset, target: targetProp, positioning, children, className, style, onKeyDown, onKeyDownCapture, onFocus, onPointerEnter, onPointerLeave, onPointerMove, onContextMenu, ref, ...rest }: MenuPopoverProps): JSX.Element | null;
         displayName: string;
     };
     ItemCheckbox: {
@@ -7305,7 +7423,7 @@ export declare interface MenuItemSwitchProps extends MenuItemProps, MenuItemSele
  * Also exported as `MenuPopover` (import the flat name from React Server Components).
  */
 export declare const MenuPopover: {
-    ({ side, align, offset, target, children, className, style, onKeyDown, onKeyDownCapture, onFocus, onPointerEnter, onPointerLeave, onPointerMove, onContextMenu, ref, ...rest }: MenuPopoverProps): React_2.JSX.Element | null;
+    ({ side, align, offset, target: targetProp, positioning, children, className, style, onKeyDown, onKeyDownCapture, onFocus, onPointerEnter, onPointerLeave, onPointerMove, onContextMenu, ref, ...rest }: MenuPopoverProps): React_2.JSX.Element | null;
     displayName: string;
 };
 
@@ -7331,11 +7449,18 @@ export declare interface MenuPopoverProps extends Omit<React_2.HTMLAttributes<HT
      * with a `target` needs no trigger; name it with `aria-label`, and give a toggle button you use
      * as the target `aria-haspopup="menu"` and `aria-expanded` yourself (the menu's `id` is
      * generated, so the toggle cannot point `aria-controls` at it). A press on a target element
-     * does not close the menu. Hold the element in state (a ref cannot be observed;
-     * TeachingPopover's `target` also takes a ref). A menu opened by `openOnContext` is placed at
+     * does not close the menu. Hold the element in state, or pass a ref object (read after
+     * each render of the menu). A menu opened by `openOnContext` is placed at
      * the gesture instead.
      */
-    target?: PopupTarget;
+    target?: PopupTargetInput;
+    /**
+     * Advanced positioning (Fluent's `positioning`): `offset`, `fitViewport`, `matchReferenceWidth`,
+     * `fallbackPlacements` and `target` (used when the `target` prop is not set). `side` and `align`
+     * stay separate props, and the `offset` prop wins over `positioning.offset`.
+     * @default `{ fitViewport: true }`
+     */
+    positioning?: PopupPositioning;
     /** Menu items and dividers. */
     children: React_2.ReactNode;
     /**
@@ -7798,6 +7923,22 @@ export declare interface MessageBarTitleProps extends React_2.HTMLAttributes<HTM
     ref?: React_2.Ref<HTMLSpanElement>;
 }
 
+/**
+ * Props that mark an app-owned region (a notification area, a live status bar) so that WaveUI's
+ * modal surfaces leave it usable. Spread them on the region's element: `<div {...modalAllowProps}>`.
+ * Over an open Dialog or Drawer the region
+ *
+ * - counts as inside every dismiss layer, so a press in it closes nothing;
+ * - has its tabbable elements in the Tab cycle of every focus trap;
+ * - is never made `inert` by the modal's page isolation.
+ *
+ * The attribute it sets, `data-wave-focus-trap-allow`, is the one the Toaster's own region
+ * carries, and it is a stable contract.
+ */
+export declare const modalAllowProps: {
+    readonly 'data-wave-focus-trap-allow': "";
+};
+
 /**
  * Why a Dialog or Drawer asks to open or close: `trigger` (its Trigger part), `close` (a
  * `.Close` part), `close-button` (the built-in Close button), `escape`, `outside-press` (the
@@ -9159,7 +9300,7 @@ export declare type PolymorphicProps<C extends React_2.ElementType, OwnProps> =
  * </Popover>
  */
 export declare const Popover: {
-    ({ open: openProp, defaultOpen, onOpenChange, side, align, ignoreOutsideRefs, openOnHover, openDelay, closeDelay, openOnContext, target, children, }: PopoverProps): React_2.JSX.Element;
+    ({ open: openProp, defaultOpen, onOpenChange, side, align, ignoreOutsideRefs, openOnHover, openDelay, closeDelay, openOnContext, target: targetProp, positioning, children, }: PopoverProps): React_2.JSX.Element;
     displayName: string;
 } & {
     Trigger: {
@@ -9316,10 +9457,18 @@ export declare interface PopoverProps {
      * `aria-labelledby`, and give a toggle button you use as the target `aria-haspopup="dialog"`,
      * `aria-expanded` and `aria-controls` yourself. A press on a target element does not close the
      * popover, and Tab from it enters the content when there is no trigger. Hold the element in
-     * state (a ref cannot be observed; TeachingPopover's `target` also takes a ref). A popover
+     * state, or pass a ref object (read after each render of the popover, so an element that attaches without it rendering is noticed on its next render). A popover
      * opened by `openOnContext` is placed at the gesture instead.
      */
-    target?: PopupTarget;
+    target?: PopupTargetInput;
+    /**
+     * Advanced positioning (Fluent's `positioning`): `offset` (px from the anchor), `fitViewport`
+     * (limit the content to the space the viewport leaves; Fluent's `autoSize`), `matchReferenceWidth`,
+     * `fallbackPlacements` (tried in order when the requested side has no room) and `target` (used
+     * when the `target` prop is not set). `side` and `align` stay separate props.
+     * @default `{ offset: 8 }`
+     */
+    positioning?: PopupPositioning;
     /** `Popover.Trigger` and `Popover.Content`. */
     children: React_2.ReactNode;
 }
@@ -9404,6 +9553,39 @@ export declare interface PopoverTriggerProps extends Omit<React_2.HTMLAttributes
 /** Alignment of a popup along the anchor's edge. */
 export declare type PopupAlign = 'start' | 'center' | 'end';
 
+/** A placement for `PopupPositioning.fallbackPlacements`: a side, and optionally an alignment on it. */
+export declare interface PopupPlacement {
+    /** Side of the anchor. `start` and `end` follow the writing direction. */
+    side: PopupSide;
+    /** Alignment along that side. @default the surface's own `align` */
+    align?: PopupAlign;
+}
+
+/**
+ * The advanced positioning options of a popup (the `positioning` prop; Fluent's `positioning`).
+ * `side` and `align` stay separate props of each component, so every option has one source.
+ */
+export declare interface PopupPositioning {
+    /** Distance from the anchor in px. @default the component's own (Popover 8, Tooltip 8, TeachingPopover 12, listboxes 4) */
+    offset?: number;
+    /**
+     * Limit the surface to the space the viewport leaves (Fluent's `autoSize`). Popover also scrolls
+     * its content inside its border; the other surfaces only limit their size (their own lists and
+     * grids scroll as they always did).
+     * @default the component's own
+     */
+    fitViewport?: boolean;
+    /** Make the surface as wide as its anchor. @default the component's own */
+    matchReferenceWidth?: boolean;
+    /** Placements to try, in order, when the requested side has no room; replaces the opposite side. */
+    fallbackPlacements?: readonly PopupPlacement[];
+    /** Position against this instead of the trigger. */
+    target?: PopupTargetInput;
+}
+
+/** {@link PopupPositioning} without `target`: the options of a popup that has no `target` prop. */
+export declare type PopupPositioningOptions = Omit<PopupPositioning, 'target'>;
+
 /** A rectangle in viewport coordinates, as `getBoundingClientRect()` returns it (a `DOMRect` is one). */
 export declare interface PopupRect {
     x: number;
@@ -9423,12 +9605,20 @@ export declare interface PopupRect {
 export declare type PopupSide = 'top' | 'bottom' | 'start' | 'end' | 'left' | 'right';
 
 /**
- * Where a popup is placed instead of next to its trigger (`Menu.Popover` and `Popover` `target`):
- * an element held in state, or a `VirtualElement`. TeachingPopover's `target` (0.6) also takes a
- * ref and no `VirtualElement`; ROADMAP P7-01 unifies them.
+ * Where a popup is placed instead of next to its trigger (`Menu.Popover`, `Popover` and
+ * `TeachingPopover` `target`): an element held in state, or a `VirtualElement`. Those components
+ * also take a ref object (`PopupPositioning['target']`).
  */
 export declare type PopupTarget = HTMLElement | VirtualElement | null;
 
+/**
+ * What a popup's `target` prop accepts: a {@link PopupTarget}, or a ref object (an element that
+ * attaches without the popup rendering is read after each render of the popup).
+ */
+export declare type PopupTargetInput = PopupTarget | {
+    readonly current: HTMLElement | null;
+};
+
 /**
  * Renders its children into `document.body` (or the WaveProvider `portalContainer`), wrapped in a
  * `<div class="wave-portal …">` that carries the provider's theme classes, direction and font, so
@@ -9485,6 +9675,16 @@ export declare interface PortalProps {
     ref?: React_2.Ref<HTMLDivElement>;
 }
 
+/** What {@link UsePopupPositionOptions.onPositioned} receives. */
+export declare interface PositionedInfo {
+    /** Final placement after flipping, e.g. `'top-start'`. */
+    placement: string;
+    /** Final physical side after flipping. */
+    side: 'top' | 'bottom' | 'left' | 'right';
+    /** Always `true`: the callback runs once a position exists. */
+    isPositioned: boolean;
+}
+
 /**
  * Shows and hides its child with CSS enter and exit motion: the child stays mounted while its exit
  * motion runs, `inert` and marked `data-presence="exiting"`, and unmounts when it ends (at once
@@ -12839,6 +13039,13 @@ export declare interface TagPickerProps extends Omit<React_2.HTMLAttributes<HTML
      * option list keeps its size.
      */
     size?: TagPickerSize;
+    /**
+     * Advanced positioning of the popup (Fluent's `positioning`): `offset`, `fitViewport`,
+     * `matchReferenceWidth` and `fallbackPlacements` (tried in order when the requested side has no
+     * room). The popup opens below the field.
+     * @default `{ matchReferenceWidth: true, fitViewport: true }`
+     */
+    positioning?: PopupPositioningOptions;
     /**
      * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
      * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
@@ -12974,7 +13181,9 @@ export declare type TagSize = Extract<Size, 'extra-small' | 'small' | 'medium'>;
  * - With `target`, the popover is portaled and positioned next to that element with a beak (it
  *   inherits the surface colors); it stays hidden while the target is `null`, not positioned yet or
  *   no longer mounted (a ref target is read after each render of the popover; see `target`).
- * - With `target`, the keyboard order treats the popover as if it followed the target: Tab past
+ * - With a `VirtualElement` target there is no element to follow: the popover keeps the place of
+ *   its portal in the keyboard order.
+ * - With an element or ref `target`, the keyboard order treats the popover as if it followed the target: Tab past
  *   its last button continues after the target, Shift+Tab from its first button (or from the
  *   popover itself) returns to the target (for a target outside the Tab order, to the last control
  *   inside it, else to the control before it), Tab from there enters the popover, and Shift+Tab
@@ -12986,7 +13195,7 @@ export declare type TagSize = Extract<Size, 'extra-small' | 'small' | 'medium'>;
  *   it.
  */
 export declare const TeachingPopover: {
-    ({ steps, activeStep: activeStepProp, defaultActiveStep, currentStep, defaultCurrentStep, onStepChange, onDismiss, open: openProp, defaultOpen, onOpenChange, closeLabel, labels, target, side, align, className, style, onKeyDown, ref, ...rest }: TeachingPopoverProps): React_2.JSX.Element | null;
+    ({ steps, activeStep: activeStepProp, defaultActiveStep, currentStep, defaultCurrentStep, onStepChange, onDismiss, open: openProp, defaultOpen, onOpenChange, closeLabel, labels, target: targetProp, positioning, side, align, className, style, onKeyDown, ref, ...rest }: TeachingPopoverProps): React_2.JSX.Element | null;
     displayName: string;
 };
 
@@ -13071,7 +13280,8 @@ export declare interface TeachingPopoverProps extends React_2.HTMLAttributes<HTM
      */
     labels?: TeachingPopoverLabels;
     /**
-     * The element the popover points at (a ref or the element). When given, the popover is
+     * The element the popover points at (a ref, the element, or a `VirtualElement`: a rectangle such as a
+     * point; an inline object is fine). When given, the popover is
      * rendered in a portal, positioned next to it with a beak, and flips or shifts to stay in view;
      * without it (`undefined`) the popover renders inline where it is placed (0.4 behaviour).
      * While the target is `null` or has not been positioned against yet (an element held in state
@@ -13092,7 +13302,7 @@ export declare interface TeachingPopoverProps extends React_2.HTMLAttributes<HTM
      * attached hides the popover right after that commit. Pass the element held in state when the
      * target can mount or unmount without the popover re-rendering.
      */
-    target?: React_2.RefObject<HTMLElement | null> | HTMLElement | null;
+    target?: React_2.RefObject<HTMLElement | null> | HTMLElement | VirtualElement | null;
     /** Side of the `target` to open on; `start`/`end` follow the writing direction.
      * @default 'bottom'
      */
@@ -13101,6 +13311,13 @@ export declare interface TeachingPopoverProps extends React_2.HTMLAttributes<HTM
      * @default 'center'
      */
     align?: PopupAlign;
+    /**
+     * Advanced positioning (Fluent's `positioning`): `offset`, `fitViewport`, `matchReferenceWidth`,
+     * `fallbackPlacements` and `target` (used when the `target` prop is not set). `side` and `align`
+     * stay separate props.
+     * @default `{ offset: 12 }`
+     */
+    positioning?: PopupPositioning;
     /** Ref to the popover surface (`role="dialog"`). */
     ref?: React_2.Ref<HTMLDivElement>;
 }
@@ -13390,6 +13607,13 @@ export declare interface TimePickerProps extends Omit<React_2.HTMLAttributes<HTM
      * list keeps its size.
      */
     size?: CoreSize;
+    /**
+     * Advanced positioning of the popup (Fluent's `positioning`): `offset`, `fitViewport`,
+     * `matchReferenceWidth` and `fallbackPlacements` (tried in order when the requested side has no
+     * room). The popup opens below the field.
+     * @default `{ matchReferenceWidth: true, fitViewport: true }`
+     */
+    positioning?: PopupPositioningOptions;
     /**
      * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
      * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
@@ -14319,7 +14543,7 @@ export declare interface ToolbarToggleButtonProps extends Omit<ToggleButtonProps
  * </Menu>
  */
 export declare const Tooltip: {
-    ({ content, appearance: appearanceProp, variant, openDelay: openDelayProp, closeDelay, delay, open: openProp, defaultOpen, onOpenChange, relationship, side, align, children, className, onMouseEnter, onMouseLeave, onFocus, onBlur, ref, ...rest }: TooltipProps): React_2.JSX.Element;
+    ({ content, appearance: appearanceProp, variant, openDelay: openDelayProp, closeDelay, delay, open: openProp, defaultOpen, onOpenChange, relationship, side, align, positioning, children, className, onMouseEnter, onMouseLeave, onFocus, onBlur, ref, ...rest }: TooltipProps): React_2.JSX.Element;
     displayName: string;
 };
 
@@ -14395,6 +14619,13 @@ export declare interface TooltipProps extends Omit<React_2.HTMLAttributes<HTMLSp
      * @default 'center'
      */
     align?: PopupAlign;
+    /**
+     * Advanced positioning (Fluent's `positioning`): `offset`, `fitViewport`, `matchReferenceWidth`
+     * and `fallbackPlacements`. `side` and `align` stay separate props. The hover bridge across the
+     * gap covers the default 8px, so a larger `offset` leaves a gap the pointer cannot cross.
+     * @default `{ offset: 8 }`
+     */
+    positioning?: PopupPositioningOptions;
     /**
      * A single element that triggers the tooltip on hover and focus: it receives the
      * `aria-describedby`/`aria-labelledby`, plus any `id` and `aria-*` props given to the Tooltip
@@ -14817,6 +15048,82 @@ export declare function useAnnounce(): (message: string, politeness?: Politeness
  */
 export declare function useControllable<T>(controlledValue: T | undefined, defaultValue: T, onChange?: (value: T) => void): [value: T, setValue: SetValue<T>, isControlled: boolean];
 
+/**
+ * Registers an open overlay surface as a **dismiss layer** in the shared layer stack and closes it
+ * on Escape, outside presses and (optionally) focus leaving it — with correct nesting:
+ *
+ * - **Escape** (document `keydown`, bubble phase) is routed by focus location: the innermost layer
+ *   whose tree contains the event target or the focused element is the scope, and the topmost
+ *   escape-enabled layer of that scope's subtree handles it — so a tooltip or popover opened from
+ *   the focused dialog closes before the dialog, while an unrelated layer opened later does not
+ *   steal the key. With no escape-enabled layer there, an escape-enabled ancestor handles it; when
+ *   no layer contains the focus (or none of those takes Escape), the global topmost
+ *   escape-enabled one. Layers stacked below the topmost **isolating** modal (a Dialog/Drawer
+ *   whose `useModalIsolation` is active — its ancestors and older siblings) never take Escape, so
+ *   a modal that ignores Escape blocks it whether it is nested in a dialog or opened beside it.
+ *   A layer with `escape: 'inside'` (a non-modal Dialog or Drawer) takes Escape only while the
+ *   event target or the focused element is in its tree, so an Escape typed on the page leaves it
+ *   open and goes to the layers below it.
+ *   The handler calls `preventDefault()`. Events whose default is already prevented (an inner
+ *   widget consumed Escape) and IME composition events are ignored.
+ * - **Outside press**: on `pointerdown` (capture) every open layer whose tree does not contain the
+ *   target is recorded; on the following `click` each recorded layer whose tree still does not
+ *   contain the click target is dismissed (children first). A drag from inside to outside never
+ *   dismisses, clicks inside nested portaled layers count as inside, a popup opened by the same
+ *   click survives, and an external toggle works. Layers stacked below the topmost isolating modal
+ *   are inert and never dismissed by presses on that modal or its backdrop; a `kind: 'modal'`
+ *   layer without isolation (the DatePicker calendar) shields nothing, so a page click closes it
+ *   and the layers around it. The pending press survives modifier keys (Shift/Ctrl+click) and
+ *   ends on Enter/Space, on `pointercancel`, or when no click follows a mouse `pointerup` in the
+ *   same task; touch and pen presses are kept until their click, which the browser dispatches
+ *   from a separate tap gesture.
+ * - **Focus outside** (`focusOutside: true`): dismisses when focus moves outside the layer's tree.
+ *   That is decided in a microtask, once the current commit has run: an `autoFocus` field of a
+ *   popover, dialog or plain portal opened inside the layer gets focus before that surface's
+ *   portal and layer register, and keeps the layer open. Focus that is back inside the tree by
+ *   then keeps it open too.
+ *
+ * A layer's tree is its `refs`, the portal wrappers rendered inside it, its descendant layers and
+ * the `[data-wave-focus-trap-allow]` regions (toasts). Parentage follows the React tree: wrap the surface in
+ * `Portal layerId={layerId}` (or {@link DismissLayerProvider}) so layers opened inside it become
+ * its children.
+ *
+ * @example
+ * const { layerId } = useDismiss({ open, onDismiss: () => setOpen(false), refs: [surfaceRef, triggerRef], anchorRef: triggerRef });
+ * return open && <Portal layerId={layerId}><div ref={surfaceRef}>…</div></Portal>;
+ */
+export declare function useDismiss(options: UseDismissOptions): DismissLayer;
+
+/** Options of {@link useDismiss}. */
+export declare interface UseDismissOptions {
+    /** Whether the layer is open; the layer is registered only while `true`. */
+    open: boolean;
+    /** Called when the layer should close (the component sets its `open` state to `false`). */
+    onDismiss: (reason: DismissReason, event: Event) => void;
+    /**
+     * Elements that belong to the layer: the content surface, the trigger/anchor and any extra
+     * targets that must not count as "outside" (read at event time).
+     */
+    refs: ReadonlyArray<React_2.RefObject<HTMLElement | null>>;
+    /** The trigger; focus traps leave a descendant layer through it (Tab → the element after it). */
+    anchorRef?: React_2.RefObject<HTMLElement | null>;
+    /** @default 'popover' */
+    kind?: LayerKind;
+    /**
+     * Whether Escape dismisses the layer: always (`true`), never (`false`), or only while the key's
+     * target or the focused element is in the layer's tree (`'inside'`).
+     * @default true
+     */
+    escape?: boolean | 'inside';
+    /**
+     * Whether a press outside the layer's tree dismisses it. A predicate receives the `pointerdown`
+     * event; returning `false` ignores that press. @default true
+     */
+    outsidePress?: boolean | ((event: PointerEvent | MouseEvent) => boolean);
+    /** Whether focus moving outside the layer's tree dismisses it (listboxes). @default false */
+    focusOutside?: boolean;
+}
+
 /**
  * Returns a callback with a stable identity that always invokes the latest `fn` passed to the hook.
  * Use it for handlers read by effects or passed to memoised children, so neither re-runs when the
@@ -14891,6 +15198,172 @@ export declare interface UseFieldControlOptions {
     nativeRequired?: boolean;
 }
 
+/**
+ * A focusable group (Fluent's `useFocusableGroup`, tabster's groupper): one tab stop that holds
+ * several focusable elements, so a long list of rich rows does not cost a Tab press per control.
+ * With `tabBehavior: 'limited'` or `'limited-trap-focus'`, Tab skips the elements inside while focus
+ * is on the group element itself, and Shift+Tab from outside lands on the group element instead of
+ * its last element; Enter or F2 enters the group, and Escape leaves it. A group is entered while
+ * focus is on an element inside it, however it got there (a click, a popup returning focus, a
+ * script). No tabindex is rewritten: components with their own tab stops (Toolbar, TabList) work
+ * inside a group. A key from a popup portaled out of the group, a key that belongs to a nested
+ * group and a key an inner element already handled (`preventDefault()`, as an input consuming
+ * Escape does) are left alone.
+ *
+ * @example
+ * const { groupProps } = useFocusableGroup({ tabBehavior: 'limited' });
+ * <li role="group" aria-label="Message" {...groupProps}>
+ *   <button>Reply</button> <button>Forward</button>
+ * </li>
+ */
+export declare function useFocusableGroup(options?: UseFocusableGroupOptions): UseFocusableGroupResult;
+
+/** Options of {@link useFocusableGroup}. */
+export declare interface UseFocusableGroupOptions {
+    /**
+     * How the group treats the elements inside it (Fluent's `tabBehavior`):
+     *
+     * - `'unlimited'`: the group is one more tab stop and the elements inside it stay reachable by
+     *   Tab; no key is intercepted.
+     * - `'limited'`: the group is one tab stop, in both directions. Enter or F2 on it moves focus to
+     *   its first tabbable element, Tab and Shift+Tab then move between the elements inside, Tab
+     *   past the last one leaves the group, and Escape returns focus to the group.
+     * - `'limited-trap-focus'`: as `'limited'`, but Tab past the last element wraps to the first and
+     *   Shift+Tab before the first wraps to the last, until Escape.
+     *
+     * @default 'unlimited'
+     */
+    tabBehavior?: FocusableGroupTabBehavior;
+}
+
+/** Result of {@link useFocusableGroup}. */
+export declare interface UseFocusableGroupResult {
+    /** Spread onto the group element. */
+    groupProps: FocusableGroupProps;
+}
+
+/**
+ * Keeps keyboard focus inside `container` while `enabled` (modal dialogs, drawers, the DatePicker
+ * calendar). Element-based: pass the surface held in state via a callback ref, so the trap starts
+ * when the element appears.
+ *
+ * - **Initial focus** runs synchronously in the commit in which the container appears (no
+ *   `requestAnimationFrame`), and does nothing when focus is already inside (an `autoFocus`
+ *   element wins).
+ * - **Tab / Shift+Tab** are handled by a document bubble-phase `keydown` listener that ignores
+ *   events whose default is already prevented, so a React handler inside (a menu closing on Tab, a
+ *   grid) can take the key first. Focus wraps at the edges, and from the container itself or a
+ *   non-tabbable element it continues in document order. Tabbable elements are computed on every
+ *   keydown (content may change; radio-group stops depend on focus), never cached.
+ * - Tabbables inside `[data-wave-focus-trap-allow]` regions (the Toaster viewport) join the cycle.
+ * - **Descendant layers** (a popover or menu opened from inside, identified through `layerId`):
+ *   Tab moves natively inside them; leaving one moves focus to the element after its anchor
+ *   (Shift+Tab: the anchor itself). Inside a plain `<Portal>` rendered in the surface (no layer,
+ *   no anchor) Tab is native too; leaving it wraps to the first (Shift+Tab: last) element. A
+ *   layer's trigger (its anchor, or an element around it such as a tooltip's wrapper) belongs to
+ *   the region it sits in, so Tab from an open info button or a button showing its tooltip moves
+ *   on as from any other element of that portal or popover.
+ * - Focus that lands outside (not in the container, an allowed region or a descendant layer)
+ *   returns to the last focused element inside, also when that outside element loses it again
+ *   (removed or blurred, leaving focus on `<body>`). That is decided in a microtask, once the
+ *   current commit has run: an `autoFocus` element of a surface opened above the trap (a nested or
+ *   stacked dialog, a popover opened from the surface) gets focus before that surface's layer and
+ *   trap exist, and keeps it. The layer's own `refs` (its trigger, outside the container) are
+ *   outside: opening from the focused trigger still moves focus in, and focus moving back onto
+ *   the trigger is returned. Focus pulled out again while it is being returned (another focus
+ *   trap on the page) is left there.
+ * - Traps form a stack (shared through the global registry): only the topmost acts.
+ */
+export declare function useFocusTrap(container: HTMLElement | null, options: UseFocusTrapOptions): void;
+
+/** Options of {@link useFocusTrap}. */
+export declare interface UseFocusTrapOptions {
+    /** Whether the trap is active. */
+    enabled: boolean;
+    /**
+     * The surface's dismiss layer; focus inside its descendant layers (portaled popovers opened from
+     * inside) is allowed. The layer's own `refs` outside the container (its trigger) are not.
+     */
+    layerId?: string;
+    /**
+     * What to focus when the trap starts, unless focus is already inside (an `autoFocus` element
+     * wins). @default 'first' (the first tabbable element, else the container)
+     */
+    initialFocus?: React_2.RefObject<HTMLElement | null> | 'first' | 'container' | (() => HTMLElement | null);
+    /** Regions outside the container whose tabbables join the Tab cycle. @default '[data-wave-focus-trap-allow]' (the regions marked with `modalAllowProps`) */
+    allowOutsideSelector?: string;
+}
+
+/**
+ * Whether the page is in keyboard-navigation mode: `true` after the last input was a key press
+ * (any key but a lone modifier), `false` after a pointer or touch press and before any input. For
+ * logic that needs the mode in script, such as showing a focus cue in a widget that draws its own;
+ * plain focus rings should keep using the `focus-visible` variant. One set of document listeners
+ * serves every caller and goes away with the last one. `false` on the server and during
+ * hydration.
+ *
+ * @example
+ * const keyboard = useFocusVisible();
+ * return <div data-keyboard={keyboard ? '' : undefined}>…</div>;
+ */
+export declare function useFocusVisible(): boolean;
+
+/**
+ * Grid keyboard model of the APG Grid pattern for a `<table role="grid">` (DataGrid).
+ *
+ * - **One tab stop.** Exactly one cell of the grid is in the tab order (initially the first cell).
+ *   Its focus target is its only focusable widget when that widget is not a text-entry control
+ *   (a checkbox, a sort button, a link); otherwise — no widget, several widgets, a text-entry
+ *   control or a nested composite — the cell itself. An unchecked radio whose named group has a
+ *   checked radio is not a target either (browsers skip it in the Tab order), so its cell is.
+ *   Every other cell and every widget inside a cell gets `tabindex="-1"`. Rows are never focusable.
+ *   When a widget becomes the target of the focused cell (Space on the cell checks its radio), the
+ *   cell keeps focus and the tab stop (removing its `tabindex` would blur it) while its target stays
+ *   at `tabindex="-1"`; the target takes the tab stop once the cell is blurred.
+ * - **Navigation mode** (focus on a cell or on its target widget): ArrowLeft/ArrowRight (the
+ *   previous/next cell of the row, mirrored in RTL), ArrowUp/ArrowDown, Home/End (first/last cell
+ *   of the row), Ctrl+Home/Ctrl+End (first cell of the grid / last cell of the last row) and
+ *   PageUp/PageDown ({@link UseGridNavigationOptions.pageSize} rows) move focus between cells.
+ *   ArrowUp/ArrowDown and PageUp/PageDown keep the visual column (`colSpan` and `rowSpan` counted,
+ *   so a grouped header works), clamped to a shorter row. Space and Enter on a target widget reach
+ *   the widget.
+ * - **Interaction mode**: Enter or F2 on a cell that is its own target moves focus into its first
+ *   widget; clicking a widget that is not the cell's target (a text input) enters it too. The
+ *   grid keys are then ignored, so the arrow keys move the caret, and Tab moves between the cell's
+ *   widgets. Escape returns focus to the cell. Leaving the grid ends interaction mode.
+ * - **Nested composites** (an element with `data-roving-container` or role toolbar, radiogroup,
+ *   listbox, grid, treegrid, tablist, menu, menubar or tree) count as one widget that uses the arrow
+ *   keys: its cell takes focus, and Enter/F2 enters the composite at its own tab stop. The grid never
+ *   writes `tabindex` on or inside a composite (the composite manages its own), so a composite
+ *   keeps its own Tab stop — the same documented limitation as `useRovingTabIndex`.
+ *
+ * Keys are ignored when the event's default was prevented (a widget that handled the key, a
+ * consumer handler), or with Alt/Meta held. The tab indexes are written to the DOM (layout effect
+ * plus a `MutationObserver`), so rows and widgets added later are covered without a re-render. Focus
+ * moves re-sync only the cells involved, the observer only the cells that changed, and the grid's
+ * own `tabindex` writes do not trigger a re-sync.
+ *
+ * Internal to the table package.
+ */
+export declare function useGridNavigation(options?: UseGridNavigationOptions): UseGridNavigationResult;
+
+/** Options of {@link useGridNavigation}. */
+export declare interface UseGridNavigationOptions {
+    /**
+     * How many rows PageUp and PageDown move focus.
+     * @default 10
+     */
+    pageSize?: number;
+}
+
+/** Result of {@link useGridNavigation}. */
+export declare interface UseGridNavigationResult {
+    /** Callback ref for the `<table role="grid">` element. Stable identity. */
+    gridRef: React_2.RefCallback<HTMLTableElement>;
+    /** Keyboard and focus handlers for the grid element. Stable identities. */
+    gridProps: GridNavigationHandlers;
+}
+
 /**
  * Generates a stable, SSR-safe unique id, optionally with a prefix. Wraps React's `useId` so every
  * component builds DOM ids the same way (C-IDS).
@@ -14906,6 +15379,26 @@ export declare interface UseFieldControlOptions {
  */
 export declare function useId(prefix?: string): string;
 
+/**
+ * The trap's initial focus without the trap (a non-modal Dialog or Drawer, which moves focus in
+ * when it opens but does not keep it there): in the layout phase of the commit in which
+ * `enabled && container` becomes true, does nothing when focus is already inside the container or
+ * one of the layer's descendant layers (an `autoFocus` element wins), else focuses
+ * `initialFocus` (default: the first tabbable element), else the container. `useFocusTrap` runs
+ * the same code when it starts. It adds no listener.
+ */
+export declare function useInitialFocus(container: HTMLElement | null, options: UseInitialFocusOptions): void;
+
+/** Options of {@link useInitialFocus}. */
+export declare interface UseInitialFocusOptions {
+    /** Whether the surface is open: focus moves in when it becomes `true` with a container. */
+    enabled: boolean;
+    /** The surface's dismiss layer: focus already in one of its descendant layers stays there. */
+    layerId?: string;
+    /** What to focus first. @default 'first' (the first tabbable element, else the container) */
+    initialFocus?: UseFocusTrapOptions['initialFocus'];
+}
+
 /**
  * `false` on the server and during hydration, `true` in every other client render — including the
  * first render of a component mounted on the client, so no second commit is needed.
@@ -15241,6 +15734,11 @@ export declare interface UseListboxPopupOptions {
      * `setReference` too (merged into its ref), which places the surface against it.
      */
     anchorRef: React_2.RefObject<HTMLElement | null>;
+    /**
+     * Advanced positioning: `offset`, `fitViewport`, `matchReferenceWidth` and `fallbackPlacements`.
+     * @default `{ matchReferenceWidth: true, fitViewport: true }`
+     */
+    positioning?: PopupPositioningOptions;
 }
 
 /**
@@ -15358,6 +15856,84 @@ export declare interface UseListboxResult {
  */
 export declare function useMergedRefs<T>(...refs: Array<React_2.Ref<T> | undefined | null>): React_2.RefCallback<T>;
 
+/**
+ * Everything a modal surface (Dialog, Drawer) needs, composed in the order that works:
+ *
+ * 1. `useDismiss({ kind: 'modal' })` — Escape and outside presses (the backdrop is outside the
+ *    content surface, so a click on it dismisses; a drag from the content does not).
+ * 2. `useFocusTrap` — initial focus, Tab cycle incl. toasts and descendant layers.
+ * 3. `useModalIsolation` — the rest of the page is `inert` (instead of `aria-modal`).
+ * 4. `useScrollLock` — ref-counted page scroll lock.
+ * 5. `useRestoreFocus` — the opener (or `triggerRef`/`finalFocusRef`) gets focus back.
+ *
+ * On close the trap is released before the isolation is lifted, and the isolation is lifted
+ * before focus is restored (an inert opener cannot take focus). Wrap the surface in
+ * `Portal layerId={layerId}` so layers opened inside the modal become its descendants.
+ *
+ * `modalType: 'alert'` composes the same with `outsidePress: false`. `modalType: 'non-modal'`
+ * registers a `dialog` layer (Escape only from inside its tree, no outside press, no focus-outside
+ * dismissal), keeps the trap, the isolation and the scroll lock off, moves focus in on open with
+ * the trap's initial-focus rule (`useInitialFocus`) and restores focus only when it is inside the
+ * surface (or in a layer opened from it) at close, or was lost to `<body>` from there. Every hook
+ * is always called and keys on `open`: a `modalType` that changes while open applies at once (the
+ * trap, isolation and lock follow). It leaves focus inside the surface where it is; focus outside
+ * it moves in, as on open: a switch to `modal` or `alert` starts the trap (the page turns inert),
+ * and a switch to `non-modal` runs the initial focus (focus in the toast region, which a trap lets
+ * in, moves into the surface). The Tab order of a non-modal surface (its place after the opener)
+ * is the component's.
+ *
+ * A surface that mounts through the presence core (Dialog, Drawer) passes its open state as
+ * `open`, never its mount (`isMounted`), and its element as `container` also while it is mounted
+ * closed: the layer, the trap, the isolation and the scroll lock end and focus is restored in the
+ * commit that closes it, while the element still runs its exit motion (`inert`) or stays mounted
+ * (`hidden`, with `unmountOnClose={false}`); the next open starts them again with the same
+ * element.
+ */
+export declare function useModalLayer(options: UseModalLayerOptions): DismissLayer;
+
+/**
+ * Options of {@link useModalLayer}: `useDismiss` options (the kind follows `modalType`) plus focus.
+ */
+export declare interface UseModalLayerOptions extends Omit<UseDismissOptions, 'kind'> {
+    /** The modal surface, held in state via a callback ref. */
+    container: HTMLElement | null;
+    /**
+     * `modal` (default) and `alert` register a `modal` layer, trap focus, isolate the page, lock its
+     * scroll and restore focus (an `alert` layer ignores outside presses); `non-modal` registers a
+     * `dialog` layer (`escape: 'inside'`, no outside press, no focus-outside), traps, isolates and
+     * locks nothing, moves focus in on open with the trap's initial-focus rule and restores focus only
+     * from inside (`requireFocusInside`).
+     * @default 'modal'
+     */
+    modalType?: ModalType;
+    /** What the focus trap (or a non-modal surface's initial focus) focuses first. @default 'first' */
+    initialFocus?: UseFocusTrapOptions['initialFocus'];
+    /** The trigger: preferred focus-restore target. */
+    triggerRef?: React_2.RefObject<HTMLElement | null>;
+    /** Consumer override for the focus-restore target. */
+    finalFocusRef?: React_2.RefObject<HTMLElement | null>;
+}
+
+/**
+ * Whether a modal surface is open (a Dialog, an overlay Drawer, an alert, the DatePicker's calendar, or your
+ * own `useDismiss({ kind: 'modal' })` layer): `true` from the
+ * commit that opens it to the commit that closes it, not until its exit motion ends. A non-modal
+ * Dialog or Drawer, a Popover or a Menu is no modal. `false` on the server and during hydration.
+ *
+ * Use it to hold back app behavior the modal should own, such as global keyboard shortcuts, instead
+ * of guessing from the page's `inert` attributes.
+ *
+ * @example
+ * const modalOpen = useModalOpen();
+ * useEffect(() => {
+ *   if (modalOpen) return;
+ *   const onKey = (event: KeyboardEvent) => { if (event.key === '/') focusSearch(); };
+ *   document.addEventListener('keydown', onKey);
+ *   return () => document.removeEventListener('keydown', onKey);
+ * }, [modalOpen]);
+ */
+export declare function useModalOpen(): boolean;
+
 /**
  * The items an {@link Overflow} currently hides: their `itemId`s in DOM order and their count. Use
  * it in the component that `overflowButton` renders to list the hidden items in a menu. Must be
@@ -15373,6 +15949,117 @@ export declare interface UseOverflowMenuResult {
     count: number;
 }
 
+/**
+ * Positions a popup surface next to its anchor with `@floating-ui/react-dom` (Tooltip, Popover,
+ * Menu, listboxes, the DatePicker calendar, TeachingPopover): `offset`, `flip`, `shift`, optional
+ * `size` (reference width / available space as CSS variables) and `arrow`. `flip`, `shift` and
+ * `size` keep the same viewport padding, taken from the `shift` option (8px by default). Logical
+ * `start`/`end` sides follow `useDirection()` (the WaveProvider `dir`, else the document
+ * direction), and so does start/end alignment.
+ *
+ * Positions update only while `open` (`autoUpdate` on scroll/resize; element resizes and layout
+ * shifts only where `ResizeObserver`/`IntersectionObserver` exist). Spread `floatingProps` onto the
+ * surface: `data-side`/`data-align` expose the final placement for styling (C-CLASS).
+ *
+ * The anchor is an element or a `VirtualElement` (a rectangle such as the pointer position; a new
+ * object on every render is fine); give it a `contextElement` so scrolling its containers updates
+ * the position. A virtual anchor reaches floating-ui through one stable proxy that reads the latest
+ * object: a new object only recomputes the position (which renders only when the position
+ * changes), and a new proxy is made only when the `contextElement` changes.
+ *
+ * Destructure the result: `eslint-plugin-react-hooks` (`react-hooks/refs`) treats an object
+ * whose member is passed to a `ref` prop as a ref, and then rejects reading its other members
+ * during render.
+ *
+ * @example
+ * const { setReference, setFloating, floatingProps } = usePopupPosition({ open, side: 'bottom' });
+ * <button ref={setReference} />
+ * {open && <Portal><div ref={setFloating} {...floatingProps} /></Portal>}
+ */
+export declare function usePopupPosition(options: UsePopupPositionOptions): UsePopupPositionResult;
+
+/** Options of {@link usePopupPosition}. */
+export declare interface UsePopupPositionOptions {
+    /** Whether the popup is open; positions are kept up to date only while `true`. */
+    open: boolean;
+    /** Side of the anchor. `start`/`end` follow the writing direction. @default 'bottom' */
+    side?: PopupSide;
+    /** Alignment along that side. @default 'start' */
+    align?: PopupAlign;
+    /** Distance from the anchor in px. @default 4 (tooltips use 8) */
+    offset?: number;
+    /** Flip to the opposite side when there is not enough room. @default true */
+    flip?: boolean;
+    /**
+     * Shift along the side to stay inside the viewport. Its padding is also the viewport padding of
+     * `flip` and of `size` (`fitViewport`, `matchReferenceWidth`): `true` means 8px, and `false`
+     * lets the popup flip only once it touches the viewport edge and grow right up to it. With
+     * `crossAxis: true` it also shifts across the side, over the anchor, when neither side has room
+     * after `flip` (submenus), and `fitViewport` then offers the whole viewport in that direction.
+     * @default { padding: 8 }
+     */
+    shift?: boolean | {
+        padding: number;
+        crossAxis?: boolean;
+    };
+    /** Make the surface as wide as the anchor (listboxes). @default false */
+    matchReferenceWidth?: boolean;
+    /** Limit the surface to the available space (`max-width`/`max-height`). @default false */
+    fitViewport?: boolean;
+    /** An arrow (beak) element inside the surface, positioned through `arrowStyles`. */
+    arrowRef?: React_2.RefObject<HTMLElement | null>;
+    /** CSS positioning strategy. @default 'fixed' */
+    strategy?: 'absolute' | 'fixed';
+    /**
+     * Placements to try, in order, when the requested side has no room, instead of only the opposite
+     * side. Ignored with `flip: false`. An omitted `align` is the hook's own `align`.
+     */
+    fallbackPlacements?: readonly PopupPlacement[];
+    /**
+     * Hide the surface (`visibility: hidden`: its layout is unaffected, but its content cannot take
+     * focus, so a surface that holds focus loses it) while the anchor is scrolled out of view or
+     * clipped away. @default false
+     */
+    hideWhenDetached?: boolean;
+    /**
+     * Called after the surface is positioned, and again whenever the final placement changes (a flip,
+     * a fallback): not on every scroll or resize recompute. It runs from an effect, never during
+     * render, and not while closed.
+     */
+    onPositioned?: (info: PositionedInfo) => void;
+}
+
+/** Returned by {@link usePopupPosition}. */
+export declare interface UsePopupPositionResult {
+    /**
+     * Sets the anchor: a ref callback for the anchor (trigger) element, or a call from a layout
+     * effect or an event. The anchor is an element or a `VirtualElement` (a rectangle such as the
+     * pointer position; a new object on every render is fine); give it a `contextElement` so
+     * scrolling its containers updates the position.
+     */
+    setReference(el: HTMLElement | VirtualElement | null): void;
+    /** Ref callback for the popup surface. */
+    setFloating(el: HTMLElement | null): void;
+    /** Position styles for the surface (also in `floatingProps.style`). */
+    floatingStyles: React_2.CSSProperties;
+    /** Position styles for the arrow element. */
+    arrowStyles: React_2.CSSProperties;
+    /** Final placement after flipping, e.g. `'top-start'`. */
+    placement: string;
+    /** Final physical side after flipping. */
+    side: 'top' | 'bottom' | 'left' | 'right';
+    /** Whether a position has been computed since the popup opened. */
+    isPositioned: boolean;
+    /** Recomputes the position now, for a change floating-ui cannot observe. A no-op while closed. */
+    update(): void;
+    /** Spread onto the surface: `data-side`, `data-align` and the position style. */
+    floatingProps: {
+        'data-side': string;
+        'data-align': string;
+        style: React_2.CSSProperties;
+    };
+}
+
 /**
  * Mounts and unmounts an element with CSS enter and exit motion. Style the phases with
  * `data-presence` variants, e.g. `transition-opacity duration-wave-normal
@@ -15454,6 +16141,102 @@ export declare interface UsePresenceResult {
     presenceProps: PresenceAttributes;
 }
 
+/**
+ * Returns focus to where it came from when a surface closes (dialogs, drawers, popovers, menus,
+ * the DatePicker calendar, TeachingPopover).
+ *
+ * - **Capture**: when `enabled` flips to `true`, the opener is captured in an insertion effect —
+ *   before React applies `autoFocus` inside the new surface — preferring `triggerRef.current` and
+ *   ignoring `<body>` and elements inside `container`. When that finds nothing (a surface that
+ *   mounts open, before the refs of its commit are attached), it is captured again in the layout
+ *   phase of the same commit. Its place in the document and the triggers of the overlays it sits
+ *   in are recorded with it. When focus is already on `<body>` because
+ *   the focused element was removed earlier in the same commit (a menu item in a popover that
+ *   closes as the dialog it opens appears, the popover coming first in the tree), a document
+ *   focus tracker supplies that element with its recorded place and overlay triggers. The tracker
+ *   runs while any instance of the hook is mounted, and it forgets an element the user moved focus
+ *   away from on purpose.
+ * - **Restore** when `enabled` flips to `false` (layout phase) and when the component unmounts
+ *   while enabled. The unmount restore runs in a microtask and is cancelled if the same instance
+ *   mounts again, so React StrictMode's simulated unmount does not pull focus out of a surface
+ *   that just opened.
+ * - **Targets**, first valid wins:
+ *   1. `finalFocusRef` → the captured opener → `triggerRef` → `fallback()`.
+ *   2. When the opener was removed or cannot take focus, its replacement, nearest first: the
+ *      tabbable element next to where it was (in the innermost surviving ancestor that holds one,
+ *      the next one — the next row's action after a delete — else the previous one; then the same
+ *      one level up), else the trigger of the overlay it was in (a menu item's menu button), else
+ *      the element next to that trigger. When the surface is rendered inside another open layer
+ *      (its parent layer, from `DismissLayerContext`: a confirm Dialog in a Drawer's content),
+ *      only the replacements inside that layer's tree are tried here.
+ *   3. The parent layer's surface, then the replacements outside the parent layer.
+ *   4. The surface of the modal layer that stays open.
+ *
+ *   So a confirm Dialog rendered in a Drawer's content and one rendered next to the Drawer both
+ *   return focus to the adjacent row, not to the Drawer's panel. A target is valid when it is
+ *   connected, focusable, not inside `[inert]` or `[aria-hidden="true"]`, and not cut off behind
+ *   another open modal layer — so focus never lands on the inert page behind a Drawer that stays
+ *   open, and is not dropped on `<body>` while a valid target exists. Focus uses `preventScroll`.
+ * - `onlyIfFocusInside` (popovers): restores only when focus is inside the surface or was lost to
+ *   `<body>`.
+ * - `requireFocusInside` (surfaces that do not trap focus: a non-modal Dialog or Drawer, an inline
+ *   Drawer): restores only when focus is inside the surface or in a layer opened from it (a
+ *   descendant layer of `layerId`, or a layer anchored inside the surface), or was lost to
+ *   `<body>` from an element in either; a close from code while focus is on `<body>` or on the
+ *   page moves nothing.
+ * - `isHoverClose`: a close by the hover intent restores only when focus is inside the surface, so
+ *   a hover close never moves focus from `<body>` or from where the user put it. The same holds for
+ *   a surface opened from inside one that closes by hover (a submenu, a hover card in a hover
+ *   card): every mounted instance is known to the others through the focus tracker's record.
+ */
+export declare function useRestoreFocus(options: UseRestoreFocusOptions): void;
+
+/** Options of {@link useRestoreFocus}. */
+export declare interface UseRestoreFocusOptions {
+    /** `true` while the surface is open. */
+    enabled: boolean;
+    /** The layer surface: opener candidates inside it are ignored. */
+    container?: HTMLElement | null;
+    /** The trigger: preferred restore target. */
+    triggerRef?: React_2.RefObject<HTMLElement | null>;
+    /** Consumer override: focused first when valid. */
+    finalFocusRef?: React_2.RefObject<HTMLElement | null>;
+    /** Used when neither the override, the opener nor the trigger can take focus. */
+    fallback?: () => HTMLElement | null;
+    /**
+     * Popovers: restore only when focus was inside the surface (or lost to `<body>`) at close, so a
+     * click that moved focus elsewhere is respected. @default false
+     */
+    onlyIfFocusInside?: boolean;
+    /**
+     * Read when the surface closes, or unmounts while open: `true` when the hover intent closed it
+     * (Popover and Menu `openOnHover`, a submenu closing by hover). A hover close never moves focus:
+     * it restores only while focus is inside the surface, so focus on `<body>` (where a hover-opened
+     * surface leaves it) or elsewhere stays where it is. A surface opened from inside one that closes
+     * by hover (its opener, else its trigger, lies in that surface: a submenu, a hover card in a
+     * hover card, at any depth) is taken along, and its close counts as a hover close too. Every
+     * other close keeps the rules above.
+     */
+    isHoverClose?: () => boolean;
+    /**
+     * Surfaces that do not trap focus (a non-modal Dialog or Drawer, an inline Drawer): restore only
+     * when focus is inside the surface at close, or was lost to `<body>` from an element inside it
+     * (removed, or made unable to take focus). Focus elsewhere, or on `<body>` for another reason
+     * (nothing had focus, a press on a spot that takes no focus, a close from code), stays where it
+     * is. Wins over `onlyIfFocusInside`. Focus in a layer opened from the surface (a Popover or a
+     * confirm Dialog, portaled outside it) counts as inside: a descendant layer of `layerId`, or a
+     * layer anchored to an element inside the surface; so does focus lost to `<body>` from one.
+     * @default false
+     */
+    requireFocusInside?: boolean;
+    /**
+     * The surface's own dismiss layer, with `requireFocusInside`: focus in one of its descendant
+     * layers counts as inside the surface, also after the surface's layer has unregistered (in the
+     * commit that closes it).
+     */
+    layerId?: string;
+}
+
 /**
  * Implements the WAI-ARIA roving tabindex pattern for composite widgets: one item holds the tab
  * stop (`tabIndex=0`, all others `-1`), arrow keys move focus between items, Home/End jump to the
@@ -15542,10 +16325,23 @@ export declare interface UseRovingTabIndexOptions {
     items?: readonly string[];
     /**
      * Arrow key axis: `'horizontal'` uses Left/Right (mirrored in RTL), `'vertical'` uses Up/Down,
-     * `'both'` uses all four.
+     * `'both'` uses all four, in the DOM order of the items.
+     *
+     * `'grid'` is a two-dimensional grid: Left/Right move through the cells in reading order across
+     * rows (mirrored in RTL); Up/Down go to the cell at the same index in the previous or next row,
+     * else to the nearest enabled cell of that row (the earlier one on a tie), skipping rows without
+     * an enabled cell, and stop at the first and last row; Home/End go to the first and last enabled
+     * cell of the row, Ctrl+Home/End of the grid (whatever `homeEndKeys` says). Rows are the
+     * `role="row"` elements inside the container, else groups of `columns` items in DOM order. Without
+     * either, `'grid'` acts as `'both'` and a development warning says so.
      * @default 'horizontal'
      */
-    orientation?: 'horizontal' | 'vertical' | 'both';
+    orientation?: 'horizontal' | 'vertical' | 'both' | 'grid';
+    /**
+     * With `orientation: 'grid'` and no `role="row"` elements: the number of cells per row. The last
+     * row may be shorter.
+     */
+    columns?: number;
     /**
      * Whether arrow keys wrap around at the ends.
      * @default true