@mortenbrudvik/waveui 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -306,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: 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;
+    ({ src, name, size: sizeProp, shape: shapeProp, color: colorProp, idForColor, active, activeAppearance, initials: initialsSlot, 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;
 };
 
@@ -325,30 +325,48 @@ export declare const avatarClassNames: {
     readonly badge: "wave-avatar__badge";
 };
 
+/** The color of an Avatar that shows initials: a look, `colorful` (hashed), or a named color. */
+export declare type AvatarColor = 'neutral' | 'brand' | 'colorful' | AvatarNamedColor;
+
 /**
- * A row of overlapping avatars (`role="group"`; name it with `aria-label`).
+ * A row of avatars (`role="group"`; name it with `aria-label`), laid out as a `stack` (overlapping),
+ * `spread` or `pie` (`layout`). `size` reaches the members.
  *
  * With `max`, the avatars beyond the limit are replaced by an overflow `<button>` ("+3", named
- * "3 more", see `overflowLabel`). It toggles a popup that lists the hidden members' names: an
- * `Avatar` by its `aria-label` or `name` prop, text as it is. Other members, such as an `Avatar`
- * inside a link or one labelled by `aria-labelledby`, are rendered as they are, and an `Avatar` or
- * text with no accessible name is listed as `unnamedMemberLabel` with a development warning.
- * Focus moves into the popup; Escape, a press outside or the button close it and focus returns to
- * the button. Tab and Shift+Tab move through the popup's own tab stops (links in rendered
+ * "3 more", see `overflowLabel`; `overflowIndicator="icon"` shows an icon, and a count above 99
+ * reads "99+"). It toggles a popup that lists the hidden members: an `AvatarGroup.Item` as a row
+ * with its avatar and name, an `Avatar` by its `aria-label` or `name` prop, text as it is. Other
+ * members, such as an `Avatar` inside a link or one labelled by `aria-labelledby`, are rendered as
+ * they are, and an `Avatar` or text with no accessible name is listed as `unnamedMemberLabel` with
+ * a development warning. Focus moves into the popup; Escape, a press outside or the button close
+ * it and focus returns to the button (`open`, `defaultOpen` and `onOpenChange(open, details)`
+ * control it). Tab and Shift+Tab move through the popup's own tab stops (links in rendered
  * members); Tab from the last one closes the popup and moves on to the element after the button,
  * Shift+Tab from the first one closes it and returns to the button. When the button is the last
  * tab stop (of the page, or of the Wave layer the group is in, such as a dialog), Tab is left to
  * the browser or the enclosing focus trap.
  *
+ * To split the members yourself, render `AvatarGroup.Item`s and an `AvatarGroup.Popover` holding
+ * the overflow items (see `partitionAvatarGroupItems`).
+ *
  * @example
  * <AvatarGroup aria-label="Project team" max={3}>
- *   <Avatar name="Ada Lovelace" />
- *   <Avatar name="Alan Turing" />
+ *   <AvatarGroup.Item name="Ada Lovelace" />
+ *   <AvatarGroup.Item name="Alan Turing" />
  * </AvatarGroup>
  */
 export declare const AvatarGroup: {
-    ({ max, size, overflowLabel, unnamedMemberLabel, className, children, ref, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...props }: AvatarGroupProps): React_2.JSX.Element;
+    ({ max, size, layout, overflowIndicator, overflowLabel, unnamedMemberLabel, open, defaultOpen, onOpenChange, className, children, ref, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...props }: AvatarGroupProps): React_2.JSX.Element;
     displayName: string;
+} & {
+    Item: {
+        ({ className, ...props }: AvatarGroupItemProps): React_2.JSX.Element;
+        displayName: string;
+    };
+    Popover: {
+        ({ children, indicator, count, label: labelProp, unnamedMemberLabel, open: openProp, defaultOpen, onOpenChange, className, ref, }: AvatarGroupPopoverProps): React_2.JSX.Element;
+        displayName: string;
+    };
 };
 
 /**
@@ -360,24 +378,120 @@ export declare const avatarGroupClassNames: {
     readonly root: "wave-avatar-group";
     readonly item: "wave-avatar-group__item";
     readonly overflowButton: "wave-avatar-group__overflow-button";
+    readonly pie: "wave-avatar-group__pie";
     readonly surface: "wave-avatar-group__surface";
     readonly list: "wave-avatar-group__list";
     readonly listItem: "wave-avatar-group__list-item";
 };
 
+/**
+ * A member of an AvatarGroup. In the group it renders as an `Avatar`; in the overflow list of the
+ * popup it renders as a row with the avatar and the name. It takes the props of an `Avatar`.
+ */
+export declare const AvatarGroupItem: {
+    ({ className, ...props }: AvatarGroupItemProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * AvatarGroup.Item: `root` on the avatar it renders in the group, and on the row (avatar and name)
+ * it renders in the overflow list; `name` on the name text of that row.
+ */
+export declare const avatarGroupItemClassNames: {
+    readonly root: "wave-avatar-group-item";
+    readonly name: "wave-avatar-group-item__name";
+};
+
+/** Properties for the AvatarGroup.Item sub-component: the props of an Avatar. */
+export declare type AvatarGroupItemProps = AvatarProps;
+
+/** The layouts of an AvatarGroup. */
+export declare type AvatarGroupLayout = 'stack' | 'spread' | 'pie';
+
+/** Why the popup of an AvatarGroup opens or closes: its trigger, or a dismissal. */
+export declare type AvatarGroupOpenChangeDetails = OpenChangeDetails<DismissReason | 'trigger'>;
+
+/**
+ * The overflow of an AvatarGroup, written by hand: a "+N" button that opens a popup listing its
+ * children (`AvatarGroup.Item`s, `Avatar`s, text or other elements). Write it as a child of the
+ * group to replace the overflow that `max` makes; its `count`, `indicator`, `label`, `open` and
+ * `onOpenChange` take over what `max` would have derived. Tab leaves the popup from the button.
+ */
+export declare const AvatarGroupPopover: {
+    ({ children, indicator, count, label: labelProp, unnamedMemberLabel, open: openProp, defaultOpen, onOpenChange, className, ref, }: AvatarGroupPopoverProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/** AvatarGroup.Popover: `root` on the overflow button (which also carries the group's button class). */
+export declare const avatarGroupPopoverClassNames: {
+    readonly root: "wave-avatar-group-popover";
+};
+
+/** Properties for the AvatarGroup.Popover sub-component. */
+export declare interface AvatarGroupPopoverProps {
+    /** The overflow members: `AvatarGroup.Item`s, `Avatar`s, text or other elements. */
+    children?: React_2.ReactNode;
+    /**
+     * What the overflow button shows: the number of hidden members (`+3`, capped at `99+`), or an
+     * icon.
+     * @default 'count'
+     */
+    indicator?: 'count' | 'icon';
+    /** The number of hidden members. @default the number of `children` */
+    count?: number;
+    /**
+     * Accessible name of the overflow button and its popup. A function receives the number of hidden
+     * members.
+     * @default (count) => `${count} more`
+     */
+    label?: string | ((count: number) => string);
+    /**
+     * Text listed in the overflow popup for a hidden member that has no accessible name.
+     * @default 'Unnamed member'
+     */
+    unnamedMemberLabel?: string;
+    /** Whether the popup is open (controlled). */
+    open?: boolean;
+    /**
+     * Whether the popup starts open (uncontrolled).
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /** Called when the popup asks to open or close, with the reason (`trigger`, `escape`, …). */
+    onOpenChange?: (open: boolean, details?: AvatarGroupOpenChangeDetails) => void;
+    /** Extra classes for the overflow button. */
+    className?: string;
+    /** Ref to the overflow `<button>`. */
+    ref?: React_2.Ref<HTMLButtonElement>;
+}
+
 /** Properties for the AvatarGroup component. */
 export declare interface AvatarGroupProps extends React_2.HTMLAttributes<HTMLDivElement> {
     /**
      * Maximum number of avatars to display. The others are replaced by an overflow button that
      * lists their names. `0` or a negative value shows only the overflow button, a fraction is
      * rounded down, and `NaN` shows every member (as without `max`). The members of a Fragment
-     * count one by one.
+     * count one by one. A `pie` shows at most three.
      */
     max?: number;
-    /** Size of the overflow button (match it to the avatars).
-     * @default 'medium'
+    /**
+     * Size of the avatars. It reaches the members that set no `size` of their own, and the overflow
+     * button.
+     * @default 'medium' ('large' in a `pie`)
      */
-    size?: Size;
+    size?: AvatarSize;
+    /**
+     * How the members are laid out: `stack` overlaps them, `spread` puts them side by side, `pie`
+     * draws up to three of them as the wedges of one circle (the group's name is then the only name).
+     * @default 'stack'
+     */
+    layout?: AvatarGroupLayout;
+    /**
+     * What the overflow button shows: the number of hidden members (`+3`, capped at `99+`), or an
+     * icon.
+     * @default 'count'
+     */
+    overflowIndicator?: 'count' | 'icon';
     /**
      * Accessible name of the overflow button (and its popup). A function receives the number of
      * hidden members. Localise it here.
@@ -391,10 +505,31 @@ export declare interface AvatarGroupProps extends React_2.HTMLAttributes<HTMLDiv
      * @default 'Unnamed member'
      */
     unnamedMemberLabel?: string;
+    /** Whether the overflow popup is open (controlled). */
+    open?: boolean;
+    /**
+     * Whether the overflow popup starts open (uncontrolled).
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Called when the overflow popup asks to open or close, with the reason: `trigger` (the button),
+     * `escape`, `outside-press` or `focus-outside`.
+     */
+    onOpenChange?: (open: boolean, details?: AvatarGroupOpenChangeDetails) => void;
     /** Ref to the root `<div>`. */
     ref?: React_2.Ref<HTMLDivElement>;
 }
 
+/** The named colors of an Avatar: the persona palette (`--wave-palette-<name>` tokens). */
+export declare type AvatarNamedColor = 'red' | 'pumpkin' | 'gold' | 'forest' | 'teal' | 'blue' | 'navy' | 'lavender' | 'purple' | 'magenta' | 'brown' | 'steel';
+
+/**
+ * The numeric sizes of an Avatar, in pixels (Fluent's 14 sizes). A literal union: Tailwind can only
+ * generate the classes of {@link avatarBoxClasses}.
+ */
+export declare type AvatarNumericSize = 16 | 20 | 24 | 28 | 32 | 36 | 40 | 48 | 56 | 64 | 72 | 96 | 120 | 128;
+
 /** Properties for the Avatar component. */
 export declare interface AvatarProps extends React_2.HTMLAttributes<HTMLSpanElement> {
     /**
@@ -409,11 +544,49 @@ export declare interface AvatarProps extends React_2.HTMLAttributes<HTMLSpanElem
      */
     name?: string;
     /**
-     * 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.
+     * Size of the avatar: a named size (`extra-small` 24px to `extra-large` 56px) or a pixel size from
+     * 16 to 128. 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;
+    size?: AvatarSize;
+    /**
+     * Shape of the avatar. Without it, an Avatar in the `media` of a rounded tag is square.
+     * @default 'circular'
+     */
+    shape?: 'circular' | 'square';
+    /**
+     * Color of the avatar when it shows initials: `brand` (the primary color), `neutral` (muted),
+     * `colorful` (one of the named colors, chosen from `idForColor`, else from `name`; `brand`
+     * without either) or a named color of the persona palette. An image, or an icon, keeps its own
+     * look.
+     * @default 'brand'
+     */
+    color?: AvatarColor;
+    /**
+     * Whether the person is active: `active` draws the `activeAppearance` around the avatar, `inactive`
+     * dims it, `unset` shows neither.
+     * @default 'unset'
+     */
+    active?: 'active' | 'inactive' | 'unset';
+    /**
+     * How an `active` avatar is marked: a `ring`, a `shadow`, both (`ring-shadow`) or a `glow` in the
+     * primary color.
+     * @default 'ring'
+     */
+    activeAppearance?: 'ring' | 'ring-shadow' | 'shadow' | 'glow';
+    /**
+     * A stable id (a user id, say) that picks the color of `color="colorful"`, so the same person has
+     * the same color wherever they are shown, whatever their name looks like.
+     */
+    idForColor?: string;
+    /**
+     * The initials shown when there is no image and no icon, instead of the ones computed from
+     * `name` (see `getInitials`): a string, an element or an object of `<span>` attributes. A value
+     * that renders nothing (`''`, `[]`) keeps the computed initials. Rendered in an `aria-hidden`
+     * `<span>`.
+     */
+    initials?: Slot<'span'>;
     /**
      * Icon shown instead of the initials when there is no image. Rendered in an `aria-hidden`
      * `<span>` (a slot object can override its attributes). A falsy value (`null`, `false`, `''`,
@@ -455,6 +628,9 @@ export declare interface AvatarProps extends React_2.HTMLAttributes<HTMLSpanElem
     ref?: React_2.Ref<HTMLSpanElement>;
 }
 
+/** The size of an Avatar: a named size (24 to 56px) or one of the {@link AvatarNumericSize}s. */
+export declare type AvatarSize = Size | AvatarNumericSize;
+
 /** How a modal surface's backdrop paints the page: `dimmed`, or `transparent` (a modal over another). */
 export declare type BackdropAppearance = 'dimmed' | 'transparent';
 
@@ -1071,7 +1247,8 @@ export declare interface CalendarValueChangeDetails {
 }
 
 /**
- * A surface that groups related content, with `Card.Header`, `Card.Body` and `Card.Footer`.
+ * A surface that groups related content, with `Card.Header`, `Card.Preview`, `Card.Body` and
+ * `Card.Footer`.
  *
  * **Selectable cards** (`onSelect`) come in two patterns:
  * - A card without interactive content is itself the control (`selectionControl="card"`, the
@@ -1088,7 +1265,7 @@ export declare interface CalendarValueChangeDetails {
  * the selected look only; its state is not exposed to assistive technology.
  *
  * React Server Components cannot dot into a client module: import the flat names `CardHeader`,
- * `CardBody` and `CardFooter` there; `Card.Header` etc. work in client files.
+ * `CardPreview`, `CardBody` and `CardFooter` there; `Card.Header` etc. work in client files.
  *
  * @example
  * <Card onSelect={toggle} selected={selected}>
@@ -1102,10 +1279,14 @@ export declare interface CalendarValueChangeDetails {
  */
 export declare const Card: PolymorphicComponent<"div", CardOwnProps> & {
     Header: PolymorphicComponent<"div", CardHeaderOwnProps>;
+    Preview: PolymorphicComponent<"div", CardPreviewOwnProps>;
     Body: PolymorphicComponent<"div", CardBodyOwnProps>;
     Footer: PolymorphicComponent<"div", CardFooterOwnProps>;
 };
 
+/** The look of a Card: a filled surface with a shadow, a muted fill, an outline, or no surface. */
+export declare type CardAppearance = 'filled' | 'filled-alternative' | 'outline' | 'subtle';
+
 /**
  * The main content of a {@link Card}. Flat export for React Server Components (`Card.Body` in
  * client files).
@@ -1131,6 +1312,7 @@ export declare const cardClassNames: {
     readonly root: "wave-card";
     readonly checkbox: "wave-card__checkbox";
     readonly checkmark: "wave-card__checkmark";
+    readonly floatingAction: "wave-card__floating-action";
 };
 
 /**
@@ -1160,8 +1342,11 @@ export declare const CardHeader: PolymorphicComponent<'div', CardHeaderOwnProps>
 /** Card.Header: `root` on the rendered element; `title` on the title; `subtitle` on the subtitle. */
 export declare const cardHeaderClassNames: {
     readonly root: "wave-card-header";
+    readonly image: "wave-card-header__image";
+    readonly text: "wave-card-header__text";
     readonly title: "wave-card-header__title";
     readonly subtitle: "wave-card-header__subtitle";
+    readonly action: "wave-card-header__action";
 };
 
 /** The Card.Header's own props (component-specific props only). */
@@ -1174,6 +1359,16 @@ export declare interface CardHeaderOwnProps {
     title?: React_2.ReactNode;
     /** Subtitle content displayed below the title (none when it renders nothing, as `title`). */
     subtitle?: React_2.ReactNode;
+    /**
+     * An image beside the text, at the start: an `Avatar`, an icon, a logo. A value that renders
+     * nothing renders no element.
+     */
+    image?: Slot<'span'>;
+    /**
+     * An action beside the text, at the end: a menu button, say. A value that renders nothing
+     * renders no element.
+     */
+    action?: Slot<'span'>;
 }
 
 /** Props of {@link CardHeader} rendered as `C` (default `'div'`), including `ref`. */
@@ -1184,6 +1379,25 @@ export declare type CardHeaderProps<C extends React_2.ElementType = 'div'> = Pol
  * Every other prop comes from the rendered element (`as`).
  */
 export declare interface CardOwnProps {
+    /**
+     * Look of the card: `filled` (a surface with a border and a shadow), `filled-alternative` (a
+     * muted fill), `outline` (a border only) or `subtle` (no surface until hovered or selected). A
+     * selectable card gets a hover and pressed look for its appearance; the selected look is the
+     * same in every appearance.
+     * @default 'filled'
+     */
+    appearance?: CardAppearance;
+    /**
+     * Padding of the card's parts: `small` 0.75rem, `medium` 1rem, `large` 1.25rem.
+     * @default 'medium'
+     */
+    size?: CoreSize;
+    /**
+     * Layout of the card's parts: `vertical` stacks them, `horizontal` puts them in a row (put the
+     * text parts in one wrapper element to keep them stacked beside a `Card.Preview`).
+     * @default 'vertical'
+     */
+    orientation?: Orientation;
     /**
      * Whether the card is selected. Shown with the selected colors plus non-color cues: a 2px primary
      * border (a 1px border plus an inset 1px ring), a Highlight outline in forced-colors mode, and a
@@ -1225,8 +1439,54 @@ export declare interface CardOwnProps {
      * `Card.Header` title, which the checkbox references with `aria-labelledby`.
      */
     selectLabel?: string;
+    /**
+     * The built-in checkbox of `selectionControl="checkbox"`: an object of `<input>` attributes is
+     * merged onto it (a class, `aria-describedby`, `name`; its type, checked state and change
+     * handling stay the card's), an element replaces it (give that control its own name and call
+     * `onSelect` from it), and `null` or `false` removes it, for a control you render elsewhere.
+     * Ignored with the default `selectionControl`.
+     */
+    checkbox?: Slot<'input'>;
+    /**
+     * An action over the top end corner of the card (a menu button, say). A card with one is
+     * positioned; with `selectionControl="checkbox"` the built-in checkbox then moves to the top
+     * start corner. Content that renders nothing renders no element.
+     */
+    floatingAction?: Slot<'span'>;
 }
 
+/**
+ * Edge-to-edge media of a {@link Card} (an image, a video, a map), with an optional `logo` over its
+ * bottom start corner. It has no padding: in a vertical card it fills the width, in a horizontal
+ * one it is the full-height block at the start. Flat export for React Server Components
+ * (`Card.Preview` in client files).
+ *
+ * @example
+ * <Card>
+ *   <Card.Preview logo={<img alt="Contoso" src="/logo.svg" />}><img alt="" src="/cover.jpg" /></Card.Preview>
+ *   <Card.Header title="Contoso" />
+ * </Card>
+ */
+export declare const CardPreview: PolymorphicComponent<'div', CardPreviewOwnProps>;
+
+/** Card.Preview: `root` on the rendered element; `logo` on the logo over its bottom start corner. */
+export declare const cardPreviewClassNames: {
+    readonly root: "wave-card-preview";
+    readonly logo: "wave-card-preview__logo";
+};
+
+/** The Card.Preview's own props (component-specific props only). */
+export declare interface CardPreviewOwnProps {
+    /**
+     * A logo placed over the bottom start corner of the preview: a string, an element or an object
+     * of `<span>` attributes. A value that renders nothing renders no element.
+     */
+    logo?: Slot<'span'>;
+}
+
+/** Props of {@link CardPreview} rendered as `C` (default `'div'`), including `ref`. */
+export declare type CardPreviewProps<C extends React_2.ElementType = 'div'> = PolymorphicProps<C, CardPreviewOwnProps>;
+
 /**
  * Props of {@link Card} rendered as `C` (default `'div'`). `CardProps` without a type argument is
  * the 0.4 name: the props of a Card rendered as a `<div>`, including `ref`.
@@ -1261,19 +1521,32 @@ export declare type CardProps<C extends React_2.ElementType = 'div'> = Polymorph
  * - The controls are layered over the slides inside the carousel's own stacking context, so they
  *   never paint over page headers that stay in view while the page scrolls.
  *
- * Compound access (`Carousel.Item`) needs a client module; React Server Components import the
- * flat name `CarouselItem` instead.
+ * - `groupSize` shows several slides per page, `draggable` lets the pointer drag them, and a
+ *   `thumbnail` on a `Carousel.Item` turns the picker into a row of thumbnails.
+ * - `controlsLayout` places the Previous and Next buttons over the slides (`overlay`,
+ *   `overlay-wide`) or beside them (`inline`, `inline-wide`); `Carousel.Button` replaces the
+ *   built-in button of its `direction` with one of your own glyph.
+ *
+ * Compound access (`Carousel.Item`, `Carousel.Button`) needs a client module; React Server
+ * Components import the flat names `CarouselItem` and `CarouselButton` instead.
  */
 export declare const Carousel: {
-    ({ value: controlledValue, defaultValue, onValueChange, autoPlay, autoPlayInterval, autoPlayLabels, labels, loop, className, children, onMouseEnter, onMouseLeave, onFocus, onBlur, ref, ...rest }: CarouselProps): React_2.JSX.Element;
+    ({ value: controlledValue, defaultValue, onValueChange, autoPlay, autoPlayInterval, autoPlayLabels, labels, loop, groupSize, align, draggable, controlsLayout, appearance, className, children, onMouseEnter, onMouseLeave, onFocus, onBlur, ref, ...rest }: CarouselProps): React_2.JSX.Element;
     displayName: string;
 } & {
     Item: {
-        ({ className, children, ref, ...rest }: CarouselItemProps): React_2.JSX.Element;
+        ({ thumbnail: _thumbnail, className, children, ref, ...rest }: CarouselItemProps): React_2.JSX.Element;
+        displayName: string;
+    };
+    Button: {
+        ({ direction, onClick, className, children, ref, ...rest }: CarouselButtonProps): React_2.JSX.Element;
         displayName: string;
     };
 };
 
+/** How a Carousel is drawn: `flat`, or `elevated` with rounded corners and a shadow. */
+export declare type CarouselAppearance = 'flat' | 'elevated';
+
 /** Accessible names of the rotation control shown while `autoPlay` is on. */
 export declare interface CarouselAutoPlayLabels {
     /** Name of the control while slides rotate (activating it stops the rotation).
@@ -1286,15 +1559,42 @@ export declare interface CarouselAutoPlayLabels {
     play?: string;
 }
 
+/**
+ * A Previous or Next button written in a {@link Carousel}, for a glyph or look of your own.
+ * Write it as a direct child of the Carousel: it replaces the built-in button of its
+ * `direction`, takes its place in the layout and is named, disabled and wired to the slides the
+ * same way (`labels.previous`/`labels.next`, `aria-controls`, `aria-disabled` at the ends
+ * without `loop`, which keeps it focusable). Its children replace the chevron, which mirrors in
+ * right-to-left layouts; `aria-label` replaces the name.
+ */
+export declare const CarouselButton: {
+    ({ direction, onClick, className, children, ref, ...rest }: CarouselButtonProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/** Carousel.Button: `root` on the button element. */
+export declare const carouselButtonClassNames: {
+    readonly root: "wave-carousel-button";
+};
+
+/** Properties for the CarouselButton sub-component. */
+export declare interface CarouselButtonProps extends React_2.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Which way the button moves the carousel. */
+    direction: 'previous' | 'next';
+    ref?: React_2.Ref<HTMLButtonElement>;
+}
+
 /**
  * Carousel: `root` on the `role="region"` element; `autoPlayButton` on the pause and start
- * button; `track` on the moving element around the slides; `slide` on each slide wrapper;
+ * button; `viewport` on the clipping element around the track; `track` on the moving element
+ * around the slides; `slide` on each slide wrapper;
  * `previousButton` and `nextButton` on the arrow buttons; `picker` on the `role="group"` of
  * picker buttons; `pickerButton` on each of them; `pickerIndicator` on each button's dot.
  */
 export declare const carouselClassNames: {
     readonly root: "wave-carousel";
     readonly autoPlayButton: "wave-carousel__auto-play-button";
+    readonly viewport: "wave-carousel__viewport";
     readonly track: "wave-carousel__track";
     readonly slide: "wave-carousel__slide";
     readonly previousButton: "wave-carousel__previous-button";
@@ -1304,23 +1604,35 @@ export declare const carouselClassNames: {
     readonly pickerIndicator: "wave-carousel__picker-indicator";
 };
 
+/** Where a Carousel puts its Previous and Next buttons. */
+export declare type CarouselControlsLayout = 'overlay' | 'inline' | 'overlay-wide' | 'inline-wide';
+
 /**
  * One slide of a {@link Carousel}. Write it in the Carousel, directly or in a Fragment: a component
  * that renders `Carousel.Item` itself is not recognised as a slide (put that component inside the
  * `Carousel.Item` instead).
  */
 export declare const CarouselItem: {
-    ({ className, children, ref, ...rest }: CarouselItemProps): React_2.JSX.Element;
+    ({ thumbnail: _thumbnail, className, children, ref, ...rest }: CarouselItemProps): React_2.JSX.Element;
     displayName: string;
 };
 
-/** Carousel.Item: `root` on the item element. */
+/** Carousel.Item: `root` on the item element; `thumbnail` on the image in its picker button. */
 export declare const carouselItemClassNames: {
     readonly root: "wave-carousel-item";
+    readonly thumbnail: "wave-carousel-item__thumbnail";
 };
 
 /** Properties for the CarouselItem sub-component. */
 export declare interface CarouselItemProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    /**
+     * An image for this slide's button in the picker, in place of the dot. A string is the image
+     * `src`; an object sets the `<img>`'s attributes. The button keeps its slide-label name, so the
+     * image is decorative (`alt=""`). When any slide has one, the picker becomes a row of
+     * thumbnails below the slides; a slide without one keeps its dot. With `groupSize` above 1, a
+     * page shows the thumbnail of its first slide.
+     */
+    thumbnail?: Slot<'img'>;
     ref?: React_2.Ref<HTMLDivElement>;
 }
 
@@ -1350,6 +1662,13 @@ export declare interface CarouselLabels {
      * @default (index, total) => `Slide ${index + 1} of ${total}`
      */
     slide?: (index: number, total: number) => string;
+    /**
+     * Name of a page of several slides, from the one-based number of its first and last slide, out
+     * of `total` slides (`groupSize` above 1). It names the page's picker button and is announced
+     * by the live region when the page is shown. A page of one slide uses `slide`.
+     * @default (start, end, total) => `Slides ${start} to ${end} of ${total}`
+     */
+    slides?: (start: number, end: number, total: number) => string;
     /** How assistive technology announces the carousel region (`aria-roledescription`).
      * @default 'carousel'
      */
@@ -1362,14 +1681,57 @@ export declare interface CarouselLabels {
 
 /** Properties for the Carousel component. */
 export declare interface CarouselProps extends React_2.HTMLAttributes<HTMLDivElement> {
-    /** Controlled index of the currently active slide. Out-of-range values show the nearest slide. */
+    /**
+     * Controlled index of the active slide: with `groupSize` above 1, the first slide of the shown
+     * page. A value in the middle of a page shows that page and out-of-range values show the
+     * nearest one.
+     */
     value?: number;
     /** Default active slide index for uncontrolled usage.
      * @default 0
      */
     defaultValue?: number;
-    /** Called with the new index when the active slide changes (not when it stays the same). */
+    /**
+     * Called with the new index when the active slide changes (not when it stays the same): the
+     * first slide of the new page when `groupSize` is above 1.
+     */
     onValueChange?: (index: number) => void;
+    /**
+     * How many slides one page shows: a number, or `'auto'` to show as many as fit the width of the
+     * carousel (the slides keep their own width, which must be equal). Previous, Next, the picker
+     * (one button per page), looping and autoplay move by page, and the slides of the shown page
+     * form one arrow-key focus group. With `1` each slide fills the width, as before.
+     * @default 1
+     */
+    groupSize?: number | 'auto';
+    /**
+     * With `groupSize="auto"`, where the shown page sits when its slides do not fill the width.
+     * @default 'start'
+     */
+    align?: 'start' | 'center' | 'end';
+    /**
+     * Lets the pointer drag the slides (mouse, touch and pen). The track follows the pointer and,
+     * on release, the page changes when the drag passed a quarter of the width or left fast, else
+     * it snaps back; the direction follows the carousel's. The click that ends a drag is not
+     * delivered to the slide, and a vertical swipe still scrolls the page. Dragging pauses
+     * autoplay like the pointer over the carousel does. The buttons and the keyboard stay the way
+     * to operate the carousel without a pointer.
+     * @default false
+     */
+    draggable?: boolean;
+    /**
+     * Where the Previous and Next buttons go. `overlay` floats round buttons over the slides;
+     * `overlay-wide` makes them full-height strips at the edges; `inline` puts them in a row with
+     * the slides, outside them; `inline-wide` is `inline` with full-height buttons. The rotation
+     * control stays the first focusable element at the start corner in every layout.
+     * @default 'overlay'
+     */
+    controlsLayout?: CarouselControlsLayout;
+    /**
+     * `elevated` rounds the corners and adds a shadow.
+     * @default 'flat'
+     */
+    appearance?: CarouselAppearance;
     /**
      * Rotates the slides automatically. A Pause/Start control is rendered as the first focusable
      * element. Rotation pauses while focus is anywhere inside the carousel (the control included;
@@ -2345,6 +2707,13 @@ export declare interface ComboboxProps<M extends boolean = false> extends Omit<R
      * listbox keeps its size.
      */
     size?: CoreSize;
+    /**
+     * Advanced positioning of the popup (Fluent's `positioning`): `offset`, `fitViewport`,
+     * `matchReferenceWidth` and `fallbackPlacements` (tried in order when the requested side has no
+     * room). The popup opens below the field.
+     * @default `{ matchReferenceWidth: true, fitViewport: true }`
+     */
+    positioning?: PopupPositioningOptions;
     /**
      * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
      * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
@@ -3239,6 +3608,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
@@ -3373,6 +3749,12 @@ export declare interface DatePickerProps extends Omit<React_2.HTMLAttributes<HTM
 /** A day of the week, as `Date.prototype.getDay()` numbers them: 0 is Sunday, 6 is Saturday. */
 export declare type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
 
+/**
+ * The 0.5 spellings of two presence statuses. They still work and warn once in development; use
+ * `'do-not-disturb'` and `'out-of-office'` instead. Removed in 1.0.
+ */
+export declare type DeprecatedPresenceStatus = 'dnd' | 'oof';
+
 /**
  * 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
@@ -3799,6 +4181,23 @@ export declare interface DialogTriggerRenderProps extends React_2.HTMLAttributes
     ref: React_2.RefCallback<HTMLElement>;
 }
 
+/** Returned by {@link useDismiss}. */
+export declare interface DismissLayer {
+    /** The layer's id: pass it to `Portal layerId` or `DismissLayerProvider` around the surface. */
+    layerId: string;
+    /** Whether the layer is currently the topmost open layer (read at call time). */
+    isTopmost(): boolean;
+}
+
+/**
+ * Makes `layerId` the parent layer of everything rendered inside (`Portal layerId` does this for
+ * its children automatically).
+ */
+export declare function DismissLayerProvider(props: {
+    layerId: string;
+    children: React_2.ReactNode;
+}): React_2.ReactElement;
+
 /** Why a popup layer is dismissed: Escape, a press outside it, or focus moving outside it. */
 export declare type DismissReason = 'escape' | 'outside-press' | 'focus-outside';
 
@@ -4697,6 +5096,13 @@ export declare interface DropdownProps<M extends boolean = false> extends Omit<R
      * listbox keeps its size; the multi-select value text and clear button follow it.
      */
     size?: CoreSize;
+    /**
+     * Advanced positioning of the popup (Fluent's `positioning`): `offset`, `fitViewport`,
+     * `matchReferenceWidth` and `fallbackPlacements` (tried in order when the requested side has no
+     * room). The popup opens below the field.
+     * @default `{ matchReferenceWidth: true, fitViewport: true }`
+     */
+    positioning?: PopupPositioningOptions;
     /**
      * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
      * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
@@ -5190,12 +5596,86 @@ 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 initials of a person's name, for an avatar: the first letter of the first and, with two or
+ * more words, of the last word, upper-cased.
+ *
+ * Text in `()`, `[]`, `{}` and `<>` and all punctuation are ignored (`'Jane Doe (Contoso)'` gives
+ * `'JD'`). A name with no letters (a phone number, an emoji) or with letters of a script without
+ * letter initials (Han, Hiragana, Katakana, Hangul, Thai, Lao, Khmer, Myanmar, Tibetan) gives
+ * `''`, so an avatar falls back to its person glyph. Server-safe.
+ *
+ * @example
+ * getInitials('Jane Doe (Contoso)'); // 'JD'
+ * getInitials('Jane Doe', { dir: 'rtl' }); // 'DJ'
+ * getInitials('+1 (555) 010-0000'); // ''
+ */
+export declare function getInitials(name: string, options?: GetInitialsOptions): string;
+
+/** Options of {@link getInitials}. */
+export declare interface GetInitialsOptions {
+    /**
+     * Text direction of the place the initials are shown. In `'rtl'` the first and last initial of a
+     * left-to-right script swap, so they read in the order of the name on screen; a Hebrew or Arabic
+     * name keeps its order, which the text direction already mirrors.
+     * @default 'ltr'
+     */
+    dir?: 'ltr' | 'rtl';
+    /**
+     * Keep only the first initial, also for a name of several words.
+     * @default false
+     */
+    firstInitialOnly?: boolean;
+}
+
+/** The last tabbable element inside `container`, or `null`. */
+export declare function getLastTabbable(container: Element, options?: {
+    includeContainer?: boolean;
+}): HTMLElement | null;
+
+/**
+ * The tabbable elements inside `container` in sequential focus order: positive `tabindex` first
+ * (ascending), then `tabindex=0` / natively tabbable elements in document order. Named radio
+ * groups follow {@link isTabbable}, so the result depends on where focus currently is: when focus
+ * is on a radio, the rest of its group is left out, which makes the focused radio the last entry
+ * when its group ends the container (the element a focus trap wraps from).
+ *
+ * @param options.includeContainer Also consider `container` itself.
+ */
+export declare function getTabbableElements(container: Element, options?: {
+    includeContainer?: boolean;
+}): HTMLElement[];
+
 /**
  * The classes that select a theme's tokens: `'wave-light'`, `'wave-dark dark'` or
  * `'wave-high-contrast high-contrast'`. Unknown values fall back to the light classes. Safe to call
@@ -5246,6 +5726,13 @@ export declare const gridClassNames: {
     readonly root: "wave-grid";
 };
 
+/** Handlers {@link useGridNavigation} needs on the grid element (compose them with the consumer's). */
+export declare interface GridNavigationHandlers {
+    onKeyDown: React_2.KeyboardEventHandler<HTMLTableElement>;
+    onFocus: React_2.FocusEventHandler<HTMLTableElement>;
+    onBlur: React_2.FocusEventHandler<HTMLTableElement>;
+}
+
 /**
  * The Grid's own props (the XOwnProps rule of `PolymorphicProps`: component-specific props only).
  * Every other prop comes from the rendered element (`as`).
@@ -5339,6 +5826,13 @@ export declare interface HamburgerProps extends React_2.ButtonHTMLAttributes<HTM
     ref?: React_2.Ref<HTMLButtonElement>;
 }
 
+/**
+ * Whether a modal surface is open now: a layer of kind `'modal'` (a Dialog, an overlay Drawer, an
+ * alert, the DatePicker's calendar, or your own `useDismiss({ kind: 'modal' })`). A non-modal
+ * surface is no modal. Server-safe: `false` when no layer is registered, as on the server.
+ */
+export declare function hasOpenModal(): boolean;
+
 /** Level of a heading element, `<h1>` … `<h6>`. */
 export declare type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 
@@ -5732,6 +6226,20 @@ export declare interface InputErrorMessageProps extends React_2.HTMLAttributes<H
     [dataAttribute: `data-${string}`]: unknown;
 }
 
+/**
+ * Focus indicator of text-entry controls: a 2px primary bottom border. `focus:outline-hidden`
+ * removes the outline while focused but — unlike `outline-none` — keeps a visible outline in
+ * forced-colors mode, where the border colour change is not perceivable. (Scoped to `:focus` so
+ * unfocused inputs do not show that outline in forced colors.)
+ */
+export declare const inputFocus = "focus:outline-hidden focus:border-b-2 focus:border-b-primary";
+
+/**
+ * Wrapper form of {@link inputFocus} for inputs rendered inside a styled wrapper (slots,
+ * SearchBox, TagPicker). Put `focus:outline-hidden` on the inner control.
+ */
+export declare const inputFocusWithin = "focus-within:border-b-2 focus-within:border-b-primary";
+
 /** Properties for the Input component. */
 export declare interface InputProps extends Omit<React_2.InputHTMLAttributes<HTMLInputElement>, 'size'> {
     /**
@@ -6035,6 +6543,16 @@ export declare interface LabelProps extends React_2.LabelHTMLAttributes<HTMLLabe
     ref?: React_2.Ref<HTMLLabelElement>;
 }
 
+/**
+ * What kind of surface a layer is. `modal` marks dialog-like surfaces (focus-restore validation and
+ * modal isolation look for them); a modal blocks presses and Escape for the layers below it only
+ * while its page isolation is active ({@link registerLayerIsolation}). `dialog` marks a non-modal
+ * Dialog or Drawer: it shields nothing (no isolation), takes Escape only from inside its tree
+ * (`escape: 'inside'`), and the Toaster moves out of its way; focus-restore validation and modal
+ * isolation do not count it.
+ */
+export declare type LayerKind = 'modal' | 'dialog' | 'popover' | 'menu' | 'listbox' | 'tooltip' | 'toast';
+
 /**
  * A hyperlink with Fluent link styling. Renders an `<a>` by default; `as` renders a router link
  * (`<Link as={RouterLink} to="/">`) or a `<button>` styled as a link (`type="button"` by default).
@@ -6834,7 +7352,7 @@ export declare const Menu: {
         displayName: string;
     };
     Popover: {
-        ({ side, align, offset, target, children, className, style, onKeyDown, onKeyDownCapture, onFocus, onPointerEnter, onPointerLeave, onPointerMove, onContextMenu, ref, ...rest }: MenuPopoverProps): JSX.Element | null;
+        ({ side, align, offset, target: targetProp, positioning, children, className, style, onKeyDown, onKeyDownCapture, onFocus, onPointerEnter, onPointerLeave, onPointerMove, onContextMenu, ref, ...rest }: MenuPopoverProps): JSX.Element | null;
         displayName: string;
     };
     ItemCheckbox: {
@@ -7305,7 +7823,7 @@ export declare interface MenuItemSwitchProps extends MenuItemProps, MenuItemSele
  * Also exported as `MenuPopover` (import the flat name from React Server Components).
  */
 export declare const MenuPopover: {
-    ({ side, align, offset, target, children, className, style, onKeyDown, onKeyDownCapture, onFocus, onPointerEnter, onPointerLeave, onPointerMove, onContextMenu, ref, ...rest }: MenuPopoverProps): React_2.JSX.Element | null;
+    ({ side, align, offset, target: targetProp, positioning, children, className, style, onKeyDown, onKeyDownCapture, onFocus, onPointerEnter, onPointerLeave, onPointerMove, onContextMenu, ref, ...rest }: MenuPopoverProps): React_2.JSX.Element | null;
     displayName: string;
 };
 
@@ -7331,11 +7849,18 @@ export declare interface MenuPopoverProps extends Omit<React_2.HTMLAttributes<HT
      * with a `target` needs no trigger; name it with `aria-label`, and give a toggle button you use
      * as the target `aria-haspopup="menu"` and `aria-expanded` yourself (the menu's `id` is
      * generated, so the toggle cannot point `aria-controls` at it). A press on a target element
-     * does not close the menu. Hold the element in state (a ref cannot be observed;
-     * TeachingPopover's `target` also takes a ref). A menu opened by `openOnContext` is placed at
+     * does not close the menu. Hold the element in state, or pass a ref object (read after
+     * each render of the menu). A menu opened by `openOnContext` is placed at
      * the gesture instead.
      */
-    target?: PopupTarget;
+    target?: PopupTargetInput;
+    /**
+     * Advanced positioning (Fluent's `positioning`): `offset`, `fitViewport`, `matchReferenceWidth`,
+     * `fallbackPlacements` and `target` (used when the `target` prop is not set). `side` and `align`
+     * stay separate props, and the `offset` prop wins over `positioning.offset`.
+     * @default `{ fitViewport: true }`
+     */
+    positioning?: PopupPositioning;
     /** Menu items and dividers. */
     children: React_2.ReactNode;
     /**
@@ -7798,6 +8323,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
@@ -9016,17 +9557,53 @@ export declare interface PaginationProps extends Omit<React_2.HTMLAttributes<HTM
 }
 
 /**
- * A person's avatar next to their name and optional secondary text (job title, email), with an
- * optional presence badge.
+ * Splits the items of an AvatarGroup into the ones shown inline and the ones in the overflow list.
+ * `AvatarGroup` uses it for `max`; use it yourself to render `AvatarGroup.Item`s and
+ * `AvatarGroup.Popover` from your own list. Server-safe: it imports nothing.
+ *
+ * @example
+ * const { inlineItems, overflowItems } = partitionAvatarGroupItems({ items: people, maxInlineItems: 4 });
+ */
+export declare function partitionAvatarGroupItems<T>({ items, maxInlineItems, layout, }: PartitionAvatarGroupItemsOptions<T>): PartitionAvatarGroupItemsResult<T>;
+
+/** Options of {@link partitionAvatarGroupItems}. */
+export declare interface PartitionAvatarGroupItemsOptions<T> {
+    /** All the items of the group. */
+    items: readonly T[];
+    /**
+     * How many items are shown inline; the rest go to the overflow. A fraction is rounded down, `0`
+     * or a negative value shows none, and `undefined` or `NaN` shows all (up to the layout's cap).
+     */
+    maxInlineItems?: number;
+    /**
+     * The layout of the group. A `pie` shows at most three items inline.
+     * @default 'stack'
+     */
+    layout?: AvatarGroupLayout;
+}
+
+/** Result of {@link partitionAvatarGroupItems}. */
+export declare interface PartitionAvatarGroupItemsResult<T> {
+    /** The items shown inline, in order. */
+    inlineItems: T[];
+    /** The items in the overflow list, in order; `undefined` when nothing overflows. */
+    overflowItems: T[] | undefined;
+}
+
+/**
+ * A person's avatar next to their name and up to three more text lines (job title, location,
+ * status), with an optional presence badge. The text can sit after, before or below the avatar
+ * (`textPosition`), `presenceOnly` swaps the avatar for the presence badge, and the text scales with
+ * `size` up to `huge`.
  *
  * The built-in avatar is decorative (`<Avatar decorative>`): the visible name is announced once,
  * not a second time as the avatar's image name. The presence badge stays exposed as a named image.
  *
  * @example
- * <Persona name="Jane Doe" secondaryText="Designer" status="available" />
+ * <Persona name="Jane Doe" secondaryText="Designer" tertiaryText="Oslo" status="available" />
  */
 export declare const Persona: {
-    ({ name, secondaryText, src, size, status, avatar, badge, className, ref, ...props }: PersonaProps): React_2.JSX.Element;
+    ({ name, primaryText, secondaryText, tertiaryText, quaternaryText, textPosition, textAlignment, presenceOnly, src, size, status, avatar, badge, className, ref, ...props }: PersonaProps): React_2.JSX.Element;
     displayName: string;
 };
 
@@ -9041,20 +9618,52 @@ export declare const personaClassNames: {
     readonly badge: "wave-persona__badge";
     readonly primaryText: "wave-persona__primary-text";
     readonly secondaryText: "wave-persona__secondary-text";
+    readonly tertiaryText: "wave-persona__tertiary-text";
+    readonly quaternaryText: "wave-persona__quaternary-text";
 };
 
 /** Properties for the Persona component. */
 export declare interface PersonaProps extends React_2.HTMLAttributes<HTMLDivElement> {
-    /** Display name of the person. */
-    name: string;
-    /** Secondary text such as job title or email. */
-    secondaryText?: string;
+    /**
+     * Display name of the person. It gives the avatar its initials and the first text line its text
+     * (unless `primaryText` is given). A persona with neither `name` nor `primaryText` warns in
+     * development.
+     */
+    name?: string;
+    /**
+     * The first text line (the name). A string, an element or an object of `<span>` attributes.
+     * @default the `name`
+     */
+    primaryText?: Slot<'span'>;
+    /** The second text line, such as a job title or email. */
+    secondaryText?: Slot<'span'>;
+    /** The third text line, such as a location. */
+    tertiaryText?: Slot<'span'>;
+    /** The fourth text line, such as a status message. */
+    quaternaryText?: Slot<'span'>;
+    /**
+     * Where the text sits relative to the avatar, in reading order: after it, before it, or below it.
+     * @default 'after'
+     */
+    textPosition?: 'after' | 'before' | 'below';
+    /**
+     * How the text lines align with each other.
+     * @default 'start' ('center' when the text is below the avatar)
+     */
+    textAlignment?: 'start' | 'center';
+    /**
+     * Shows only the presence badge (from `status` or `badge`) in place of the avatar. The text
+     * stays.
+     * @default false
+     */
+    presenceOnly?: boolean;
     /** URL of the person's avatar image. */
     src?: string;
-    /** Size of the persona avatar.
+    /**
+     * Size of the persona: its avatar and its text.
      * @default 'medium'
      */
-    size?: Size;
+    size?: PersonaSize;
     /** Presence status shown as a badge on the avatar. Ignored when a `badge` is given. */
     status?: PresenceStatus;
     /**
@@ -9074,6 +9683,9 @@ export declare interface PersonaProps extends React_2.HTMLAttributes<HTMLDivElem
     ref?: React_2.Ref<HTMLDivElement>;
 }
 
+/** The size of a Persona: the Avatar sizes, and `huge` (a 72px avatar). */
+export declare type PersonaSize = Size | 'huge';
+
 /** How urgently assistive technology should read a message. */
 export declare type Politeness = 'polite' | 'assertive';
 
@@ -9159,7 +9771,7 @@ export declare type PolymorphicProps<C extends React_2.ElementType, OwnProps> =
  * </Popover>
  */
 export declare const Popover: {
-    ({ open: openProp, defaultOpen, onOpenChange, side, align, ignoreOutsideRefs, openOnHover, openDelay, closeDelay, openOnContext, target, children, }: PopoverProps): React_2.JSX.Element;
+    ({ open: openProp, defaultOpen, onOpenChange, side, align, ignoreOutsideRefs, openOnHover, openDelay, closeDelay, openOnContext, target: targetProp, positioning, children, }: PopoverProps): React_2.JSX.Element;
     displayName: string;
 } & {
     Trigger: {
@@ -9316,10 +9928,18 @@ export declare interface PopoverProps {
      * `aria-labelledby`, and give a toggle button you use as the target `aria-haspopup="dialog"`,
      * `aria-expanded` and `aria-controls` yourself. A press on a target element does not close the
      * popover, and Tab from it enters the content when there is no trigger. Hold the element in
-     * state (a ref cannot be observed; TeachingPopover's `target` also takes a ref). A popover
+     * state, or pass a ref object (read after each render of the popover, so an element that attaches without it rendering is noticed on its next render). A popover
      * opened by `openOnContext` is placed at the gesture instead.
      */
-    target?: PopupTarget;
+    target?: PopupTargetInput;
+    /**
+     * Advanced positioning (Fluent's `positioning`): `offset` (px from the anchor), `fitViewport`
+     * (limit the content to the space the viewport leaves; Fluent's `autoSize`), `matchReferenceWidth`,
+     * `fallbackPlacements` (tried in order when the requested side has no room) and `target` (used
+     * when the `target` prop is not set). `side` and `align` stay separate props.
+     * @default `{ offset: 8 }`
+     */
+    positioning?: PopupPositioning;
     /** `Popover.Trigger` and `Popover.Content`. */
     children: React_2.ReactNode;
 }
@@ -9404,6 +10024,39 @@ export declare interface PopoverTriggerProps extends Omit<React_2.HTMLAttributes
 /** Alignment of a popup along the anchor's edge. */
 export declare type PopupAlign = 'start' | 'center' | 'end';
 
+/** A placement for `PopupPositioning.fallbackPlacements`: a side, and optionally an alignment on it. */
+export declare interface PopupPlacement {
+    /** Side of the anchor. `start` and `end` follow the writing direction. */
+    side: PopupSide;
+    /** Alignment along that side. @default the surface's own `align` */
+    align?: PopupAlign;
+}
+
+/**
+ * The advanced positioning options of a popup (the `positioning` prop; Fluent's `positioning`).
+ * `side` and `align` stay separate props of each component, so every option has one source.
+ */
+export declare interface PopupPositioning {
+    /** Distance from the anchor in px. @default the component's own (Popover 8, Tooltip 8, TeachingPopover 12, listboxes 4) */
+    offset?: number;
+    /**
+     * Limit the surface to the space the viewport leaves (Fluent's `autoSize`). Popover also scrolls
+     * its content inside its border; the other surfaces only limit their size (their own lists and
+     * grids scroll as they always did).
+     * @default the component's own
+     */
+    fitViewport?: boolean;
+    /** Make the surface as wide as its anchor. @default the component's own */
+    matchReferenceWidth?: boolean;
+    /** Placements to try, in order, when the requested side has no room; replaces the opposite side. */
+    fallbackPlacements?: readonly PopupPlacement[];
+    /** Position against this instead of the trigger. */
+    target?: PopupTargetInput;
+}
+
+/** {@link PopupPositioning} without `target`: the options of a popup that has no `target` prop. */
+export declare type PopupPositioningOptions = Omit<PopupPositioning, 'target'>;
+
 /** A rectangle in viewport coordinates, as `getBoundingClientRect()` returns it (a `DOMRect` is one). */
 export declare interface PopupRect {
     x: number;
@@ -9423,12 +10076,20 @@ export declare interface PopupRect {
 export declare type PopupSide = 'top' | 'bottom' | 'start' | 'end' | 'left' | 'right';
 
 /**
- * Where a popup is placed instead of next to its trigger (`Menu.Popover` and `Popover` `target`):
- * an element held in state, or a `VirtualElement`. TeachingPopover's `target` (0.6) also takes a
- * ref and no `VirtualElement`; ROADMAP P7-01 unifies them.
+ * Where a popup is placed instead of next to its trigger (`Menu.Popover`, `Popover` and
+ * `TeachingPopover` `target`): an element held in state, or a `VirtualElement`. Those components
+ * also take a ref object (`PopupPositioning['target']`).
  */
 export declare type PopupTarget = HTMLElement | VirtualElement | null;
 
+/**
+ * What a popup's `target` prop accepts: a {@link PopupTarget}, or a ref object (an element that
+ * attaches without the popup rendering is read after each render of the popup).
+ */
+export declare type PopupTargetInput = PopupTarget | {
+    readonly current: HTMLElement | null;
+};
+
 /**
  * Renders its children into `document.body` (or the WaveProvider `portalContainer`), wrapped in a
  * `<div class="wave-portal …">` that carries the provider's theme classes, direction and font, so
@@ -9485,6 +10146,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
@@ -9537,9 +10208,10 @@ export declare interface PresenceAttributes {
  *
  * @example
  * <PresenceBadge status="busy" />
+ * <PresenceBadge status="do-not-disturb" />
  */
 export declare const PresenceBadge: {
-    ({ status, size, className, ref, ...props }: PresenceBadgeProps): React_2.JSX.Element;
+    ({ status: statusProp, size: sizeProp, className, ref, ...props }: PresenceBadgeProps): React_2.JSX.Element;
     displayName: string;
 };
 
@@ -9551,9 +10223,14 @@ export declare const presenceBadgeClassNames: {
 
 /** Properties for the PresenceBadge component. */
 export declare interface PresenceBadgeProps extends React_2.HTMLAttributes<HTMLSpanElement> {
-    /** Presence status to display. */
-    status: PresenceStatus;
-    /** Size of the presence indicator.
+    /**
+     * Presence status to display. `'dnd'` and `'oof'` are deprecated aliases of `'do-not-disturb'`
+     * and `'out-of-office'`: they render the same and warn once in development (removed in 1.0).
+     * @default 'available'
+     */
+    status?: PresenceStatus;
+    /**
+     * Size of the presence indicator. In the `badge` slot of an Avatar it is sized from the avatar.
      * @default 'medium'
      */
     size?: Size;
@@ -9579,8 +10256,11 @@ export declare interface PresenceProps extends UsePresenceOptions {
     children: React_2.ReactElement | ((presence: UsePresenceResult) => React_2.ReactNode);
 }
 
-/** User presence status for Avatar and Persona components. */
-export declare type PresenceStatus = 'available' | 'busy' | 'away' | 'offline' | 'dnd' | 'oof';
+/**
+ * User presence status for Avatar and Persona components. `'dnd'` and `'oof'` are deprecated
+ * aliases of `'do-not-disturb'` and `'out-of-office'` ({@link DeprecatedPresenceStatus}).
+ */
+export declare type PresenceStatus = 'available' | 'busy' | 'away' | 'offline' | 'do-not-disturb' | 'out-of-office' | DeprecatedPresenceStatus;
 
 /**
  * Shows the progress of a task, or that a task is running (indeterminate, `value` omitted).
@@ -11819,11 +12499,11 @@ export declare interface TableRowProps extends React_2.HTMLAttributes<HTMLTableR
  * `TabListPanels`) for React Server Components, which cannot use the dotted form.
  */
 export declare const TabList: {
-    ({ value: valueProp, defaultValue: defaultValueProp, onValueChange, orientation: orientationProp, selectTabOnFocus, selectedValue, defaultSelectedValue, onTabSelect, vertical, className, children, onKeyDown, onFocus, ref, ...rest }: TabListProps): React_2.JSX.Element;
+    ({ value: valueProp, defaultValue: defaultValueProp, onValueChange, orientation: orientationProp, appearance, size, selectTabOnFocus, selectedValue, defaultSelectedValue, onTabSelect, vertical, className, children, onKeyDown, onFocus, ref, ...rest }: TabListProps): React_2.JSX.Element;
     displayName: string;
 } & {
     Tab: {
-        ({ value, id: idProp, className, children, onClick, ref, ...rest }: TabProps): React_2.JSX.Element;
+        ({ value, id: idProp, icon, className, children, onClick, ref, ...rest }: TabProps): React_2.JSX.Element;
         displayName: string;
     };
     Panel: {
@@ -11836,6 +12516,9 @@ export declare const TabList: {
     };
 };
 
+/** The look of a TabList: an underline, subtle fills, or circular subtle or filled tabs. */
+export declare type TabListAppearance = 'transparent' | 'subtle' | 'subtle-circular' | 'filled-circular';
+
 /** TabList: `root` on the `role="tablist"` element. */
 export declare const tabListClassNames: {
     readonly root: "wave-tab-list";
@@ -11898,6 +12581,19 @@ export declare interface TabListProps extends Omit<React_2.HTMLAttributes<HTMLDi
      * @default 'horizontal'
      */
     orientation?: Orientation;
+    /**
+     * Look of the tabs: `transparent` underlines the selected tab, `subtle` and `subtle-circular`
+     * fill it with a subtle color (square or fully rounded), `filled-circular` fills it with the
+     * primary color. In forced colors the selected tab keeps a Highlight outline (or underline) in
+     * every appearance.
+     * @default 'transparent'
+     */
+    appearance?: TabListAppearance;
+    /**
+     * Size of the tabs: their padding and type (`medium` is 14px text on 16 by 8px padding).
+     * @default 'medium'
+     */
+    size?: CoreSize;
     /**
      * Whether moving focus with the arrow keys, Home and End also selects the tab (automatic
      * activation, as in 0.5). With `false`, the keys only move focus and Enter, Space or a click
@@ -11929,13 +12625,14 @@ export declare interface TabListProps extends Omit<React_2.HTMLAttributes<HTMLDi
  * with its value is mounted.
  */
 export declare const TabListTab: {
-    ({ value, id: idProp, className, children, onClick, ref, ...rest }: TabProps): React_2.JSX.Element;
+    ({ value, id: idProp, icon, className, children, onClick, ref, ...rest }: TabProps): React_2.JSX.Element;
     displayName: string;
 };
 
 /** TabList.Tab: `root` on the `role="tab"` button. */
 export declare const tabListTabClassNames: {
     readonly root: "wave-tab-list-tab";
+    readonly icon: "wave-tab-list-tab__icon";
 };
 
 /** Properties for the TabPanel sub-component. */
@@ -11956,6 +12653,11 @@ export declare interface TabPanelsProps extends React_2.HTMLAttributes<HTMLDivEl
 export declare interface TabProps extends React_2.ButtonHTMLAttributes<HTMLButtonElement> {
     /** Unique value identifying this tab (and its panel). */
     value: string;
+    /**
+     * An icon before the text, hidden from assistive technology. A tab with an icon and no text is
+     * icon-only (a square hit area): name it with `aria-label`, or a development warning asks for it.
+     */
+    icon?: Slot<'span'>;
     /** Ref to the tab `<button>`. */
     ref?: React_2.Ref<HTMLButtonElement>;
 }
@@ -12839,6 +13541,13 @@ export declare interface TagPickerProps extends Omit<React_2.HTMLAttributes<HTML
      * option list keeps its size.
      */
     size?: TagPickerSize;
+    /**
+     * Advanced positioning of the popup (Fluent's `positioning`): `offset`, `fitViewport`,
+     * `matchReferenceWidth` and `fallbackPlacements` (tried in order when the requested side has no
+     * room). The popup opens below the field.
+     * @default `{ matchReferenceWidth: true, fitViewport: true }`
+     */
+    positioning?: PopupPositioningOptions;
     /**
      * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
      * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
@@ -12974,7 +13683,9 @@ export declare type TagSize = Extract<Size, 'extra-small' | 'small' | 'medium'>;
  * - With `target`, the popover is portaled and positioned next to that element with a beak (it
  *   inherits the surface colors); it stays hidden while the target is `null`, not positioned yet or
  *   no longer mounted (a ref target is read after each render of the popover; see `target`).
- * - With `target`, the keyboard order treats the popover as if it followed the target: Tab past
+ * - With a `VirtualElement` target there is no element to follow: the popover keeps the place of
+ *   its portal in the keyboard order.
+ * - With an element or ref `target`, the keyboard order treats the popover as if it followed the target: Tab past
  *   its last button continues after the target, Shift+Tab from its first button (or from the
  *   popover itself) returns to the target (for a target outside the Tab order, to the last control
  *   inside it, else to the control before it), Tab from there enters the popover, and Shift+Tab
@@ -12986,7 +13697,7 @@ export declare type TagSize = Extract<Size, 'extra-small' | 'small' | 'medium'>;
  *   it.
  */
 export declare const TeachingPopover: {
-    ({ steps, activeStep: activeStepProp, defaultActiveStep, currentStep, defaultCurrentStep, onStepChange, onDismiss, open: openProp, defaultOpen, onOpenChange, closeLabel, labels, target, side, align, className, style, onKeyDown, ref, ...rest }: TeachingPopoverProps): React_2.JSX.Element | null;
+    ({ steps, activeStep: activeStepProp, defaultActiveStep, currentStep, defaultCurrentStep, onStepChange, onDismiss, open: openProp, defaultOpen, onOpenChange, closeLabel, labels, target: targetProp, positioning, side, align, className, style, onKeyDown, ref, ...rest }: TeachingPopoverProps): React_2.JSX.Element | null;
     displayName: string;
 };
 
@@ -13071,7 +13782,8 @@ export declare interface TeachingPopoverProps extends React_2.HTMLAttributes<HTM
      */
     labels?: TeachingPopoverLabels;
     /**
-     * The element the popover points at (a ref or the element). When given, the popover is
+     * The element the popover points at (a ref, the element, or a `VirtualElement`: a rectangle such as a
+     * point; an inline object is fine). When given, the popover is
      * rendered in a portal, positioned next to it with a beak, and flips or shifts to stay in view;
      * without it (`undefined`) the popover renders inline where it is placed (0.4 behaviour).
      * While the target is `null` or has not been positioned against yet (an element held in state
@@ -13092,7 +13804,7 @@ export declare interface TeachingPopoverProps extends React_2.HTMLAttributes<HTM
      * attached hides the popover right after that commit. Pass the element held in state when the
      * target can mount or unmount without the popover re-rendering.
      */
-    target?: React_2.RefObject<HTMLElement | null> | HTMLElement | null;
+    target?: React_2.RefObject<HTMLElement | null> | HTMLElement | VirtualElement | null;
     /** Side of the `target` to open on; `start`/`end` follow the writing direction.
      * @default 'bottom'
      */
@@ -13101,6 +13813,13 @@ export declare interface TeachingPopoverProps extends React_2.HTMLAttributes<HTM
      * @default 'center'
      */
     align?: PopupAlign;
+    /**
+     * Advanced positioning (Fluent's `positioning`): `offset`, `fitViewport`, `matchReferenceWidth`,
+     * `fallbackPlacements` and `target` (used when the `target` prop is not set). `side` and `align`
+     * stay separate props.
+     * @default `{ offset: 12 }`
+     */
+    positioning?: PopupPositioning;
     /** Ref to the popover surface (`role="dialog"`). */
     ref?: React_2.Ref<HTMLDivElement>;
 }
@@ -13390,6 +14109,13 @@ export declare interface TimePickerProps extends Omit<React_2.HTMLAttributes<HTM
      * list keeps its size.
      */
     size?: CoreSize;
+    /**
+     * Advanced positioning of the popup (Fluent's `positioning`): `offset`, `fitViewport`,
+     * `matchReferenceWidth` and `fallbackPlacements` (tried in order when the requested side has no
+     * room). The popup opens below the field.
+     * @default `{ matchReferenceWidth: true, fitViewport: true }`
+     */
+    positioning?: PopupPositioningOptions;
     /**
      * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
      * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
@@ -14319,7 +15045,7 @@ export declare interface ToolbarToggleButtonProps extends Omit<ToggleButtonProps
  * </Menu>
  */
 export declare const Tooltip: {
-    ({ content, appearance: appearanceProp, variant, openDelay: openDelayProp, closeDelay, delay, open: openProp, defaultOpen, onOpenChange, relationship, side, align, children, className, onMouseEnter, onMouseLeave, onFocus, onBlur, ref, ...rest }: TooltipProps): React_2.JSX.Element;
+    ({ content, appearance: appearanceProp, variant, openDelay: openDelayProp, closeDelay, delay, open: openProp, defaultOpen, onOpenChange, relationship, side, align, positioning, children, className, onMouseEnter, onMouseLeave, onFocus, onBlur, ref, ...rest }: TooltipProps): React_2.JSX.Element;
     displayName: string;
 };
 
@@ -14395,6 +15121,13 @@ export declare interface TooltipProps extends Omit<React_2.HTMLAttributes<HTMLSp
      * @default 'center'
      */
     align?: PopupAlign;
+    /**
+     * Advanced positioning (Fluent's `positioning`): `offset`, `fitViewport`, `matchReferenceWidth`
+     * and `fallbackPlacements`. `side` and `align` stay separate props. The hover bridge across the
+     * gap covers the default 8px, so a larger `offset` leaves a gap the pointer cannot cross.
+     * @default `{ offset: 8 }`
+     */
+    positioning?: PopupPositioningOptions;
     /**
      * A single element that triggers the tooltip on hover and focus: it receives the
      * `aria-describedby`/`aria-labelledby`, plus any `id` and `aria-*` props given to the Tooltip
@@ -14817,6 +15550,82 @@ export declare function useAnnounce(): (message: string, politeness?: Politeness
  */
 export declare function useControllable<T>(controlledValue: T | undefined, defaultValue: T, onChange?: (value: T) => void): [value: T, setValue: SetValue<T>, isControlled: boolean];
 
+/**
+ * Registers an open overlay surface as a **dismiss layer** in the shared layer stack and closes it
+ * on Escape, outside presses and (optionally) focus leaving it — with correct nesting:
+ *
+ * - **Escape** (document `keydown`, bubble phase) is routed by focus location: the innermost layer
+ *   whose tree contains the event target or the focused element is the scope, and the topmost
+ *   escape-enabled layer of that scope's subtree handles it — so a tooltip or popover opened from
+ *   the focused dialog closes before the dialog, while an unrelated layer opened later does not
+ *   steal the key. With no escape-enabled layer there, an escape-enabled ancestor handles it; when
+ *   no layer contains the focus (or none of those takes Escape), the global topmost
+ *   escape-enabled one. Layers stacked below the topmost **isolating** modal (a Dialog/Drawer
+ *   whose `useModalIsolation` is active — its ancestors and older siblings) never take Escape, so
+ *   a modal that ignores Escape blocks it whether it is nested in a dialog or opened beside it.
+ *   A layer with `escape: 'inside'` (a non-modal Dialog or Drawer) takes Escape only while the
+ *   event target or the focused element is in its tree, so an Escape typed on the page leaves it
+ *   open and goes to the layers below it.
+ *   The handler calls `preventDefault()`. Events whose default is already prevented (an inner
+ *   widget consumed Escape) and IME composition events are ignored.
+ * - **Outside press**: on `pointerdown` (capture) every open layer whose tree does not contain the
+ *   target is recorded; on the following `click` each recorded layer whose tree still does not
+ *   contain the click target is dismissed (children first). A drag from inside to outside never
+ *   dismisses, clicks inside nested portaled layers count as inside, a popup opened by the same
+ *   click survives, and an external toggle works. Layers stacked below the topmost isolating modal
+ *   are inert and never dismissed by presses on that modal or its backdrop; a `kind: 'modal'`
+ *   layer without isolation (the DatePicker calendar) shields nothing, so a page click closes it
+ *   and the layers around it. The pending press survives modifier keys (Shift/Ctrl+click) and
+ *   ends on Enter/Space, on `pointercancel`, or when no click follows a mouse `pointerup` in the
+ *   same task; touch and pen presses are kept until their click, which the browser dispatches
+ *   from a separate tap gesture.
+ * - **Focus outside** (`focusOutside: true`): dismisses when focus moves outside the layer's tree.
+ *   That is decided in a microtask, once the current commit has run: an `autoFocus` field of a
+ *   popover, dialog or plain portal opened inside the layer gets focus before that surface's
+ *   portal and layer register, and keeps the layer open. Focus that is back inside the tree by
+ *   then keeps it open too.
+ *
+ * A layer's tree is its `refs`, the portal wrappers rendered inside it, its descendant layers and
+ * the `[data-wave-focus-trap-allow]` regions (toasts). Parentage follows the React tree: wrap the surface in
+ * `Portal layerId={layerId}` (or {@link DismissLayerProvider}) so layers opened inside it become
+ * its children.
+ *
+ * @example
+ * const { layerId } = useDismiss({ open, onDismiss: () => setOpen(false), refs: [surfaceRef, triggerRef], anchorRef: triggerRef });
+ * return open && <Portal layerId={layerId}><div ref={surfaceRef}>…</div></Portal>;
+ */
+export declare function useDismiss(options: UseDismissOptions): DismissLayer;
+
+/** Options of {@link useDismiss}. */
+export declare interface UseDismissOptions {
+    /** Whether the layer is open; the layer is registered only while `true`. */
+    open: boolean;
+    /** Called when the layer should close (the component sets its `open` state to `false`). */
+    onDismiss: (reason: DismissReason, event: Event) => void;
+    /**
+     * Elements that belong to the layer: the content surface, the trigger/anchor and any extra
+     * targets that must not count as "outside" (read at event time).
+     */
+    refs: ReadonlyArray<React_2.RefObject<HTMLElement | null>>;
+    /** The trigger; focus traps leave a descendant layer through it (Tab → the element after it). */
+    anchorRef?: React_2.RefObject<HTMLElement | null>;
+    /** @default 'popover' */
+    kind?: LayerKind;
+    /**
+     * Whether Escape dismisses the layer: always (`true`), never (`false`), or only while the key's
+     * target or the focused element is in the layer's tree (`'inside'`).
+     * @default true
+     */
+    escape?: boolean | 'inside';
+    /**
+     * Whether a press outside the layer's tree dismisses it. A predicate receives the `pointerdown`
+     * event; returning `false` ignores that press. @default true
+     */
+    outsidePress?: boolean | ((event: PointerEvent | MouseEvent) => boolean);
+    /** Whether focus moving outside the layer's tree dismisses it (listboxes). @default false */
+    focusOutside?: boolean;
+}
+
 /**
  * Returns a callback with a stable identity that always invokes the latest `fn` passed to the hook.
  * Use it for handlers read by effects or passed to memoised children, so neither re-runs when the
@@ -14891,6 +15700,172 @@ export declare interface UseFieldControlOptions {
     nativeRequired?: boolean;
 }
 
+/**
+ * A focusable group (Fluent's `useFocusableGroup`, tabster's groupper): one tab stop that holds
+ * several focusable elements, so a long list of rich rows does not cost a Tab press per control.
+ * With `tabBehavior: 'limited'` or `'limited-trap-focus'`, Tab skips the elements inside while focus
+ * is on the group element itself, and Shift+Tab from outside lands on the group element instead of
+ * its last element; Enter or F2 enters the group, and Escape leaves it. A group is entered while
+ * focus is on an element inside it, however it got there (a click, a popup returning focus, a
+ * script). No tabindex is rewritten: components with their own tab stops (Toolbar, TabList) work
+ * inside a group. A key from a popup portaled out of the group, a key that belongs to a nested
+ * group and a key an inner element already handled (`preventDefault()`, as an input consuming
+ * Escape does) are left alone.
+ *
+ * @example
+ * const { groupProps } = useFocusableGroup({ tabBehavior: 'limited' });
+ * <li role="group" aria-label="Message" {...groupProps}>
+ *   <button>Reply</button> <button>Forward</button>
+ * </li>
+ */
+export declare function useFocusableGroup(options?: UseFocusableGroupOptions): UseFocusableGroupResult;
+
+/** Options of {@link useFocusableGroup}. */
+export declare interface UseFocusableGroupOptions {
+    /**
+     * How the group treats the elements inside it (Fluent's `tabBehavior`):
+     *
+     * - `'unlimited'`: the group is one more tab stop and the elements inside it stay reachable by
+     *   Tab; no key is intercepted.
+     * - `'limited'`: the group is one tab stop, in both directions. Enter or F2 on it moves focus to
+     *   its first tabbable element, Tab and Shift+Tab then move between the elements inside, Tab
+     *   past the last one leaves the group, and Escape returns focus to the group.
+     * - `'limited-trap-focus'`: as `'limited'`, but Tab past the last element wraps to the first and
+     *   Shift+Tab before the first wraps to the last, until Escape.
+     *
+     * @default 'unlimited'
+     */
+    tabBehavior?: FocusableGroupTabBehavior;
+}
+
+/** Result of {@link useFocusableGroup}. */
+export declare interface UseFocusableGroupResult {
+    /** Spread onto the group element. */
+    groupProps: FocusableGroupProps;
+}
+
+/**
+ * Keeps keyboard focus inside `container` while `enabled` (modal dialogs, drawers, the DatePicker
+ * calendar). Element-based: pass the surface held in state via a callback ref, so the trap starts
+ * when the element appears.
+ *
+ * - **Initial focus** runs synchronously in the commit in which the container appears (no
+ *   `requestAnimationFrame`), and does nothing when focus is already inside (an `autoFocus`
+ *   element wins).
+ * - **Tab / Shift+Tab** are handled by a document bubble-phase `keydown` listener that ignores
+ *   events whose default is already prevented, so a React handler inside (a menu closing on Tab, a
+ *   grid) can take the key first. Focus wraps at the edges, and from the container itself or a
+ *   non-tabbable element it continues in document order. Tabbable elements are computed on every
+ *   keydown (content may change; radio-group stops depend on focus), never cached.
+ * - Tabbables inside `[data-wave-focus-trap-allow]` regions (the Toaster viewport) join the cycle.
+ * - **Descendant layers** (a popover or menu opened from inside, identified through `layerId`):
+ *   Tab moves natively inside them; leaving one moves focus to the element after its anchor
+ *   (Shift+Tab: the anchor itself). Inside a plain `<Portal>` rendered in the surface (no layer,
+ *   no anchor) Tab is native too; leaving it wraps to the first (Shift+Tab: last) element. A
+ *   layer's trigger (its anchor, or an element around it such as a tooltip's wrapper) belongs to
+ *   the region it sits in, so Tab from an open info button or a button showing its tooltip moves
+ *   on as from any other element of that portal or popover.
+ * - Focus that lands outside (not in the container, an allowed region or a descendant layer)
+ *   returns to the last focused element inside, also when that outside element loses it again
+ *   (removed or blurred, leaving focus on `<body>`). That is decided in a microtask, once the
+ *   current commit has run: an `autoFocus` element of a surface opened above the trap (a nested or
+ *   stacked dialog, a popover opened from the surface) gets focus before that surface's layer and
+ *   trap exist, and keeps it. The layer's own `refs` (its trigger, outside the container) are
+ *   outside: opening from the focused trigger still moves focus in, and focus moving back onto
+ *   the trigger is returned. Focus pulled out again while it is being returned (another focus
+ *   trap on the page) is left there.
+ * - Traps form a stack (shared through the global registry): only the topmost acts.
+ */
+export declare function useFocusTrap(container: HTMLElement | null, options: UseFocusTrapOptions): void;
+
+/** Options of {@link useFocusTrap}. */
+export declare interface UseFocusTrapOptions {
+    /** Whether the trap is active. */
+    enabled: boolean;
+    /**
+     * The surface's dismiss layer; focus inside its descendant layers (portaled popovers opened from
+     * inside) is allowed. The layer's own `refs` outside the container (its trigger) are not.
+     */
+    layerId?: string;
+    /**
+     * What to focus when the trap starts, unless focus is already inside (an `autoFocus` element
+     * wins). @default 'first' (the first tabbable element, else the container)
+     */
+    initialFocus?: React_2.RefObject<HTMLElement | null> | 'first' | 'container' | (() => HTMLElement | null);
+    /** Regions outside the container whose tabbables join the Tab cycle. @default '[data-wave-focus-trap-allow]' (the regions marked with `modalAllowProps`) */
+    allowOutsideSelector?: string;
+}
+
+/**
+ * Whether the page is in keyboard-navigation mode: `true` after the last input was a key press
+ * (any key but a lone modifier), `false` after a pointer or touch press and before any input. For
+ * logic that needs the mode in script, such as showing a focus cue in a widget that draws its own;
+ * plain focus rings should keep using the `focus-visible` variant. One set of document listeners
+ * serves every caller and goes away with the last one. `false` on the server and during
+ * hydration.
+ *
+ * @example
+ * const keyboard = useFocusVisible();
+ * return <div data-keyboard={keyboard ? '' : undefined}>…</div>;
+ */
+export declare function useFocusVisible(): boolean;
+
+/**
+ * Grid keyboard model of the APG Grid pattern for a `<table role="grid">` (DataGrid).
+ *
+ * - **One tab stop.** Exactly one cell of the grid is in the tab order (initially the first cell).
+ *   Its focus target is its only focusable widget when that widget is not a text-entry control
+ *   (a checkbox, a sort button, a link); otherwise — no widget, several widgets, a text-entry
+ *   control or a nested composite — the cell itself. An unchecked radio whose named group has a
+ *   checked radio is not a target either (browsers skip it in the Tab order), so its cell is.
+ *   Every other cell and every widget inside a cell gets `tabindex="-1"`. Rows are never focusable.
+ *   When a widget becomes the target of the focused cell (Space on the cell checks its radio), the
+ *   cell keeps focus and the tab stop (removing its `tabindex` would blur it) while its target stays
+ *   at `tabindex="-1"`; the target takes the tab stop once the cell is blurred.
+ * - **Navigation mode** (focus on a cell or on its target widget): ArrowLeft/ArrowRight (the
+ *   previous/next cell of the row, mirrored in RTL), ArrowUp/ArrowDown, Home/End (first/last cell
+ *   of the row), Ctrl+Home/Ctrl+End (first cell of the grid / last cell of the last row) and
+ *   PageUp/PageDown ({@link UseGridNavigationOptions.pageSize} rows) move focus between cells.
+ *   ArrowUp/ArrowDown and PageUp/PageDown keep the visual column (`colSpan` and `rowSpan` counted,
+ *   so a grouped header works), clamped to a shorter row. Space and Enter on a target widget reach
+ *   the widget.
+ * - **Interaction mode**: Enter or F2 on a cell that is its own target moves focus into its first
+ *   widget; clicking a widget that is not the cell's target (a text input) enters it too. The
+ *   grid keys are then ignored, so the arrow keys move the caret, and Tab moves between the cell's
+ *   widgets. Escape returns focus to the cell. Leaving the grid ends interaction mode.
+ * - **Nested composites** (an element with `data-roving-container` or role toolbar, radiogroup,
+ *   listbox, grid, treegrid, tablist, menu, menubar or tree) count as one widget that uses the arrow
+ *   keys: its cell takes focus, and Enter/F2 enters the composite at its own tab stop. The grid never
+ *   writes `tabindex` on or inside a composite (the composite manages its own), so a composite
+ *   keeps its own Tab stop — the same documented limitation as `useRovingTabIndex`.
+ *
+ * Keys are ignored when the event's default was prevented (a widget that handled the key, a
+ * consumer handler), or with Alt/Meta held. The tab indexes are written to the DOM (layout effect
+ * plus a `MutationObserver`), so rows and widgets added later are covered without a re-render. Focus
+ * moves re-sync only the cells involved, the observer only the cells that changed, and the grid's
+ * own `tabindex` writes do not trigger a re-sync.
+ *
+ * Internal to the table package.
+ */
+export declare function useGridNavigation(options?: UseGridNavigationOptions): UseGridNavigationResult;
+
+/** Options of {@link useGridNavigation}. */
+export declare interface UseGridNavigationOptions {
+    /**
+     * How many rows PageUp and PageDown move focus.
+     * @default 10
+     */
+    pageSize?: number;
+}
+
+/** Result of {@link useGridNavigation}. */
+export declare interface UseGridNavigationResult {
+    /** Callback ref for the `<table role="grid">` element. Stable identity. */
+    gridRef: React_2.RefCallback<HTMLTableElement>;
+    /** Keyboard and focus handlers for the grid element. Stable identities. */
+    gridProps: GridNavigationHandlers;
+}
+
 /**
  * Generates a stable, SSR-safe unique id, optionally with a prefix. Wraps React's `useId` so every
  * component builds DOM ids the same way (C-IDS).
@@ -14906,6 +15881,26 @@ export declare interface UseFieldControlOptions {
  */
 export declare function useId(prefix?: string): string;
 
+/**
+ * The trap's initial focus without the trap (a non-modal Dialog or Drawer, which moves focus in
+ * when it opens but does not keep it there): in the layout phase of the commit in which
+ * `enabled && container` becomes true, does nothing when focus is already inside the container or
+ * one of the layer's descendant layers (an `autoFocus` element wins), else focuses
+ * `initialFocus` (default: the first tabbable element), else the container. `useFocusTrap` runs
+ * the same code when it starts. It adds no listener.
+ */
+export declare function useInitialFocus(container: HTMLElement | null, options: UseInitialFocusOptions): void;
+
+/** Options of {@link useInitialFocus}. */
+export declare interface UseInitialFocusOptions {
+    /** Whether the surface is open: focus moves in when it becomes `true` with a container. */
+    enabled: boolean;
+    /** The surface's dismiss layer: focus already in one of its descendant layers stays there. */
+    layerId?: string;
+    /** What to focus first. @default 'first' (the first tabbable element, else the container) */
+    initialFocus?: UseFocusTrapOptions['initialFocus'];
+}
+
 /**
  * `false` on the server and during hydration, `true` in every other client render — including the
  * first render of a component mounted on the client, so no second commit is needed.
@@ -15241,6 +16236,11 @@ export declare interface UseListboxPopupOptions {
      * `setReference` too (merged into its ref), which places the surface against it.
      */
     anchorRef: React_2.RefObject<HTMLElement | null>;
+    /**
+     * Advanced positioning: `offset`, `fitViewport`, `matchReferenceWidth` and `fallbackPlacements`.
+     * @default `{ matchReferenceWidth: true, fitViewport: true }`
+     */
+    positioning?: PopupPositioningOptions;
 }
 
 /**
@@ -15358,6 +16358,84 @@ export declare interface UseListboxResult {
  */
 export declare function useMergedRefs<T>(...refs: Array<React_2.Ref<T> | undefined | null>): React_2.RefCallback<T>;
 
+/**
+ * Everything a modal surface (Dialog, Drawer) needs, composed in the order that works:
+ *
+ * 1. `useDismiss({ kind: 'modal' })` — Escape and outside presses (the backdrop is outside the
+ *    content surface, so a click on it dismisses; a drag from the content does not).
+ * 2. `useFocusTrap` — initial focus, Tab cycle incl. toasts and descendant layers.
+ * 3. `useModalIsolation` — the rest of the page is `inert` (instead of `aria-modal`).
+ * 4. `useScrollLock` — ref-counted page scroll lock.
+ * 5. `useRestoreFocus` — the opener (or `triggerRef`/`finalFocusRef`) gets focus back.
+ *
+ * On close the trap is released before the isolation is lifted, and the isolation is lifted
+ * before focus is restored (an inert opener cannot take focus). Wrap the surface in
+ * `Portal layerId={layerId}` so layers opened inside the modal become its descendants.
+ *
+ * `modalType: 'alert'` composes the same with `outsidePress: false`. `modalType: 'non-modal'`
+ * registers a `dialog` layer (Escape only from inside its tree, no outside press, no focus-outside
+ * dismissal), keeps the trap, the isolation and the scroll lock off, moves focus in on open with
+ * the trap's initial-focus rule (`useInitialFocus`) and restores focus only when it is inside the
+ * surface (or in a layer opened from it) at close, or was lost to `<body>` from there. Every hook
+ * is always called and keys on `open`: a `modalType` that changes while open applies at once (the
+ * trap, isolation and lock follow). It leaves focus inside the surface where it is; focus outside
+ * it moves in, as on open: a switch to `modal` or `alert` starts the trap (the page turns inert),
+ * and a switch to `non-modal` runs the initial focus (focus in the toast region, which a trap lets
+ * in, moves into the surface). The Tab order of a non-modal surface (its place after the opener)
+ * is the component's.
+ *
+ * A surface that mounts through the presence core (Dialog, Drawer) passes its open state as
+ * `open`, never its mount (`isMounted`), and its element as `container` also while it is mounted
+ * closed: the layer, the trap, the isolation and the scroll lock end and focus is restored in the
+ * commit that closes it, while the element still runs its exit motion (`inert`) or stays mounted
+ * (`hidden`, with `unmountOnClose={false}`); the next open starts them again with the same
+ * element.
+ */
+export declare function useModalLayer(options: UseModalLayerOptions): DismissLayer;
+
+/**
+ * Options of {@link useModalLayer}: `useDismiss` options (the kind follows `modalType`) plus focus.
+ */
+export declare interface UseModalLayerOptions extends Omit<UseDismissOptions, 'kind'> {
+    /** The modal surface, held in state via a callback ref. */
+    container: HTMLElement | null;
+    /**
+     * `modal` (default) and `alert` register a `modal` layer, trap focus, isolate the page, lock its
+     * scroll and restore focus (an `alert` layer ignores outside presses); `non-modal` registers a
+     * `dialog` layer (`escape: 'inside'`, no outside press, no focus-outside), traps, isolates and
+     * locks nothing, moves focus in on open with the trap's initial-focus rule and restores focus only
+     * from inside (`requireFocusInside`).
+     * @default 'modal'
+     */
+    modalType?: ModalType;
+    /** What the focus trap (or a non-modal surface's initial focus) focuses first. @default 'first' */
+    initialFocus?: UseFocusTrapOptions['initialFocus'];
+    /** The trigger: preferred focus-restore target. */
+    triggerRef?: React_2.RefObject<HTMLElement | null>;
+    /** Consumer override for the focus-restore target. */
+    finalFocusRef?: React_2.RefObject<HTMLElement | null>;
+}
+
+/**
+ * Whether a modal surface is open (a Dialog, an overlay Drawer, an alert, the DatePicker's calendar, or your
+ * own `useDismiss({ kind: 'modal' })` layer): `true` from the
+ * commit that opens it to the commit that closes it, not until its exit motion ends. A non-modal
+ * Dialog or Drawer, a Popover or a Menu is no modal. `false` on the server and during hydration.
+ *
+ * Use it to hold back app behavior the modal should own, such as global keyboard shortcuts, instead
+ * of guessing from the page's `inert` attributes.
+ *
+ * @example
+ * const modalOpen = useModalOpen();
+ * useEffect(() => {
+ *   if (modalOpen) return;
+ *   const onKey = (event: KeyboardEvent) => { if (event.key === '/') focusSearch(); };
+ *   document.addEventListener('keydown', onKey);
+ *   return () => document.removeEventListener('keydown', onKey);
+ * }, [modalOpen]);
+ */
+export declare function useModalOpen(): boolean;
+
 /**
  * The items an {@link Overflow} currently hides: their `itemId`s in DOM order and their count. Use
  * it in the component that `overflowButton` renders to list the hidden items in a menu. Must be
@@ -15373,6 +16451,117 @@ export declare interface UseOverflowMenuResult {
     count: number;
 }
 
+/**
+ * Positions a popup surface next to its anchor with `@floating-ui/react-dom` (Tooltip, Popover,
+ * Menu, listboxes, the DatePicker calendar, TeachingPopover): `offset`, `flip`, `shift`, optional
+ * `size` (reference width / available space as CSS variables) and `arrow`. `flip`, `shift` and
+ * `size` keep the same viewport padding, taken from the `shift` option (8px by default). Logical
+ * `start`/`end` sides follow `useDirection()` (the WaveProvider `dir`, else the document
+ * direction), and so does start/end alignment.
+ *
+ * Positions update only while `open` (`autoUpdate` on scroll/resize; element resizes and layout
+ * shifts only where `ResizeObserver`/`IntersectionObserver` exist). Spread `floatingProps` onto the
+ * surface: `data-side`/`data-align` expose the final placement for styling (C-CLASS).
+ *
+ * The anchor is an element or a `VirtualElement` (a rectangle such as the pointer position; a new
+ * object on every render is fine); give it a `contextElement` so scrolling its containers updates
+ * the position. A virtual anchor reaches floating-ui through one stable proxy that reads the latest
+ * object: a new object only recomputes the position (which renders only when the position
+ * changes), and a new proxy is made only when the `contextElement` changes.
+ *
+ * Destructure the result: `eslint-plugin-react-hooks` (`react-hooks/refs`) treats an object
+ * whose member is passed to a `ref` prop as a ref, and then rejects reading its other members
+ * during render.
+ *
+ * @example
+ * const { setReference, setFloating, floatingProps } = usePopupPosition({ open, side: 'bottom' });
+ * <button ref={setReference} />
+ * {open && <Portal><div ref={setFloating} {...floatingProps} /></Portal>}
+ */
+export declare function usePopupPosition(options: UsePopupPositionOptions): UsePopupPositionResult;
+
+/** Options of {@link usePopupPosition}. */
+export declare interface UsePopupPositionOptions {
+    /** Whether the popup is open; positions are kept up to date only while `true`. */
+    open: boolean;
+    /** Side of the anchor. `start`/`end` follow the writing direction. @default 'bottom' */
+    side?: PopupSide;
+    /** Alignment along that side. @default 'start' */
+    align?: PopupAlign;
+    /** Distance from the anchor in px. @default 4 (tooltips use 8) */
+    offset?: number;
+    /** Flip to the opposite side when there is not enough room. @default true */
+    flip?: boolean;
+    /**
+     * Shift along the side to stay inside the viewport. Its padding is also the viewport padding of
+     * `flip` and of `size` (`fitViewport`, `matchReferenceWidth`): `true` means 8px, and `false`
+     * lets the popup flip only once it touches the viewport edge and grow right up to it. With
+     * `crossAxis: true` it also shifts across the side, over the anchor, when neither side has room
+     * after `flip` (submenus), and `fitViewport` then offers the whole viewport in that direction.
+     * @default { padding: 8 }
+     */
+    shift?: boolean | {
+        padding: number;
+        crossAxis?: boolean;
+    };
+    /** Make the surface as wide as the anchor (listboxes). @default false */
+    matchReferenceWidth?: boolean;
+    /** Limit the surface to the available space (`max-width`/`max-height`). @default false */
+    fitViewport?: boolean;
+    /** An arrow (beak) element inside the surface, positioned through `arrowStyles`. */
+    arrowRef?: React_2.RefObject<HTMLElement | null>;
+    /** CSS positioning strategy. @default 'fixed' */
+    strategy?: 'absolute' | 'fixed';
+    /**
+     * Placements to try, in order, when the requested side has no room, instead of only the opposite
+     * side. Ignored with `flip: false`. An omitted `align` is the hook's own `align`.
+     */
+    fallbackPlacements?: readonly PopupPlacement[];
+    /**
+     * Hide the surface (`visibility: hidden`: its layout is unaffected, but its content cannot take
+     * focus, so a surface that holds focus loses it) while the anchor is scrolled out of view or
+     * clipped away. @default false
+     */
+    hideWhenDetached?: boolean;
+    /**
+     * Called after the surface is positioned, and again whenever the final placement changes (a flip,
+     * a fallback): not on every scroll or resize recompute. It runs from an effect, never during
+     * render, and not while closed.
+     */
+    onPositioned?: (info: PositionedInfo) => void;
+}
+
+/** Returned by {@link usePopupPosition}. */
+export declare interface UsePopupPositionResult {
+    /**
+     * Sets the anchor: a ref callback for the anchor (trigger) element, or a call from a layout
+     * effect or an event. The anchor is an element or a `VirtualElement` (a rectangle such as the
+     * pointer position; a new object on every render is fine); give it a `contextElement` so
+     * scrolling its containers updates the position.
+     */
+    setReference(el: HTMLElement | VirtualElement | null): void;
+    /** Ref callback for the popup surface. */
+    setFloating(el: HTMLElement | null): void;
+    /** Position styles for the surface (also in `floatingProps.style`). */
+    floatingStyles: React_2.CSSProperties;
+    /** Position styles for the arrow element. */
+    arrowStyles: React_2.CSSProperties;
+    /** Final placement after flipping, e.g. `'top-start'`. */
+    placement: string;
+    /** Final physical side after flipping. */
+    side: 'top' | 'bottom' | 'left' | 'right';
+    /** Whether a position has been computed since the popup opened. */
+    isPositioned: boolean;
+    /** Recomputes the position now, for a change floating-ui cannot observe. A no-op while closed. */
+    update(): void;
+    /** Spread onto the surface: `data-side`, `data-align` and the position style. */
+    floatingProps: {
+        'data-side': string;
+        'data-align': string;
+        style: React_2.CSSProperties;
+    };
+}
+
 /**
  * Mounts and unmounts an element with CSS enter and exit motion. Style the phases with
  * `data-presence` variants, e.g. `transition-opacity duration-wave-normal
@@ -15454,6 +16643,102 @@ export declare interface UsePresenceResult {
     presenceProps: PresenceAttributes;
 }
 
+/**
+ * Returns focus to where it came from when a surface closes (dialogs, drawers, popovers, menus,
+ * the DatePicker calendar, TeachingPopover).
+ *
+ * - **Capture**: when `enabled` flips to `true`, the opener is captured in an insertion effect —
+ *   before React applies `autoFocus` inside the new surface — preferring `triggerRef.current` and
+ *   ignoring `<body>` and elements inside `container`. When that finds nothing (a surface that
+ *   mounts open, before the refs of its commit are attached), it is captured again in the layout
+ *   phase of the same commit. Its place in the document and the triggers of the overlays it sits
+ *   in are recorded with it. When focus is already on `<body>` because
+ *   the focused element was removed earlier in the same commit (a menu item in a popover that
+ *   closes as the dialog it opens appears, the popover coming first in the tree), a document
+ *   focus tracker supplies that element with its recorded place and overlay triggers. The tracker
+ *   runs while any instance of the hook is mounted, and it forgets an element the user moved focus
+ *   away from on purpose.
+ * - **Restore** when `enabled` flips to `false` (layout phase) and when the component unmounts
+ *   while enabled. The unmount restore runs in a microtask and is cancelled if the same instance
+ *   mounts again, so React StrictMode's simulated unmount does not pull focus out of a surface
+ *   that just opened.
+ * - **Targets**, first valid wins:
+ *   1. `finalFocusRef` → the captured opener → `triggerRef` → `fallback()`.
+ *   2. When the opener was removed or cannot take focus, its replacement, nearest first: the
+ *      tabbable element next to where it was (in the innermost surviving ancestor that holds one,
+ *      the next one — the next row's action after a delete — else the previous one; then the same
+ *      one level up), else the trigger of the overlay it was in (a menu item's menu button), else
+ *      the element next to that trigger. When the surface is rendered inside another open layer
+ *      (its parent layer, from `DismissLayerContext`: a confirm Dialog in a Drawer's content),
+ *      only the replacements inside that layer's tree are tried here.
+ *   3. The parent layer's surface, then the replacements outside the parent layer.
+ *   4. The surface of the modal layer that stays open.
+ *
+ *   So a confirm Dialog rendered in a Drawer's content and one rendered next to the Drawer both
+ *   return focus to the adjacent row, not to the Drawer's panel. A target is valid when it is
+ *   connected, focusable, not inside `[inert]` or `[aria-hidden="true"]`, and not cut off behind
+ *   another open modal layer — so focus never lands on the inert page behind a Drawer that stays
+ *   open, and is not dropped on `<body>` while a valid target exists. Focus uses `preventScroll`.
+ * - `onlyIfFocusInside` (popovers): restores only when focus is inside the surface or was lost to
+ *   `<body>`.
+ * - `requireFocusInside` (surfaces that do not trap focus: a non-modal Dialog or Drawer, an inline
+ *   Drawer): restores only when focus is inside the surface or in a layer opened from it (a
+ *   descendant layer of `layerId`, or a layer anchored inside the surface), or was lost to
+ *   `<body>` from an element in either; a close from code while focus is on `<body>` or on the
+ *   page moves nothing.
+ * - `isHoverClose`: a close by the hover intent restores only when focus is inside the surface, so
+ *   a hover close never moves focus from `<body>` or from where the user put it. The same holds for
+ *   a surface opened from inside one that closes by hover (a submenu, a hover card in a hover
+ *   card): every mounted instance is known to the others through the focus tracker's record.
+ */
+export declare function useRestoreFocus(options: UseRestoreFocusOptions): void;
+
+/** Options of {@link useRestoreFocus}. */
+export declare interface UseRestoreFocusOptions {
+    /** `true` while the surface is open. */
+    enabled: boolean;
+    /** The layer surface: opener candidates inside it are ignored. */
+    container?: HTMLElement | null;
+    /** The trigger: preferred restore target. */
+    triggerRef?: React_2.RefObject<HTMLElement | null>;
+    /** Consumer override: focused first when valid. */
+    finalFocusRef?: React_2.RefObject<HTMLElement | null>;
+    /** Used when neither the override, the opener nor the trigger can take focus. */
+    fallback?: () => HTMLElement | null;
+    /**
+     * Popovers: restore only when focus was inside the surface (or lost to `<body>`) at close, so a
+     * click that moved focus elsewhere is respected. @default false
+     */
+    onlyIfFocusInside?: boolean;
+    /**
+     * Read when the surface closes, or unmounts while open: `true` when the hover intent closed it
+     * (Popover and Menu `openOnHover`, a submenu closing by hover). A hover close never moves focus:
+     * it restores only while focus is inside the surface, so focus on `<body>` (where a hover-opened
+     * surface leaves it) or elsewhere stays where it is. A surface opened from inside one that closes
+     * by hover (its opener, else its trigger, lies in that surface: a submenu, a hover card in a
+     * hover card, at any depth) is taken along, and its close counts as a hover close too. Every
+     * other close keeps the rules above.
+     */
+    isHoverClose?: () => boolean;
+    /**
+     * Surfaces that do not trap focus (a non-modal Dialog or Drawer, an inline Drawer): restore only
+     * when focus is inside the surface at close, or was lost to `<body>` from an element inside it
+     * (removed, or made unable to take focus). Focus elsewhere, or on `<body>` for another reason
+     * (nothing had focus, a press on a spot that takes no focus, a close from code), stays where it
+     * is. Wins over `onlyIfFocusInside`. Focus in a layer opened from the surface (a Popover or a
+     * confirm Dialog, portaled outside it) counts as inside: a descendant layer of `layerId`, or a
+     * layer anchored to an element inside the surface; so does focus lost to `<body>` from one.
+     * @default false
+     */
+    requireFocusInside?: boolean;
+    /**
+     * The surface's own dismiss layer, with `requireFocusInside`: focus in one of its descendant
+     * layers counts as inside the surface, also after the surface's layer has unregistered (in the
+     * commit that closes it).
+     */
+    layerId?: string;
+}
+
 /**
  * Implements the WAI-ARIA roving tabindex pattern for composite widgets: one item holds the tab
  * stop (`tabIndex=0`, all others `-1`), arrow keys move focus between items, Home/End jump to the
@@ -15542,10 +16827,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