@mortenbrudvik/waveui 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { ClassValue } from 'clsx';
+import { FC } from 'react';
 import { JSX } from 'react';
 import { JSXElementConstructor } from 'react';
+import { NamedExoticComponent } from 'react';
 import * as React_2 from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
@@ -54,8 +56,8 @@ export declare const accordionClassNames: {
     readonly root: "wave-accordion";
 };
 
-/** Heading level of the element that wraps each Accordion trigger. */
-export declare type AccordionHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/** Heading level of the element that wraps each Accordion trigger: the shared {@link HeadingLevel}. */
+export declare type AccordionHeadingLevel = HeadingLevel;
 
 /**
  * One section of an Accordion. Place an `Accordion.Trigger` and an `Accordion.Panel` inside it:
@@ -304,7 +306,7 @@ export declare type Appearance = 'primary' | 'outline' | 'subtle' | 'transparent
  * <Avatar name="Jane Doe" src="/jane.jpg" badge={<PresenceBadge status="available" />} />
  */
 export declare const Avatar: {
-    ({ src, name, size, icon, image, badge, decorative, className, ref, role, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-description": ariaDescription, "aria-details": ariaDetails, ...rest }: AvatarProps): React_2.JSX.Element;
+    ({ src, name, size: sizeProp, icon, image, badge, decorative, className, ref, role, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-description": ariaDescription, "aria-details": ariaDetails, ...rest }: AvatarProps): React_2.JSX.Element;
     displayName: string;
 };
 
@@ -406,7 +408,9 @@ export declare interface AvatarProps extends React_2.HTMLAttributes<HTMLSpanElem
      * `role="img"` unless `role` is given) and generates the initials shown when there is no image.
      */
     name?: string;
-    /** Size of the avatar.
+    /**
+     * Size of the avatar. Without it, an Avatar in the `media` of a tag (Tag, InteractionTag) takes
+     * the tag's media box instead: 24, 20 or 16px by the tag's size.
      * @default 'medium'
      */
     size?: Size;
@@ -451,6 +455,9 @@ export declare interface AvatarProps extends React_2.HTMLAttributes<HTMLSpanElem
     ref?: React_2.Ref<HTMLSpanElement>;
 }
 
+/** How a modal surface's backdrop paints the page: `dimmed`, or `transparent` (a modal over another). */
+export declare type BackdropAppearance = 'dimmed' | 'transparent';
+
 /**
  * A short, non-interactive label that highlights a status or category ("New", "Beta", "3").
  * `appearance` picks a solid fill, a light tint or an outline; `color` the semantic color. Colors
@@ -2338,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
@@ -3232,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
@@ -3367,8 +3388,9 @@ export declare interface DatePickerProps extends Omit<React_2.HTMLAttributes<HTM
 export declare type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
 
 /**
- * A modal dialog (Fluent UI v2 style): `Dialog` holds the open state; `Dialog.Trigger` opens it and
- * `Dialog.Content` renders the surface in a portal while open.
+ * A dialog (Fluent UI v2 style), modal by default: `Dialog` holds the open state; `Dialog.Trigger`
+ * opens and closes it and `Dialog.Content` renders the surface in a portal while open (and, with
+ * `unmountOnClose={false}`, keeps it there while closed, `hidden` and `inert`).
  *
  * - **Modal**: focus moves into the dialog and Tab stays inside it (toasts included), the rest of
  *   the page is `inert` (instead of `aria-modal`, so toasts and live regions stay announced), and
@@ -3383,8 +3405,29 @@ export declare type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
  *   that had focus when the dialog opened, the trigger, an element next to where that opener was.
  * - **Alert dialogs**: `modalType="alert"` renders `role="alertdialog"` for a confirmation that
  *   needs an answer; a backdrop press does not close it.
+ * - **Non-modal dialogs**: `modalType="non-modal"` leaves the page usable (no backdrop, no focus
+ *   trap, nothing inert, the page scrolls). Focus moves in on open; Tab and Shift+Tab leave the
+ *   dialog in the page's order right after the element that opened it; Escape closes it only while
+ *   focus is inside it; presses on the page never close it; focus returns to the opener only from
+ *   inside. Keep the page's controls clear of the dialog, which covers the page under it.
+ * - **Size**: `Dialog.Content` `size` caps the width at 400px (`small`), 600px (`medium`, the
+ *   default) or 940px (`large`); `full` covers the viewport and pads its safe-area insets.
+ * - **Backdrop**: the backdrop is the surface's sibling and a slot (`backdrop`: `null` removes it,
+ *   `appearance` picks `dimmed` or `transparent`). A modal opened over another modal dims the page
+ *   once: its backdrop is transparent while the lower one is open.
+ * - **Close button and title actions**: `closeButton` sets the built-in Close button's content, or
+ *   hides it (`null`); a button passed there is merged into it. `titleAction` and `Dialog.Title`'s
+ *   `action` place header buttons before the Close button in the top end corner, in DOM and Tab
+ *   order, and the titles' end padding makes room for them. Initial focus goes to the first
+ *   focusable element: a title action, else the Close button.
  * - **Footer**: `Dialog.Footer` sticks to the bottom of the scrolling body, and the body keeps a
  *   focused field above it.
+ * - **Kept mounted**: `unmountOnClose={false}` keeps the content mounted while the dialog is
+ *   closed, so a form keeps what was typed and the components inside keep their state; each open
+ *   focuses the first focusable element again (an `autoFocus` inside never applies), and a kept
+ *   dialog opened while another overlay is open stacks above it.
+ * - **Presence**: the surface mounts through the presence core and renders `data-presence`; no
+ *   motion ships, and `data-[presence=…]:` classes on `Dialog.Content` animate it.
  * - **Naming**: give `Dialog.Content` a `title`, a `Dialog.Title`, or `aria-label`.
  *
  * The sub-components are also exported under flat names (`DialogTrigger`, `DialogContent`,
@@ -3404,7 +3447,7 @@ export declare type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
  * </Dialog>
  */
 export declare const Dialog: {
-    ({ open, defaultOpen, onOpenChange, modalType, finalFocusRef, children, }: DialogProps): React_2.JSX.Element;
+    ({ open, defaultOpen, onOpenChange, modalType, finalFocusRef, unmountOnClose, children, }: DialogProps): React_2.JSX.Element;
     displayName: string;
 } & {
     Trigger: {
@@ -3412,7 +3455,7 @@ export declare const Dialog: {
         displayName: string;
     };
     Content: {
-        ({ title, size, closeLabel, children, className, id, ref, ...rest }: DialogContentProps): React_2.JSX.Element | null;
+        ({ title, size, backdrop, closeButton, titleAction, closeLabel, children, className, style, id, onKeyDown, ref, ...rest }: DialogContentProps): React_2.JSX.Element | null;
         displayName: string;
     };
     Footer: {
@@ -3420,7 +3463,7 @@ export declare const Dialog: {
         displayName: string;
     };
     Title: {
-        ({ id, className, children, ref, ...rest }: DialogTitleProps): React_2.JSX.Element;
+        ({ id, action, className, children, ref, ...rest }: DialogTitleProps): React_2.JSX.Element;
         displayName: string;
     };
     Close: {
@@ -3464,28 +3507,47 @@ export declare interface DialogCloseRenderProps extends React_2.HTMLAttributes<H
 
 /**
  * The dialog surface, rendered in a portal (inheriting the WaveProvider theme) while the dialog is
- * open: backdrop, title, Close button and a scrolling body. It takes the full width up to its
- * `size` and never exceeds the viewport (the body scrolls, also sideways for content wider than
- * the dialog). Its 1rem gap to the viewport edges is its own margin, so a margin in `className`
- * replaces the gap: with the width and height caps lifted as well and its height set to the
- * viewport's, it fills the viewport (a full-screen dialog). It is `role="dialog"`, or
- * `role="alertdialog"` when the Dialog has `modalType="alert"` (a `role` you pass wins), and
- * carries `data-modal-type` with the resolved type.
+ * open, and kept there while it is closed, `hidden` and `inert`, when the Dialog has
+ * `unmountOnClose={false}`: the backdrop, and the surface centred in the positioner (the
+ * backdrop's sibling) with the title, the title-actions area (title actions, then the Close
+ * button) and a scrolling body. It takes the full width up to its `size` and never exceeds the
+ * viewport (the body scrolls, also sideways for content wider than the dialog); `size="full"`
+ * fills the viewport. Its 1rem gap to the viewport edges is its own margin, so a margin in
+ * `className` replaces the gap: with the width and height caps lifted as well and its height set
+ * to the viewport's, it fills the viewport. It is `role="dialog"`, or `role="alertdialog"` when the
+ * Dialog has `modalType="alert"` (a `role` you pass wins), and carries `data-modal-type` and
+ * `data-size` with the resolved values. A non-modal dialog has no backdrop: the positioner only
+ * centres the surface and lets presses through to the page. The titles' end padding follows the
+ * width of the title-actions area (`--wave-dialog-title-end-padding`, 2rem until it is measured).
+ *
+ * It mounts through the presence core: the backdrop, the positioner and the surface render
+ * `data-presence` (`entered` while open, `exited` while kept closed; `entering` and `exiting`
+ * only while a motion of yours runs on the surface), and the backdrop and the positioner are
+ * `inert` while exiting and `hidden` and `inert` while kept closed. No motion ships: animate the
+ * surface with `data-[presence=…]:` classes in `className` (an enter's start as
+ * `data-[presence=entering]:starting:`, each with a `motion-reduce:` counterpart); a closed
+ * surface waits for that motion before it unmounts or hides, while focus, the trap and the
+ * isolation follow the open state at once.
  */
 export declare const DialogContent: {
-    ({ title, size, closeLabel, children, className, id, ref, ...rest }: DialogContentProps): React_2.JSX.Element | null;
+    ({ title, size, backdrop, closeButton, titleAction, closeLabel, children, className, style, id, onKeyDown, ref, ...rest }: DialogContentProps): React_2.JSX.Element | null;
     displayName: string;
 };
 
 /**
- * Dialog.Content: `root` on the surface (`role="dialog"` or `"alertdialog"`); `backdrop` on the
- * backdrop around it; `closeButton` on the built-in Close button (which also carries Button's
- * root); `body` on the scrolling body. The heading of its `title` prop carries Dialog.Title's
- * class.
+ * Dialog.Content: `root` on the surface (`role="dialog"` or `"alertdialog"`, also while kept
+ * mounted); `backdrop` on the backdrop behind it; `positioner` on the element that centres the
+ * surface (the backdrop's sibling); `titleActions` on the area of header buttons in the top end
+ * corner; `titleAction` on the element of the `titleAction` slot; `closeButton` on the built-in
+ * Close button (which also carries Button's root); `body` on the scrolling body. The heading of
+ * its `title` prop carries Dialog.Title's class.
  */
 export declare const dialogContentClassNames: {
     readonly root: "wave-dialog-content";
     readonly backdrop: "wave-dialog-content__backdrop";
+    readonly positioner: "wave-dialog-content__positioner";
+    readonly titleActions: "wave-dialog-content__title-actions";
+    readonly titleAction: "wave-dialog-content__title-action";
     readonly closeButton: "wave-dialog-content__close-button";
     readonly body: "wave-dialog-content__body";
 };
@@ -3498,13 +3560,52 @@ export declare interface DialogContentProps extends Omit<React_2.HTMLAttributes<
      * (`''`, `[]`, `true`) counts as none.
      */
     title?: React_2.ReactNode;
-    /** Maximum width of the dialog: 400px (`small`) or 600px (`medium`); it never exceeds the viewport.
+    /**
+     * Width cap: 400px (`small`), 600px (`medium`) or 940px (`large`), never wider than the viewport
+     * (a 1rem margin). `full` covers the viewport: no margin, radius or border, the viewport's
+     * dynamic height, and the safe-area insets as padding (with `viewport-fit=cover`); the body
+     * scrolls under the sticky `Dialog.Footer`. Rendered as `data-size`. Fluent has no size. For
+     * another width, put a width cap in `className` (it replaces the size's).
      * @default 'medium'
      */
-    size?: 'small' | 'medium';
+    size?: DialogSize;
+    /**
+     * The backdrop of a modal or alert dialog: a `div` behind the dialog, `aria-hidden`. Shorthand
+     * content renders inside it; a slot object's `className` (merged last), `style`, data
+     * attributes, `ref` and handlers go to it, and its `appearance` (`'dimmed'` or `'transparent'`)
+     * overrides the automatic one: while another modal Dialog or Drawer is open below this one the
+     * backdrop is transparent, so the page is dimmed once. `null` renders no backdrop (the page stays
+     * inert, and a press outside still closes a modal dialog); a boolean is no slot. Ignored with
+     * `modalType="non-modal"` (a development warning says so). Fluent's `backdrop`.
+     */
+    backdrop?: Slot<'div'> | (SlotObject<'div'> & {
+        appearance?: BackdropAppearance;
+    });
+    /**
+     * Content of the built-in Close button (the dismiss glyph by default). It renders inside the
+     * button, decorative (`aria-hidden`), so the button keeps the name `closeLabel`; a slot object's
+     * `aria-label`, `aria-labelledby` or `title` names it instead, and its handlers run before the
+     * close (`preventDefault()` keeps the dialog open). `null` hides the button (Escape and
+     * `Dialog.Close` still close); a boolean is no slot, so `closeButton={cond && <MyIcon />}` keeps
+     * the default; content that renders nothing keeps the default glyph. A `<button>` or Wave
+     * `Button` passed here is merged into the built-in button, never nested (a development warning
+     * says so): its props apply, its text label (`<button>Done</button>`) names the button instead
+     * of `closeLabel`, and a Button's `icon`, `iconPosition` and `disabledFocusable` apply while
+     * `appearance` and `size` are ignored. Fluent's `DialogTitle` `action` holds Fluent's close
+     * button; WaveUI renders its own.
+     */
+    closeButton?: Slot<'span'>;
+    /**
+     * Header buttons for the `title` prop form, placed before the built-in Close button in the
+     * dialog's top end corner, in DOM and Tab order (an expand toggle, a menu). The title's end
+     * padding makes room for them. Interactive: name icon-only buttons. Renders nothing when empty.
+     * See also `Dialog.Title`'s `action`. Fluent's `DialogTitle` `action`, for the `title` prop
+     * form.
+     */
+    titleAction?: Slot<'span'>;
     /**
      * Accessible name of the built-in Close button (an icon-only button). Localize it with the
-     * page's language.
+     * page's language. A text label of a button merged into `closeButton` names it instead.
      * @default 'Close'
      */
     closeLabel?: string;
@@ -3544,8 +3645,8 @@ export declare interface DialogFooterProps extends React_2.HTMLAttributes<HTMLDi
 }
 
 /**
- * How a {@link Dialog} blocks the page (the shared `ModalType`; Drawer reuses it when it gains
- * `modalType`).
+ * How a {@link Dialog} relates to the page: `modal`, `alert` or `non-modal` (the shared
+ * `ModalType`; `DrawerModalType` is the same type).
  */
 export declare type DialogModalType = ModalType;
 
@@ -3585,11 +3686,18 @@ export declare interface DialogProps {
      */
     onOpenChange?: (open: boolean, details?: DialogOpenChangeDetails) => void;
     /**
-     * `modal`: a backdrop press, Escape, the Close button and `Dialog.Close` close it. `alert`: a
-     * confirmation that needs an answer — `role="alertdialog"`, and a backdrop press does not close
-     * it (Escape still does). Initial focus goes to the first focusable element, the built-in Close
-     * button; give the least destructive action `autoFocus` to focus it instead. (`'non-modal'` is
-     * planned.)
+     * `modal`: the page behind is `inert` and does not scroll; a backdrop press, Escape, the Close
+     * button and `Dialog.Close` close it. `alert`: a confirmation that needs an answer —
+     * `role="alertdialog"`, and a backdrop press does not close it (Escape still does). `non-modal`:
+     * the page stays usable — no backdrop, no focus trap, nothing inert, the page scrolls; Tab and
+     * Shift+Tab leave the dialog in the page's order right after the element that opened it, Escape
+     * closes it while focus is inside it, presses on the page never close it, and focus returns to
+     * the opener only when it was inside the dialog. A non-modal dialog covers the page under it
+     * while Tab still reaches that page: keep the controls the user works with outside it, or use
+     * `modal` (with `size="full"` it covers everything, and a development warning says so). Every
+     * type moves focus to the first focusable element on open (a title action, else the built-in
+     * Close button); give another element `autoFocus` to start there (an alert dialog's least
+     * destructive action). `Dialog.Trigger` toggles the dialog. Fluent's `modalType`.
      * @default 'modal'
      */
     modalType?: DialogModalType;
@@ -3600,43 +3708,75 @@ export declare interface DialogProps {
      * send focus somewhere else.
      */
     finalFocusRef?: React_2.RefObject<HTMLElement | null>;
+    /**
+     * Removes `Dialog.Content` (the surface and everything in it) when the dialog closes. `false`
+     * keeps it mounted while closed, `hidden` and `inert`, so a form inside keeps what was typed and
+     * the components inside keep their state; the surface then mounts with the Dialog, closed (in
+     * the browser only, as an open one), and an `autoFocus` inside it never applies (each open
+     * focuses the first focusable element). A popup opened inside that is still open when the
+     * dialog closes stays open over the page (a development warning says so): close it first.
+     * Fluent's `unmountOnClose`.
+     * @default true
+     */
+    unmountOnClose?: boolean;
     /** `Dialog.Trigger` and `Dialog.Content`. */
     children: React_2.ReactNode;
 }
 
+/**
+ * The width cap of a {@link Dialog}'s surface: `small` 400px, `medium` 600px, `large` 940px, or
+ * `full`, the whole viewport (the shared `SurfaceSize`; `DrawerSize` is the same type).
+ */
+export declare type DialogSize = SurfaceSize;
+
 /**
  * A heading that names the dialog (`aria-labelledby`), for rich titles or custom layouts. Render it
- * inside `Dialog.Content` (instead of the `title` prop). Like the `title` heading it reserves end
- * padding (`pe-8`) so a long first line stays clear of the Close button; a `className` padding wins.
+ * inside `Dialog.Content` (instead of the `title` prop). Like the `title` heading, its end padding
+ * follows the width of the dialog's title-actions area (2rem until it is measured), so a long first
+ * line stays clear of the title actions and the Close button; a `className` padding wins. Its
+ * `action` renders in that area, before the Close button, and never inside the heading.
  */
 export declare const DialogTitle: {
-    ({ id, className, children, ref, ...rest }: DialogTitleProps): React_2.JSX.Element;
+    ({ id, action, className, children, ref, ...rest }: DialogTitleProps): React_2.JSX.Element;
     displayName: string;
 };
 
-/** Dialog.Title: `root` on the `<h2>`. */
+/** Dialog.Title: `root` on the `<h2>`; `action` on the element of its `action` slot. */
 export declare const dialogTitleClassNames: {
     readonly root: "wave-dialog-title";
+    readonly action: "wave-dialog-title__action";
 };
 
 /** Properties for the DialogTitle sub-component. */
 export declare interface DialogTitleProps extends React_2.HTMLAttributes<HTMLHeadingElement> {
     /** The title; any content. */
     children: React_2.ReactNode;
+    /**
+     * Header buttons for this title, placed before the built-in Close button in the dialog's top end
+     * corner (after `Dialog.Content`'s `titleAction`), not inside the heading, so they never become
+     * part of the dialog's name. Outside `Dialog.Content` (in a Drawer) they render right after the
+     * heading. Interactive: name icon-only buttons. Renders nothing when empty. Fluent's
+     * `DialogTitle` `action`; unlike Fluent's, it is never filled by default (the Close button is
+     * the Content's).
+     */
+    action?: Slot<'span'>;
     /** Ref to the heading element. */
     ref?: React_2.Ref<HTMLHeadingElement>;
 }
 
 /**
- * Opens the dialog. Puts `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` (while open), a
- * click handler and a ref on its single child (no wrapper element), or passes them to a
- * render-prop child. A custom child component must forward `ref` and spread its props; one that
- * does not is wrapped in a `<span>` automatically (with a development warning), the span that
- * `asChild={false}` renders. Focus returns to the trigger when the dialog closes (with several
- * triggers, to the one that opened it). On the span, the state ARIA goes to the first element in
- * the tab order inside it, and focus returns to that element (to the span when you made it the
- * trigger with a `role` such as `button` and `tabIndex={0}`, or when nothing inside it can take
- * focus).
+ * Opens and closes the dialog: a click while it is open asks it to close (reason `trigger`). Only a
+ * non-modal dialog's trigger, or a trigger rendered inside the dialog's own content, can receive
+ * one (a modal dialog makes the page inert). Fluent's `DialogTrigger` never toggles (outside the
+ * surface it only opens, inside it only closes); this trigger always does. Puts
+ * `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` (while open), a click handler and a
+ * ref on its single child (no wrapper element), or passes them to a render-prop child. A custom
+ * child component must forward `ref` and spread its props; one that does not is wrapped in a
+ * `<span>` automatically (with a development warning), the span that `asChild={false}` renders.
+ * Focus returns to the trigger when the dialog closes (with several triggers, to the one that
+ * opened it). On the span, the state ARIA goes to the first element in the tab order inside it,
+ * and focus returns to that element (to the span when you made it the trigger with a `role` such
+ * as `button` and `tabIndex={0}`, or when nothing inside it can take focus).
  */
 export declare const DialogTrigger: {
     (props: DialogTriggerProps): React_2.ReactNode;
@@ -3646,8 +3786,9 @@ export declare const DialogTrigger: {
 /** Properties for the DialogTrigger sub-component. */
 export declare interface DialogTriggerProps extends Omit<React_2.HTMLAttributes<HTMLElement>, 'children'> {
     /**
-     * The element that opens the dialog. A single element receives the trigger props (merged with
-     * its own: handlers composed, classes joined, its own `id` kept); a function receives them.
+     * The element that opens and closes the dialog. A single element receives the trigger props
+     * (merged with its own: handlers composed, classes joined, its own `id` kept); a function
+     * receives them.
      */
     children: React_2.ReactNode | ((props: DialogTriggerRenderProps) => React_2.ReactNode);
     /**
@@ -3672,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';
 
@@ -3728,62 +3886,175 @@ export declare interface DividerOwnProps {
 export declare type DividerProps<C extends React_2.ElementType = 'hr'> = PolymorphicProps<C, DividerOwnProps>;
 
 /**
- * A modal panel attached to a side of the screen (Fluent UI v2 style), rendered in a portal
- * (inheriting the WaveProvider theme) while open.
+ * A side or bottom panel (Fluent UI v2 style): by default an overlay, modal unless it is
+ * non-modal, rendered in a portal (inheriting the WaveProvider theme) while open; with
+ * `type="inline"` a panel in the page layout, rendered in place. With `unmountOnClose={false}`
+ * either kind stays mounted while closed, `hidden` and `inert`.
  *
  * - **Opening**: controlled (`open`), or uncontrolled with a `Drawer.Trigger` placed directly inside
- *   the Drawer or in a Fragment there (it renders in place, outside the panel).
+ *   the Drawer or in a Fragment there (it renders in place, outside the panel); the trigger opens
+ *   and closes it.
  * - **Modal**: focus moves into the panel and Tab stays inside it (toasts included), the rest of the
- *   page is `inert` (instead of `aria-modal`), and the page does not scroll.
+ *   page is `inert` (instead of `aria-modal`), and the page does not scroll. `modalType="alert"`
+ *   renders `role="alertdialog"`, and a backdrop press does not close it.
+ * - **Non-modal**: `modalType="non-modal"` leaves the page usable (no backdrop, no focus trap,
+ *   nothing inert, the page scrolls). Focus moves in on open; Tab and Shift+Tab leave the panel in
+ *   the page's order right after the element that opened it; Escape closes it only while focus is
+ *   inside it; presses on the page never close it; focus returns to the opener only from inside.
+ *   Reserve the panel's room in the page layout while it is open, so it hides no page control.
+ * - **Inline**: `type="inline"` renders the panel where the Drawer is, after its direct triggers,
+ *   as an `<aside>` (a complementary landmark named by its title), also in the server HTML. It is
+ *   page content: no portal, backdrop, focus trap, inert page or scroll lock, and toasts keep
+ *   their corner next to it. Its trigger toggles it (with `aria-expanded` and `aria-controls`, no
+ *   `aria-haspopup`); opening it moves no focus; Escape and presses outside never close it;
+ *   closing it returns focus only when focus was inside. `position` picks its inner edge and
+ *   `size` its width (its height at the bottom); `separator` draws the inner edge. Place it in
+ *   your layout, for example a flex row of the panel and the page content. Changing `type`
+ *   remounts the panel and its content.
  * - **Closing**: Escape (only the topmost layer: a popup opened inside closes first), a click on the
- *   backdrop (a drag that starts inside does not close it), the Close button and `Drawer.Close`.
+ *   backdrop (a drag that starts inside does not close it), the Close button and `Drawer.Close`
+ *   (an inline drawer: the trigger, the Close button and `Drawer.Close`).
  *   `onOpenChange` gets the reason as its second argument (`details.reason`), so a controlled
  *   drawer can refuse some of them. A backdrop press blurs the focused field before the drawer
  *   closes, so a typed value is committed as with the Close button; when a controlled drawer
  *   refuses the press, the field gets focus back. Focus returns to the first of these that can
  *   take focus: `finalFocusRef`, the element that had focus when the drawer opened, the trigger,
  *   an element next to where that opener was.
- * - **Position**: `end` (default) and `start` follow the text direction.
+ * - **Size and position**: `position` is `end` (default) or `start`, which follow the text
+ *   direction, `left` or `right`, or `bottom` (along the bottom edge, the window wide). `size` sets
+ *   the width at a side and the height at the bottom: `small` (default, 320px), `medium` (592px),
+ *   `large` (940px) or `full`; the panel never grows past the window (an inline one past its
+ *   container). A width class in `className` (a height class for `bottom`) replaces the size. An
+ *   overlay panel pads the safe-area insets of the screen edges it touches (the iOS home
+ *   indicator, once the page sets `viewport-fit=cover`). Both render as `data-position` and
+ *   `data-size`, next to `data-type`.
+ * - **Layout**: the `title` prop and the built-in Close button make the header row; a
+ *   `Drawer.Header` replaces it, with a `Drawer.HeaderNavigation` row (a Back button, commands)
+ *   and a `Drawer.HeaderTitle` (the heading, an `action` area and the Close button). The rest of
+ *   the content scrolls in the body (`Drawer.Body` gives it your props); a `Drawer.Footer` is an
+ *   action row below the body that never scrolls. Make the parts direct children of the Drawer (a
+ *   Fragment there is fine). The header draws a line under itself once the body is scrolled, the
+ *   footer one above itself while content continues below: the body, the header and the footer
+ *   render the body's scroll state as `data-scroll-state` (`none`, `top`, `middle`, `bottom`).
+ * - **Backdrop, Close button and title actions**: the backdrop is the panel's sibling and a slot
+ *   (`backdrop`: `null` removes it, `appearance` picks `dimmed` or `transparent`); a modal opened
+ *   over another modal dims the page once. `closeButton` sets the content of every built-in Close
+ *   button, or hides them (`null`); a button passed there is merged into it. `titleAction` places
+ *   header buttons between the `title` heading and the Close button.
+ * - **Kept mounted**: `unmountOnClose={false}` keeps the panel and its content mounted while the
+ *   drawer is closed, so a form keeps what was typed and the components inside keep their state;
+ *   each open of an overlay focuses the first focusable element again (an `autoFocus` inside never
+ *   applies), and a kept overlay opened while another overlay is open stacks above it. A kept
+ *   inline drawer is in the server HTML, hidden.
+ * - **Presence**: the panel and the backdrop mount through the presence core and render
+ *   `data-presence` (`entered` while open, `exited` while kept closed); the backdrop and the
+ *   panel (an inline drawer's `<aside>`) are `inert` while exiting and `hidden` and `inert` while
+ *   kept closed. No motion ships:
+ *   `data-[presence=…]:` classes in `className` animate the panel, whose motion a closed drawer
+ *   waits for before it unmounts or hides (focus, the trap and the isolation follow the open
+ *   state at once).
  *
  * The sub-components are also exported under flat names (`DrawerTrigger`, `DrawerClose`,
- * `DrawerTitle`) for React Server Components, which cannot use the dotted form; dotted access
+ * `DrawerTitle`, `DrawerHeader`, `DrawerHeaderTitle`, `DrawerHeaderNavigation`, `DrawerBody`,
+ * `DrawerFooter`) for React Server Components, which cannot use the dotted form; dotted access
  * (`Drawer.Trigger`) needs a client file.
  *
  * @example
- * <Drawer title="Filters">
+ * <Drawer>
  *   <Drawer.Trigger><Button>Filters</Button></Drawer.Trigger>
- *   <FilterForm />
- *   <Drawer.Close><Button appearance="primary">Apply</Button></Drawer.Close>
+ *   <Drawer.Header>
+ *     <Drawer.HeaderTitle>Filters</Drawer.HeaderTitle>
+ *   </Drawer.Header>
+ *   <FilterForm id="filters" />
+ *   <Drawer.Footer>
+ *     <Button appearance="primary" type="submit" form="filters">Apply</Button>
+ *     <Drawer.Close><Button>Cancel</Button></Drawer.Close>
+ *   </Drawer.Footer>
  * </Drawer>
  */
 export declare const Drawer: {
-    ({ open: openProp, defaultOpen, onOpenChange, position, title, closeLabel, finalFocusRef, children, className, id, ref, ...rest }: DrawerProps): React_2.JSX.Element;
+    ({ open: openProp, defaultOpen, onOpenChange, type, separator, position, size, modalType, backdrop, closeButton, titleAction, title, closeLabel, finalFocusRef, unmountOnClose, children, id, ref, ...rest }: DrawerProps): JSX.Element;
     displayName: string;
 } & {
     Trigger: {
-        (props: DrawerTriggerProps): React_2.ReactNode;
+        (props: DrawerTriggerProps): ReactNode;
         displayName: string;
     };
     Close: {
-        (props: DrawerCloseProps): React_2.ReactNode;
+        (props: DrawerCloseProps): ReactNode;
         displayName: string;
     };
     Title: {
-        ({ id, className, children, ref, ...rest }: DrawerTitleProps): React_2.JSX.Element;
+        ({ id, headingLevel, className, children, ref, ...rest }: DrawerTitleProps): JSX.Element;
+        displayName: string;
+    };
+    Header: {
+        ({ className, children, ref, ...rest }: DrawerHeaderProps): JSX.Element | null;
         displayName: string;
     };
+    HeaderTitle: {
+        ({ id, headingLevel, action, className, children, ref, ...rest }: DrawerHeaderTitleProps): JSX.Element;
+        displayName: string;
+    };
+    HeaderNavigation: {
+        ({ className, children, ref, ...rest }: DrawerHeaderNavigationProps): JSX.Element;
+        displayName: string;
+    };
+    Body: {
+        ({ className, children, ref, ...rest }: DrawerBodyProps): JSX.Element;
+        displayName: string;
+    };
+    Footer: {
+        ({ className, children, ref, ...rest }: DrawerFooterProps): JSX.Element | null;
+        displayName: string;
+    };
+};
+
+/**
+ * Optional: gives the drawer's scrolling body your props (`className`, `style`, `ref`, `id`,
+ * `role`, `tabIndex`, `aria-*`, `data-*`, handlers), for example `tabIndex={0} role="region"
+ * aria-label="…"` to let the keyboard scroll a body without focusable content (the body then
+ * shows the focus ring inside its edge). Its children render in its place among the drawer's
+ * other content. Make it a direct child of `Drawer` (a Fragment there is fine) and render one;
+ * nested in an element or rendered by a component of yours it renders as an element inside the
+ * body, with a development warning. Fluent's `DrawerBody`.
+ */
+export declare const DrawerBody: {
+    ({ className, children, ref, ...rest }: DrawerBodyProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * Drawer.Body: `root` on the scrolling body while a Drawer.Body gives it its props (the body also
+ * carries Drawer's `body`), or on the element of a Drawer.Body rendered inside the body.
+ */
+export declare const drawerBodyClassNames: {
+    readonly root: "wave-drawer-body";
 };
 
+/** Properties for the DrawerBody sub-component. */
+export declare interface DrawerBodyProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    /** Content of the scrolling body, rendered in the Body's place among the other content. */
+    children?: React_2.ReactNode;
+    /** Ref to the scrolling body element. */
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
 /**
- * Drawer: `root` on the portaled panel (`role="dialog"`, while open); `backdrop` on the backdrop;
- * `header` on the header row; `closeButton` on the Close button (which also carries Button's
- * root); `body` on the scrolling body. The heading of its `title` prop carries Drawer.Title's
- * class.
+ * Drawer: `root` on the panel (the portaled `role="dialog"` element of an overlay drawer, while it
+ * is open or kept mounted, or the `<aside>` of an inline one); `backdrop` on the backdrop of a
+ * modal or alert overlay drawer; `header` on the built-in header row (absent with a
+ * Drawer.Header); `titleAction` on the element of the `titleAction` slot in that row;
+ * `closeButton` on every built-in Close button (which also carries Button's root), in the built-in
+ * header and in each Drawer.HeaderTitle; `body` on the scrolling body. The heading of its `title`
+ * prop carries Drawer.Title's class. The panel carries `data-type`, `data-position` and
+ * `data-size`; the body, the header and the footer carry `data-scroll-state`.
  */
 export declare const drawerClassNames: {
     readonly root: "wave-drawer";
     readonly backdrop: "wave-drawer__backdrop";
     readonly header: "wave-drawer__header";
+    readonly titleAction: "wave-drawer__title-action";
     readonly closeButton: "wave-drawer__close-button";
     readonly body: "wave-drawer__body";
 };
@@ -3818,11 +4089,144 @@ export declare interface DrawerCloseRenderProps extends React_2.HTMLAttributes<H
     ref: React_2.RefCallback<HTMLElement>;
 }
 
-/** The second argument of a {@link Drawer}'s `onOpenChange`: the reason and the DOM event. */
+/**
+ * The drawer's action row, below the scrolling body: it never scrolls and never covers a focused
+ * field. Its actions start at the inline start and wrap. Make it a direct child of `Drawer` (a
+ * Fragment there is fine): it renders after the body wherever it is written; nested in an element
+ * (a `<form>`) or rendered by a component of yours it renders where it is, in the body, with a
+ * development warning. For a form in the body, give the footer's submit button `form={formId}`.
+ * It draws a line above itself while content continues below (`data-scroll-state`). A footer
+ * whose children render nothing renders no element. Fluent's `DrawerFooter`.
+ */
+export declare const DrawerFooter: {
+    ({ className, children, ref, ...rest }: DrawerFooterProps): React_2.JSX.Element | null;
+    displayName: string;
+};
+
+/** Drawer.Footer: `root` on the footer element. */
+export declare const drawerFooterClassNames: {
+    readonly root: "wave-drawer-footer";
+};
+
+/** Properties for the DrawerFooter sub-component. */
+export declare interface DrawerFooterProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    /** The drawer's actions, typically buttons (wrap closing ones in `Drawer.Close`). */
+    children?: React_2.ReactNode;
+    /** Ref to the footer element. */
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
+/**
+ * The drawer's header, replacing the built-in one (the `title` and Close button row): a
+ * `Drawer.HeaderNavigation` row and a `Drawer.HeaderTitle`, or your own content. The built-in
+ * Close button ends each `Drawer.HeaderTitle`; a header without one has no Close button (wrap your
+ * own in `Drawer.Close`). Make it a direct child of `Drawer` (a Fragment there is fine); nested in
+ * an element or rendered by a component of yours it renders in the body, with a development
+ * warning. It draws a line under itself while the body is scrolled away from its top
+ * (`data-scroll-state`). When an overlay drawer opens, focus goes to the header's first focusable
+ * element (a Back button, a title action): give the control that should start `autoFocus`. A
+ * header whose children render nothing renders no element (the drawer then has no header; Escape
+ * and the backdrop of an overlay, and `Drawer.Close`, still close it). Fluent's `DrawerHeader`.
+ */
+export declare const DrawerHeader: {
+    ({ className, children, ref, ...rest }: DrawerHeaderProps): React_2.JSX.Element | null;
+    displayName: string;
+};
+
+/** Drawer.Header: `root` on the header element (it replaces the built-in header row). */
+export declare const drawerHeaderClassNames: {
+    readonly root: "wave-drawer-header";
+};
+
+/**
+ * A `<nav>` row at the top of `Drawer.Header`, for a multi-level drawer's Back button and the
+ * drawer's commands. Give it an `aria-label` when the page has other navigation landmarks.
+ * Fluent's `DrawerHeaderNavigation`.
+ */
+export declare const DrawerHeaderNavigation: {
+    ({ className, children, ref, ...rest }: DrawerHeaderNavigationProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/** Drawer.HeaderNavigation: `root` on the navigation element. */
+export declare const drawerHeaderNavigationClassNames: {
+    readonly root: "wave-drawer-header-navigation";
+};
+
+/** Properties for the DrawerHeaderNavigation sub-component. */
+export declare interface DrawerHeaderNavigationProps extends React_2.HTMLAttributes<HTMLElement> {
+    /** The navigation controls: a Back button, a Toolbar of commands. */
+    children?: React_2.ReactNode;
+    /** Ref to the `<nav>` element. */
+    ref?: React_2.Ref<HTMLElement>;
+}
+
+/** Properties for the DrawerHeader sub-component. */
+export declare interface DrawerHeaderProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    /** `Drawer.HeaderNavigation`, `Drawer.HeaderTitle`, or any content, in the order written. */
+    children?: React_2.ReactNode;
+    /** Ref to the header element. */
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
+/**
+ * A title row for `Drawer.Header`: the heading that names the drawer, your `action` content and
+ * the built-in Close button (named by the Drawer's `closeLabel`; the Drawer's `closeButton` sets
+ * its content, or hides it with `null`), in that DOM and Tab order.
+ * Render one per header; `headingLevel` picks the heading element (`h2` by default). Outside a
+ * `Drawer.Header` it renders without the Close button and warns: use `Drawer.Title` for a heading
+ * in the body. Unlike Fluent's `DrawerHeaderTitle`, whose `action` is where you put a close
+ * button, it renders the Close button itself.
+ */
+export declare const DrawerHeaderTitle: {
+    ({ id, headingLevel, action, className, children, ref, ...rest }: DrawerHeaderTitleProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * Drawer.HeaderTitle: `root` on the title row; `heading` on the heading that names the drawer;
+ * `action` on the element of the `action` slot. Its Close button carries Drawer's `closeButton`.
+ */
+export declare const drawerHeaderTitleClassNames: {
+    readonly root: "wave-drawer-header-title";
+    readonly heading: "wave-drawer-header-title__heading";
+    readonly action: "wave-drawer-header-title__action";
+};
+
+/** Properties for the DrawerHeaderTitle sub-component. */
+export declare interface DrawerHeaderTitleProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    /** The title; any content. The heading names the drawer (`aria-labelledby`). */
+    children: React_2.ReactNode;
+    /**
+     * Content between the heading and the built-in Close button, such as icon buttons for the
+     * drawer's own commands (Fluent's `action`). It comes before the Close button in DOM and Tab
+     * order and is interactive (not `aria-hidden`): name icon-only buttons. Renders nothing when it
+     * renders no content.
+     */
+    action?: Slot<'span'>;
+    /** Id of the heading element, the element that names the drawer. @default a generated id */
+    id?: string;
+    /**
+     * Level of the heading element (`h1` … `h6`). Fluent's `heading` slot, which also takes another
+     * element.
+     * @default 2
+     */
+    headingLevel?: HeadingLevel;
+    /** Ref to the title row (the heading's parent). */
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
+/**
+ * How a `Drawer` relates to the page: `modal`, `alert` or `non-modal` (the shared `ModalType`;
+ * `DialogModalType` is the same type).
+ */
+export declare type DrawerModalType = ModalType;
+
+/** The second argument of a `Drawer`'s `onOpenChange`: the reason and the DOM event. */
 export declare type DrawerOpenChangeDetails = OpenChangeDetails<DrawerOpenChangeReason>;
 
 /**
- * Why a {@link Drawer} asks to open or close: `trigger` (`Drawer.Trigger`), `close`
+ * Why a `Drawer` asks to open or close: `trigger` (`Drawer.Trigger`), `close`
  * (`Drawer.Close`), `close-button` (the built-in Close button), `escape`, `outside-press` (the
  * backdrop). The shared `ModalOpenChangeReason`, as for Dialog.
  */
@@ -3830,20 +4234,23 @@ export declare type DrawerOpenChangeReason = ModalOpenChangeReason;
 
 /**
  * Side of the screen the drawer is attached to. `start`/`end` follow the text direction (in a
- * right-to-left layout `end` is the left edge); `left`/`right` are physical sides.
+ * right-to-left layout `end` is the left edge); `left`/`right` are physical sides; `bottom` runs
+ * along the bottom edge, as wide as the viewport. An inline drawer sits where the page layout puts
+ * it: the position picks its inner edge (the one facing the page content) and its size's axis.
  */
-export declare type DrawerPosition = 'start' | 'end' | 'left' | 'right';
+export declare type DrawerPosition = 'start' | 'end' | 'left' | 'right' | 'bottom';
 
 /** Properties for the Drawer component. */
-export declare interface DrawerProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'title'> {
+export declare interface DrawerProps extends Omit<React_2.HTMLAttributes<HTMLElement>, 'title'> {
     /**
-     * Controlled open state of the drawer. The panel renders only in the browser: an open drawer
-     * is closed in the server HTML and opens once it has hydrated.
+     * Controlled open state of the drawer. An overlay drawer's panel renders only in the browser:
+     * open, it is closed in the server HTML and opens once it has hydrated. An inline drawer renders
+     * in the server HTML: open, or hidden when kept mounted (`unmountOnClose={false}`).
      */
     open?: boolean;
     /**
-     * Default open state for uncontrolled usage. The panel renders only in the browser: a drawer
-     * open by default is closed in the server HTML and opens once it has hydrated.
+     * Default open state for uncontrolled usage. An overlay drawer open by default is closed in the
+     * server HTML and opens once it has hydrated; an inline one is open in the server HTML.
      * @default false
      */
     defaultOpen?: boolean;
@@ -3853,61 +4260,193 @@ export declare interface DrawerProps extends Omit<React_2.HTMLAttributes<HTMLDiv
      * `outside-press` (the backdrop) — so a controlled drawer can refuse only some ways of closing
      * (for example keep a form with unsaved changes open on `outside-press`); `details.event` is the
      * DOM event behind the request. WaveUI always passes `details`; it is typed optional until 1.0
-     * so that code which calls this prop itself keeps compiling.
+     * so that code which calls this prop itself keeps compiling. An inline drawer asks only with
+     * `trigger` (its `Drawer.Trigger` toggles it), `close` and `close-button`: Escape and presses
+     * outside it never close it.
      *
      * Fires only when the value changes; a controlled drawer stays as it is until the parent updates
      * `open`.
      */
     onOpenChange?: (open: boolean, details?: DrawerOpenChangeDetails) => void;
+    /**
+     * How the drawer sits on the page (Fluent's `type`).
+     * - `overlay`: a panel over the page, rendered in a portal while open: modal by default (focus
+     *   moves in and stays there, toasts included; the rest of the page is `inert` and does not
+     *   scroll; Escape and a backdrop press close it), or `modalType="non-modal"`.
+     * - `inline`: a panel in the page layout, rendered where the Drawer is (after its direct
+     *   `Drawer.Trigger`s) as an `<aside>`, a complementary landmark named by its title. The page
+     *   stays usable around it: no backdrop, no focus trap, no portal, no scroll lock; Escape and
+     *   presses outside do not close it. Opening it leaves focus where it is; closing it while focus
+     *   is inside returns focus to `finalFocusRef`, else the element that opened it, else the
+     *   trigger. `position` and `size` pick its inner edge and its width (its height at the bottom);
+     *   where it sits is up to your layout (a flex row of panel and content, for example).
+     *   `modalType` and `backdrop` do not apply to it, and toasts do not move out of its way: it is
+     *   page content.
+     *
+     * Changing `type` remounts the panel and its content (what was typed in it is lost); focus
+     * inside an overlay that becomes inline returns to the trigger, and focus inside an inline panel
+     * that becomes an overlay moves into the overlay. Rendered as `data-type`.
+     * @default 'overlay'
+     */
+    type?: DrawerType;
+    /**
+     * Inline drawers: draws a line on the panel's inner edge, the edge facing the page content
+     * (`data-separator`). An overlay drawer always draws that edge and ignores this prop. In forced
+     * colours an inline drawer's inner edge is always drawn. Fluent's `separator`.
+     * @default false
+     */
+    separator?: boolean;
     /**
      * Side of the screen the drawer is attached to. `start`/`end` follow the text direction;
-     * `left`/`right` are physical sides.
+     * `left`/`right` are physical sides; `bottom` runs along the bottom edge (`size` sets its
+     * height). An inline drawer takes its place from your layout: `position` picks its inner edge
+     * (the one facing the page content: the end edge of a `start` panel, the top edge of a `bottom`
+     * one) and the axis `size` sets. Rendered as `data-position`.
      * @default 'end'
      */
     position?: DrawerPosition;
     /**
-     * Title displayed in the drawer header; it names the drawer (`aria-labelledby`). Without it,
-     * render a `Drawer.Title` or pass `aria-label`/`aria-labelledby`. A title that renders nothing
-     * (`''`, `[]`, `true`) counts as none.
+     * The panel's width at a side — `small` 320px, `medium` 592px, `large` 940px, `full` the
+     * viewport's width — or its height at the bottom (the same values; `full` the viewport's height).
+     * It never exceeds the viewport. An inline panel takes the same sizes, where `full` is its
+     * container's width (height), and never grows past its container. A width class in `className`
+     * (a height class for `bottom`) replaces it. Rendered as `data-size`. Fluent's `size`.
+     * @default 'small'
+     */
+    size?: DrawerSize;
+    /**
+     * `modal`, `alert` or `non-modal`, as Dialog's `modalType`. `modal`: the page behind is `inert`
+     * and does not scroll; a backdrop press, Escape, the Close button and `Drawer.Close` close it.
+     * `alert`: `role="alertdialog"` (a `role` you pass wins), and a backdrop press does not close it
+     * (Escape still does). `non-modal`: no backdrop, and the page stays usable — no focus trap,
+     * nothing inert, the page scrolls; Tab and Shift+Tab leave the drawer in the page's order right
+     * after the element that opened it, Escape closes it while focus is inside it, presses on the
+     * page never close it, and focus returns to the opener only when it was inside the drawer. A
+     * non-modal drawer covers the page under it while Tab still reaches that page: reserve its width
+     * (its height at the bottom) in your layout while it is open, or use `modal`, or, for a panel
+     * beside the content, an inline drawer (`type="inline"`) (with `size="full"` it covers
+     * everything, and a development warning says so). Every type moves focus to the first focusable
+     * element on open. Rendered as `data-modal-type`. Ignored by an inline drawer, which is never
+     * modal and renders no `data-modal-type`. Fluent's `modalType`.
+     * @default 'modal'
+     */
+    modalType?: DrawerModalType;
+    /**
+     * The backdrop of a modal or alert drawer, as `Dialog.Content`'s `backdrop`: a `div` behind the
+     * panel, `aria-hidden`. Shorthand content renders inside it; a slot object's `className` (merged
+     * last), `style`, data attributes, `ref` and handlers go to it, and its `appearance`
+     * (`'dimmed'` or `'transparent'`) overrides the automatic one: while another modal Dialog or
+     * Drawer is open below this one the backdrop is transparent, so the page is dimmed once. `null`
+     * renders no backdrop (the page stays inert, and a press outside still closes a modal drawer); a
+     * boolean is no slot. Ignored with `modalType="non-modal"` and by an inline drawer (a
+     * development warning says so). Fluent's `backdrop`.
+     */
+    backdrop?: Slot<'div'> | (SlotObject<'div'> & {
+        appearance?: BackdropAppearance;
+    });
+    /**
+     * Content of the built-in Close button, in the built-in header and in every
+     * `Drawer.HeaderTitle`, as `Dialog.Content`'s `closeButton`: decorative content inside the button
+     * (the dismiss glyph by default), so the button keeps the name `closeLabel`; a slot object's
+     * `aria-label`, `aria-labelledby` or `title` names it instead, and its handlers run before the
+     * close (`preventDefault()` keeps the drawer open). `null` hides them all (`Drawer.Close`, and
+     * Escape on an overlay, still close); a boolean is no slot; content that renders nothing keeps the
+     * default glyph. A `<button>` or Wave `Button` passed here is merged into the built-in button,
+     * never nested (a development warning says so), and its text label names the button. Fluent's
+     * `DrawerHeaderTitle` `action` holds Fluent's close button; WaveUI renders its own.
+     */
+    closeButton?: Slot<'span'>;
+    /**
+     * Header buttons for the `title` prop form, between the heading and the built-in Close button in
+     * DOM and Tab order. Ignored, with a development warning, next to a `Drawer.Header` (use the
+     * `action` of `Drawer.HeaderTitle`). Interactive: name icon-only buttons. Renders nothing when
+     * empty. Fluent's `DrawerHeaderTitle` `action`, for the `title` prop form.
+     */
+    titleAction?: Slot<'span'>;
+    /**
+     * Title displayed in the built-in header; it names the drawer (`aria-labelledby`). Without it,
+     * render a `Drawer.HeaderTitle` (in a `Drawer.Header`) or a `Drawer.Title`, or pass
+     * `aria-label`/`aria-labelledby`. A title that renders nothing (`''`, `[]`, `true`) counts as
+     * none. Ignored, with a development warning, when the children hold a `Drawer.Header`, which
+     * replaces the built-in header. The heading is an `<h2>`; for another level use
+     * `Drawer.HeaderTitle` with `headingLevel`. In the server HTML of an inline drawer only `title`
+     * (or `aria-label`/`aria-labelledby`) names the panel: a `Drawer.HeaderTitle` or `Drawer.Title`
+     * names it once the page has hydrated.
      */
     title?: React_2.ReactNode;
     /**
-     * Accessible name of the built-in Close button (an icon-only button). Localize it with the
-     * page's language.
+     * Accessible name of the built-in Close button (an icon-only button), in the built-in header and
+     * in every `Drawer.HeaderTitle`. Localize it with the page's language. A text label of a button
+     * merged into `closeButton` names it instead.
      * @default 'Close'
      */
     closeLabel?: string;
     /**
      * Where focus goes when the drawer closes, if it can take focus. Otherwise focus returns to the
      * element that had focus when the drawer opened, then to the trigger, then to an element next to
-     * where that opener was.
+     * where that opener was. An inline or non-modal drawer moves focus on close only when focus was
+     * inside it.
      */
     finalFocusRef?: React_2.RefObject<HTMLElement | null>;
     /**
-     * The drawer body. `Drawer.Trigger` children placed directly inside the Drawer, or in a Fragment
-     * there (`{isMobile && <>…</>}`), render in place (outside the panel); everything else renders in
-     * the panel's scrolling body. A `Drawer.Trigger` nested in another element, or rendered by a
-     * component, is panel content, so it only exists while the drawer is open (development warnings
-     * say so, also when an uncontrolled drawer still has no direct trigger a second after it mounts
-     * and therefore cannot open; a controlled drawer whose trigger a component such as a Tooltip
-     * wraps warns only once it opens).
+     * Removes the panel and its content when the drawer closes. `false` keeps them mounted while
+     * closed, `hidden` and `inert` (out of the layout, the Tab order and the accessibility tree), so
+     * what was typed and the state of the components inside survive closing and opening again; the
+     * content then mounts with the Drawer, closed, and an `autoFocus` inside it never applies (an
+     * overlay focuses its first focusable element on each open). An overlay panel still renders only
+     * in the browser; a kept inline panel is in the server HTML, hidden. Kept content still belongs
+     * to its form: a `required` empty field in a closed inline drawer inside a page `<form>` blocks
+     * its submission without a visible message. A popup opened inside that is still open when the
+     * drawer closes stays open over the page (a development warning says so): close it first. A
+     * `key` on the Drawer resets the kept content. Fluent's `unmountOnClose`.
+     * @default true
+     */
+    unmountOnClose?: boolean;
+    /**
+     * The drawer's content, placed by the Drawer, also from a Fragment (`{isMobile && <>…</>}`) and
+     * when written in a Server Component: `Drawer.Trigger` children render in place (outside the
+     * panel); a `Drawer.Header` replaces the built-in header (the `title` and Close button row); a
+     * `Drawer.Body` gives the scrolling body its props; `Drawer.Footer` renders below the scrolling
+     * body, outside it, wherever it is written among the children; everything else renders in the
+     * scrolling body. A part nested in another element (a `<form>`) or rendered by a component of
+     * yours renders where it is, in the body (a development warning says so). A `Drawer.Trigger`
+     * nested in another element, or rendered by a component, is panel content, so it is not rendered
+     * (or, kept mounted, is hidden) while the drawer is closed (development warnings say so, also
+     * when an uncontrolled drawer still has no direct trigger a second after it mounts and therefore
+     * cannot open; a controlled drawer whose trigger a component such as a Tooltip wraps warns only
+     * once it renders in the panel).
      * Put wrappers inside the trigger instead: see `Drawer.Trigger`.
      */
     children: React_2.ReactNode;
-    /** Ref to the drawer panel (`role="dialog"`). */
-    ref?: React_2.Ref<HTMLDivElement>;
+    /**
+     * Ref to the panel: the `role="dialog"` element of an overlay drawer (`alertdialog` with
+     * `modalType="alert"`), the `<aside>` of an inline one. A ref to a `div` still type-checks.
+     */
+    ref?: React_2.Ref<HTMLElement>;
 }
 
+/**
+ * How much room a Drawer takes: its width at a side, its height at the bottom. `small` 320px,
+ * `medium` 592px, `large` 940px; `full` the viewport (an inline drawer: its container). The shared
+ * `SurfaceSize`.
+ */
+export declare type DrawerSize = SurfaceSize;
+
 /**
  * A heading that names the drawer (`aria-labelledby`), for rich titles or custom layouts. Render it
- * inside the Drawer's content (instead of the `title` prop).
+ * inside the Drawer's content (instead of the `title` prop); for the title of a composed header,
+ * use `Drawer.HeaderTitle` in a `Drawer.Header`. `headingLevel` picks the heading element (`h2`
+ * by default).
  */
 export declare const DrawerTitle: {
-    ({ id, className, children, ref, ...rest }: DrawerTitleProps): React_2.JSX.Element;
+    ({ id, headingLevel, className, children, ref, ...rest }: DrawerTitleProps): React_2.JSX.Element;
     displayName: string;
 };
 
-/** Drawer.Title: `root` on the `<h2>`. */
+/**
+ * Drawer.Title: `root` on its heading (an `<h2>`, or the level `headingLevel` picks); also on the
+ * heading of Drawer's `title` prop.
+ */
 export declare const drawerTitleClassNames: {
     readonly root: "wave-drawer-title";
 };
@@ -3916,21 +4455,34 @@ export declare const drawerTitleClassNames: {
 export declare interface DrawerTitleProps extends React_2.HTMLAttributes<HTMLHeadingElement> {
     /** The title; any content. */
     children: React_2.ReactNode;
+    /**
+     * Level of the heading element (`h1` … `h6`). Fluent's `heading` slot, which also takes another
+     * element.
+     * @default 2
+     */
+    headingLevel?: HeadingLevel;
     /** Ref to the heading element. */
     ref?: React_2.Ref<HTMLHeadingElement>;
 }
 
 /**
- * Opens the drawer. Place it directly inside `Drawer`, or in a Fragment there (not inside a wrapper
- * element or a component of your own): it renders in place, not in the panel; a misplaced one warns
- * in development. A Drawer may have several triggers: focus returns to the one that opened it. Puts
- * `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` (while open), a click handler and a
- * ref on its single child, or passes them to a render-prop child. A custom child component must
- * forward `ref` and spread its props; one that does not is wrapped in a `<span>` automatically
- * (with a development warning), the span that `asChild={false}` renders. Focus returns to the
- * trigger when the drawer closes. On the span, the state ARIA goes to the first element in the tab
- * order inside it, and focus returns to that element (to the span when you made it the trigger
- * with a `role` such as `button` and `tabIndex={0}`, or when nothing inside it can take focus).
+ * Opens and closes the drawer: a click while it is open asks it to close (reason `trigger`), which
+ * the trigger of a non-modal or inline drawer can receive (a modal one makes the page inert).
+ * Fluent's `DialogTrigger` never toggles (outside the surface it only opens, inside it only
+ * closes); this trigger always does.
+ * Place it directly inside `Drawer`, or in a Fragment there (not inside a wrapper element or a
+ * component of your own): it renders in place, not in the panel (an inline drawer's triggers
+ * render right before its panel, so the panel follows its button in the reading order); a
+ * misplaced one warns in development. A Drawer may have several triggers: focus returns to the one
+ * that opened it. Puts `aria-haspopup="dialog"` (none on an inline drawer's trigger: an inline
+ * panel is page content, not a popup), `aria-expanded`, `aria-controls` (while open), a click
+ * handler and a ref on its single child, or passes them to a render-prop child. A custom child
+ * component must forward `ref` and spread its props; one that does not is wrapped in a `<span>`
+ * automatically (with a development warning), the span that `asChild={false}` renders. Focus
+ * returns to the trigger when the drawer closes (for a non-modal or inline drawer, only when focus
+ * was inside it). On the span, the state ARIA goes to the first element in the tab order inside
+ * it, and focus returns to that element (to the span when you made it the trigger with a `role`
+ * such as `button` and `tabIndex={0}`, or when nothing inside it can take focus).
  *
  * A Tooltip (or any other wrapper) goes inside the trigger, not around it. Use a render-prop child
  * so the trigger props land on the button and the Tooltip describes that same button:
@@ -3955,8 +4507,8 @@ export declare const DrawerTrigger: {
 /** Properties for the DrawerTrigger sub-component. */
 export declare interface DrawerTriggerProps extends Omit<React_2.HTMLAttributes<HTMLElement>, 'children'> {
     /**
-     * The element that opens the drawer. A single element receives the trigger props (merged with its
-     * own); a function receives them.
+     * The element that opens and closes the drawer. A single element receives the trigger props
+     * (merged with its own); a function receives them.
      */
     children: React_2.ReactNode | ((props: DrawerTriggerRenderProps) => React_2.ReactNode);
     /**
@@ -3972,7 +4524,10 @@ export declare interface DrawerTriggerProps extends Omit<React_2.HTMLAttributes<
 
 /** Props a `Drawer.Trigger` puts on its element (and passes to a render-prop child). */
 export declare interface DrawerTriggerRenderProps extends React_2.HTMLAttributes<HTMLElement> {
-    'aria-haspopup': 'dialog';
+    /**
+     * `'dialog'` for an overlay drawer; absent (no key) for an inline drawer, which is not a popup.
+     */
+    'aria-haspopup'?: 'dialog';
     'aria-expanded': boolean;
     /** The panel's id, while the drawer is open. */
     'aria-controls'?: string;
@@ -3981,6 +4536,12 @@ export declare interface DrawerTriggerRenderProps extends React_2.HTMLAttributes
     ref: React_2.RefCallback<HTMLElement>;
 }
 
+/**
+ * How a Drawer sits on the page: `overlay`, a panel over the page (in a portal), or `inline`, a
+ * panel in the page layout, rendered where the Drawer is. Fluent's `type`.
+ */
+export declare type DrawerType = 'overlay' | 'inline';
+
 /**
  * A select-only combobox (APG): a button that opens a listbox of `Option`s. Enter, Space,
  * ArrowDown/ArrowUp, Home/End and typing a character open it and move the highlight
@@ -4167,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
@@ -4660,6 +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
@@ -4710,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`).
@@ -4737,6 +5360,82 @@ export declare interface GridOwnProps {
  */
 export declare type GridProps<C extends React_2.ElementType = 'div'> = PolymorphicProps<C, GridOwnProps>;
 
+/**
+ * A button that opens and closes a navigation drawer: a `Button` (`subtle`, icon-only) with the
+ * navigation glyph, named "Navigation" by default. Inside a `NavDrawer` (in its header) it toggles
+ * that drawer and reports it with `aria-expanded` and `aria-controls`. Elsewhere (your page
+ * header) it is a plain button: pass `aria-expanded={open}`, `aria-controls` (while the drawer's
+ * panel is rendered) and, for an overlay drawer, `aria-haspopup="dialog"`, and toggle your state
+ * in `onClick`. Fluent's `Hamburger`.
+ *
+ * @example
+ * <Hamburger
+ *   aria-expanded={open}
+ *   aria-controls={open ? 'main-nav' : undefined}
+ *   aria-haspopup="dialog"
+ *   onClick={() => setOpen(!open)}
+ * />
+ */
+export declare const Hamburger: {
+    ({ appearance, size, icon, onClick, className, children, ref, ...rest }: HamburgerProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * Hamburger (a Button variant: it also carries Button's root and icon classes): `root` on the
+ * `<button>`; `icon` on the icon span.
+ */
+export declare const hamburgerClassNames: {
+    readonly root: "wave-hamburger";
+    readonly icon: "wave-hamburger__icon";
+};
+
+/** Properties for the Hamburger component. */
+export declare interface HamburgerProps extends React_2.ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Visual style. Fluent's `transparent` look is WaveUI's `subtle` (WaveUI's `transparent` is
+     * link-coloured).
+     * @default 'subtle'
+     */
+    appearance?: Appearance;
+    /**
+     * Size: the button's height and the glyph (12, 16, 20, 24 or 28px).
+     * @default 'medium'
+     */
+    size?: Size;
+    /**
+     * Replaces the navigation glyph (three bars). Decorative (`aria-hidden`). Unlike Button's `icon`,
+     * a Hamburger always shows a glyph: `null`, `undefined` and a value that renders nothing keep
+     * the default (the last warns in development). A `<button>` or `Button` passed here is not
+     * nested: its children become the glyph and its props are dropped, with a warning.
+     */
+    icon?: Slot<'span'>;
+    /**
+     * The button's name. Without `aria-label`, `aria-labelledby`, `title` or a visible label
+     * (children), the Hamburger is named "Navigation"; localize it here. The name stays the same
+     * while the drawer opens and closes (the state is `aria-expanded`).
+     * @default 'Navigation'
+     */
+    'aria-label'?: string;
+    /**
+     * Unavailable but focusable (see `Button.disabledFocusable`): no toggle, no `onClick`.
+     * @default false
+     */
+    disabledFocusable?: boolean;
+    /** Ref to the `<button>`. */
+    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;
+
 /**
  * The HSV color of a hex string: `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa` (surrounding whitespace
  * ignored, any case). `a` is set only when the input has alpha digits. Returns `null` for anything
@@ -5127,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'> {
     /**
@@ -5182,50 +5895,244 @@ export declare interface InputProps extends Omit<React_2.InputHTMLAttributes<HTM
     ref?: React_2.Ref<HTMLInputElement>;
 }
 
-/** Whether both dates are on the same calendar day (time of day ignored); `false` when either is missing. */
-export declare function isSameDay(a: Date | null | undefined, b: Date | null | undefined): boolean;
-
 /**
- * A text label for a form control (`htmlFor`), on the Fluent type ramp. The optional required
- * indicator is decorative (`aria-hidden`). `Field` renders its own label; use `Label` for custom
- * layouts.
+ * A tag with a main action and a separate Dismiss button: an element that holds two sibling
+ * buttons, `InteractionTag.Primary` (the action) and `InteractionTag.Secondary` (Dismiss), never
+ * one inside the other. Use it for a chip the user acts on (opens, toggles) and can also remove;
+ * a `Tag` is a chip that only displays, or only dismisses.
+ *
+ * - **Two Tab stops**, the Primary then the Secondary. In a TagGroup toolbar both join its arrow
+ *   order (Primary, Secondary, next tag).
+ * - **The Secondary is named after the Primary's text**: its `dismissLabel` plus the primary
+ *   text, "Dismiss Cherry" (never the secondary text). A text label in its children replaces
+ *   `dismissLabel` ("Remove Cherry"); an `aria-label` replaces the whole name.
+ * - **Delete and Backspace** on either button dismiss the tag through the Secondary's click (a
+ *   held key dismisses once); without a Secondary they do nothing. Enter, Space and a click on the
+ *   Secondary dismiss too: remove the tag in its `onClick`, or in a TagGroup's `onDismiss(value)`,
+ *   which is called after it.
+ * - **In a selecting TagGroup** (`value`, `defaultValue` or `onValueChange` on the group) the
+ *   Primary toggles the tag's `value` in the group's selection (`aria-pressed`, the selected
+ *   look), and dismissing a selected tag also removes its value from the selection.
+ * - **`selected`**, outside a selecting TagGroup, draws the selected look and makes the Primary a
+ *   toggle (`aria-pressed`); leave it `undefined` for an action that is not a toggle.
+ * - **Look**: `size`, `appearance` and `shape`, Tag's sizes and colours (a TagGroup gives its
+ *   defaults); `disabled` disables both buttons natively. The Primary takes `media` (an Avatar,
+ *   sized for the tag), `icon` and `secondaryText`.
+ * - Fluent's `hasSecondaryAction` is not needed: the Primary squares its end corners next to a
+ *   Secondary by itself, also when the Secondary is rendered conditionally or wrapped.
+ * - React Server Components cannot dot into a client module: import the flat names
+ *   `InteractionTagPrimary` and `InteractionTagSecondary` there.
+ * - Renders `data-appearance`, `data-size` and `data-shape`, and while set `data-selected` and
+ *   `data-disabled`, on the root; `data-selected` on both buttons.
  *
  * @example
- * <Label htmlFor="email" required>Email</Label>
- * <Input id="email" required />
- */
-export declare const Label: {
-    ({ required, disabled, size, weight, className, children, ref, ...rest }: LabelProps): React_2.JSX.Element;
+ * <InteractionTag value="cherry">
+ *   <InteractionTag.Primary icon={<FruitIcon />} onClick={openDetails}>
+ *     Cherry
+ *   </InteractionTag.Primary>
+ *   <InteractionTag.Secondary onClick={() => remove('cherry')} />
+ * </InteractionTag>
+ */
+export declare const InteractionTag: {
+    ({ value, appearance: appearanceProp, size: sizeProp, shape: shapeProp, disabled: disabledProp, selected: selectedProp, role, hidden, className, children, ref, ...rest }: InteractionTagProps): React_2.JSX.Element;
     displayName: string;
+} & {
+    Primary: {
+        ({ media, icon, secondaryText, disabled: disabledProp, "aria-pressed": ariaPressed, className, children, onClick, onKeyDown, onFocus, onBlur, ref, ...rest }: InteractionTagPrimaryProps): React_2.JSX.Element;
+        displayName: string;
+    };
+    Secondary: {
+        ({ dismissLabel, disabled: disabledProp, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className, children, onClick, onKeyDown, onFocus, onBlur, ref, ...rest }: InteractionTagSecondaryProps): React_2.JSX.Element;
+        displayName: string;
+    };
 };
 
-/** Label: `root` on the `<label>`; `required` on the asterisk. */
-export declare const labelClassNames: {
-    readonly root: "wave-label";
-    readonly required: "wave-label__required";
+/** InteractionTag: `root` on the element that holds its two buttons. */
+export declare const interactionTagClassNames: {
+    readonly root: "wave-interaction-tag";
 };
 
 /**
- * Where a label renders relative to its control or indicator. Components accept a subset,
- * derived with `Extract<LabelPosition, …>` (never `Exclude<>`, so a later value does not widen
- * them silently): Checkbox `'before' | 'after'`, Switch `'before' | 'after' | 'above'`.
+ * The main action of an {@link InteractionTag}: a `<button type="button">` named by its text and
+ * `secondaryText` (`media` and `icon` are decorative), with the InteractionTag's look. In a
+ * selecting TagGroup it is a toggle (`aria-pressed`): a click, Enter or Space adds the tag's
+ * `value` to the group's selection or removes it, after its `onClick` (whose `preventDefault()`
+ * cancels the toggle). Elsewhere the InteractionTag's `selected` makes it a toggle. Either state
+ * renders its `aria-pressed` over one passed here, which applies only when neither is set. Delete
+ * and Backspace on it click the tag's Secondary when there is one. Its props, `ref` and
+ * `className` go to the button. Flat name of `InteractionTag.Primary`, for React Server
+ * Components.
  */
-export declare type LabelPosition = 'before' | 'after' | 'above' | 'below';
+export declare const InteractionTagPrimary: {
+    ({ media, icon, secondaryText, disabled: disabledProp, "aria-pressed": ariaPressed, className, children, onClick, onKeyDown, onFocus, onBlur, ref, ...rest }: InteractionTagPrimaryProps): React_2.JSX.Element;
+    displayName: string;
+};
 
-/** Properties for the Label component. */
-export declare interface LabelProps extends React_2.LabelHTMLAttributes<HTMLLabelElement> {
-    /** Whether to show a required indicator. `true` shows a decorative asterisk; other content
-     * replaces it (for example a `(required)` text). Decorative (`aria-hidden`), so it must not be
-     * focusable; mark the control itself `required`.
-     * @default false
+/**
+ * InteractionTag.Primary: `root` on its button; `media`, `icon`, `primaryText` and
+ * `secondaryText` on the slot elements.
+ */
+export declare const interactionTagPrimaryClassNames: {
+    readonly root: "wave-interaction-tag-primary";
+    readonly media: "wave-interaction-tag-primary__media";
+    readonly icon: "wave-interaction-tag-primary__icon";
+    readonly primaryText: "wave-interaction-tag-primary__primary-text";
+    readonly secondaryText: "wave-interaction-tag-primary__secondary-text";
+};
+
+/** Props of InteractionTag.Primary: the tag's main action (or its toggle in a selecting TagGroup). */
+export declare interface InteractionTagPrimaryProps extends React_2.ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * A visual before the text (an Avatar, sized for the tag: 24, 20 or 16px, unless it sets its
+     * own `size`). Decorative (`aria-hidden`): the button is named by its text.
      */
-    required?: boolean | React_2.ReactNode;
-    /** Whether the label is visually dimmed.
+    media?: Slot<'span'>;
+    /** A decorative icon before the text (`aria-hidden`), in a 20, 16 or 12px box. */
+    icon?: Slot<'span'>;
+    /**
+     * A second, smaller line under the text. Part of the Primary's name, not of the Secondary's. A
+     * small or extra-small tag grows to 28px to fit it.
+     */
+    secondaryText?: React_2.ReactNode;
+    /**
+     * Disables the Primary natively; or-ed with the InteractionTag's `disabled` (it cannot
+     * re-enable a disabled tag).
      * @default false
      */
     disabled?: boolean;
-    /** Text size of the label: `small` = caption-1, `medium` = body-1, `large` = body-2.
-     * @default 'medium'
+    ref?: React_2.Ref<HTMLButtonElement>;
+}
+
+/** Props of InteractionTag: the element that holds the Primary and Secondary buttons. */
+export declare interface InteractionTagProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Identifies the tag in a TagGroup: the value `onDismiss` receives and the selection holds. Give
+     * every tag of a group its own value.
+     * @default a generated id (a development warning in a group that reports values)
+     */
+    value?: string;
+    /**
+     * Colour scheme of both buttons: `filled` (a neutral fill), `outline` (a border on the surface
+     * behind it) or `brand` (a light brand tint that follows the brand ramp).
+     * @default the TagGroup's `appearance`, else 'filled'
+     */
+    appearance?: TagAppearance;
+    /**
+     * `medium` (28px tall), `small` (24px) or `extra-small` (20px); an Avatar in the Primary's
+     * `media` is 24, 20 or 16px. Fluent's medium tag is 32px.
+     * @default the TagGroup's `size`, else 'medium'
+     */
+    size?: TagSize;
+    /**
+     * `circular` (a pill) or `rounded` (4px corners). Fluent's default is `rounded`.
+     * @default the TagGroup's `shape`, else 'circular'
+     */
+    shape?: TagShape;
+    /**
+     * Disables both buttons natively (a disabled TagGroup does too; a part's own `disabled` cannot
+     * re-enable it). A button that has focus when it is disabled keeps it, unavailable, until focus
+     * leaves it. Rendered as `data-disabled` on the root.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Outside a selecting TagGroup: draws the selected look and makes the Primary a toggle:
+     * `aria-pressed="true"`, or `"false"` for `selected={false}`. Leave it `undefined` for an
+     * action that is not a toggle (no `aria-pressed`). Inside a selecting TagGroup (`value`,
+     * `defaultValue` or `onValueChange`) the group's `value` decides, and a defined `selected` is
+     * ignored (a development warning). Rendered as `data-selected` on the root and both buttons.
+     * Disabled wins over the selected look (`aria-pressed` and `data-selected` still render).
+     * Fluent's `selected` is a look only.
+     */
+    selected?: boolean;
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
+/**
+ * The separate Dismiss button of an {@link InteractionTag}: a `<button type="button">` after the
+ * Primary, named `dismissLabel` plus the Primary's text ("Dismiss Cherry"). Its children replace
+ * the default dismiss glyph; a text label among them replaces `dismissLabel` in the name ("Remove
+ * Cherry"), an `aria-label` the whole name. A button passed as its child is unwrapped (its children
+ * become the content). Enter, Space, a click, Delete and Backspace call its `onClick`, then, in a
+ * TagGroup, the group's `onDismiss(value)`. Its props, `ref` and `className` go to the button.
+ * Flat name of `InteractionTag.Secondary`, for React Server Components.
+ */
+export declare const InteractionTagSecondary: {
+    ({ dismissLabel, disabled: disabledProp, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className, children, onClick, onKeyDown, onFocus, onBlur, ref, ...rest }: InteractionTagSecondaryProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * InteractionTag.Secondary: `root` on its button; `dismissIcon` on the glyph inside it (the
+ * default glyph, or the element that wraps the children).
+ */
+export declare const interactionTagSecondaryClassNames: {
+    readonly root: "wave-interaction-tag-secondary";
+    readonly dismissIcon: "wave-interaction-tag-secondary__dismiss-icon";
+};
+
+/** Props of InteractionTag.Secondary: the tag's separate Dismiss button. */
+export declare interface InteractionTagSecondaryProps extends React_2.ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Visually hidden text that names the button with the Primary's text ("Dismiss Cherry"). A text
+     * label in the children replaces it ("Remove Cherry"); an `aria-label` replaces the whole name.
+     * Localise it here. Fluent's order is the primary text, then the label ("Cherry remove").
+     * @default 'Dismiss'
+     */
+    dismissLabel?: string;
+    /**
+     * Disables the Secondary natively; or-ed with the InteractionTag's `disabled` (it cannot
+     * re-enable a disabled tag).
+     * @default false
+     */
+    disabled?: boolean;
+    ref?: React_2.Ref<HTMLButtonElement>;
+}
+
+/** Whether both dates are on the same calendar day (time of day ignored); `false` when either is missing. */
+export declare function isSameDay(a: Date | null | undefined, b: Date | null | undefined): boolean;
+
+/**
+ * A text label for a form control (`htmlFor`), on the Fluent type ramp. The optional required
+ * indicator is decorative (`aria-hidden`). `Field` renders its own label; use `Label` for custom
+ * layouts.
+ *
+ * @example
+ * <Label htmlFor="email" required>Email</Label>
+ * <Input id="email" required />
+ */
+export declare const Label: {
+    ({ required, disabled, size, weight, className, children, ref, ...rest }: LabelProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/** Label: `root` on the `<label>`; `required` on the asterisk. */
+export declare const labelClassNames: {
+    readonly root: "wave-label";
+    readonly required: "wave-label__required";
+};
+
+/**
+ * Where a label renders relative to its control or indicator. Components accept a subset,
+ * derived with `Extract<LabelPosition, …>` (never `Exclude<>`, so a later value does not widen
+ * them silently): Checkbox `'before' | 'after'`, Switch `'before' | 'after' | 'above'`.
+ */
+export declare type LabelPosition = 'before' | 'after' | 'above' | 'below';
+
+/** Properties for the Label component. */
+export declare interface LabelProps extends React_2.LabelHTMLAttributes<HTMLLabelElement> {
+    /** Whether to show a required indicator. `true` shows a decorative asterisk; other content
+     * replaces it (for example a `(required)` text). Decorative (`aria-hidden`), so it must not be
+     * focusable; mark the control itself `required`.
+     * @default false
+     */
+    required?: boolean | React_2.ReactNode;
+    /** Whether the label is visually dimmed.
+     * @default false
+     */
+    disabled?: boolean;
+    /** Text size of the label: `small` = caption-1, `medium` = body-1, `large` = body-2.
+     * @default 'medium'
      */
     size?: CoreSize;
     /** Font weight of the label (the shared `TextWeight` vocabulary).
@@ -5236,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).
@@ -5775,6 +6692,15 @@ export declare const listboxSurfaceClassNames: {
     readonly list: "wave-listbox-surface__list";
 };
 
+/**
+ * Attributes of the list element that ListboxSurface renders (see `listProps`). Its content is the
+ * surface's `children`.
+ */
+export declare type ListboxSurfaceListProps = Omit<React_2.HTMLAttributes<HTMLUListElement>, 'role' | 'id' | 'hidden' | 'tabIndex' | 'className' | 'aria-label' | 'aria-labelledby' | 'aria-multiselectable' | 'aria-activedescendant' | 'children' | 'dangerouslySetInnerHTML'> & {
+    /** Ref to the `role="listbox"` element (it moves between the picker and the popup). */
+    ref?: React_2.Ref<HTMLUListElement>;
+};
+
 /**
  * Props of {@link ListboxSurface}. The options of one listbox live in one list at a time, and this
  * surface renders that list: render every option of the listbox inside it, never in a second list
@@ -5825,6 +6751,14 @@ export declare interface ListboxSurfaceProps {
      * classes they conflict with.
      */
     surfaceClassName?: string;
+    /**
+     * Attributes spread onto the list element before the listbox's own (`role`, `id`, `tabIndex`,
+     * `aria-multiselectable`, `aria-activedescendant` and `hidden` win, also where the listbox
+     * renders none of the last two): `data-*` and other `aria-*` attributes, `style`, and handlers,
+     * composed before the listbox's own `onMouseDown`. `ref` is merged with the list's. Name the list
+     * with `aria-label`/`aria-labelledby` (the props above), not here.
+     */
+    listProps?: ListboxSurfaceListProps;
     /** The options (`Option`, `OptionGroup` or options of your own on `useListboxOption`). */
     children?: React_2.ReactNode;
 }
@@ -6018,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: {
@@ -6489,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;
 };
 
@@ -6515,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;
     /**
@@ -6982,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
@@ -6989,8 +7946,14 @@ export declare interface MessageBarTitleProps extends React_2.HTMLAttributes<HTM
  */
 export declare type ModalOpenChangeReason = 'trigger' | 'close' | 'close-button' | 'escape' | 'outside-press';
 
-/** How a modal surface blocks the page (`'non-modal'` joins in a later release). */
-export declare type ModalType = 'modal' | 'alert';
+/**
+ * How a Dialog or Drawer relates to the page (Fluent's `modalType`). `modal`: a backdrop dims the
+ * page, focus stays in the surface, the rest of the page is `inert` and does not scroll. `alert`:
+ * modal, for a confirmation that needs an answer (`role="alertdialog"`; a backdrop press does not
+ * close it). `non-modal`: the page stays usable (no backdrop, no focus trap, nothing inert, the
+ * page scrolls).
+ */
+export declare type ModalType = 'modal' | 'alert' | 'non-modal';
 
 /**
  * A vertical side navigation (`<nav>` landmark, default name "Navigation") with items, links and
@@ -7008,12 +7971,25 @@ export declare type ModalType = 'modal' | 'alert';
  *   for sub-items your own component renders inside a closed category.
  * - **Values** are unique: among the items and sub-items, and among the categories (a duplicate
  *   warns in development).
- *
- * Sub-components are also exported under flat names (`NavCategory`, `NavItem`, `NavSubItem`):
- * React Server Components import those, because dotted access (`Nav.Item`) needs a client file.
+ * - **Structure**: every child of the Nav, and of a category, is a part or your own `<li>`; a
+ *   development warning names anything else (a `<div>`, text, the wrapper of a Tooltip around an
+ *   item). `Nav.SectionHeader` is a heading between groups of items (`<h3>` unless
+ *   `headingLevel`, which stands for the `as` of Fluent's NavSectionHeader), and `Nav.Divider` a
+ *   line between groups, hidden from assistive technology (Fluent's NavDivider is a separator).
+ * - **App identity**: `Nav.AppItem` shows the app's name and logo at the top, as a link with
+ *   `href` or a button; it is never selected. `Nav.AppItemStatic` shows them as plain text.
+ * - **Item actions**: `actions` on `Nav.Item` and `Nav.SubItem` (Fluent's SplitNavItem) puts your
+ *   own controls beside the item, in a group named by it; each is a Tab stop after the item, and
+ *   none selects it. They are drawn while the row is hovered or has focus, while one is pressed or
+ *   has its menu open, and always on touch screens and in forced colours. With actions, a selected
+ *   item's background and indicator are drawn on its row (`.wave-nav-item__list-item`).
+ *
+ * Sub-components are also exported under flat names (`NavCategory`, `NavItem`, `NavSubItem`,
+ * `NavSectionHeader`, `NavDivider`, `NavAppItem`, `NavAppItemStatic`): React Server Components
+ * import those, because dotted access (`Nav.Item`) needs a client file.
  */
 export declare const Nav: {
-    ({ value: valueProp, defaultValue: defaultValueProp, onValueChange, selectedValue, defaultSelectedValue, onNavItemSelect, openCategories: openCategoriesProp, defaultOpenCategories, onOpenCategoriesChange, currentCategory, className, children, ref, ...rest }: NavProps): React_2.JSX.Element;
+    ({ value: valueProp, defaultValue: defaultValueProp, onValueChange, selectedValue, defaultSelectedValue, onNavItemSelect, openCategories, defaultOpenCategories, onOpenCategoriesChange, currentCategory, className, children, ref, ...rest }: NavProps): React_2.JSX.Element;
     displayName: string;
 } & {
     Category: {
@@ -7022,8 +7998,139 @@ export declare const Nav: {
     };
     Item: typeof NavItem;
     SubItem: typeof NavSubItem;
+    SectionHeader: {
+        ({ headingLevel, className, children, ref, ...rest }: NavSectionHeaderProps): React_2.JSX.Element | null;
+        displayName: string;
+    };
+    Divider: {
+        ({ className, ref, ...rest }: NavDividerProps): React_2.JSX.Element;
+        displayName: string;
+    };
+    AppItem: typeof NavAppItem;
+    AppItemStatic: {
+        ({ icon, className, children, ref, ...rest }: NavAppItemStaticProps): React_2.JSX.Element;
+        displayName: string;
+    };
+};
+
+/**
+ * The app's name and logo at the top of the navigation: a link with `href` (the app's start page),
+ * a button otherwise. It is never selected and never marked as the current page (a consumer's
+ * `aria-current` passes through), has no `value` and is not registered with the Nav; a click runs
+ * only your `onClick` and the browser's default. A `disabled` button or an `aria-disabled` link
+ * looks unavailable; the item adds no disabled logic of its own. Fluent's AppItem picks its element
+ * through `as`; here `href` does.
+ *
+ * Typed by overloads like `Nav.Item`, resolved in order: without `href` (button props), with a
+ * string `href` (anchor props), then an `href` that may be `undefined` at run time
+ * ({@link NavAppItemDynamicProps}).
+ *
+ * Also exported as `NavAppItem` (import the flat name from React Server Components).
+ */
+export declare function NavAppItem(props: NavAppItemButtonProps): React_2.ReactElement;
+
+export declare function NavAppItem(props: NavAppItemAnchorProps): React_2.ReactElement;
+
+export declare function NavAppItem(props: NavAppItemDynamicProps): React_2.ReactElement;
+
+export declare namespace NavAppItem {
+    var displayName: string;
+}
+
+/**
+ * Nav.AppItem rendered as a link (`href` given): anchor attributes, handlers typed on
+ * `HTMLAnchorElement`.
+ */
+export declare interface NavAppItemAnchorProps extends NavAppItemOwnProps, Omit<React_2.AnchorHTMLAttributes<HTMLAnchorElement>, keyof NavAppItemOwnProps> {
+    /**
+     * URL of the app's start page; renders an `<a>`. Required in this branch, so `href`
+     * discriminates the union.
+     */
+    href: string;
+    /** Ref to the `<a>` element. */
+    ref?: React_2.Ref<HTMLAnchorElement>;
+}
+
+/**
+ * Nav.AppItem rendered as a button (no `href`): button attributes without `value` (an app item is
+ * never selected).
+ */
+export declare interface NavAppItemButtonProps extends NavAppItemOwnProps, NoAnchorOnlyAttributes_2, Omit<React_2.ButtonHTMLAttributes<HTMLButtonElement>, keyof NavAppItemOwnProps | 'value'> {
+    /** Button app items have no `href`. */
+    href?: undefined;
+    /** Ref to the `<button>` element. */
+    ref?: React_2.Ref<HTMLButtonElement>;
+}
+
+/**
+ * Nav.AppItem: `root` on the `<a>` (with `href`) or `<button>`; `listItem` on the list item around
+ * it; `icon` on the icon span; `content` on the label span.
+ */
+export declare const navAppItemClassNames: {
+    readonly root: "wave-nav-app-item";
+    readonly listItem: "wave-nav-app-item__list-item";
+    readonly icon: "wave-nav-app-item__icon";
+    readonly content: "wave-nav-app-item__content";
+};
+
+/**
+ * Nav.AppItem with an `href` known only at run time (`string | undefined`): a link when it is a
+ * string, a button otherwise; only the attributes both elements share, handlers of either element.
+ */
+export declare interface NavAppItemDynamicProps extends NavAppItemOwnProps, Omit<React_2.HTMLAttributes<HTMLAnchorElement | HTMLButtonElement>, keyof NavAppItemOwnProps> {
+    /** URL of the app's start page; renders an `<a>` when defined, a `<button>` otherwise. */
+    href?: string;
+    /** Ref to the rendered `<a>` or `<button>` element. */
+    ref?: React_2.Ref<HTMLAnchorElement | HTMLButtonElement>;
+}
+
+/** The props of Nav.AppItem that every branch shares. */
+export declare interface NavAppItemOwnProps {
+    /**
+     * The app's logo or an Avatar, before its name. Rendered with `aria-hidden="true"` in a box at
+     * least 20px square that grows with its content. A falsy icon (`''`, `0`) or a list of nothing
+     * renders no icon box.
+     */
+    icon?: Slot<'span'>;
+    /** The app's name. */
+    children?: React_2.ReactNode;
+}
+
+/** Properties for the NavAppItem sub-component: link props with `href`, button props without. */
+export declare type NavAppItemProps = NavAppItemAnchorProps | NavAppItemButtonProps;
+
+/**
+ * The app's name and logo as plain text (not a link or button): the layout of `Nav.AppItem` in a
+ * `<div>`, not focusable, with no role and no hover. It does not carry Nav.AppItem's class.
+ *
+ * Also exported as `NavAppItemStatic` (import the flat name from React Server Components).
+ */
+export declare const NavAppItemStatic: {
+    ({ icon, className, children, ref, ...rest }: NavAppItemStaticProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * Nav.AppItemStatic: `root` on the `<div>`; `listItem` on the list item around it; `icon` on the
+ * icon span; `content` on the label span.
+ */
+export declare const navAppItemStaticClassNames: {
+    readonly root: "wave-nav-app-item-static";
+    readonly listItem: "wave-nav-app-item-static__list-item";
+    readonly icon: "wave-nav-app-item-static__icon";
+    readonly content: "wave-nav-app-item-static__content";
 };
 
+/** Properties for the NavAppItemStatic sub-component. */
+export declare interface NavAppItemStaticProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    /** The app's logo or an Avatar (as Nav.AppItem's `icon`). */
+    icon?: Slot<'span'>;
+    /** The app's name. */
+    children?: React_2.ReactNode;
+    /** Ref to the `<div>`. */
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
 /**
  * A collapsible group of sub-items. Its toggle button shows `label` and reports `aria-expanded`
  * (and `aria-controls` while open); the sub-items render in a nested list while it is open.
@@ -7075,7 +8182,10 @@ export declare interface NavCategoryProps extends React_2.HTMLAttributes<HTMLLIE
      * (`''`, `0`) or a list of nothing renders no icon box.
      */
     icon?: Slot<'span'>;
-    /** The category's sub-items (`Nav.SubItem`), rendered in its list while it is open. */
+    /**
+     * The category's sub-items (`Nav.SubItem`), and `Nav.SectionHeader` and `Nav.Divider`, rendered
+     * in its list while it is open.
+     */
     children?: React_2.ReactNode;
     /** Ref to the category's `<li>` element. */
     ref?: React_2.Ref<HTMLLIElement>;
@@ -7087,6 +8197,310 @@ export declare const navClassNames: {
     readonly list: "wave-nav__list";
 };
 
+/**
+ * A line between groups of items, in its own list item, hidden from assistive technology (a list
+ * holds only list items; use `Nav.SectionHeader` to name a group). Fluent's NavDivider is a
+ * `separator`, which a list cannot hold, so this one is decorative.
+ *
+ * Also exported as `NavDivider` (import the flat name from React Server Components).
+ */
+export declare const NavDivider: {
+    ({ className, ref, ...rest }: NavDividerProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/** Nav.Divider: `root` on its list item (hidden from assistive technology). */
+export declare const navDividerClassNames: {
+    readonly root: "wave-nav-divider";
+};
+
+/** Properties for the NavDivider sub-component. */
+export declare interface NavDividerProps extends Omit<React_2.HTMLAttributes<HTMLLIElement>, 'children' | 'role' | 'aria-hidden'> {
+    /** Ref to the divider's list item. */
+    ref?: React_2.Ref<HTMLLIElement>;
+}
+
+/**
+ * A navigation pane in a drawer: Nav's items, categories and selection in a `<nav>` landmark that
+ * sits over the page (`type="overlay"`) or in the page layout (`type="inline"`). Fluent's
+ * `NavDrawer`.
+ *
+ * - **Composition:** `NavDrawer.Header` (a row: a `Hamburger`, the app's name), `NavDrawer.Body`
+ *   (the scrolling list) and `NavDrawer.Footer` (a list pinned below it), rendered in the order
+ *   written. Nav parts (`Nav.Item`, `Nav.Category`, `Nav.SectionHeader`, `Nav.Divider`,
+ *   `Nav.AppItem`, …) go in the Body and the Footer, which render the lists; wrap anything else
+ *   there in an `<li>`.
+ * - **Types:** `overlay` (default) is a panel over the page, in a portal, opened in the browser
+ *   only; `inline` is a panel in the page layout, also in the server HTML. Changing `type`
+ *   remounts the panel; the selection and the open categories are kept.
+ * - **Opening and closing:** keep it controlled (`open`, `onOpenChange`): an uncontrolled drawer
+ *   that is closed cannot open again. A `Hamburger` inside it toggles it (reason `trigger`);
+ *   Escape and a backdrop press close an overlay (`escape`, `outside-press`). Closing an overlay
+ *   when an item is chosen is yours, in `onItemSelect`, which also fires when the current page is
+ *   activated again. A non-modal overlay (`modalType="non-modal"`) covers the page, which keeps
+ *   its Tab order: keep the page's controls clear of it, or use `type="inline"`.
+ * - **Focus:** pass your page's Hamburger as `finalFocusRef`, so focus returns to it when a
+ *   Hamburger inside the drawer closes it. An overlay moves focus in when it opens; an inline
+ *   drawer does not.
+ * - **Keyboard:** every item is a Tab stop; `NavDrawer.Body focusMode="arrow"` makes the body one
+ *   Tab stop with arrow keys, Home and End.
+ * - **Landmark:** one `<nav>`, named "Navigation" by default (`aria-label`, `aria-labelledby`);
+ *   an overlay is also a dialog with that name. Rename it when the page has another navigation
+ *   landmark.
+ * - **Selection:** Nav's `value`/`onValueChange` (only on a change), `openCategories` and
+ *   `currentCategory`, and `onItemSelect` on every activation (Fluent's `selectedValue` and
+ *   `onNavItemSelect`).
+ * - **Server Components:** the parts are also exported as `NavDrawerHeader`, `NavDrawerBody` and
+ *   `NavDrawerFooter`.
+ *
+ * @example
+ * const [open, setOpen] = useState(false);
+ * const hamburgerRef = useRef<HTMLButtonElement>(null);
+ * <Hamburger
+ *   ref={hamburgerRef}
+ *   aria-expanded={open}
+ *   aria-controls={open ? 'main-nav' : undefined}
+ *   aria-haspopup="dialog"
+ *   onClick={() => setOpen(!open)}
+ * />
+ * <NavDrawer
+ *   id="main-nav"
+ *   open={open}
+ *   onOpenChange={setOpen}
+ *   onItemSelect={() => setOpen(false)}
+ *   finalFocusRef={hamburgerRef}
+ *   defaultValue="home"
+ * >
+ *   <NavDrawer.Header>
+ *     <Hamburger />
+ *     Contoso HR
+ *   </NavDrawer.Header>
+ *   <NavDrawer.Body>
+ *     <Nav.Item value="home" href="/">Home</Nav.Item>
+ *   </NavDrawer.Body>
+ * </NavDrawer>
+ */
+export declare const NavDrawer: {
+    ({ type, open: openProp, defaultOpen, onOpenChange, onItemSelect, position, size, separator, modalType: modalTypeProp, unmountOnClose, finalFocusRef, backdrop, value, defaultValue, onValueChange, openCategories, defaultOpenCategories, onOpenCategoriesChange, currentCategory, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, id, children, ref, ...rest }: NavDrawerProps): React_2.JSX.Element;
+    displayName: string;
+} & {
+    Header: {
+        ({ className, children, ref, ...rest }: NavDrawerHeaderProps): React_2.JSX.Element;
+        displayName: string;
+    };
+    Body: {
+        ({ focusMode, className, onKeyDown, onFocus, children, ref, ...rest }: NavDrawerBodyProps): React_2.JSX.Element;
+        displayName: string;
+    };
+    Footer: {
+        ({ className, children, ref, ...rest }: NavDrawerFooterProps): React_2.JSX.Element;
+        displayName: string;
+    };
+};
+
+/**
+ * The scrolling list of a NavDrawer: the Nav parts (`Nav.Item`, `Nav.Category`, …) as the items of
+ * its list. With `focusMode="arrow"` it is one Tab stop and the arrow keys move through it.
+ */
+export declare const NavDrawerBody: {
+    ({ focusMode, className, onKeyDown, onFocus, children, ref, ...rest }: NavDrawerBodyProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/** NavDrawer.Body: `root` on the scrolling body; `list` on its list. */
+export declare const navDrawerBodyClassNames: {
+    readonly root: "wave-nav-drawer-body";
+    readonly list: "wave-nav-drawer-body__list";
+};
+
+/** Properties for the NavDrawerBody sub-component. */
+export declare interface NavDrawerBodyProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    /**
+     * How the keyboard reaches the items. `'tab'`: every item is a Tab stop and the arrow keys do
+     * nothing (Nav's model). `'arrow'`: the body is one Tab stop, the last focused element (at first
+     * the current page, or the closed category that holds it, else the first item); Down and Right
+     * move to the next element and Up and Left to the previous one (Left and Right swap in a
+     * right-to-left layout), wrapping, and Home and End go to the ends. Every focusable element in
+     * the body joins the order, item actions included. Screen readers do not announce arrow keys in
+     * a navigation landmark: prefer `'tab'` unless your users expect an app pane. Rendered as
+     * `data-focus-mode`. Fluent's NavDrawer uses arrow keys by default (its `tabbable` adds Tab
+     * stops).
+     * @default 'tab'
+     */
+    focusMode?: FocusMode;
+    /** Nav parts: `Nav.Item`, `Nav.Category`, `Nav.SectionHeader`, … (each renders its own list item). */
+    children?: React_2.ReactNode;
+    /** Ref to the scrolling body element. */
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
+/**
+ * NavDrawer (a Drawer variant: it also carries Drawer's root, and its backdrop Drawer's backdrop
+ * class): `root` on the panel (the portaled `role="dialog"` element of an overlay drawer, the
+ * panel element of an inline one); `backdrop` on the backdrop of a modal overlay; `nav` on the
+ * navigation landmark that fills the panel.
+ */
+export declare const navDrawerClassNames: {
+    readonly root: "wave-nav-drawer";
+    readonly backdrop: "wave-nav-drawer__backdrop";
+    readonly nav: "wave-nav-drawer__nav";
+};
+
+/**
+ * The list pinned below a NavDrawer's body (Settings, Help): Nav parts as the items of its list,
+ * each a Tab stop. Its line above shows while more of the body is below.
+ */
+export declare const NavDrawerFooter: {
+    ({ className, children, ref, ...rest }: NavDrawerFooterProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/** NavDrawer.Footer: `root` on the footer; `list` on its list. */
+export declare const navDrawerFooterClassNames: {
+    readonly root: "wave-nav-drawer-footer";
+    readonly list: "wave-nav-drawer-footer__list";
+};
+
+/** Properties for the NavDrawerFooter sub-component. */
+export declare interface NavDrawerFooterProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    /** Nav parts pinned below the body (Settings, Help); wrap other content in an `<li>`. */
+    children?: React_2.ReactNode;
+    /** Ref to the footer element. */
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
+/**
+ * The header row of a NavDrawer: a Hamburger, the app's name, … (no list: Nav items go in the
+ * body or the footer). Its line underneath shows while the body is scrolled away from its top.
+ */
+export declare const NavDrawerHeader: {
+    ({ className, children, ref, ...rest }: NavDrawerHeaderProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/** NavDrawer.Header: `root` on the header row. */
+export declare const navDrawerHeaderClassNames: {
+    readonly root: "wave-nav-drawer-header";
+};
+
+/** Properties for the NavDrawerHeader sub-component. */
+export declare interface NavDrawerHeaderProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    /** A Hamburger, the app's name, …: any content (Nav items go in the body or the footer). */
+    children?: React_2.ReactNode;
+    /** Ref to the header element. */
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
+/** Properties for the NavDrawer component. */
+export declare interface NavDrawerProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'defaultValue'>, Pick<NavProps, 'value' | 'defaultValue' | 'onValueChange' | 'openCategories' | 'defaultOpenCategories' | 'onOpenCategoriesChange' | 'currentCategory'> {
+    /**
+     * How the drawer sits on the page (Fluent's `type`).
+     * - `overlay`: a panel over the page, rendered in a portal while open (in the browser only: an
+     *   open overlay is closed in the server HTML and opens once hydrated). Modal by default: focus
+     *   moves in and stays there, the rest of the page is `inert` and does not scroll, and Escape
+     *   and a backdrop press close it. It is a dialog with the navigation's name.
+     * - `inline`: a panel in the page layout, rendered where the NavDrawer is (also in the server
+     *   HTML). The page stays usable around it; Escape and presses outside do nothing; opening it
+     *   moves no focus, and closing it while focus is inside returns focus to `finalFocusRef`, else
+     *   to the element that opened it.
+     *
+     * Changing `type` remounts the panel; the selection and the open categories are kept. Rendered
+     * as `data-type`.
+     * @default 'overlay'
+     */
+    type?: DrawerType;
+    /** Controlled open state. */
+    open?: boolean;
+    /**
+     * Open state for uncontrolled usage. Keep the drawer controlled instead: a closed uncontrolled
+     * NavDrawer cannot be opened again (a Hamburger inside it is not shown while it is closed).
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Called with the new open state when it changes, with `details.reason`: `trigger` (a Hamburger
+     * inside the drawer), `escape` and `outside-press` (the backdrop; overlay only). `details` is
+     * typed optional until 1.0. A controlled drawer stays as it is until you update `open`.
+     */
+    onOpenChange?: (open: boolean, details?: DrawerOpenChangeDetails) => void;
+    /**
+     * Called with an item's value every time an item is activated, also when the current page is
+     * activated again (a disabled item, a link opened in another tab or window, and a button item
+     * whose `onClick` calls `preventDefault()` are not activations). Close an overlay drawer here:
+     * `onValueChange` fires only when the value changes. Fluent's `onNavItemSelect`.
+     */
+    onItemSelect?: (value: string) => void;
+    /**
+     * The edge the panel is attached to: an overlay's screen edge; an inline panel's inner edge is
+     * the opposite one. `start`/`end` follow the text direction; `left`/`right` are physical sides;
+     * `bottom` runs along the bottom edge. Unlike Drawer's (`'end'`), the default is the start edge,
+     * where navigation sits (Fluent's). Rendered as `data-position`.
+     * @default 'start'
+     */
+    position?: DrawerPosition;
+    /**
+     * The panel's width at a side (its height at the bottom), on Drawer's scale: `small` 320px,
+     * `medium` 592px, `large` 940px, `full` the viewport (inline: the container). A width class in
+     * `className` replaces it (Fluent's navigation pane is 260px wide: the width class of 65
+     * spacing steps). Rendered as `data-size`. Drawer's default too.
+     * @default 'small'
+     */
+    size?: DrawerSize;
+    /**
+     * Inline drawers: draws a line on the panel's inner edge (`data-separator`), as Nav does
+     * (Drawer's `separator` defaults to `false`). An overlay always draws that edge; forced colours
+     * always draw it.
+     * @default true
+     */
+    separator?: boolean;
+    /**
+     * Overlay drawers: `modal` (backdrop, focus trapped, page inert and not scrolling) or
+     * `non-modal` (no backdrop, no trap, nothing inert; Escape closes it while focus is inside, and
+     * its Tab place follows the element that opened it). A non-modal overlay covers the page under
+     * it while the page keeps its Tab order: keep the page's controls clear of it (reserve its width,
+     * or its height at the bottom, in your layout while it is open) or use `type="inline"`; with
+     * `size="full"` it hides the whole page and warns. Ignored by inline drawers. Rendered as
+     * `data-modal-type` on an overlay's panel. Fluent's `modalType` (without `alert`: a navigation
+     * pane is never an alert, so an `'alert'` is treated as `'modal'`). Drawer's default too.
+     * @default 'modal'
+     */
+    modalType?: Extract<ModalType, 'modal' | 'non-modal'>;
+    /**
+     * Removes the panel when the drawer closes. `false` keeps it mounted while closed, out of view
+     * and `inert`, so the state of what is inside survives, and a Hamburger outside can point
+     * `aria-controls` at it at all times: always for an inline drawer, and once the page has
+     * hydrated for an overlay (whose panel is not in the server HTML). Fluent's `unmountOnClose`.
+     * Drawer's default too.
+     * @default true
+     */
+    unmountOnClose?: boolean;
+    /**
+     * Where focus goes when the drawer closes with focus inside it (a modal overlay: whenever it
+     * closes). Pass your page's Hamburger, so a Hamburger inside the drawer that closes it hands
+     * focus to the one that opens it again.
+     */
+    finalFocusRef?: React_2.RefObject<HTMLElement | null>;
+    /**
+     * The backdrop of a modal overlay (Drawer's `backdrop` slot: `null` renders none, a slot
+     * object's `appearance` picks the fill). Ignored, with a development warning, by a non-modal or
+     * inline drawer.
+     */
+    backdrop?: Slot<'div'> | (SlotObject<'div'> & {
+        appearance?: BackdropAppearance;
+    });
+    /**
+     * Name of the navigation landmark (and of an overlay's dialog). Localize it; rename it when the
+     * page has another navigation landmark (two with one name are ambiguous). An `aria-labelledby`
+     * replaces the default.
+     * @default 'Navigation'
+     */
+    'aria-label'?: string;
+    /** `NavDrawer.Header`, `NavDrawer.Body` and `NavDrawer.Footer`, rendered in the order written. */
+    children?: React_2.ReactNode;
+    /** Ref to the panel: the `role="dialog"` element of an overlay drawer, the panel element of an inline one. */
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
 /**
  * A top-level navigation entry: a link when `href` is given (anchor props), a button otherwise
  * (button props). Clicking selects it (`aria-current="page"`); activating a disabled entry never
@@ -7098,6 +8512,9 @@ export declare const navClassNames: {
  * `onClick` calls `preventDefault()` (client-side routing), the browser opens nothing, so the item
  * is selected whatever the keys, button or `target`.
  *
+ * `actions` puts your own controls (a pin toggle, a menu button) beside the item in its row, in a
+ * group named by the item; they never select it.
+ *
  * Typed by overloads, resolved in order: without `href` (button props, button events), with a
  * string `href` (anchor props, anchor events), then an `href` that may be `undefined` at run time
  * ({@link NavItemDynamicProps}: events of either element).
@@ -7141,13 +8558,14 @@ export declare interface NavItemButtonProps extends NavItemOwnProps, NoAnchorOnl
 
 /**
  * Nav.Item: `root` on the `<a>` (with `href`) or `<button>`; `listItem` on the `<li>` around it;
- * `icon` on the icon span; `content` on the label span.
+ * `icon` on the icon span; `content` on the label span; `actions` on the group of its `actions`.
  */
 export declare const navItemClassNames: {
     readonly root: "wave-nav-item";
     readonly listItem: "wave-nav-item__list-item";
     readonly icon: "wave-nav-item__icon";
     readonly content: "wave-nav-item__content";
+    readonly actions: "wave-nav-item__actions";
 };
 
 /**
@@ -7192,6 +8610,20 @@ export declare interface NavItemOwnProps {
     disabled?: boolean;
     /** Label content. */
     children?: React_2.ReactNode;
+    /**
+     * Controls beside the item in its row (Fluent's SplitNavItem): a ToggleButton that pins the
+     * page, a MenuButton with more commands, each with its own name (a Tooltip with
+     * `relationship="label"` names an icon-only one). They render after the item's link or button,
+     * never inside it, in a group named by the item; each is a Tab stop after the item, and a click
+     * or key on one never selects the item. They are drawn while the row is hovered or has focus,
+     * while one of them is pressed or has its popup open, and always in forced colours and on touch
+     * screens; otherwise they are transparent and still focusable. They stay enabled when the item
+     * is `disabled`. With actions, the selected background and indicator are drawn on the row (the
+     * item's list item, `.wave-nav-item__list-item`), so a `className` on the item no longer covers
+     * them. Content that renders nothing renders no group. Fluent's `actionButton`, `toggleButton`
+     * and `menuButton` slots and their tooltips are your own controls here.
+     */
+    actions?: React_2.ReactNode;
 }
 
 /**
@@ -7246,11 +8678,43 @@ export declare interface NavProps extends Omit<React_2.HTMLAttributes<HTMLElemen
     ref?: React_2.Ref<HTMLElement>;
 }
 
+/**
+ * A heading between groups of items (`<h3>` by default, `headingLevel`), in its own list item. It
+ * names nothing by itself: place it before the items it introduces. A header whose children render
+ * nothing renders nothing. It may also sit in a `Nav.Category`, between its sub-items.
+ *
+ * Also exported as `NavSectionHeader` (import the flat name from React Server Components).
+ */
+export declare const NavSectionHeader: {
+    ({ headingLevel, className, children, ref, ...rest }: NavSectionHeaderProps): React_2.JSX.Element | null;
+    displayName: string;
+};
+
+/** Nav.SectionHeader: `root` on the heading element; `listItem` on the list item around it. */
+export declare const navSectionHeaderClassNames: {
+    readonly root: "wave-nav-section-header";
+    readonly listItem: "wave-nav-section-header__list-item";
+};
+
+/** Properties for the NavSectionHeader sub-component. */
+export declare interface NavSectionHeaderProps extends React_2.HTMLAttributes<HTMLHeadingElement> {
+    /**
+     * Level of the heading element (`<h1>` … `<h6>`). Pick the level that fits the page's outline.
+     * Fluent's NavSectionHeader changes its element through `as`.
+     * @default 3
+     */
+    headingLevel?: HeadingLevel;
+    /** The header text. A header whose children render nothing renders nothing at all. */
+    children?: React_2.ReactNode;
+    /** Ref to the heading element. */
+    ref?: React_2.Ref<HTMLHeadingElement>;
+}
+
 /**
  * An indented entry inside a `Nav.Category`: a link when `href` is given, a button otherwise.
  * Selected like `Nav.Item` (a click that the browser opens somewhere else selects nothing; one
  * whose default your `onClick` prevents is selected), and typed by overloads like `Nav.Item`
- * (button, link, then {@link NavSubItemDynamicProps}).
+ * (button, link, then {@link NavSubItemDynamicProps}). Takes `actions` like `Nav.Item`.
  *
  * Also exported as `NavSubItem` (import the flat name from React Server Components).
  */
@@ -7286,10 +8750,14 @@ export declare interface NavSubItemButtonProps extends NavSubItemOwnProps, NoAnc
     ref?: React_2.Ref<HTMLButtonElement>;
 }
 
-/** Nav.SubItem: `root` on the `<a>` or `<button>`; `listItem` on the `<li>` around it. */
+/**
+ * Nav.SubItem: `root` on the `<a>` or `<button>`; `listItem` on the `<li>` around it; `actions` on
+ * the group of its `actions`.
+ */
 export declare const navSubItemClassNames: {
     readonly root: "wave-nav-sub-item";
     readonly listItem: "wave-nav-sub-item__list-item";
+    readonly actions: "wave-nav-sub-item__actions";
 };
 
 /**
@@ -7832,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: {
@@ -7989,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;
 }
@@ -8077,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;
@@ -8096,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
@@ -8158,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
@@ -9939,6 +11466,12 @@ export declare interface StrictImageProps extends Omit<ImageProps, 'alt'> {
     alt: string;
 }
 
+/**
+ * Size of an overlay surface: Dialog.Content's width cap, a Drawer's width (its height at the
+ * bottom). `small`, `medium`, `large`, or `full`, the whole viewport.
+ */
+export declare type SurfaceSize = CoreSize | 'full';
+
 /** Represents a single color swatch option. */
 export declare interface SwatchItem {
     /** Unique identifier for the swatch (the value `onValueChange` reports and a form submits). */
@@ -10074,7 +11607,7 @@ export declare interface SwatchPickerProps extends Omit<React_2.HTMLAttributes<H
      * applies, as the group cannot carry `aria-required`.
      * @default 'arrow'
      */
-    focusMode?: 'arrow' | 'tab';
+    focusMode?: FocusMode;
     /** Built-in strings, for localization. */
     labels?: SwatchPickerLabels;
     /** Size of each swatch button (20, 24, 32 or 40px). A 20px swatch passes the target-size bar
@@ -10631,55 +12164,304 @@ export declare interface TabProps extends React_2.ButtonHTMLAttributes<HTMLButto
  * A compact label (a "chip") for a keyword, category or filter, optionally dismissible.
  *
  * - The dismiss button is a real `<button type="button">` wired to `onDismiss`. Its accessible
- *   name is `dismissLabel` plus the tag content ("Dismiss Cherry"), so a row of tags has
- *   distinguishable dismiss buttons.
+ *   name is `dismissLabel` plus the tag's text (its children; not `media`, `icon` or
+ *   `secondaryText`): "Dismiss Cherry", so a row of tags has distinguishable dismiss buttons.
+ *   Enter, Space, Delete and Backspace on it dismiss the tag (a held key dismisses once), and so do
+ *   Delete and Backspace on a link in the tag's text.
  * - `dismissIcon` replaces only the icon inside that button (see {@link TagOwnProps.dismissIcon}).
- * - Polymorphic: `as="a"` renders a link chip with anchor props type-checked.
- *
- * **Focus after dismissal.** A tag cannot keep focus once you remove it. When `onDismiss` removes
- * the tag, move focus to the next tag's dismiss button (else the previous one, else a sensible
- * element nearby); TagGroup (planned) will do this for you. The neighbour stays mounted, so you
- * can focus it in `onDismiss` before removing the tag.
+ * - The look: `appearance` (`filled`, `outline` or `brand`), `size` (28, 24 or 20px tall),
+ *   `shape` (`circular` or `rounded`) and the look-only `selected`, rendered as `data-appearance`,
+ *   `data-size`, `data-shape` and `data-selected`. `disabled` dims the tag and disables its
+ *   dismiss button natively (`data-disabled`).
+ * - Slots before and under the text: `media` (an Avatar, sized for the tag), a decorative `icon`
+ *   and a second line, `secondaryText`.
+ * - In a TagGroup, a tag takes the group's `size`, `appearance`, `shape` and `dismissible` unless
+ *   it sets its own, is disabled with the group, reports its dismissal to the group's
+ *   `onDismiss(value)`, and is a list item in a `role="list"` group.
+ * - Polymorphic: `as="a"` renders a link chip with anchor props type-checked. A dismissible link
+ *   chip puts the link in the content, `<Tag dismissible><a href>…</a></Tag>`: a dismiss button
+ *   cannot sit inside a link.
+ *
+ * **Focus after dismissal.** A tag cannot keep focus once you remove it. In a TagGroup, focus
+ * moves to the next tag for you (else the previous one, else the group's `fallbackFocusRef`). For
+ * a standalone tag, move focus to the next tag's dismiss button, else the previous one, else a
+ * nearby control, then remove the tag: the neighbour stays mounted, so you can focus it in
+ * `onDismiss` before removing the tag.
  *
  * @example
  * <Tag>React</Tag>
+ * <Tag appearance="brand" size="small">Beta</Tag>
  * <Tag dismissible onDismiss={() => remove('cherry')}>Cherry</Tag>
+ * <Tag media={<Avatar name="Katri Athokas" />} secondaryText="Designer">Katri</Tag>
  * <Tag dismissible dismissLabel="Remove" dismissIcon={<CloseIcon />}>Cherry</Tag>
  */
 export declare const Tag: PolymorphicComponent<'span', TagOwnProps>;
 
+/** Colour scheme of a tag (Fluent's `TagAppearance`): a neutral fill, a border, or a light brand tint. */
+export declare type TagAppearance = 'filled' | 'outline' | 'brand';
+
 /**
- * Tag: `root` on the rendered element (your `as`, default `<span>`); `primaryText` on the content
- * span; `dismissButton` on the Dismiss button; `dismissIcon` on the icon inside it (what
- * `dismissIcon` renders, a merged Button's icon span, else the default `<svg>`).
+ * Tag: `root` on the rendered element (your `as`, default `<span>`); `media` on the element of the
+ * media slot; `icon` on the icon box; `primaryText` on the content span; `secondaryText` on the
+ * second line of text; `dismissButton` on the Dismiss button; `dismissIcon` on the icon inside it
+ * (what `dismissIcon` renders, a merged Button's icon span, else the default `<svg>`).
  */
 export declare const tagClassNames: {
     readonly root: "wave-tag";
+    readonly media: "wave-tag__media";
+    readonly icon: "wave-tag__icon";
     readonly primaryText: "wave-tag__primary-text";
+    readonly secondaryText: "wave-tag__secondary-text";
     readonly dismissButton: "wave-tag__dismiss-button";
     readonly dismissIcon: "wave-tag__dismiss-icon";
 };
 
+/**
+ * A set of tags with one keyboard model: by default an APG toolbar (`role="toolbar"`), or with
+ * `role="list"` a list of tags that only display.
+ *
+ * - **Toolbar** (the default): one Tab stop, the last focused control (at first the first enabled
+ *   one). Left/Right move between the controls when horizontal (mirrored in RTL), Up/Down when
+ *   `orientation="vertical"`, the other axis does nothing; the arrows wrap, in DOM order across
+ *   wrapped rows, and Home/End jump to the first and last control, the same rule as Toolbar.
+ *   Natively disabled controls are skipped. Use it for tags that are actions: dismissible tags,
+ *   InteractionTags (both of their buttons join the arrow order), link chips. Renders
+ *   `aria-orientation`, and `aria-disabled` while disabled.
+ * - **List** (`role="list"`): every tag is a list item (`role="listitem"`), every control keeps
+ *   its own Tab stop and the group handles no arrow key. A tag rendered as a link or a button
+ *   takes no list item role: put the link in the tag's content (`<Tag><a href>…</a></Tag>`), or
+ *   wrap the tag in an element with `role="listitem"`.
+ * - **Delete and Backspace** on a tag's Dismiss button, on either button of an InteractionTag with
+ *   an `InteractionTag.Secondary`, or on a link in a dismissible tag's text, dismiss the tag (a
+ *   held key dismisses one tag). Enter, Space and a click on the Dismiss button do too.
+ * - **Defaults for its tags**: `size`, `appearance`, `shape` and, for Tags, `dismissible` (a tag's
+ *   own value wins; an InteractionTag is dismissible when it has a Secondary), and `disabled`,
+ *   which disables every tag (a tag cannot re-enable itself).
+ * - **`onDismiss(value)`** is called on every dismissal, after the Tag's own `onDismiss` or the
+ *   Secondary's `onClick` (whose `preventDefault()` keeps the group from being called). Remove
+ *   the tag from your state: when the tag that had focus goes, focus moves to the next tag, else
+ *   the previous one, else `fallbackFocusRef`, so it never falls to the page. Give every tag a
+ *   `value`. A dismissal you refuse (the tag stays) moves no focus.
+ * - **Selection**: with `value`, `defaultValue` or `onValueChange` (Fluent's `selectedValues`,
+ *   `defaultSelectedValues` and `onTagSelect`) the group selects. Each `InteractionTag.Primary`
+ *   is then a toggle (`aria-pressed`): a click, Enter or Space adds its tag's `value` to the
+ *   selection or removes it, after the Primary's `onClick` (whose `preventDefault()` cancels the
+ *   toggle); the arrow keys only move. `onValueChange` receives the values in selection order,
+ *   and values without a tag are kept. Dismissing a selected InteractionTag calls `onDismiss`
+ *   and then `onValueChange` without its value. Plain Tags are never selected; selection is
+ *   multiple only (RadioGroup or `Toolbar.RadioGroup` for a single choice).
+ * - **Forms**: a selecting group with `name` submits one entry per selected value, also from
+ *   outside its form with `form`; `required` blocks the submission of an empty selection and
+ *   moves focus to the group's Tab stop (native validation only, no `aria-required`); a form
+ *   reset restores `defaultValue`. A disabled group submits nothing, and a group that does not
+ *   select renders no form input.
+ * - No accessible name by default: name the group with `aria-label` or `aria-labelledby`.
+ * - Renders `data-orientation`, `data-size`, `data-appearance`, `data-shape` and, while
+ *   disabled, `data-disabled`.
+ *
+ * @example
+ * const [filters, setFilters] = React.useState(['Red', 'Blue', 'Large']);
+ * const reset = React.useRef<HTMLButtonElement>(null);
+ * <TagGroup
+ *   aria-label="Active filters"
+ *   dismissible
+ *   fallbackFocusRef={reset}
+ *   onDismiss={(value) => setFilters((current) => current.filter((f) => f !== value))}
+ * >
+ *   {filters.map((filter) => (
+ *     <Tag key={filter} value={filter}>
+ *       {filter}
+ *     </Tag>
+ *   ))}
+ * </TagGroup>
+ * <Button ref={reset} onClick={() => setFilters(['Red', 'Blue', 'Large'])}>Reset filters</Button>
+ *
+ * @example
+ * // Selectable chips, submitted with a form as "fruit".
+ * const [fruit, setFruit] = React.useState<string[]>(['plum']);
+ * <TagGroup aria-label="Fruit" name="fruit" value={fruit} onValueChange={setFruit}>
+ *   <InteractionTag value="cherry">
+ *     <InteractionTag.Primary>Cherry</InteractionTag.Primary>
+ *   </InteractionTag>
+ *   <InteractionTag value="plum">
+ *     <InteractionTag.Primary>Plum</InteractionTag.Primary>
+ *   </InteractionTag>
+ * </TagGroup>
+ */
+export declare const TagGroup: {
+    ({ role: roleProp, orientation, size: sizeProp, appearance: appearanceProp, shape: shapeProp, disabled, dismissible, onDismiss, fallbackFocusRef, value: valueProp, defaultValue, onValueChange, name, form, required, className, onKeyDown, onFocus, "aria-orientation": ariaOrientation, "aria-disabled": ariaDisabled, ref, children, ...rest }: TagGroupProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/** TagGroup: `root` on the group element (the toolbar or the list). */
+export declare const tagGroupClassNames: {
+    readonly root: "wave-tag-group";
+};
+
+/** Props of {@link TagGroup}: the element that holds the tags (a `<div>`). */
+export declare interface TagGroupProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'defaultValue'> {
+    /**
+     * `'toolbar'`: one Tab stop and arrow keys, for tags that are actions (dismissible tags,
+     * InteractionTags, links). `'list'`: a list (every tag gets `role="listitem"`), each control
+     * its own Tab stop and no arrow keys, for tags that only display. Another role keeps the
+     * toolbar keyboard; `'listbox'` is not supported (an option cannot hold a Dismiss button).
+     * Name the group with `aria-label` or `aria-labelledby`.
+     * @default 'toolbar'
+     */
+    role?: React_2.AriaRole;
+    /**
+     * Layout and arrow-key axis, as on Toolbar: Left/Right (mirrored in RTL) when horizontal,
+     * Up/Down when vertical; a wrapping set moves in DOM order. `aria-orientation` (toolbar role)
+     * and `data-orientation`.
+     * @default 'horizontal'
+     */
+    orientation?: Orientation;
+    /** Default `size` of its tags (a tag's own wins) and the gap between them. @default 'medium' */
+    size?: TagSize;
+    /** Default `appearance` of its tags (a tag's own wins). @default 'filled' */
+    appearance?: TagAppearance;
+    /** Default `shape` of its tags (a tag's own wins). @default 'circular' */
+    shape?: TagShape;
+    /**
+     * Disables every tag: a tag cannot re-enable itself. A control that has focus keeps it,
+     * unavailable, until focus leaves it. `aria-disabled` (not with `role="list"`), `data-disabled`.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Default `dismissible` of its Tags (a Tag's own value wins). An InteractionTag is dismissible
+     * when it has an `InteractionTag.Secondary`.
+     * @default false
+     */
+    dismissible?: boolean;
+    /**
+     * Called with the tag's `value` on every dismissal: a click, Enter or Space on a Dismiss
+     * button, or Delete or Backspace on a tag (Fluent's `onDismiss(event, { value })`). Remove the
+     * tag from your state; when it goes, focus moves to the next tag, else the previous one, else
+     * `fallbackFocusRef`. Fluent's TagGroup moves focus as it calls `onDismiss`, whether or not the
+     * tag goes, and has no fallback. Dismissing a selected tag also removes its value from the
+     * selection; Fluent's TagGroup leaves the selection alone.
+     */
+    onDismiss?: (value: string) => void;
+    /**
+     * Where focus goes when the tag that had it is removed and no other tag can take it, for
+     * example an "Add" or "Reset filters" button outside the group. WaveUI-only.
+     */
+    fallbackFocusRef?: React_2.RefObject<HTMLElement | null>;
+    /**
+     * The selected values (controlled), in selection order: the `value`s of the pressed
+     * InteractionTags. Passing `value`, `defaultValue` or `onValueChange` makes the group select
+     * (Fluent's `selectedValues`). Plain Tags are never selected.
+     */
+    value?: readonly string[];
+    /** Initially selected values (uncontrolled; Fluent's `defaultSelectedValues`). @default [] */
+    defaultValue?: readonly string[];
+    /** Called with the new selected values when they change (Fluent's `onTagSelect`). */
+    onValueChange?: (value: string[]) => void;
+    /**
+     * Form field name: one hidden input per selected value (a selecting group only). Fluent's
+     * TagGroup submits nothing.
+     */
+    name?: string;
+    /** The id of the form the hidden inputs belong to, when the group is outside it. */
+    form?: string;
+    /**
+     * An empty selection blocks the form's submission (native validation only: a toolbar has no
+     * `aria-required`).
+     * @default false
+     */
+    required?: boolean;
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
 /**
  * The Tag's own props (the XOwnProps rule of `PolymorphicProps`: component-specific props only).
- * Every other prop comes from the rendered element (`as`, default `span`).
+ * Every other prop comes from the rendered element (`as`, default `span`). The own props shadow
+ * the element's attributes of the same names: `TagProps<'button'>['value']` is a `string`.
  */
 export declare interface TagOwnProps {
     /**
-     * Whether the tag renders a dismiss button. `onDismiss` and `dismissIcon` take effect only with
-     * it (a development warning says so when they are passed without it).
+     * Colour scheme: `filled` (a neutral fill), `outline` (a border on the surface behind it) or
+     * `brand` (a light brand tint that follows the brand ramp).
+     * @default the TagGroup's `appearance`, else 'filled'
+     */
+    appearance?: TagAppearance;
+    /**
+     * `medium` (28px tall, the 0.10 look), `small` (24px) or `extra-small` (20px); an Avatar in
+     * `media` is 24, 20 or 16px. Fluent's medium tag is 32px.
+     * @default the TagGroup's `size`, else 'medium'
+     */
+    size?: TagSize;
+    /**
+     * `circular` (a pill, the 0.10 look) or `rounded` (4px corners). Fluent's default is `rounded`.
+     * @default the TagGroup's `shape`, else 'circular'
+     */
+    shape?: TagShape;
+    /**
+     * Dims the tag and disables its Dismiss button natively (no `onDismiss`, out of the Tab
+     * order), whatever `dismissIcon` passes. A disabled TagGroup disables every tag. A Dismiss
+     * button that has focus when the tag is disabled keeps it, unavailable, until focus leaves it.
+     * Rendered as `data-disabled`. With `as="a"` the link is disabled too: `aria-disabled="true"`,
+     * `role="link"`, no `href` (out of the Tab order) and no click; a link that has focus keeps it,
+     * and its `href`, until focus leaves it. With another `as`, an element that takes a native
+     * `disabled` (a `<button>`) or a component receives `disabled`; a `<button>` that has focus
+     * when it is disabled keeps it, unavailable (`aria-disabled`, no click), until focus leaves it.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Draws the selected look (the brand fill) and sets `data-selected`. A Tag is not interactive,
+     * so the state is not announced: for a tag the user selects, use `InteractionTag` (its
+     * `InteractionTag.Primary` is a toggle button). Disabled wins over the selected look.
+     * @default false
+     */
+    selected?: boolean;
+    /**
+     * Identifies the tag in a TagGroup: the value its `onDismiss` receives (without one, a generated
+     * id). Give every tag of a group its own value. Renders nothing on the default `<span>`; with
+     * `as`, an element that takes a native `value` (a `<button>`, an `<li>`) still receives it.
+     */
+    value?: string;
+    /**
+     * A visual before the text, usually an `Avatar`, which takes the tag's size (24, 20 or 16px)
+     * unless it sets its own `size`. Not interactive. It is not hidden from assistive technology:
+     * pass `decorative` to an Avatar whose name repeats the tag's text. Use `media` or `icon`, not
+     * both.
+     */
+    media?: Slot<'span'>;
+    /** A decorative icon before the text (`aria-hidden`), in a 20, 16 or 12px box. */
+    icon?: Slot<'span'>;
+    /**
+     * A second, smaller line under the text (`secondaryText="Designer"`). It is not part of the
+     * Dismiss button's name. A small or extra-small tag grows to 28px to fit it.
+     */
+    secondaryText?: React_2.ReactNode;
+    /**
+     * Whether the tag renders a Dismiss button. `onDismiss` and `dismissIcon` take effect only with
+     * it (a development warning says so when they are passed without it). `dismissible={false}`
+     * opts a tag out of a dismissible TagGroup. A Dismiss button cannot sit inside a link or a
+     * button: a dismissible tag rendered as one holds it inside (a development warning). For a
+     * dismissible link chip, put the link in the content,
+     * `<Tag dismissible><a href="/topics/react">React</a></Tag>`; for an action with a separate
+     * Dismiss button, use `InteractionTag`. Fluent's dismissible Tag is a single button that
+     * dismisses when it is activated.
+     * @default the TagGroup's `dismissible`, else `false`
      */
     dismissible?: boolean;
     /**
-     * Called when the dismiss button is activated (click, Enter or Space). Passing it does not render
-     * the dismiss button: set `dismissible` too. When it removes the tag, move focus yourself (see
-     * "Focus after dismissal" on {@link Tag}).
+     * Called when the Dismiss button is activated: a click, Enter, Space, Delete or Backspace (a
+     * held key dismisses once). Passing it does not render the button: set `dismissible` too. In a
+     * TagGroup the group's `onDismiss(value)` is called after it, and focus moves to the next tag
+     * when the tag is removed. A standalone Tag cannot keep focus once you remove it: move focus
+     * yourself (see "Focus after dismissal" on {@link Tag}). Fluent's Tag dismisses on Delete and
+     * Backspace only inside a TagGroup.
      */
     onDismiss?: () => void;
     /**
      * Content of the dismiss button (an icon). The Tag always renders its own dismiss
-     * `<button type="button">`, wired to `onDismiss` and named by `dismissLabel` plus the tag
-     * content; this slot only replaces the icon inside it.
+     * `<button type="button">`, wired to `onDismiss` and named by `dismissLabel` plus the tag's text
+     * (its children; not `media`, `icon` or `secondaryText`); this slot only replaces the icon
+     * inside it.
      *
      * A `<button>` element or a Wave `Button` passed here is not nested (a button cannot contain a
      * button): its props are merged into the dismiss button (its `onClick` runs first and can call
@@ -10697,7 +12479,7 @@ export declare interface TagOwnProps {
      * The `aria-*` attributes of an icon slot object also go to the dismiss button, because the icon
      * is `aria-hidden`.
      *
-     * The dismiss button's name is `dismissLabel` plus the tag content ("Dismiss Cherry"):
+     * The dismiss button's name is `dismissLabel` plus the tag's text ("Dismiss Cherry"):
      * `aria-label` and `aria-labelledby` on the slot are ignored (development warning). Icon
      * content is decorative (`aria-hidden`). The children of a merged `<button>`/`Button` (or its
      * `dangerouslySetInnerHTML` markup) are rendered as is inside the dismiss button, next to the
@@ -10717,58 +12499,162 @@ export declare interface TagOwnProps {
      */
     dismissIcon?: Slot<'span'> | SlotObject<'button'>;
     /**
-     * Visually hidden text that names the dismiss button together with the tag content
-     * (`aria-labelledby`), e.g. "Dismiss Cherry". Localise it here. A text label rendered by a
-     * merged `<button>` slot replaces it (see `dismissIcon`).
+     * Visually hidden text that names the dismiss button together with the tag's text (its
+     * children; not `media`, `icon` or `secondaryText`; `aria-labelledby`), e.g. "Dismiss Cherry".
+     * Localise it here. A text label rendered by a merged `<button>` slot replaces it (see
+     * `dismissIcon`). TagPicker names the Dismiss buttons of the tags it renders itself with its
+     * `labels.remove`.
      * @default 'Dismiss'
      */
     dismissLabel?: string;
 }
 
 /**
- * A multi-select combobox that shows the selected values as removable tags. Typing filters the
- * options and makes the first match active; ArrowDown/ArrowUp move the highlight
- * (`aria-activedescendant`), Enter adds the highlighted option and keeps the list open (with
- * nothing highlighted — no typed text, or text that matches no option — Enter is left to the
- * surrounding form), Escape closes the list (and then clears the typed text). Backspace in the
- * empty input moves focus to the last tag; Backspace or Delete there removes it. Additions and
- * removals are announced ("Cherry removed, 2 selected"), and so is "No matches" for text that
- * matches no option. `filter` replaces the match (it may keep options that do not contain the
- * text, for a server-side search or a "Create …" entry), and `query`/`defaultQuery`/
- * `onQueryChange` control the typed text, which resets to `''` when a tag is added, on Escape and
- * on a form reset, and stays on a blur.
+ * A multi-select combobox that shows the selected values as removable tags.
+ *
+ * - **Two forms.** The array form, `<TagPicker options={…} />`, is the parts with their defaults:
+ *   `TagPicker.Control` (holding `TagPicker.Group` and `TagPicker.Input`) and `TagPicker.List`.
+ *   The parts form replaces only the part you need: your own Tags in `TagPicker.Group` (an
+ *   Avatar in each), rich `TagPicker.Option`s in `TagPicker.List`, or `TagPicker.Button`, a
+ *   select-only trigger, in place of the Input. Render `TagPicker.Control` and `TagPicker.List`
+ *   directly inside TagPicker (a Fragment is fine); without a List the default list is added.
+ *   `options` names the values in both forms (`media` and `secondaryContent` show in the default
+ *   options, `media` in the default tags too); with a List that has children, its options are
+ *   the options, and the options of selected values stay rendered (TagPicker hides them).
+ * - **Keyboard.** Typing filters the options (`filter`, by default a case-insensitive match on
+ *   `textValue ?? label`); the option whose label equals the typed text becomes active, else the
+ *   first match. ArrowDown/ArrowUp move the highlight (`aria-activedescendant`), Enter adds the
+ *   active option and keeps the list open (with nothing active, Enter is left to the surrounding
+ *   form), Escape closes the list (and then clears the typed text). Backspace in the empty input,
+ *   and Left (Right in RTL) with the caret at its start, focus the last tag; Delete, Backspace,
+ *   Enter or Space on a remove button remove its tag and focus the next tag, else the input; a
+ *   click on one focuses the input. Additions and removals are announced ("Cherry removed, 2
+ *   selected"), and so is "No matches" for text that matches no option.
+ * - **Free tagging.** With `allowCreate`, text that matches no option label, no selected value
+ *   (ignoring case) and no option value ends the list with a create option (`Create "infra"`);
+ *   Enter on it or a click adds the text as a tag after `onOptionCreate(text)` and clears the
+ *   text.
+ * - **End buttons.** A chevron (`expandIcon`, `false` hides it) opens and closes the list without
+ *   taking focus; `clearable` adds a clear button, a Tab stop after the input, which removes every
+ *   tag. A press on the field's empty area toggles the list.
+ * - **One line.** `overflow="count"` keeps the tags on one line while focus is outside the picker
+ *   and its list is closed; the tags that do not fit give way to "+N".
+ * - **Names.** The tags form a list named "Selected"; the trigger is described by a summary of the
+ *   selected labels ("Selected: Apple, Banana"). These built-in texts are English; `labels`
+ *   localizes them.
+ * - **Routing.** The trigger (`TagPicker.Input` or `TagPicker.Button`) receives `id`,
+ *   `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-invalid`, `aria-required`,
+ *   `aria-errormessage`, `aria-details`, `tabIndex` and `autoFocus`; the Input also
+ *   `onFocus`/`onBlur`/`onKeyDown`/`onKeyUp`, `controlRef` and the text input attributes
+ *   `autoComplete`, `autoCapitalize`, `autoCorrect`, `maxLength`, `inputMode`, `spellCheck` and
+ *   `enterKeyHint` (with the Button, pass handlers and `ref` on it). `ref`, `className`, `style`,
+ *   other `aria-*` attributes and the remaining props stay on the root `<div>`. Inside a `Field`
+ *   the trigger is labelled and described by it; the field shows the error look whenever the
+ *   trigger ends up `aria-invalid`. With `name`/`required` the values take part in form
+ *   submission, validation and reset. Selected values without a matching option show their raw
+ *   value.
+ * - **Size and appearance**: `size` resolves from its own prop, then the surrounding `Field`'s
+ *   `size`, then `WaveProvider inputDefaults.size`, else `'medium'` (a Field or provider `small`
+ *   gives `'medium'` too, since TagPicker has no `small`); `appearance` from its own prop, then
+ *   `WaveProvider inputDefaults.appearance`, else `'outline'`; both render as `data-size` and
+ *   `data-appearance` on the root `<div>`, and the parts take neither. The tags are one Tag size
+ *   smaller. The option list keeps its size.
+ * - **Server rendering.** The open list renders only in the browser: an open list (`defaultOpen`,
+ *   `open`) is closed in the server HTML and opens once the picker has hydrated; the tags of
+ *   registered options show their labels in the server HTML.
+ *
+ * Fluent's `selectedOptions` and `onOptionSelect` are `value` and `onValueChange` (plus
+ * `onOptionCreate`). `TagPickerOption` is both the type of an `options` entry and the flat name of
+ * `TagPicker.Option`.
  *
- * The tags form a list named "Selected"; the input is described by a summary of the selected
- * labels ("Selected: Apple, Banana"). These built-in texts are English; `labels` localizes them.
- * The `<input>` receives `id`, `aria-label`, `aria-labelledby`, `aria-describedby`,
- * `aria-invalid`, `aria-required`, `aria-errormessage`, `aria-details`, `tabIndex`, `autoFocus`,
- * `onFocus`/`onBlur`/`onKeyDown`/`onKeyUp` and the text input attributes `autoComplete`,
- * `autoCapitalize`, `autoCorrect`, `maxLength`, `inputMode`, `spellCheck` and `enterKeyHint`.
- * `ref`, `className`, `style`, other `aria-*` attributes and the remaining props stay on the root
- * `<div>`. Inside a `Field` the input is labelled and described by it. The tag area shows the
- * error look whenever the input ends up `aria-invalid` (its own `aria-invalid` or a `Field`
- * error). With `name`/`required` the values take part in form submission, validation and reset.
- * Selected values without a matching option are shown with their raw value. The open list renders
- * only in the browser: an open list (`defaultOpen`, `open`) is closed in the server HTML and opens
- * once the picker has hydrated.
+ * @example
+ * <TagPicker aria-label="Fruits" options={[{ value: 'apple', label: 'Apple' }]} clearable />
  *
- * **Size and appearance**: `size` resolves from its own prop, then the surrounding `Field`'s
- * `size`, then `WaveProvider inputDefaults.size`, else `'medium'` (a Field or provider `small`
- * gives `'medium'` too, since TagPicker has no `small`); `appearance` from its own prop, then
- * `WaveProvider inputDefaults.appearance`, else `'outline'`; both render as `data-size` and
- * `data-appearance` on the root `<div>`. The option list keeps its size.
+ * @example
+ * <TagPicker aria-label="People" value={people} onValueChange={setPeople}>
+ *   <TagPicker.Control>
+ *     <TagPicker.Group>
+ *       {people.map((id) => (
+ *         <Tag key={id} value={id} media={<Avatar name={nameOf(id)} />} dismissLabel="Remove">
+ *           {nameOf(id)}
+ *         </Tag>
+ *       ))}
+ *     </TagPicker.Group>
+ *     <TagPicker.Input />
+ *   </TagPicker.Control>
+ *   <TagPicker.List>
+ *     <TagPicker.Option value="katri" label="Katri Athokas" secondaryContent="Designer">
+ *       Katri Athokas
+ *     </TagPicker.Option>
+ *   </TagPicker.List>
+ * </TagPicker>
+ */
+export declare const TagPicker: {
+    (props: TagPickerProps): JSX.Element;
+    displayName: string;
+} & {
+    Control: {
+        (props: TagPickerControlProps): JSX.Element | null;
+        displayName: string;
+    };
+    Group: {
+        (props: TagPickerGroupProps): JSX.Element | null;
+        displayName: string;
+    };
+    Input: {
+        (props: TagPickerInputProps): JSX.Element | null;
+        displayName: string;
+    };
+    Button: {
+        (props: TagPickerButtonProps): JSX.Element | null;
+        displayName: string;
+    };
+    List: {
+        (props: TagPickerListProps): JSX.Element | null;
+        displayName: string;
+    };
+    Option: NamedExoticComponent<TagPickerOptionProps>;
+    OptionGroup: FC<OptionGroupProps>;
+};
+
+/**
+ * A select-only trigger for a TagPicker (`TagPicker.Button`), in place of `TagPicker.Input`: a
+ * `<button role="combobox">` for a short fixed list, with no text entry. Down, Up, Home, End and
+ * typing a letter open the list and move; Enter and Space open it or add the active option and
+ * keep it open; Escape, Alt+Up and Tab close it; a click toggles it. Backspace and Left (Right in
+ * RTL) focus the last tag. It shows the placeholder while no tag is selected, else nothing, and
+ * stays the click area of the rest of the row. No query, no filter and no create option
+ * (`allowCreate` needs `TagPicker.Input`). TagPicker's `id`, name, description and Field wiring
+ * reach it; pass handlers and `ref` on it (TagPicker's `onKeyDown` and `controlRef` are the
+ * Input's). Read-only, it renders `aria-readonly`. Fluent's TagPickerButton is visually hidden
+ * once a tag is selected; this one stays.
  */
-export declare const TagPicker: {
-    (props: TagPickerProps): React_2.JSX.Element;
+export declare const TagPickerButton: {
+    (props: TagPickerButtonProps): React_2.JSX.Element | null;
     displayName: string;
 };
 
+/** TagPicker.Button: `root` on the `role="combobox"` button. */
+export declare const tagPickerButtonClassNames: {
+    readonly root: "wave-tag-picker-button";
+};
+
+/** Props of TagPicker.Button: a trigger without text entry (select-only). */
+export declare interface TagPickerButtonProps extends Omit<React_2.ButtonHTMLAttributes<HTMLButtonElement>, 'value' | 'type' | 'disabled' | 'children'> {
+    /** Shown while no tag is selected. @default TagPicker's `placeholder` */
+    placeholder?: string;
+    ref?: React_2.Ref<HTMLButtonElement>;
+}
+
 /**
- * TagPicker: `root` on the outer element; `control` on the tag area; `group` on the list of tags;
- * `tag` on each tag; `removeButton` on each tag's remove button; `input` on the `role="combobox"`
- * input; `listbox` on the `role="listbox"` list; `option` on each Option it renders (which also
- * carries Option's classes); `surface` on the portaled popup; `emptyMessage` on the "No matches"
- * row.
+ * TagPicker: `root` on the outer element; `control` on the tag area and `group` on the list of
+ * tags (both deprecated, kept until 1.0 next to TagPicker.Control's and TagPicker.Group's own
+ * classes); `tag` on each tag; `removeButton` on each tag's remove button; `input` on the
+ * `role="combobox"` input; `expandButton` on the expand button and `expandIcon` on its glyph;
+ * `clearButton` on the clear button; `listbox` on the `role="listbox"` list; `option` on each
+ * Option it renders (which also carries Option's classes); `createOption` on the create option of
+ * `allowCreate`; `overflowCount` on the "+N" count of the single-line layout; `surface` on the
+ * portaled popup; `emptyMessage` on the "No matches" row.
  */
 export declare const tagPickerClassNames: {
     readonly root: "wave-tag-picker";
@@ -10777,12 +12663,121 @@ export declare const tagPickerClassNames: {
     readonly tag: "wave-tag-picker__tag";
     readonly removeButton: "wave-tag-picker__remove-button";
     readonly input: "wave-tag-picker__input";
+    readonly expandButton: "wave-tag-picker__expand-button";
+    readonly expandIcon: "wave-tag-picker__expand-icon";
+    readonly clearButton: "wave-tag-picker__clear-button";
     readonly listbox: "wave-tag-picker__listbox";
     readonly option: "wave-tag-picker__option";
+    readonly createOption: "wave-tag-picker__create-option";
+    readonly overflowCount: "wave-tag-picker__overflow-count";
     readonly surface: "wave-tag-picker__surface";
     readonly emptyMessage: "wave-tag-picker__empty-message";
 };
 
+/**
+ * The field of a TagPicker (`TagPicker.Control`): a `role="group"` box in the picker's look that
+ * holds the tag list, the trigger and, at its inline end, the clear button (`clearable`) and the
+ * expand button (`expandIcon`, a chevron by default; this part's `expandIcon` wins over
+ * TagPicker's). Without children it renders `TagPicker.Group` and `TagPicker.Input`. A press on
+ * its empty area (not on a tag's button or link, or a trigger) toggles the list and keeps focus in
+ * the trigger; read-only, it only focuses the trigger. Render exactly one trigger in it,
+ * `TagPicker.Input` or `TagPicker.Button`. It takes neither `size` nor `appearance`: TagPicker's
+ * apply.
+ */
+export declare const TagPickerControl: {
+    (props: TagPickerControlProps): React_2.JSX.Element | null;
+    displayName: string;
+};
+
+/**
+ * TagPicker.Control: `root` on the field that holds the tags, the trigger and the end buttons (it
+ * also carries TagPicker's `control` part).
+ */
+export declare const tagPickerControlClassNames: {
+    readonly root: "wave-tag-picker-control";
+};
+
+/** Props of TagPicker.Control: the field that holds the tags, the trigger and the end buttons. */
+export declare interface TagPickerControlProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    /** As TagPicker's `expandIcon`; wins over it when it is not `undefined`. */
+    expandIcon?: Slot<'span'>;
+    /** @default `<TagPicker.Group /><TagPicker.Input />` */
+    children?: React_2.ReactNode;
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
+/**
+ * The selected tags of a TagPicker (`TagPicker.Group`): a `TagGroup` with `role="list"` named
+ * "Selected" (`labels.selected`, or its own `aria-label`), rendered only while a value is
+ * selected. Without children it renders a Tag per selected value, named by the option's label,
+ * with a remove button named "Remove <label>" (`labels.remove`). Your own Tags in it are the
+ * selected values' tags: give each a `value`, leave `dismissible` unset (a read-only picker then
+ * shows no remove buttons), and pass `dismissLabel="Remove"` for TagPicker's wording (a Tag's own
+ * Dismiss button is named "Dismiss <text>"). Each remove button is a Tab stop; Delete, Backspace,
+ * Enter and Space remove its tag, and focus moves to the next tag, else to the trigger; a click
+ * focuses the trigger. Left and Right (mirrored in RTL) move between the controls of the list and
+ * from the last one to the trigger; Escape returns to the trigger. Its tags take the picker's look,
+ * one Tag size smaller (a Tag's own `size` and `appearance` win). With `overflow="count"` the
+ * tags are measured by position: render your own Tags in `value` order. Fluent's TagPickerGroup is a
+ * listbox of tags: an option cannot hold a Dismiss button.
+ */
+export declare const TagPickerGroup: {
+    (props: TagPickerGroupProps): React_2.JSX.Element | null;
+    displayName: string;
+};
+
+/**
+ * TagPicker.Group: `root` on the list of tags (also a TagGroup's root, and TagPicker's `group`
+ * part).
+ */
+export declare const tagPickerGroupClassNames: {
+    readonly root: "wave-tag-picker-group";
+};
+
+/** Props of TagPicker.Group: the list of selected tags (a TagGroup with `role="list"`). */
+export declare interface TagPickerGroupProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'role' | 'defaultValue'> {
+    /**
+     * The tags of the selected values: `Tag`s with a `value` each (leave `dismissible` unset), in
+     * `value` order (the single-line layout matches the tags to the values by position).
+     * @default one Tag per selected value, named "Remove <label>" (`labels.remove`)
+     */
+    children?: React_2.ReactNode;
+    /** @default TagPicker's `labels.selected` ('Selected') */
+    'aria-label'?: string;
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
+/**
+ * The text field of a TagPicker (`TagPicker.Input`): the `<input role="combobox">` that filters
+ * the options as you type, inside `TagPicker.Control`. TagPicker's `id`, name, description, Field
+ * wiring and text input attributes reach it (its own `id`, `aria-label` and `aria-labelledby`
+ * replace TagPicker's, and its `aria-describedby` comes first); its handlers run before
+ * TagPicker's `onKeyDown` and the built-in keys. Backspace in the empty field, and Left (Right in
+ * RTL) with the caret at its start, focus the last tag. The form fields are TagPicker's.
+ */
+export declare const TagPickerInput: {
+    (props: TagPickerInputProps): React_2.JSX.Element | null;
+    displayName: string;
+};
+
+/**
+ * TagPicker.Input: `root` on the `role="combobox"` input (it also carries TagPicker's `input`
+ * part).
+ */
+export declare const tagPickerInputClassNames: {
+    readonly root: "wave-tag-picker-input";
+};
+
+/**
+ * Props of TagPicker.Input: the text field, the combobox. The form fields (`name`, `form`,
+ * `required`) are TagPicker's: its hidden inputs submit the tags, never the typed text.
+ */
+export declare interface TagPickerInputProps extends Omit<React_2.InputHTMLAttributes<HTMLInputElement>, 'value' | 'defaultValue' | 'type' | 'size' | 'disabled' | 'readOnly' | 'name' | 'form' | 'required'> {
+    /** Shown while no tag is selected. @default TagPicker's `placeholder` */
+    placeholder?: string;
+    ref?: React_2.Ref<HTMLInputElement>;
+}
+
 /**
  * The TagPicker's built-in names, descriptions and announcements, for localization. Each member is
  * optional and falls back to its English default.
@@ -10812,21 +12807,155 @@ export declare interface TagPickerLabels {
      * @default 'No matches'
      */
     noMatches?: string;
+    /**
+     * Text and name of the create option (`allowCreate`), from the trimmed typed text.
+     * @default (text) => `Create "${text}"`
+     */
+    create?: (text: string) => string;
+    /** Name of the clear button (`clearable`). @default 'Clear selection' */
+    clear?: string;
+    /** Name of the expand button at the end of the field. @default 'Show options' */
+    expand?: string;
+    /**
+     * The "+N" text of the single-line layout (`overflow="count"`); hidden from assistive
+     * technology, which hears the input's summary of every tag.
+     * @default (count) => `+${count}`
+     */
+    overflowCount?: (count: number) => string;
+}
+
+/**
+ * The option list of a TagPicker (`TagPicker.List`): a `<ul role="listbox">`, multi-selectable,
+ * that opens in a popup below the field. Render it directly inside TagPicker (a Fragment is fine);
+ * without one TagPicker adds the default list. Without children it renders a `TagPicker.Option`
+ * per available entry of TagPicker's `options`. With children (`TagPicker.Option`s, `Option`s,
+ * `TagPicker.OptionGroup`s) they are the options: keep the options of selected values rendered,
+ * since TagPicker hides them and reads their labels. Its own `aria-label`/`aria-labelledby`
+ * replace the list's name (TagPicker's, else the Field label); its `className` comes last on the
+ * list, its other attributes and `ref` reach the list element.
+ */
+export declare const TagPickerList: {
+    (props: TagPickerListProps): React_2.JSX.Element | null;
+    displayName: string;
+};
+
+/**
+ * TagPicker.List: `root` on the `role="listbox"` list (it also carries ListboxSurface's `list` and
+ * TagPicker's `listbox` parts).
+ */
+export declare const tagPickerListClassNames: {
+    readonly root: "wave-tag-picker-list";
+};
+
+/** Props of TagPicker.List: the option list, shown in a popup while open. */
+export declare interface TagPickerListProps extends Omit<React_2.HTMLAttributes<HTMLUListElement>, 'role' | 'id' | 'hidden' | 'tabIndex' | 'aria-multiselectable' | 'aria-activedescendant' | 'dangerouslySetInnerHTML'> {
+    /**
+     * `TagPicker.Option`s, `Option`s and `TagPicker.OptionGroup`s. Keep the options of selected
+     * values rendered: TagPicker hides them and reads their labels.
+     * @default one TagPicker.Option per available entry of TagPicker's `options`
+     */
+    children?: React_2.ReactNode;
+    /**
+     * Names the listbox (with `aria-labelledby`): the List's own pair replaces TagPicker's name.
+     * @default TagPicker's `aria-label`, else its `aria-labelledby`, else the Field label
+     */
+    'aria-label'?: string;
+    /** Ids of the elements that name the listbox (see `aria-label`). */
+    'aria-labelledby'?: string;
+    /** Merged last onto the `role="listbox"` element (a `max-h-*` replaces the default height). */
+    className?: string;
+    ref?: React_2.Ref<HTMLUListElement>;
 }
 
-/** Represents a single selectable tag option. */
+/**
+ * One entry of `options`, the array form of TagPicker's options. The component of the same name,
+ * `TagPickerOption`, is `TagPicker.Option`, the parts form.
+ */
 export declare interface TagPickerOption {
     /** Unique identifier for the option. */
     value: string;
-    /** Display label for the option. */
+    /** Display label: the option's text, its tag's text, and the text the filter and the announcements use. */
     label: string;
+    /**
+     * A visual before the label, in the option and in its tag (an Avatar, an icon). Decorative in
+     * both: the label names them. An Avatar takes the tag's size (24, 20 or 16px).
+     */
+    media?: React_2.ReactNode;
+    /** A second line under the label in the option (a role, an e-mail address); tags do not show it. */
+    secondaryContent?: React_2.ReactNode;
+}
+
+/**
+ * An option of TagPicker's list (`TagPicker.Option`): an `Option` with a decorative visual before
+ * its text (`media`, an Avatar or an icon, `aria-hidden`) and a second, smaller line under it
+ * (`secondaryContent`, part of the option's accessible name). Its label, the text of its tag, the
+ * filter and the announcements, is `label`, else `textValue`, else the text of its children, so
+ * the visual and the second line never enter it; pass `label` when the children are not plain
+ * text (a development warning otherwise, and the value is used). It works in any listbox:
+ * TagPicker's list, a Combobox, a Listbox or a custom picker. Without `media` and
+ * `secondaryContent` it renders `Option`'s DOM. The interface of the same name, `TagPickerOption`,
+ * is an entry of TagPicker's `options` array.
+ *
+ * @example
+ * <TagPicker.Option
+ *   value="katri"
+ *   label="Katri Athokas"
+ *   media={<Avatar name="Katri Athokas" />}
+ *   secondaryContent="Designer"
+ * >
+ *   Katri Athokas
+ * </TagPicker.Option>
+ */
+export declare const TagPickerOption: React_2.NamedExoticComponent<TagPickerOptionProps>;
+
+/**
+ * TagPicker.Option (an Option variant): `root` on the option; `media` on the visual before its
+ * text; `secondaryContent` on its second line.
+ */
+export declare const tagPickerOptionClassNames: {
+    readonly root: "wave-tag-picker-option";
+    readonly media: "wave-tag-picker-option__media";
+    readonly secondaryContent: "wave-tag-picker-option__secondary-content";
+};
+
+/**
+ * A group of options in TagPicker's list (`TagPicker.OptionGroup`): `OptionGroup` itself, with a
+ * heading that names it. It hides itself while every option in it is hidden, so a group whose
+ * options are all selected disappears.
+ */
+export declare const TagPickerOptionGroup: React_2.FC<OptionGroupProps>;
+
+/** Props of TagPicker.Option: an Option with a visual and a second line. */
+export declare interface TagPickerOptionProps extends OptionProps {
+    /** A visual before the text (an Avatar, an icon). Decorative (`aria-hidden`): the text names the option. */
+    media?: Slot<'span'>;
+    /** A second, smaller line under the text. Part of the option's name, not of its label. */
+    secondaryContent?: Slot<'span'>;
+    /**
+     * The text of the option's tag, the filter and the announcements. Pass it when the children
+     * are not plain text (a development warning otherwise).
+     * @default `textValue`, else the text of the children, else `value`
+     */
+    label?: string;
 }
 
 /** Properties for the TagPicker component. */
 export declare interface TagPickerProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue' | RoutedHandlers> {
-    /** Available options to choose from. */
-    options: readonly TagPickerOption[];
-    /** Controlled array of selected option values (`[]` for none). */
+    /**
+     * The options, the array form (`{ value, label, media?, secondaryContent? }`). With parts whose
+     * `TagPicker.List` has children it only names values (tags, announcements). Changed in 0.11:
+     * optional.
+     */
+    options?: readonly TagPickerOption[];
+    /**
+     * The parts: `TagPicker.Control` and `TagPicker.List`, directly inside TagPicker (a Fragment is
+     * fine). Without children TagPicker renders both with their defaults; without a
+     * `TagPicker.List` it renders the default list after the children.
+     */
+    children?: React_2.ReactNode;
+    /**
+     * Controlled array of selected option values (`[]` for none). Fluent's `selectedOptions`.
+     */
     value?: readonly string[];
     /**
      * Initial selected values for uncontrolled usage; a form reset restores them.
@@ -10834,8 +12963,8 @@ export declare interface TagPickerProps extends Omit<React_2.HTMLAttributes<HTML
      */
     defaultValue?: readonly string[];
     /**
-     * Called with the new selection when it changes: a tag is added or removed, or a form reset
-     * restores different tags.
+     * Called with the new selection when it changes: a tag is added (an option, or a created tag)
+     * or removed, or a form reset restores different tags. Fluent's `onOptionSelect`.
      */
     onValueChange?: (value: string[]) => void;
     /**
@@ -10859,57 +12988,69 @@ export declare interface TagPickerProps extends Omit<React_2.HTMLAttributes<HTML
     /** Called when the option list opens or closes. */
     onOpenChange?: (open: boolean) => void;
     /**
-     * Placeholder text shown when no tags are selected.
+     * Shown by TagPicker.Input or TagPicker.Button while no tag is selected; the part's own
+     * `placeholder` wins.
      * @default 'Select...'
      */
     placeholder?: string;
     /**
-     * Whether an option matches the typed text (the query). Called with every listed option (its
-     * `value` and `label`; selected options are not listed) and the text whenever the text is not
-     * empty; an option it returns `false` for is filtered out. It may keep options that do not
-     * contain the text: `filter={() => true}` with `query` and `onQueryChange` leaves the matching
-     * to you (a server-side search that replaces `options`), and a filter that always keeps an
-     * option of your own gives a "Create …" entry. With a server-side search, keep the selected
-     * options in `options` (they are never listed): a selected value without an option shows its raw
-     * value as the tag label, with a development warning (the "Async search" story does this).
-     * @default a case-insensitive substring match on the option's `label`
+     * Whether an option matches the typed text (the query). Called with every listed option, also
+     * the options of `TagPicker.List`'s children (its `value`, `label` and `textValue`), and the
+     * text whenever the text is not empty, never with a selected option or the create option; an
+     * option it returns `false` for is filtered out. It may keep options that do not contain the
+     * text: `filter={() => true}` with `query` and `onQueryChange` leaves the matching to you (a
+     * server-side search that replaces `options`); for a create entry, use `allowCreate`. With a
+     * server-side search, keep the selected options in `options` (they are never listed): a
+     * selected value without an option shows its raw value as the tag label, with a development
+     * warning (the "Async search" story does this).
+     * @default a case-insensitive substring match on the option's `textValue ?? label`
      */
     filter?: (option: ListboxItem, query: string) => boolean;
     /**
      * Controlled query: the text typed since the last tag was added, which filters the options and
-     * shows in the input (hidden while `disabled` or `readOnly`).
+     * shows in the input (hidden while `disabled` or `readOnly`). Not used with TagPicker.Button.
      */
     query?: string;
     /**
      * Initial query for uncontrolled usage. A TagPicker that starts disabled or read-only starts
-     * without it (as it starts closed).
+     * without it (as it starts closed). Not used with TagPicker.Button.
      * @default ''
      */
     defaultQuery?: string;
     /**
      * Called with the new query when it changes: as the user types, and with `''` when it resets (a
-     * tag added, Escape on the closed list, a form reset, or `disabled` or `readOnly` turned on
-     * while text is typed). A blur or a close keeps the text. A TagPicker that mounts disabled or
-     * read-only reports nothing: it keeps a controlled query, which shows once it unlocks.
+     * tag added or created, Escape on the closed list, the clear button, a form reset, or `disabled`
+     * or `readOnly` turned on while text is typed). A blur or a close keeps the text. A TagPicker
+     * that mounts disabled or read-only reports nothing: it keeps a controlled query, which shows
+     * once it unlocks. Not used with TagPicker.Button.
      */
     onQueryChange?: (query: string) => void;
     /**
-     * Whether the tag picker is disabled: nothing can be added or removed, and the remove buttons
-     * leave the tab order.
+     * Whether the tag picker is disabled: nothing can be added or removed, the remove buttons leave
+     * the tab order, and the expand and clear buttons are disabled. The field dims once.
      * @default false
      */
     disabled?: boolean;
     /**
      * Size of the tags and the field: `medium` (the 0.7 look), `large` or `extra-large` (Fluent's
      * union; TagPicker has no `small`). Default: the surrounding Field's `size`, else `WaveProvider
-     * inputDefaults.size`, else `'medium'`; a Field or provider `small` gives `'medium'` too. The
+     * inputDefaults.size`, else `'medium'`; a Field or provider `small` gives `'medium'` too. Its
+     * tags are one Tag size smaller: medium → extra-small, large → small, extra-large → medium. The
      * 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
-     * label). Default: `WaveProvider inputDefaults.appearance`, else `'outline'`.
+     * label). Default: `WaveProvider inputDefaults.appearance`, else `'outline'`. The tags are
+     * filled, outlined on `filled-darker`.
      */
     appearance?: InputAppearance;
     /** Name of the values in form submissions (one hidden input per value). */
@@ -10922,38 +13063,88 @@ export declare interface TagPickerProps extends Omit<React_2.HTMLAttributes<HTML
      */
     required?: boolean;
     /**
-     * The `autocomplete` attribute of the `<input role="combobox">`. Browser autofill is off unless
-     * you set it (for example `'on'`).
+     * The `autocomplete` attribute of TagPicker.Input's `<input role="combobox">`. Browser autofill
+     * is off unless you set it (for example `'on'`). With TagPicker.Button, not used.
      * @default 'off'
      */
     autoComplete?: string;
-    /** The maximum length of the typed text (`maxlength` of the `<input role="combobox">`). */
+    /**
+     * The maximum length of the typed text (`maxlength` of TagPicker.Input's `<input>`). With
+     * TagPicker.Button, not used.
+     */
     maxLength?: number;
     /**
-     * The selection cannot be changed: the input is read-only, the tags have no remove buttons, and
-     * the option list neither opens (click, keyboard, a controlled `open`) nor adds tags; Escape is
-     * left to the page. Turning it (or `disabled`) on while the list is open closes it
-     * (`onOpenChange(false)`); a focused remove button hands focus to the input.
+     * The selection cannot be changed: the trigger is read-only, the tags have no remove buttons,
+     * the expand button is disabled and the clear button hidden, and the option list neither opens
+     * (click, keyboard, a controlled `open`) nor adds tags; Escape is left to the page. Turning it
+     * (or `disabled`) on while the list is open closes it (`onOpenChange(false)`); a focused remove
+     * button hands focus to the trigger.
      */
     readOnly?: boolean;
     /**
-     * Names of the remove buttons and the tag list, the summary that describes the input, the
-     * announcements and the "No matches" text, for localization. Unset members keep their English
-     * defaults.
+     * Lets the user add a tag of their own text: while the trimmed text matches no option label
+     * and no selected value (ignoring case) and no option value, the list ends with a create option
+     * (`labels.create`); Enter on it or a click adds the text as a tag, calls `onOptionCreate`, and
+     * clears the text. Needs `TagPicker.Input` (not `TagPicker.Button`). WaveUI-only: Fluent's
+     * TagPicker has no free tagging.
+     * @default false
+     */
+    allowCreate?: boolean;
+    /**
+     * Called with the trimmed text when the user creates a tag, before `onValueChange` reports the
+     * new value. Add an option for it if you keep options: until then the tag shows the raw text.
+     * WaveUI-only (see `allowCreate`).
+     */
+    onOptionCreate?: (text: string) => void;
+    /**
+     * Shows a clear button at the end of the field while a tag is selected (not while `readOnly`;
+     * disabled while `disabled`): it removes every tag (`onValueChange([])`), clears the typed
+     * text, closes the list and focuses the trigger (the input, or `TagPicker.Button`). A Tab stop
+     * after the trigger. The name of Fluent's Combobox and Dropdown prop.
+     * @default false
+     */
+    clearable?: boolean;
+    /**
+     * The glyph of the expand button at the end of the field (default: a chevron). The button
+     * opens and closes the list, keeps focus on the trigger and is not a Tab stop. `null` or
+     * `undefined` keep the chevron; `false`, or a value that renders nothing, hides the button.
+     * Decorative: a `<button>` passed here is unwrapped. `TagPicker.Control`'s `expandIcon` wins.
+     */
+    expandIcon?: Slot<'span'>;
+    /**
+     * `'wrap'`: the tags wrap onto more lines. `'count'`: while focus is outside the picker and its
+     * list is closed, the tags stay on one line and the ones that do not fit give way to "+N"
+     * (`labels.overflowCount`); focusing the picker shows them all. The tags are measured by
+     * position: your own Tags in `TagPicker.Group` render in `value` order. WaveUI-only: Fluent's
+     * single-line layout is a story, not a prop.
+     * @default 'wrap'
+     */
+    overflow?: 'wrap' | 'count';
+    /**
+     * Names of the remove buttons and the tag list, the summary that describes the trigger, the
+     * announcements, the "No matches" text, the create option, the clear and expand buttons and the
+     * "+N" count, for localization. Unset members keep their English defaults.
      */
     labels?: TagPickerLabels;
-    /** Called when the `<input role="combobox">` receives focus (the root keeps other handlers). */
+    /**
+     * Called when TagPicker.Input's `<input role="combobox">` receives focus (the root keeps other
+     * handlers). With TagPicker.Button, pass it (and `ref`) on the Button.
+     */
     onFocus?: React_2.FocusEventHandler<HTMLInputElement>;
-    /** Called when the `<input role="combobox">` loses focus. */
+    /** Called when TagPicker.Input's `<input>` loses focus. With TagPicker.Button, pass it on the Button. */
     onBlur?: React_2.FocusEventHandler<HTMLInputElement>;
     /**
-     * Called on a key press in the `<input role="combobox">`, before the built-in listbox and tag
-     * keys; `event.preventDefault()` skips them.
+     * Called on a key press in TagPicker.Input's `<input>`, after the Input's own `onKeyDown` and
+     * before the built-in listbox and tag keys; `event.preventDefault()` skips them. With
+     * TagPicker.Button, pass it on the Button.
      */
     onKeyDown?: React_2.KeyboardEventHandler<HTMLInputElement>;
-    /** Called when a key is released in the `<input role="combobox">`. */
+    /** Called when a key is released in TagPicker.Input's `<input>`. With TagPicker.Button, pass it on the Button. */
     onKeyUp?: React_2.KeyboardEventHandler<HTMLInputElement>;
-    /** Ref to the `<input role="combobox">` (the focusable element). */
+    /**
+     * Ref to TagPicker.Input's `<input role="combobox">` (the focusable element). With
+     * TagPicker.Button, pass `ref` on the Button.
+     */
     controlRef?: React_2.Ref<HTMLInputElement>;
     /** Ref to the root `<div>`. */
     ref?: React_2.Ref<HTMLDivElement>;
@@ -10968,6 +13159,12 @@ export declare type TagPickerSize = Extract<Size, 'medium' | 'large' | 'extra-la
  */
 export declare type TagProps<C extends React_2.ElementType = 'span'> = PolymorphicProps<C, TagOwnProps>;
 
+/** Corners of a tag (Fluent's `TagShape`): `circular` (a pill) or `rounded` (4px). */
+export declare type TagShape = Extract<Shape, 'rounded' | 'circular'>;
+
+/** Size of a tag (Fluent's `TagSize`): `extra-small` (20px tall), `small` (24px) or `medium` (28px). */
+export declare type TagSize = Extract<Size, 'extra-small' | 'small' | 'medium'>;
+
 /**
  * A step-by-step onboarding popover (a non-modal `role="dialog"`) with Back/Next (Done on the
  * last step) and Close.
@@ -10984,7 +13181,9 @@ export declare type TagProps<C extends React_2.ElementType = 'span'> = Polymorph
  * - 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
@@ -10996,7 +13195,7 @@ export declare type TagProps<C extends React_2.ElementType = 'span'> = Polymorph
  *   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;
 };
 
@@ -11081,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
@@ -11102,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'
      */
@@ -11111,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>;
 }
@@ -11400,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
@@ -11671,9 +13885,10 @@ export declare interface ToastDispatchOptions {
  *   those, the dispatch's `announcement`.
  *   The toasts themselves are not live regions. Each message stays in its live region for 2
  *   seconds (or until its toast goes), so browsing the region later meets the text only once.
- * - While an open modal panel covers the toasts' corner (a Drawer on the same side), the toasts
- *   move beside it, so they never hide its focused controls (WCAG 2.4.11). Without room beside it
- *   (a full-width panel on a narrow screen) they keep their corner.
+ * - While an open panel covers the toasts' corner (a modal or non-modal Drawer on the same side,
+ *   or at the bottom), the toasts move beside it, or above a bottom one (below it for top toasts),
+ *   so they never hide its focused controls (WCAG 2.4.11). Without room there (a full-width panel
+ *   on a narrow screen) they keep their corner.
  * - Timers pause while the pointer or focus is anywhere in the toast region, a menu or popover
  *   opened from a toast included (someone reading or operating one toast is reading the stack),
  *   and while the window is in the background (it has lost focus, or the page is not shown, as in
@@ -12328,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;
 };
 
@@ -12404,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
@@ -12826,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
@@ -12900,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).
@@ -12915,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.
@@ -13250,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;
 }
 
 /**
@@ -13367,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
@@ -13382,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
@@ -13463,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
@@ -13488,6 +16262,12 @@ export declare interface UsePresenceResult {
  *   tracked with a MutationObserver, so an item that disables itself moves the tab stop without
  *   the owner re-rendering. With `manageTabIndex`, a control hidden by CSS counts as disabled and
  *   `input[type=hidden]` is no item.
+ * - **Hand-back** (`manageTabIndex`): a container that stops being one (its ref detaches or moves
+ *   to another element) or that stops managing tabIndex gives every element it stamped its own
+ *   `tabindex` back (the one it had, or the one its author rendered since) and removes the
+ *   `data-roving-value` it added, so each control is its own Tab stop again; attached again, it
+ *   stamps again from the last focused item. An element `itemSelector` no longer matches is handed
+ *   back at once.
  * - **Tab stop** (`tabStop`): `'active'` — the enabled `activeValue` item, else the first enabled
  *   item; `'last-focused'` — the last focused enabled item, else the `'active'` rule. A nested
  *   composite or a control that uses the arrow keys itself holds it only when no other item can;
@@ -13545,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
@@ -13597,7 +16390,15 @@ export declare interface UseRovingTabIndexOptions {
      *  Matches that cannot take focus are no items: `input[type=hidden]` is skipped, and a control
      *  hidden by CSS inside the container (`display: none` or `visibility: hidden` on it or on an
      *  ancestor inside the container) is treated as disabled (skipped, never the tab stop, stamped
-     *  -1). A container hidden as a whole from outside keeps its items and tab stop. */
+     *  -1). A container hidden as a whole from outside keeps its items and tab stop.
+     *  When the container stops being one (its ref detaches, as when `containerProps` are no longer
+     *  spread, or moves to another element) or `manageTabIndex` turns false, every element the hook
+     *  stamped gets its own `tabindex` back (the attribute it had at its first stamp, or none; a
+     *  `tabIndex` its author rendered since, the commit that detaches the container included, stays)
+     *  and loses a `data-roving-value` the hook added (one React rendered stays). An element that
+     *  stops being an item (`itemSelector`, or a changed selector, no longer matches it) is handed
+     *  back the same way. The last focused item and the generated values are kept, so a container
+     *  that attaches again starts where it was. */
     manageTabIndex?: boolean;
     /** Called after an arrow, Home/End or typeahead key moved focus to `value`. */
     onFocusMove?: (value: string, event: React_2.KeyboardEvent) => void;