@mortenbrudvik/waveui 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -199,6 +199,19 @@ export declare interface AccordionTriggerProps extends React_2.ButtonHTMLAttribu
     ref?: React_2.Ref<HTMLButtonElement>;
 }
 
+/**
+ * `date` plus `amount` calendar days (negative to go back), at local midnight; the time of day is
+ * dropped.
+ */
+export declare function addDays(date: Date, amount: number): Date;
+
+/**
+ * `date` plus `amount` months (negative to go back), at local midnight; the time of day is dropped.
+ * The day is clamped to the length of the target month: January 31 plus one month is February 28
+ * (29 in a leap year), never a day of the following month.
+ */
+export declare function addMonths(date: Date, amount: number): Date;
+
 /**
  * A slider for a color's opacity, drawn over a checkerboard, horizontal (mirrored in right-to-left
  * layouts) or vertical (bottom to top); `transparency` shows transparency instead. The arrow keys
@@ -765,6 +778,291 @@ export declare interface ButtonOwnProps {
  */
 export declare type ButtonProps<C extends React_2.ElementType = 'button'> = PolymorphicProps<C, ButtonOwnProps>;
 
+/**
+ * A month calendar for picking one day, without a text input: the grid of DatePicker's dialog,
+ * placed in the page (APG date picker grid).
+ *
+ * - **Structure**: a `role="group"` root, named with `aria-label`/`aria-labelledby` or by a
+ *   surrounding `Field`, around the previous-month button, the month text (a polite live region
+ *   that labels the grid), the next-month button and a `role="grid"` table of six weeks, with an
+ *   optional leading column of week numbers (`showWeekNumbers`, `firstWeekOfYear`) and an
+ *   optional footer button, "Go to today" (`showGoToToday`), which shows today's month and focuses
+ *   today without selecting it. The month text is no heading, since a component cannot know the
+ *   page's heading levels.
+ * - **Month and year views** (`showMonthPicker`, on by default): the month text is a button
+ *   (named by that text, its hint `labels.chooseMonth`) that shows the 12 months of the year; their
+ *   heading, the year, is a button to the year view, a decade with the year before and after it
+ *   (muted). The header buttons move by a year, then by a decade. A picked year shows its months
+ *   and a picked month its days (the focused day keeps its day of the month, clamped); Escape
+ *   goes back a level to the period shown before. Each view change moves focus into the new
+ *   grid. Months and years wholly outside `minDate`/`maxDate` stay focusable, `aria-disabled`.
+ * - **Keyboard**: one tab stop in the grid, the focused day (the selected day of the shown month,
+ *   else today, else the first day of the month in range, which may be unavailable). Arrow keys
+ *   move by day and week (mirrored in RTL), PageUp/PageDown by month, Shift+PageUp/PageDown by
+ *   year (the day is clamped to the month), Home/End to the start and end of the week; Enter,
+ *   Space and a click pick the day. Unavailable days (`minDate`, `maxDate`, `disabledDates`) stay
+ *   focusable and are `aria-disabled`. In the month and year views the arrows move by a cell and a
+ *   row of four, Home/End to the row's ends, PageUp/PageDown by a year (months) or ten (years).
+ * - **Value**: `onValueChange` fires only when the day changes, with local midnight and `details`;
+ *   picking the selected day again does nothing. A value that moves to another month shows that
+ *   month. The selected day is `aria-selected` on its gridcell and `aria-pressed` on its button;
+ *   today is `aria-current="date"`. With `selectionRange` a pick selects the day's week, work
+ *   week (`workWeekDays`) or month: every available day of it is drawn and marked selected, the
+ *   value is the picked day, and `details.range` lists the selected days in order.
+ * - **Marked days and custom content**: `markedDates` draws a dot in the text colour under the
+ *   number, sets `data-marked` and says "marked" in the day's name; `renderDay` replaces the
+ *   content of the day button (non-interactive content only) and `dayLabel` sets its name.
+ * - **Forms and Field**: `name`/`required` add a hidden input (ISO `yyyy-mm-dd`) that resets with
+ *   its form (to `defaultValue`); a required calendar that the form reports missing focuses its
+ *   tab stop. Inside a `Field` the group takes the label, the description and `aria-invalid`; it
+ *   says "required" in its description (`labels.required`), since a group cannot carry
+ *   `aria-required`.
+ * - **Server rendering**: pass `locale`, and `today`, `initialVisibleDate` or a value, so the
+ *   server and the browser render the same month. Only `today` marks a day in the server HTML:
+ *   without it the server HTML marks none and the browser marks today once hydrated. Without any
+ *   of the three the month shown first comes from the server's clock (development warning).
+ *
+ * @example
+ * <Calendar aria-label="Due date" defaultValue={new Date(2025, 5, 12)} onValueChange={setDue} />
+ */
+export declare const Calendar: {
+    ({ value: valueProp, defaultValue, onValueChange, minDate, maxDate, disabledDates, firstDayOfWeek, locale, today: todayProp, initialVisibleDate, showMonthPicker, showWeekNumbers, firstWeekOfYear, showGoToToday, markedDates, renderDay, dayLabel, selectionRange, workWeekDays, labels, name, form, required, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, className, ref, ...rest }: CalendarProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * Calendar: `root` on the `role="group"` element; `header` on the row of the navigation buttons
+ * and the heading; `previousButton` and `nextButton` on the navigation buttons (by a month, a
+ * year or a decade); `heading` on the month, year or decade text (a `<div>`, which labels the
+ * grid); `headingButton` on the heading's button to the month and year views; `grid` on the
+ * `role="grid"` element of every view; `weekday` on each weekday header cell; `weekNumberHeader`
+ * on the header cell of the week-number column and `weekNumber` on each week's row header
+ * (`showWeekNumbers`); `day`, `month` and `year` on each day, month and year button; `markedDot`
+ * on the dot inside a marked day's button; `footer` on the row of the footer buttons, with
+ * `todayButton` on "Go to today" (`showGoToToday`).
+ */
+export declare const calendarClassNames: {
+    readonly root: "wave-calendar";
+    readonly header: "wave-calendar__header";
+    readonly previousButton: "wave-calendar__previous-button";
+    readonly heading: "wave-calendar__heading";
+    readonly headingButton: "wave-calendar__heading-button";
+    readonly nextButton: "wave-calendar__next-button";
+    readonly grid: "wave-calendar__grid";
+    readonly weekday: "wave-calendar__weekday";
+    readonly weekNumberHeader: "wave-calendar__week-number-header";
+    readonly weekNumber: "wave-calendar__week-number";
+    readonly day: "wave-calendar__day";
+    readonly markedDot: "wave-calendar__marked-dot";
+    readonly month: "wave-calendar__month";
+    readonly year: "wave-calendar__year";
+    readonly footer: "wave-calendar__footer";
+    readonly todayButton: "wave-calendar__today-button";
+};
+
+/**
+ * The built-in texts of the calendar, for localization: the names of the navigation buttons in
+ * the day, month and year views, the hints of the heading button, the "Go to today" button, the
+ * week-number column and the marked days, and (Calendar only) the required hint. Each member is
+ * optional and falls back to its English default. Month and weekday names and the day labels follow
+ * `locale`. DatePicker's labels extend this type.
+ */
+export declare interface CalendarLabels {
+    /** Name of the previous-month button.
+     * @default 'Previous month'
+     */
+    previousMonth?: string;
+    /** Name of the next-month button.
+     * @default 'Next month'
+     */
+    nextMonth?: string;
+    /** Name of the previous-year button of the month view.
+     * @default 'Previous year'
+     */
+    previousYear?: string;
+    /** Name of the next-year button of the month view.
+     * @default 'Next year'
+     */
+    nextYear?: string;
+    /** Name of the previous-decade button of the year view.
+     * @default 'Previous decade'
+     */
+    previousDecade?: string;
+    /** Name of the next-decade button of the year view.
+     * @default 'Next decade'
+     */
+    nextDecade?: string;
+    /** Description of the heading button that shows the month view.
+     * @default 'Choose a month'
+     */
+    chooseMonth?: string;
+    /** Description of the heading button that shows the year view.
+     * @default 'Choose a year'
+     */
+    chooseYear?: string;
+    /** Name of the "Go to today" button.
+     * @default 'Go to today'
+     */
+    goToToday?: string;
+    /** Hidden text of the week-number column header.
+     * @default 'Week'
+     */
+    week?: string;
+    /** Name of a week-number row header.
+     * @default (week) => `Week ${week}`
+     */
+    weekNumber?: (week: number) => string;
+    /** Name of a marked day, built from its default name.
+     * @default (dayLabel) => `${dayLabel}, marked`
+     */
+    markedDay?: (dayLabel: string) => string;
+    /**
+     * Said in the calendar's description while it is required (`required`, a required Field, or a
+     * consumer `aria-required` alone), since its role cannot carry `aria-required`.
+     * @default 'Required'
+     */
+    required?: string;
+}
+
+/** Properties for the Calendar component. */
+export declare interface CalendarProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
+    /** Controlled selected day (`null` for none). */
+    value?: Date | null;
+    /**
+     * Initial selected day for uncontrolled usage.
+     * @default null
+     */
+    defaultValue?: Date | null;
+    /**
+     * Called with the new day (local midnight) when the selected day changes: a pick of another day
+     * or a form reset (Fluent's `onSelectDate` fires on every pick). Picking the selected day again
+     * does nothing. WaveUI always passes `details`.
+     */
+    onValueChange?: (date: Date | null, details?: CalendarValueChangeDetails) => void;
+    /** Earliest available day (the whole day is included). */
+    minDate?: Date;
+    /** Latest available day (the whole day is included). */
+    maxDate?: Date;
+    /** Returns `true` for days that cannot be picked (called with local-midnight dates). */
+    disabledDates?: (date: Date) => boolean;
+    /**
+     * First day of the week (0 = Sunday, 1 = Monday, etc.).
+     * @default 0
+     */
+    firstDayOfWeek?: DayOfWeek;
+    /**
+     * BCP 47 locale of the month text, the weekday names and the day labels. Pass it when rendering
+     * on the server, so the server and the browser render the same text. The grid is Gregorian, as
+     * in DatePicker. A tag `Intl` rejects (the POSIX `de_DE`, a typo) falls back to the runtime
+     * default locale (development warning).
+     * @default the runtime default locale
+     */
+    locale?: string;
+    /**
+     * The day marked as today (`aria-current="date"`), and the tab stop when no day is selected in
+     * the shown month. Without it, the server HTML and the hydration render mark no day and the
+     * browser applies the current date once hydrated: pass it when rendering on the server, so the
+     * mark is in the HTML.
+     * @default the current date (applied after hydration when not passed)
+     */
+    today?: Date;
+    /**
+     * The month shown first when there is no value (Fluent's `initialPickerDate`), clamped into
+     * `minDate`/`maxDate` like the value's month and today's.
+     * @default today's month
+     */
+    initialVisibleDate?: Date;
+    /**
+     * Turns the month text into a button that shows the month view (the 12 months of the year),
+     * whose heading, the year, is a button to the year view (a decade with the year before and
+     * after it). A picked year shows its months and a picked month its days; Escape goes back a
+     * level to the period shown before. Fluent's `isMonthPickerVisible`, here as a drill-down in one
+     * pane.
+     * @default true
+     */
+    showMonthPicker?: boolean;
+    /**
+     * Adds a leading column of week numbers: a row header per week (`Week 23`, from
+     * `labels.weekNumber`) under a header cell named `labels.week`. The numbers follow
+     * `firstDayOfWeek` and `firstWeekOfYear`; the column is not focusable and the keys skip it.
+     * @default false
+     */
+    showWeekNumbers?: boolean;
+    /**
+     * Which week is week 1 of a year. ISO 8601 is `'first-four-day-week'` with `firstDayOfWeek={1}`.
+     * @default 'first-day'
+     */
+    firstWeekOfYear?: FirstWeekOfYear;
+    /**
+     * Adds a footer button that shows today's month in the day view and focuses today without
+     * selecting it. It is disabled while today is outside `minDate`/`maxDate`.
+     * @default false
+     */
+    showGoToToday?: boolean;
+    /**
+     * Days that draw a dot under the number (in the text colour of the day) and say "marked" in
+     * their name (`labels.markedDay`); also `data-marked` on the day's button (Fluent's
+     * `getMarkedDays`). Called with local-midnight dates.
+     */
+    markedDates?: (date: Date) => boolean;
+    /**
+     * Replaces the content inside a day's button, which keeps its role, state and keys;
+     * `defaultContent` is the day number. The content must be non-interactive (no buttons or links),
+     * and the button's name does not follow it: set the name with `dayLabel`. The marked-day dot is
+     * drawn next to the content.
+     */
+    renderDay?: (date: Date, defaultContent: React_2.ReactNode) => React_2.ReactNode;
+    /**
+     * The accessible name of a day, from its default name (the date in words, `Monday, June 2,
+     * 2025`, with `labels.markedDay` applied for a marked day). Use it to say what `renderDay` shows.
+     */
+    dayLabel?: (date: Date, defaultLabel: string) => string;
+    /**
+     * What a pick selects: the day, or its week, work week (`workWeekDays`) or month. The value is
+     * the picked day, `details.range` the selected days, and every day of the range is
+     * `aria-selected`, `aria-pressed` and `data-selected`. Days that are not available are left
+     * out. Fluent's `dateRangeType`.
+     * @default 'day'
+     */
+    selectionRange?: CalendarSelectionRange;
+    /**
+     * The days of `selectionRange="work-week"` (0 = Sunday), within the week that starts on
+     * `firstDayOfWeek`.
+     * @default [1, 2, 3, 4, 5]
+     */
+    workWeekDays?: readonly DayOfWeek[];
+    /**
+     * Names of the navigation buttons, the heading button's hints, the "Go to today" button, the
+     * week-number column, the marked days and the required hint, for localization.
+     */
+    labels?: CalendarLabels;
+    /** Form field name: the day is submitted as ISO `yyyy-mm-dd` (hidden input). */
+    name?: string;
+    /** Id of the `<form>` the value belongs to, when the calendar is outside it. */
+    form?: string;
+    /**
+     * Blocks form submission while no day is selected; the form's report focuses the calendar's
+     * tab stop. Said in the description (`labels.required`), as the group cannot carry
+     * `aria-required`. A consumer `aria-required` alone also shows that hint (assistive technology
+     * only: it does not block submission).
+     */
+    required?: boolean;
+    /** Ref to the root element. */
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
+/** What a pick selects (the Calendar's `selectionRange`). */
+export declare type CalendarSelectionRange = 'day' | 'week' | 'work-week' | 'month';
+
+/** Second argument of `Calendar`'s `onValueChange`. */
+export declare interface CalendarValueChangeDetails {
+    /**
+     * The selected days in order (local midnight): the picked day, or with `selectionRange` its
+     * week, work week or month (the days that are not available left out); `[]` for `null`.
+     */
+    range: Date[];
+}
+
 /**
  * A surface that groups related content, with `Card.Header`, `Card.Body` and `Card.Footer`.
  *
@@ -1279,6 +1577,21 @@ export declare type CheckedValuesChangeHandler = (checkedValues: Record<string,
  */
 export declare function cn(...inputs: ClassValue[]): string;
 
+/**
+ * Reads option labels from `children` during render (read-only), for display text before the
+ * options have registered: on the server, in the first client render and during hydration
+ * (layout effects have not run yet). Walks elements of components marked with
+ * {@link markListboxElement}: `'option'` elements give `value → label` (`label` prop →
+ * `textValue` → the text of their string/number children and host elements → `value` when they
+ * have no children); `'group'` elements and Fragments are walked into. Other components are
+ * opaque (their options resolve after registration). The first option of a value wins. A lazy
+ * element type (an option or group written in a React Server Component) is unwrapped first.
+ *
+ * Display text = `listbox.getItem(value)?.label ?? collectOptionLabels(children).get(value)`
+ * (`?? value` for freeform input only).
+ */
+export declare function collectOptionLabels(children: React_2.ReactNode): Map<string, string>;
+
 /**
  * A 2-D color field: saturation from left to right (mirrored in right-to-left layouts) and
  * brightness from bottom to top, at the value's hue. ArrowLeft and ArrowRight move saturation by
@@ -1772,6 +2085,71 @@ export declare interface ColorSliderProps extends Omit<React_2.HTMLAttributes<HT
     ref?: React_2.Ref<HTMLDivElement>;
 }
 
+/**
+ * One color swatch of a `SwatchPicker`, read from `items` or rendered directly as a child.
+ * Outside a `SwatchPicker` it throws in development and renders inertly in production.
+ *
+ * **Naming**: give it `aria-label`, or wrap it in a `Tooltip` with `relationship="label"` (its
+ * `aria-labelledby` reaches this element, since every rest prop lands on the swatch's own
+ * button). Without either it is named by its `color` value and a development warning is logged.
+ *
+ * **Disabled**: `disabled` is native (out of the arrow keys and the tab order, never selected);
+ * the swatch is dimmed and crossed by a diagonal slash, so the state does not rely on its color.
+ *
+ * @example
+ * <SwatchPicker aria-label="Accent color">
+ *   <ColorSwatch value="red" color="#d13438" aria-label="Red" />
+ * </SwatchPicker>
+ */
+export declare const ColorSwatch: {
+    ({ color, borderColor, ...rest }: ColorSwatchProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * ColorSwatch (also the swatches of SwatchPicker's `items`; carries SwatchPicker's `swatch`):
+ * `root` on the swatch `<button>`, where `className` lands in every layout; `icon` on the span of
+ * your `icon`.
+ */
+export declare const colorSwatchClassNames: {
+    readonly root: "wave-color-swatch";
+    readonly icon: "wave-color-swatch__icon";
+};
+
+/** Properties for the ColorSwatch component. */
+export declare interface ColorSwatchProps extends Omit<React_2.ButtonHTMLAttributes<HTMLButtonElement>, 'value' | 'color'> {
+    /** Unique identifier for the swatch (the value the picker selects and a form submits). */
+    value: string;
+    /** CSS color value (e.g., hex, rgb) used as the swatch background (a runtime user color). */
+    color: string;
+    /**
+     * Decorative glyph (`aria-hidden`) shown while the swatch is not selected; the check replaces it
+     * while selected. A `<button>` or `Button` passed here is not nested: its children become the
+     * glyph and a one-time development warning is logged.
+     */
+    icon?: Slot<'span'>;
+    /**
+     * CSS color of the swatch's border, for a color close to the page background (set by hand, as
+     * in Fluent). In forced colors the system border color replaces it.
+     */
+    borderColor?: string;
+    /**
+     * Size of the swatch (20, 24, 32 or 40px).
+     * @default the picker's
+     */
+    size?: SwatchPickerSize;
+    /**
+     * Shape of the swatch.
+     * @default the picker's
+     */
+    shape?: Shape;
+    /**
+     * Ref to the swatch button: `role="radio"` in the row layout, inside its cell in the grid
+     * layout, a toggle button in tab mode.
+     */
+    ref?: React_2.Ref<HTMLButtonElement>;
+}
+
 /**
  * An editable combobox: a text input with a filterable listbox of `Option`s (APG combobox with
  * list autocomplete). Typing filters the options; ArrowDown/ArrowUp move the highlight
@@ -1779,9 +2157,27 @@ export declare interface ColorSliderProps extends Omit<React_2.HTMLAttributes<HT
  * filter: its first match becomes active while typing, and the input shows the selected option's
  * label again when the listbox closes. With `freeform` the text itself is the value. Text that
  * matches no option shows "No matches" (`labels.noMatches`), announced through a status region.
- * The expand button at the end of the input (a chevron, see `expandIcon`) opens and closes the
- * list without taking focus from the input and is not a tab stop; `clearable` adds a clear button,
- * a tab stop after the input. Both sit with the input in a wrapper `<div>` inside the root.
+ * `filter` replaces the match (it may keep options that do not contain the text, for a server-side
+ * search or a "Create …" entry), and `query`/`defaultQuery`/`onQueryChange` control the typed
+ * text (not with `freeform`), which resets to `''` on a commit, a close, a blur, Escape, the clear
+ * button and a form reset. The expand button at the end of the input (a chevron, see
+ * `expandIcon`) opens and closes the list without taking focus from the input and is not a tab
+ * stop; `clearable` adds a clear button, a tab stop after the input. Both sit with the input in a
+ * wrapper `<div>` inside the root.
+ *
+ * `multiselect` turns the value into an array (Fluent's `selectedOptions`): options draw a
+ * checkbox; Enter and a click toggle an option and keep the list open (Tab, Escape and
+ * Alt+ArrowUp close without committing), and every toggle the user makes is announced
+ * (`labels.added`/`labels.removed`, never for a controlled change, a clear or a form reset).
+ * While no text is typed the input shows the selected labels in selection order
+ * (`labels.selection`, values without an option left out) instead of the placeholder. Focusing
+ * the input selects them, and so does their return to the focused input (a toggle, a close, a
+ * form reset), so typing, pasting or composing text replaces them with a query that filters the
+ * options; text inserted into them queries only what was inserted, an undo or a redo back to them
+ * shows them again, and a toggle, a close or a blur clears the query. Backspace and Delete only
+ * edit the text: the options, the clear button (which clears every value) and a form reset change
+ * the value. `freeform` is not available with `multiselect`, and a non-literal
+ * `multiselect={flag}` is a type error: render two elements, one for each mode.
  *
  * The `<input>` receives `id`, `aria-label`, `aria-labelledby`, `aria-describedby`,
  * `aria-invalid`, `aria-required`, `aria-errormessage`, `aria-details`, `tabIndex`, `autoFocus`,
@@ -1790,8 +2186,10 @@ export declare interface ColorSliderProps extends Omit<React_2.HTMLAttributes<HT
  * `ref`, `className`, `style`, other `aria-*` attributes and the remaining props stay on the root
  * `<div>`. Inside a `Field` the input is labelled and described by it. It shows the error look
  * whenever it ends up `aria-invalid` (its own `aria-invalid` or a `Field` error). With
- * `name`/`required` the value takes part in form submission, validation and reset. The open
- * listbox renders in a portal; while closed it stays in the DOM, hidden.
+ * `name`/`required` the value takes part in form submission (one hidden input per value with
+ * `multiselect`), validation and reset (a `multiselect` reset is compared by content, so restoring
+ * the same values reports nothing). The open listbox renders in a portal; while closed it stays
+ * in the DOM, hidden.
  *
  * **Size and appearance**: `size` resolves from its own prop, then the surrounding `Field`'s
  * `size`, then `WaveProvider inputDefaults.size`, else `'medium'`; `appearance` from its own prop,
@@ -1801,13 +2199,7 @@ export declare interface ColorSliderProps extends Omit<React_2.HTMLAttributes<HT
  * Sub-components: `Combobox.Option`, `Combobox.OptionGroup`. React Server Components import the
  * flat names `ComboboxOption` / `ComboboxOptionGroup` (dotted access needs a client file).
  */
-export declare const Combobox: {
-    (props: ComboboxProps): React_2.JSX.Element;
-    displayName: string;
-} & {
-    Option: React_2.NamedExoticComponent<OptionProps>;
-    OptionGroup: React_2.FC<OptionGroupProps>;
-};
+export declare const Combobox: ComboboxComponent;
 
 /**
  * Combobox: `root` on the outer element; `input` on the `role="combobox"` input; `clearButton` on
@@ -1826,6 +2218,17 @@ export declare const comboboxClassNames: {
     readonly emptyMessage: "wave-combobox__empty-message";
 };
 
+/** The Combobox component's type: a multi-select signature, then the single-select one. */
+export declare interface ComboboxComponent {
+    (props: ComboboxProps<true> & {
+        multiselect: true;
+    }): React_2.ReactNode;
+    (props: ComboboxProps): React_2.ReactNode;
+    displayName?: string;
+    Option: typeof Option_2;
+    OptionGroup: typeof OptionGroup;
+}
+
 /**
  * The Combobox's built-in texts, for localization. Each member is optional and falls back to its
  * English default.
@@ -1843,6 +2246,24 @@ export declare interface ComboboxLabels {
      * @default 'Show options'
      */
     expand?: string;
+    /**
+     * The text of the selected labels the input shows with `multiselect` while no text is typed, in
+     * selection order; values without an option are left out.
+     * @default (labels) => labels.join(', ')
+     */
+    selection?: (labels: string[]) => string;
+    /**
+     * Announced when a `multiselect` toggle selects an option; `count` is the number of values
+     * selected after the change.
+     * @default (label, count) => `${label} added, ${count} selected`
+     */
+    added?: (label: string, count: number) => string;
+    /**
+     * Announced when a `multiselect` toggle deselects an option; `count` is the number of values
+     * selected after the change.
+     * @default (label, count) => `${label} removed, ${count} selected`
+     */
+    removed?: (label: string, count: number) => string;
 }
 
 /** Flat name of `Combobox.Option` for React Server Components. */
@@ -1852,22 +2273,38 @@ export declare const ComboboxOption: React_2.NamedExoticComponent<OptionProps>;
 export declare const ComboboxOptionGroup: React_2.FC<OptionGroupProps>;
 
 /** Properties for the Combobox component. */
-export declare interface ComboboxProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue' | RoutedHandlers> {
-    /** Controlled selected value (`''` for none). */
-    value?: string;
+export declare interface ComboboxProps<M extends boolean = false> extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue' | RoutedHandlers> {
+    /**
+     * Several options can be selected (Fluent's `multiselect`): the value is an array, options show
+     * a checkbox, Enter and a click toggle an option and keep the list open, and each toggle is
+     * announced. While no text is typed the input shows the selected labels, selected whenever the
+     * input gains focus or they return to it, so typing replaces them with text that filters the
+     * options. Not available with `freeform`. A non-literal `multiselect={flag}` is a type error:
+     * render two elements, one for each mode.
+     * @default false
+     */
+    multiselect?: M;
+    /**
+     * Controlled selected value (`''` for none), or with `multiselect` the selected values (Fluent's
+     * `selectedOptions`).
+     */
+    value?: M extends true ? readonly string[] : string;
     /**
      * Initial selected value for uncontrolled usage.
-     * @default ''
+     * @default '' (`[]` with `multiselect`)
      */
-    defaultValue?: string;
+    defaultValue?: M extends true ? readonly string[] : string;
     /**
-     * Called with the new value when it changes: an option is selected, or (with `freeform`) the
-     * text changes. Not called when the current option is selected again.
+     * Called with the new value when it changes: an option is selected (toggled with `multiselect`,
+     * which passes a new array), or (with `freeform`) the text changes. Without `multiselect` it is
+     * not called when the current option is selected again; with it, activating a selected option
+     * deselects it, which is a change. Fluent's `onOptionSelect`, under WaveUI's value/onValueChange
+     * naming.
      */
-    onValueChange?: (value: string) => void;
+    onValueChange?: M extends true ? (value: string[]) => void : (value: string) => void;
     /**
-     * Called on every option activation, also when the current option is selected again (and, with
-     * `freeform`, on every text change).
+     * Called on every option activation, also when the current option is selected again (every
+     * toggle with `multiselect`; with `freeform`, every text change).
      * @deprecated Use `onValueChange`.
      */
     onOptionSelect?: (value: string) => void;
@@ -1885,7 +2322,10 @@ export declare interface ComboboxProps extends Omit<React_2.HTMLAttributes<HTMLD
     defaultOpen?: boolean;
     /** Called when the listbox opens or closes. */
     onOpenChange?: (open: boolean) => void;
-    /** Placeholder text shown when no value is selected. */
+    /**
+     * Placeholder text shown when no value is selected; with `multiselect`, whenever the input shows
+     * no selected labels (no value is selected, or no selected value has an option).
+     */
     placeholder?: string;
     /**
      * Whether the combobox is disabled and non-interactive.
@@ -1909,11 +2349,64 @@ export declare interface ComboboxProps extends Omit<React_2.HTMLAttributes<HTMLD
      * first match becomes active, so Enter selects it) and the input shows the selected option's
      * label again when the listbox closes or loses focus. With it, the input shows typed text as
      * typed (also when it equals an option's value), a selected option's label, and a controlled
-     * `value` as soon as the parent sets it (a parent that normalizes or rejects the text).
+     * `value` as soon as the parent sets it (a parent that normalizes or rejects the text). Not
+     * available with `multiselect` (a type error there): free text cannot be one of several values.
+     * @default false
+     */
+    freeform?: M extends true ? never : boolean;
+    /**
+     * Whether an option matches the typed text (the query, or with `freeform` the typed value).
+     * Called with every option that is not hidden (its `value`, `label` and `textValue`) and the
+     * text whenever the text is not empty; an option it returns `false` for is filtered out. It may
+     * keep options that do not contain the text: `filter={() => true}` with `query` and
+     * `onQueryChange` leaves the matching to you (a server-side search that replaces the options),
+     * and a filter that always keeps an option of your own gives a "Create …" entry. With a
+     * server-side search, keep the selected option among the children, `hidden` while the results
+     * leave it out: a value without an option shows no label (the "Async search" story does this).
+     * @default a case-insensitive substring match on the option's `textValue`, else its `label`
+     */
+    filter?: (option: ListboxItem, query: string) => boolean;
+    /**
+     * Controlled query: the text typed since the last commit, which filters the options. A
+     * non-empty query shows in the input (hidden while `disabled` or `readOnly`); `''` shows the
+     * selected option's label (the selected labels with `multiselect`), except while the user edits
+     * the text, so erased text stays empty. Not used with `freeform`, where the typed text is the
+     * value.
+     */
+    query?: string;
+    /**
+     * Initial query for uncontrolled usage. A Combobox that starts disabled or read-only starts
+     * without it (as it starts closed). Not used with `freeform`.
+     * @default ''
+     */
+    defaultQuery?: string;
+    /**
+     * Called with the new query when it changes: as the user types, and with `''` when it resets (a
+     * commit, a close, a blur, Escape, the clear button, a form reset, or `disabled` or `readOnly`
+     * turned on while text is typed). A Combobox that mounts disabled or read-only reports nothing:
+     * it keeps a controlled query, which shows once it unlocks. Never called with `freeform`.
+     */
+    onQueryChange?: (query: string) => void;
+    /**
+     * Called after the active (highlighted) option changes — opening, arrow keys, the pointer, a
+     * filter change that moves it — and with `null` when the list closes. It reports what
+     * `aria-activedescendant` points at, from an effect once the change commits. Fluent's
+     * `onActiveOptionChange` reports neither the pointer (its options have no hover highlight) nor
+     * the close.
+     */
+    onActiveOptionChange?: (value: string | null) => void;
+    /**
+     * Keeps disabled options in the arrow-key order (the first match highlighted while typing may
+     * then be a disabled one too); they still cannot be selected (Enter and a click do nothing and
+     * the list stays open). Unlike Fluent, which always keeps disabled options reachable, WaveUI
+     * skips them by default.
      * @default false
      */
-    freeform?: boolean;
-    /** Name of the value in form submissions (renders a hidden input). */
+    disabledOptionsFocusable?: boolean;
+    /**
+     * Name of the value in form submissions (renders a hidden input; one per value with
+     * `multiselect`).
+     */
     name?: string;
     /** Id of the form the value belongs to, when the Combobox is outside it. */
     form?: string;
@@ -1928,7 +2421,11 @@ export declare interface ComboboxProps extends Omit<React_2.HTMLAttributes<HTMLD
      * @default 'off'
      */
     autoComplete?: string;
-    /** The maximum length of the typed text (`maxlength` of the `<input role="combobox">`). */
+    /**
+     * The maximum length of the typed text (`maxlength` of the `<input role="combobox">`). With
+     * `multiselect` the input has no limit while it shows the selected labels, so the limit applies
+     * to the typed query only.
+     */
     maxLength?: number;
     /**
      * The value cannot be changed: the input is read-only and the listbox neither opens (click,
@@ -1939,8 +2436,8 @@ export declare interface ComboboxProps extends Omit<React_2.HTMLAttributes<HTMLD
     /**
      * Shows a clear button while a value is selected (not while `readOnly`; while `disabled` it is
      * shown disabled, as in DatePicker and TimePicker). It clears the value
-     * (`onValueChange('')`), drops typed text, closes the list and moves focus to the input. It is
-     * a tab stop after the input.
+     * (`onValueChange('')`; every value with `multiselect`, `onValueChange([])`), drops typed text,
+     * closes the list and moves focus to the input. It is a tab stop after the input.
      * @default false
      */
     clearable?: boolean;
@@ -1954,11 +2451,16 @@ export declare interface ComboboxProps extends Omit<React_2.HTMLAttributes<HTMLD
      */
     expandIcon?: Slot<'span'>;
     /**
-     * The built-in texts (the "No matches" status and the names of the clear and expand buttons),
-     * for localization. Unset members keep their English defaults.
+     * The built-in texts (the "No matches" status, the names of the clear and expand buttons and,
+     * with `multiselect`, the selected-labels text and the toggle announcements), for localization.
+     * Unset members keep their English defaults.
      */
     labels?: ComboboxLabels;
-    /** Called when the `<input role="combobox">` receives focus (the root keeps other handlers). */
+    /**
+     * Called when the `<input role="combobox">` receives focus (the root keeps other handlers).
+     * With `multiselect`, a focus while the input shows the selected labels then selects them;
+     * `event.preventDefault()` skips that.
+     */
     onFocus?: React_2.FocusEventHandler<HTMLInputElement>;
     /** Called when the `<input role="combobox">` loses focus. */
     onBlur?: React_2.FocusEventHandler<HTMLInputElement>;
@@ -2547,9 +3049,14 @@ export declare interface DataGridUncontrolledSortProps extends NoDeprecatedSortP
  *   modal dialog labelled by the month heading. Focus moves to the selected day (else today, else
  *   the first available day of the month) and Tab stays inside. Arrow keys move by day/week
  *   (mirrored in RTL), PageUp/PageDown by month, Shift+PageUp/PageDown by year (the day is clamped
- *   to the month), Home/End to the start/end of the week, Enter/Space select. Escape closes and
- *   returns focus to where the calendar was opened from (the toggle, or the input after
- *   Alt+ArrowDown); a press outside closes it too. Unavailable days stay focusable
+ *   to the month), Home/End to the start/end of the week, Enter/Space select. The month text is a
+ *   button (the heading button, `showMonthPicker`) that shows the month view, whose heading, the
+ *   year, leads to the year view; Escape steps back from the year view to the month view and from
+ *   there to the days, and closes only from the day view, returning focus to where the calendar
+ *   was opened from (the toggle, or the input after Alt+ArrowDown); a press outside closes it too.
+ *   `showCloseButton` adds a Close button that closes as Escape does from the day view, and
+ *   `showGoToToday` a button that shows today's month. `showWeekNumbers`, `markedDates`,
+ *   `renderDay` and `dayLabel` shape the day grid as in `Calendar`. Unavailable days stay focusable
  *   (`aria-disabled`); a day focused by pointer becomes the starting point of the arrow keys. The
  *   selected day is `aria-selected` on its gridcell and `aria-pressed` on its focusable button, so
  *   the state is announced when focus lands on it; today is `aria-current="date"`.
@@ -2586,9 +3093,15 @@ export declare const DatePicker: {
  * DatePicker: `root` on the outer element; `input` on the text input; `clearButton` on the clear
  * button; `openCalendarButton` on the calendar button; `errorMessage` on the `role="alert"`
  * message; `surface` on the portaled `role="dialog"` calendar; `header` on its month row;
- * `previousMonthButton` and `nextMonthButton` on the month buttons; `heading` on the month
- * `<h2>`; `grid` on the calendar's `role="grid"` element; `weekday` on each weekday header cell;
- * `day` on each day button.
+ * `previousMonthButton` and `nextMonthButton` on the navigation buttons (by a month, and in the
+ * month and year views by a year and a decade); `heading` on the `<h2>` (the month, year or
+ * decade); `headingButton` on its button to the month and year views; `grid` on the calendar's
+ * `role="grid"` element of every view; `weekday` on each weekday header cell; `weekNumberHeader`
+ * on the header cell of the week-number column and `weekNumber` on each week's row header
+ * (`showWeekNumbers`); `day`, `month` and `year` on each day, month and year button; `markedDot`
+ * on the dot inside a marked day's button; `footer` on the row of the footer buttons
+ * (`showGoToToday`, `showCloseButton`), with `todayButton` on "Go to today" and `closeButton` on
+ * "Close".
  */
 export declare const datePickerClassNames: {
     readonly root: "wave-date-picker";
@@ -2600,21 +3113,33 @@ export declare const datePickerClassNames: {
     readonly header: "wave-date-picker__header";
     readonly previousMonthButton: "wave-date-picker__previous-month-button";
     readonly heading: "wave-date-picker__heading";
+    readonly headingButton: "wave-date-picker__heading-button";
     readonly nextMonthButton: "wave-date-picker__next-month-button";
     readonly grid: "wave-date-picker__grid";
     readonly weekday: "wave-date-picker__weekday";
+    readonly weekNumberHeader: "wave-date-picker__week-number-header";
+    readonly weekNumber: "wave-date-picker__week-number";
     readonly day: "wave-date-picker__day";
+    readonly markedDot: "wave-date-picker__marked-dot";
+    readonly month: "wave-date-picker__month";
+    readonly year: "wave-date-picker__year";
+    readonly footer: "wave-date-picker__footer";
+    readonly todayButton: "wave-date-picker__today-button";
+    readonly closeButton: "wave-date-picker__close-button";
 };
 
 /** Why typed text was not accepted (see {@link DatePickerProps.onInvalidInput}). */
 export declare type DatePickerInvalidReason = 'unparseable' | 'out-of-range' | 'disabled';
 
 /**
- * The DatePicker's built-in button names and error texts, for localization. Each member is
+ * The DatePicker's built-in button names and error texts, for localization: its own (clear, open
+ * calendar, the errors of typed text, Close) and those of the calendar in its dialog
+ * ({@link CalendarLabels}: the navigation buttons, the heading button's hints, "Go to today", the
+ * week-number column and the marked days; its `required` hint does not apply). Each member is
  * optional and falls back to its English default. Month and weekday names and the day labels
  * follow `locale`.
  */
-export declare interface DatePickerLabels {
+export declare interface DatePickerLabels extends CalendarLabels {
     /** Name of the clear button.
      * @default 'Clear date'
      */
@@ -2623,14 +3148,10 @@ export declare interface DatePickerLabels {
      * @default 'Open calendar'
      */
     openCalendar?: string;
-    /** Name of the calendar's previous-month button.
-     * @default 'Previous month'
-     */
-    previousMonth?: string;
-    /** Name of the calendar's next-month button.
-     * @default 'Next month'
+    /** Name of the footer button that closes the calendar (`showCloseButton`).
+     * @default 'Close'
      */
-    nextMonth?: string;
+    close?: string;
     /**
      * Error text for typed text that is not a date. `pattern` is the default format of `locale`
      * written with English field letters (`'MM/DD/YYYY'`, `'DD.MM.YYYY'`), or `undefined` with a
@@ -2733,7 +3254,63 @@ export declare interface DatePickerProps extends Omit<React_2.HTMLAttributes<HTM
      * First day of the week (0 = Sunday, 1 = Monday, etc.).
      * @default 0
      */
-    firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    firstDayOfWeek?: DayOfWeek;
+    /**
+     * The day marked as today in the calendar (`aria-current="date"`) and the start of its keys when
+     * no day is selected. See `Calendar`'s `today`.
+     * @default the current date
+     */
+    today?: Date;
+    /**
+     * The month the calendar shows first when there is no value, clamped into `minDate`/`maxDate`.
+     * @default today's month
+     */
+    initialVisibleDate?: Date;
+    /**
+     * Turns the calendar's month text into a button that shows the month view, whose heading, the
+     * year, is a button to the year view. Escape steps back from the year view to the month view
+     * and from there to the days; it closes the calendar only from the day view.
+     * @default true
+     */
+    showMonthPicker?: boolean;
+    /**
+     * Adds a leading column of week numbers to the calendar.
+     * @default false
+     */
+    showWeekNumbers?: boolean;
+    /**
+     * Which week is week 1 of a year. ISO 8601 is `'first-four-day-week'` with `firstDayOfWeek={1}`.
+     * @default 'first-day'
+     */
+    firstWeekOfYear?: FirstWeekOfYear;
+    /**
+     * Adds a "Go to today" button to the calendar's footer: it shows today's month and focuses
+     * today without selecting it, and is disabled while today is outside `minDate`/`maxDate`.
+     * @default false
+     */
+    showGoToToday?: boolean;
+    /**
+     * Adds a Close button to the calendar's footer; it closes the calendar as Escape does from the
+     * day view (focus returns to the toggle, or to the input after Alt+ArrowDown).
+     * @default false
+     */
+    showCloseButton?: boolean;
+    /**
+     * Days that draw a dot and say "marked" in their name in the calendar (`labels.markedDay`).
+     * Called with local-midnight dates.
+     */
+    markedDates?: (date: Date) => boolean;
+    /**
+     * Replaces the content inside a calendar day's button; `defaultContent` is the day number. The
+     * content must be non-interactive, and the button's name does not follow it: set the name with
+     * `dayLabel`.
+     */
+    renderDay?: (date: Date, defaultContent: React_2.ReactNode) => React_2.ReactNode;
+    /**
+     * The accessible name of a calendar day, from its default name (the date in words, with
+     * `labels.markedDay` applied for a marked day).
+     */
+    dayLabel?: (date: Date, defaultLabel: string) => string;
     /**
      * Controlled open state of the calendar. The calendar renders only in the browser: an open
      * picker is closed in the server HTML and opens once it has hydrated.
@@ -2786,6 +3363,9 @@ export declare interface DatePickerProps extends Omit<React_2.HTMLAttributes<HTM
     ref?: React_2.Ref<HTMLDivElement>;
 }
 
+/** 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;
+
 /**
  * A modal dialog (Fluent UI v2 style): `Dialog` holds the open state; `Dialog.Trigger` opens it and
  * `Dialog.Content` renders the surface in a portal while open.
@@ -3092,6 +3672,9 @@ export declare interface DialogTriggerRenderProps extends React_2.HTMLAttributes
     ref: React_2.RefCallback<HTMLElement>;
 }
 
+/** 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';
+
 /**
  * A line that separates content, horizontally or vertically, optionally with a label in the middle.
  *
@@ -3402,8 +3985,18 @@ export declare interface DrawerTriggerRenderProps extends React_2.HTMLAttributes
  * A select-only combobox (APG): a button that opens a listbox of `Option`s. Enter, Space,
  * ArrowDown/ArrowUp, Home/End and typing a character open it and move the highlight
  * (`aria-activedescendant`); Enter/Space select, Tab selects the highlighted option and moves on,
- * Escape closes. `clearable` adds a clear button, a tab stop after the combobox button; both sit
- * in a wrapper `<div>` inside the root.
+ * Escape closes. The button's chevron (see `expandIcon`) turns while the list is open, and
+ * `renderValue` replaces its content while a value is selected. `clearable` adds a clear button,
+ * a tab stop after the combobox button; both sit in a wrapper `<div>` inside the root.
+ *
+ * `multiselect` turns the value into an array (Fluent's `selectedOptions`): options draw a
+ * checkbox; Enter and Space toggle the highlighted option, a click toggles the clicked option, and
+ * the list stays open (Tab, Escape and Alt+ArrowUp close without committing); the button shows the
+ * selected labels in selection order (`labels.selection`, replacing the placeholder while any are
+ * selected, values without an option left out) and every toggle the user makes is announced
+ * (`labels.added`/`labels.removed`, never for a controlled change, a clear or a form reset).
+ * `clearable` then clears every value. A non-literal `multiselect={flag}` is a type error: render
+ * two elements, one for each mode.
  *
  * The `<button>` receives `id`, `aria-label`, `aria-labelledby`, `aria-describedby`,
  * `aria-invalid`, `aria-required`, `aria-errormessage`, `aria-details`, `tabIndex`, `autoFocus`
@@ -3411,8 +4004,10 @@ export declare interface DrawerTriggerRenderProps extends React_2.HTMLAttributes
  * attributes and the remaining props stay on the root `<div>`. Inside a `Field` the button is
  * labelled and described by it — otherwise give it an `aria-label`. It shows the error look
  * whenever it ends up `aria-invalid` (its own `aria-invalid` or a `Field` error). With
- * `name`/`required` the value takes part in form submission, validation and reset. The open
- * listbox renders in a portal; while closed it stays in the DOM, hidden.
+ * `name`/`required` the value takes part in form submission (one hidden input per value with
+ * `multiselect`), validation and reset (a `multiselect` reset is compared by content, so restoring
+ * the same values reports nothing). The open listbox renders in a portal; while closed it stays
+ * in the DOM, hidden.
  *
  * **Size and appearance**: `size` resolves from its own prop, then the surrounding `Field`'s
  * `size`, then `WaveProvider inputDefaults.size`, else `'medium'`; `appearance` from its own prop,
@@ -3422,13 +4017,7 @@ export declare interface DrawerTriggerRenderProps extends React_2.HTMLAttributes
  * Sub-components: `Dropdown.Option`, `Dropdown.OptionGroup`. React Server Components import the
  * flat names `DropdownOption` / `DropdownOptionGroup` (dotted access needs a client file).
  */
-export declare const Dropdown: {
-    (props: DropdownProps): React_2.JSX.Element;
-    displayName: string;
-} & {
-    Option: React_2.NamedExoticComponent<OptionProps>;
-    OptionGroup: React_2.FC<OptionGroupProps>;
-};
+export declare const Dropdown: DropdownComponent;
 
 /**
  * Dropdown: `root` on the outer element; `button` on the `role="combobox"` button; `value` on the
@@ -3445,6 +4034,17 @@ export declare const dropdownClassNames: {
     readonly surface: "wave-dropdown__surface";
 };
 
+/** The Dropdown component's type: a multi-select signature, then the single-select one. */
+export declare interface DropdownComponent {
+    (props: DropdownProps<true> & {
+        multiselect: true;
+    }): React_2.ReactNode;
+    (props: DropdownProps): React_2.ReactNode;
+    displayName?: string;
+    Option: typeof Option_2;
+    OptionGroup: typeof OptionGroup;
+}
+
 /**
  * The Dropdown's built-in texts, for localization. Each member is optional and falls back to its
  * English default.
@@ -3454,6 +4054,24 @@ export declare interface DropdownLabels {
      * @default 'Clear selection'
      */
     clear?: string;
+    /**
+     * The text of the selected labels shown in the combobox with `multiselect`, in selection order;
+     * values without an option are left out. Replaces the button's joined value text.
+     * @default (labels) => labels.join(', ')
+     */
+    selection?: (labels: string[]) => string;
+    /**
+     * Announced when a `multiselect` toggle selects an option; `count` is the number of values
+     * selected after the change.
+     * @default (label, count) => `${label} added, ${count} selected`
+     */
+    added?: (label: string, count: number) => string;
+    /**
+     * Announced when a `multiselect` toggle deselects an option; `count` is the number of values
+     * selected after the change.
+     * @default (label, count) => `${label} removed, ${count} selected`
+     */
+    removed?: (label: string, count: number) => string;
 }
 
 /** Flat name of `Dropdown.Option` for React Server Components. */
@@ -3463,18 +4081,33 @@ export declare const DropdownOption: React_2.NamedExoticComponent<OptionProps>;
 export declare const DropdownOptionGroup: React_2.FC<OptionGroupProps>;
 
 /** Properties for the Dropdown component. */
-export declare interface DropdownProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue' | RoutedHandlers> {
-    /** Controlled selected value (`''` for none). */
-    value?: string;
+export declare interface DropdownProps<M extends boolean = false> extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue' | RoutedHandlers> {
+    /**
+     * Several options can be selected (Fluent's `multiselect`): the value is an array, options show
+     * a checkbox, Enter and Space toggle the highlighted option, a click toggles the clicked
+     * option, the list stays open, and each toggle is announced. A non-literal `multiselect={flag}`
+     * is a type error: render two elements, one for each mode.
+     * @default false
+     */
+    multiselect?: M;
+    /**
+     * Controlled selected value (`''` for none), or with `multiselect` the selected values (Fluent's
+     * `selectedOptions`).
+     */
+    value?: M extends true ? readonly string[] : string;
     /**
      * Initial selected value for uncontrolled usage.
-     * @default ''
+     * @default '' (`[]` with `multiselect`)
      */
-    defaultValue?: string;
-    /** Called with the new value when a different option is selected. */
-    onValueChange?: (value: string) => void;
+    defaultValue?: M extends true ? readonly string[] : string;
+    /**
+     * Called with the new value when it changes (a new array with `multiselect`; Fluent's
+     * `onOptionSelect`, under WaveUI's value/onValueChange naming).
+     */
+    onValueChange?: M extends true ? (value: string[]) => void : (value: string) => void;
     /**
-     * Called on every option activation, also when the current option is selected again.
+     * Called on every option activation, also when the current option is selected again (every
+     * toggle with `multiselect`).
      * @deprecated Use `onValueChange`.
      */
     onOptionSelect?: (value: string) => void;
@@ -3492,12 +4125,36 @@ export declare interface DropdownProps extends Omit<React_2.HTMLAttributes<HTMLD
     defaultOpen?: boolean;
     /** Called when the listbox opens or closes. */
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Called after the active (highlighted) option changes — opening, arrow keys, typeahead, the
+     * pointer — and with `null` when the list closes. It reports what `aria-activedescendant` points
+     * at, from an effect once the change commits. Fluent's `onActiveOptionChange` reports neither the
+     * pointer (its options have no hover highlight) nor the close.
+     */
+    onActiveOptionChange?: (value: string | null) => void;
+    /**
+     * Keeps disabled options in the arrow-key, Home/End, PageUp/PageDown and typeahead order (the
+     * highlighted-by-default option may then be a disabled one too); they still cannot be selected
+     * (Enter, Space and a click do nothing and the list stays open), and in single-select mode,
+     * reaching one with Tab or Alt+ArrowUp closes the list without selecting it. Unlike Fluent,
+     * which always keeps disabled options reachable, WaveUI skips them by default.
+     * @default false
+     */
+    disabledOptionsFocusable?: boolean;
     /**
      * Placeholder text shown when no value is selected. It is not an accessible name: label the
      * Dropdown with a `Field`, `aria-label` or `aria-labelledby`.
      * @default 'Select an option'
      */
     placeholder?: string;
+    /**
+     * Renders the button's content while a value is selected (the placeholder shows otherwise), in
+     * place of the selected label (`labels.selection` with `multiselect`). It receives the raw
+     * value(s), never a label; the content must be non-interactive, and its text is the combobox's
+     * value, so image-only content leaves the value empty.
+     * @default the selected label (`labels.selection` with `multiselect`)
+     */
+    renderValue?: M extends true ? (value: string[]) => React_2.ReactNode : (value: string) => React_2.ReactNode;
     /**
      * Whether the dropdown is disabled and non-interactive. Turning it on while the listbox is open
      * closes it (`onOpenChange(false)`).
@@ -3507,7 +4164,7 @@ export declare interface DropdownProps extends Omit<React_2.HTMLAttributes<HTMLD
     /**
      * Size of the field: `small` (24px tall), `medium` (32px) or `large` (40px). Default: the
      * surrounding Field's `size`, else `WaveProvider inputDefaults.size`, else `'medium'`. The
-     * listbox keeps its size.
+     * listbox keeps its size; the multi-select value text and clear button follow it.
      */
     size?: CoreSize;
     /**
@@ -3516,7 +4173,10 @@ export declare interface DropdownProps extends Omit<React_2.HTMLAttributes<HTMLD
      * label). Default: `WaveProvider inputDefaults.appearance`, else `'outline'`.
      */
     appearance?: InputAppearance;
-    /** Name of the value in form submissions (renders a hidden input). */
+    /**
+     * Name of the value in form submissions (renders a hidden input; one per value with
+     * `multiselect`).
+     */
     name?: string;
     /** Id of the form the value belongs to, when the Dropdown is outside it. */
     form?: string;
@@ -3524,11 +4184,23 @@ export declare interface DropdownProps extends Omit<React_2.HTMLAttributes<HTMLD
     required?: boolean;
     /**
      * Shows a clear button while a value is selected (shown disabled while `disabled`). It clears
-     * the value, closes the list and moves focus to the combobox button. It is a tab stop after it.
+     * the value (every value with `multiselect`), closes the list and moves focus to the combobox
+     * button. It is a tab stop after it.
      * @default false
      */
     clearable?: boolean;
-    /** The name of the clear button, for localization. Unset members keep their English defaults. */
+    /**
+     * The glyph at the end of the button (default: a chevron). `null` or `undefined` keep it;
+     * `false`, or a value that renders nothing, hides it (the button's end padding follows,
+     * together with `clearable`). The default chevron's size and the glyph's offset follow
+     * `size`. Decorative content rendered inside the button: a `<button>` or `Button` passed
+     * here is not nested (its children become the glyph, with a development warning).
+     */
+    expandIcon?: Slot<'span'>;
+    /**
+     * The clear button's name and, with `multiselect`, the selected-labels text and the toggle
+     * announcements, for localization. Unset members keep their English defaults.
+     */
     labels?: DropdownLabels;
     /** Called when the `<button role="combobox">` receives focus (the root keeps other handlers). */
     onFocus?: React_2.FocusEventHandler<HTMLButtonElement>;
@@ -3547,6 +4219,60 @@ export declare interface DropdownProps extends Omit<React_2.HTMLAttributes<HTMLD
     ref?: React_2.Ref<HTMLDivElement>;
 }
 
+/**
+ * An "add" button inside a `SwatchPicker` (for example to open a color dialog): it has no value
+ * and is never selected. In the row layout it is a plain button with its own tab stop, outside
+ * the radio group's arrow order, and arrow keys pressed on it do nothing. In the grid layout it
+ * is a cell like the others, in the arrow order (without `aria-selected`). Outside a
+ * `SwatchPicker` it throws in development and renders inertly in production.
+ *
+ * @example
+ * <SwatchPicker aria-label="Accent color" items={items}>
+ *   <EmptySwatch onClick={openColorDialog} />
+ * </SwatchPicker>
+ */
+export declare const EmptySwatch: {
+    ({ icon, size: sizeProp, shape: shapeProp, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ref, ...rest }: EmptySwatchProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * EmptySwatch (carries SwatchPicker's `swatch`): `root` on the `<button>`; `icon` on the span of
+ * its glyph (the plus, or your `icon`).
+ */
+export declare const emptySwatchClassNames: {
+    readonly root: "wave-empty-swatch";
+    readonly icon: "wave-empty-swatch__icon";
+};
+
+/** Properties for the EmptySwatch component. */
+export declare interface EmptySwatchProps extends React_2.ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Accessible name of the button.
+     * @default 'Add color'
+     */
+    'aria-label'?: string;
+    /**
+     * Decorative glyph (`aria-hidden`). `null` and `undefined` keep the plus glyph; `false` or
+     * anything that renders nothing shows none. A `<button>` or `Button` passed here is not nested:
+     * its children become the glyph and a one-time development warning is logged.
+     * @default a plus glyph
+     */
+    icon?: Slot<'span'>;
+    /**
+     * Size of the swatch (20, 24, 32 or 40px).
+     * @default the picker's
+     */
+    size?: SwatchPickerSize;
+    /**
+     * Shape of the swatch.
+     * @default the picker's
+     */
+    shape?: Shape;
+    /** Ref to the button. */
+    ref?: React_2.Ref<HTMLButtonElement>;
+}
+
 /**
  * Lays out a form control with a label, a validation message, a hint and a required indicator,
  * and wires them to the control.
@@ -3864,6 +4590,13 @@ export declare interface FieldProps extends React_2.HTMLAttributes<HTMLDivElemen
     ref?: React_2.Ref<HTMLDivElement>;
 }
 
+/**
+ * Which week is week 1 of a year: the week of January 1 (`'first-day'`), the first week that lies
+ * wholly in the year (`'first-full-week'`), or the first week with at least four days in the year
+ * (`'first-four-day-week'`, ISO 8601 when weeks start on Monday).
+ */
+export declare type FirstWeekOfYear = 'first-day' | 'first-full-week' | 'first-four-day-week';
+
 /**
  * A flexbox layout container with token-based gaps.
  *
@@ -3936,6 +4669,30 @@ export declare type FlexProps<C extends React_2.ElementType = 'div'> = Polymorph
  */
 export declare function getThemeClassName(theme: WaveTheme): string;
 
+/**
+ * The week number (1–53) of `date`'s calendar day (time of day ignored): days before a year's week
+ * 1 belong to the previous year's last week, and days in the next year's week 1 are week 1. ISO 8601
+ * is `{ firstDayOfWeek: 1, firstWeekOfYear: 'first-four-day-week' }`.
+ *
+ * @param options Defaults to Sunday weeks, week 1 being the week of January 1.
+ * @default `{ firstDayOfWeek: 0, firstWeekOfYear: 'first-day' }`
+ */
+export declare function getWeekNumber(date: Date, options?: GetWeekNumberOptions): number;
+
+/** Options of {@link getWeekNumber}. */
+export declare interface GetWeekNumberOptions {
+    /**
+     * The weekday weeks start on (0 is Sunday).
+     * @default 0
+     */
+    firstDayOfWeek?: DayOfWeek;
+    /**
+     * Which week is week 1 of a year.
+     * @default 'first-day'
+     */
+    firstWeekOfYear?: FirstWeekOfYear;
+}
+
 /**
  * A CSS grid layout with a fixed column count and token gaps.
  *
@@ -4092,6 +4849,55 @@ export declare interface ImageProps extends React_2.ImgHTMLAttributes<HTMLImageE
 /** Shape of the image corners (the shared {@link Shape} vocabulary). */
 export declare type ImageShape = Shape;
 
+/**
+ * One image swatch of a `SwatchPicker`: a pattern or texture drawn as a covering background
+ * image. Outside a `SwatchPicker` it throws in development and renders inertly in production.
+ *
+ * **Naming**: give it `aria-label`, or wrap it in a `Tooltip` with `relationship="label"`.
+ * Without either it is named by its `value` and a development warning is logged.
+ *
+ * **Selected and disabled**: an image has no single luminance, so the check and the disabled slash
+ * are the theme's foreground glyph over a background halo. Unlike `ColorSwatch` it does not opt
+ * out of forced colors (a background image stays).
+ *
+ * @example
+ * <SwatchPicker aria-label="Pattern">
+ *   <ImageSwatch value="dots" src="/dots.png" aria-label="Dots" />
+ * </SwatchPicker>
+ */
+export declare const ImageSwatch: {
+    ({ src, ...rest }: ImageSwatchProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/** ImageSwatch (carries SwatchPicker's `swatch`): `root` on the swatch `<button>`. */
+export declare const imageSwatchClassNames: {
+    readonly root: "wave-image-swatch";
+};
+
+/** Properties for the ImageSwatch component. */
+export declare interface ImageSwatchProps extends Omit<React_2.ButtonHTMLAttributes<HTMLButtonElement>, 'value'> {
+    /** Unique identifier for the swatch (the value the picker selects and a form submits). */
+    value: string;
+    /** URL of the image (drawn as a covering background image). */
+    src: string;
+    /**
+     * Size of the swatch (20, 24, 32 or 40px).
+     * @default the picker's
+     */
+    size?: SwatchPickerSize;
+    /**
+     * Shape of the swatch.
+     * @default the picker's
+     */
+    shape?: Shape;
+    /**
+     * Ref to the swatch button: `role="radio"` in the row layout, inside its cell in the grid
+     * layout, a toggle button in tab mode.
+     */
+    ref?: React_2.Ref<HTMLButtonElement>;
+}
+
 /**
  * A button with the info glyph that shows `info` in a note next to it: text, links or other rich
  * content, placed above the button with a beak (a toggletip).
@@ -4376,6 +5182,9 @@ export declare interface InputProps extends Omit<React_2.InputHTMLAttributes<HTM
     ref?: React_2.Ref<HTMLInputElement>;
 }
 
+/** Whether both dates are on the same calendar day (time of day ignored); `false` when either is missing. */
+export declare function isSameDay(a: Date | null | undefined, b: Date | null | undefined): boolean;
+
 /**
  * A text label for a form control (`htmlFor`), on the Fluent type ramp. The optional required
  * indicator is decorative (`aria-hidden`). `Field` renders its own label; use `Label` for custom
@@ -4496,60 +5305,529 @@ export declare interface LinkOwnProps {
 }
 
 /**
- * Props of {@link Link} rendered as `C` (default `'a'`). `LinkProps` without a type argument is
- * the 0.4 name: the props of a Link rendered as an `<a>`, including `ref`.
+ * Props of {@link Link} rendered as `C` (default `'a'`). `LinkProps` without a type argument is
+ * the 0.4 name: the props of a Link rendered as an `<a>`, including `ref`.
+ */
+export declare type LinkProps<C extends React_2.ElementType = 'a'> = PolymorphicProps<C, LinkOwnProps>;
+
+/** @deprecated Use {@link LinkAppearance}. */
+export declare type LinkVariant = LinkAppearance;
+
+/**
+ * A vertical list of items, optionally selectable.
+ *
+ * - **Plain** (`selectable` false): `role="list"` with `listitem`s; item actions stay in the
+ *   normal Tab order.
+ * - **Selectable** (APG Listbox): `role="listbox"` with `option`s and one Tab stop (the first
+ *   selected option, else the first option). ArrowUp/Down move focus (wrapping), Home/End jump to
+ *   the ends, typeahead is on for more than 7 items, Enter/Space and clicks toggle selection (a
+ *   Space typed within 500 ms of a typeahead character continues the search instead; with Ctrl,
+ *   Alt or Meta, Enter and Space are left to the page).
+ * - **Selectable with item actions** (APG Grid): `role="grid"` with `row`s (carrying
+ *   `aria-selected`) and `gridcell`s for the content and the action. One Tab stop; Up/Down move
+ *   between rows, Right/Left (mirrored in RTL) move into and out of the actions. A cell that holds
+ *   a text-entry widget takes focus itself: Enter/F2 enter the widget, Escape returns to the cell.
+ *   Clicks and keys that start inside an action, or inside a popup it opens (a Popover, a Menu),
+ *   never toggle selection.
+ * - **Switching semantics remounts the items.** Listbox/list and grid use different elements
+ *   (`ul`/`li` and `div`), so when a selectable list gains its first item action, loses its last
+ *   one, or `selectable` changes while items have actions, React remounts the items and their
+ *   content: state inside them (an inline rename input's draft, an uncontrolled checkbox) is reset.
+ *   Focus that is on an item or inside it when the list switches moves to the same item (by
+ *   `value`, else by position; the next item when the focused one was removed), so the switch
+ *   never drops it to `<body>`. This includes focus inside the last action when that action
+ *   removes itself (an inline rename input that unmounts on Enter). An action that removes itself
+ *   while focused without causing a switch drops focus, like any removed element. When the list
+ *   may switch, keep such state in the parent (or keep an action on at least one item).
+ * - Selection: `selectionMode` `'single'` (default) or `'multiple'`; controlled with
+ *   `selectedItems` (or `selectedItem` in single mode) or uncontrolled with the `default*` props.
+ *   Values of items that are no longer rendered are dropped from the reported selection.
+ * - Sub-component: `List.Item` (also exported as `ListItem` for React Server Components).
+ *
+ * @example
+ * <List selectable selectionMode="multiple" aria-label="Fruits" onSelectionChange={setFruits}>
+ *   <List.Item value="apple">Apple</List.Item>
+ *   <List.Item value="banana">Banana</List.Item>
+ * </List>
+ */
+export declare const List: {
+    <M extends ListSelectionMode = "single">(props: ListProps<M>): React_2.ReactNode;
+    displayName: string;
+} & {
+    Item: {
+        ({ value, action, className, children, onClick, onKeyDown, ref, ...rest }: ListItemProps): React_2.JSX.Element;
+        displayName: string;
+    };
+};
+
+/**
+ * A list of options that holds focus itself (APG listbox): one `<ul role="listbox">` of
+ * `Option`s, whose `aria-activedescendant` points at the active option while the list has focus.
+ * It is the picker option model shown in the page — typeahead, groups, disabled options and the
+ * option look of Dropdown and Combobox. Use `List` with `selectable` (`selectionMode`) instead
+ * when each item needs real focus, actions of its own or interactive content.
+ *
+ * - **Focus.** One tab stop. The active option exists only while the list has focus, and a
+ *   switch to another window keeps it: the selected option (with `multiselect`, the first
+ *   selected one in list order), else the first. While no option can be active (an empty list,
+ *   every option hidden, or every option disabled without `disabledOptionsFocusable`), and while
+ *   the active option is scrolled out of the list's view, the list draws its own focus ring. A
+ *   press on an option with the primary button focuses the list and makes that option active
+ *   without scrolling, so the click selects it even while the selected option is scrolled out of
+ *   view; a right or middle press is left to the browser. `autoFocus` focuses the list when it
+ *   mounts.
+ * - **Keys.** ArrowDown and ArrowUp move without wrapping, Home and End go to the first and last
+ *   option, PageUp and PageDown move ten options, and typing moves to the matching option
+ *   (typeahead). Space and Enter select the active option: the selection does not follow the
+ *   active option. Tab, Escape and Alt+Arrow keys are left to the page, so an enclosing Dialog
+ *   closes on Escape.
+ * - **Selection.** `value`, `defaultValue` and `onValueChange` are Fluent's `selectedOptions`,
+ *   `defaultSelectedOptions` and `onOptionSelect` under WaveUI's value naming. A single-select
+ *   Listbox keeps the selected option when it is selected again (no deselection). `multiselect`
+ *   turns the value into an array: options draw a checkbox, Space, Enter and a click toggle an
+ *   option, the value keeps selection order, and every toggle the user makes is announced
+ *   (`labels.added`/`labels.removed`; never a controlled change or a form reset). A non-literal
+ *   `multiselect={flag}` is a type error: render two elements, one for each mode.
+ * - **Disabled.** `disabled` takes the list out of the tab order (a click does not focus it
+ *   either), dims it, takes pointer input off its options, selects nothing and submits nothing.
+ *   Disabled options are skipped by the keys unless `disabledOptionsFocusable`, and are never
+ *   selected.
+ * - **Forms and Field.** With `name` the value is submitted with its form (one entry, or one per
+ *   value with `multiselect`), and `required` needs a value (native validation; a missing value
+ *   moves focus to the list). A reset of its form restores `defaultValue`, with or without a
+ *   `name` (a `multiselect` reset is compared by content, so restoring the same values reports
+ *   nothing). Inside a `Field` the list is labelled by its label, described by its message and
+ *   hint, and takes its invalid and required state; otherwise name it with `aria-label` or
+ *   `aria-labelledby` (development warns once when it has no name).
+ * - It has no built-in height: give it one through `className` and it scrolls.
+ *
+ * Every prop, the `ref` and the handlers go to the `<ul>`. Sub-components: `Listbox.Option`,
+ * `Listbox.OptionGroup`. React Server Components import the flat names `ListboxOption` /
+ * `ListboxOptionGroup` (dotted access needs a client file).
+ *
+ * @example
+ * <Listbox aria-label="Fruit" name="fruit" defaultValue="banana">
+ *   <Listbox.Option value="apple">Apple</Listbox.Option>
+ *   <Listbox.Option value="banana">Banana</Listbox.Option>
+ * </Listbox>
+ */
+export declare const Listbox: ListboxComponent;
+
+/** Listbox: `root` on the `role="listbox"` list (its options carry Option's classes). */
+export declare const listboxClassNames: {
+    readonly root: "wave-listbox";
+};
+
+/** Props for the combobox element (spread them; see {@link UseListboxResult.getComboboxProps}). */
+export declare interface ListboxComboboxProps {
+    role: 'combobox';
+    /** {@link UseListboxOptions.open}. */
+    'aria-expanded': boolean;
+    /** The listbox's id ({@link UseListboxResult.listboxId}). */
+    'aria-controls': string;
+    /** The active option's id, while the listbox is open and an option is active. */
+    'aria-activedescendant'?: string;
+    'aria-haspopup': 'listbox';
+    /** Editable mode: typing filters the options. */
+    'aria-autocomplete'?: 'list';
+}
+
+/** The Listbox component's type: a multi-select signature, then the single-select one. */
+export declare interface ListboxComponent {
+    (props: ListboxProps<true> & {
+        multiselect: true;
+    }): React_2.ReactNode;
+    (props: ListboxProps): React_2.ReactNode;
+    displayName?: string;
+    Option: typeof Option_2;
+    OptionGroup: typeof OptionGroup;
+}
+
+/**
+ * The context a listbox provides to its options (`useListbox(...).context`; pass it to
+ * `ListboxProvider` for a list rendered without `ListboxSurface`).
+ */
+export declare interface ListboxContextValue {
+    /** The listbox element's id, which the option ids start with. */
+    listboxId: string;
+    /** The per-option state and the registration of the options. */
+    store: ListboxStore;
+    /** Whether the listbox is {@link UseListboxOptions.multiselect}. */
+    multiselect: boolean;
+    /** The listbox's {@link UseListboxOptions.mode}: standalone options add the pointer press. */
+    mode: 'editable' | 'select-only' | 'standalone';
+    /**
+     * Commits `value` (an option click): `item` stands for the option while it has not registered
+     * yet, and `event` is the click behind the commit. A disabled option is never committed.
+     */
+    select(value: string, item: ListboxItem, event: Event): void;
+    /** Highlights `value` (pointer movement); not scrolled into view, so the list stays put. */
+    highlight(value: string): void;
+    /**
+     * Standalone mode: a pointer press on option `value` (its `mousedown`, whose default the option
+     * prevents). Focuses the list without scrolling and makes the option active without scrolling
+     * it into view, in one update, so the click that follows commits the pressed option even when
+     * focus would have scrolled another option into view. A press on an option that cannot be
+     * active (a disabled one, unless {@link UseListboxOptions.disabledOptionsFocusable}) keeps a
+     * focused list's active option, and an unfocused list starts on its `autoHighlight` option,
+     * not scrolled into view either. Development warns once when the list element is unknown
+     * (the `ref` of {@link UseListboxResult.getListboxProps} was not passed on).
+     */
+    press(value: string): void;
+}
+
+/**
+ * What {@link collectOptionLabels} does with the elements of a component marked by
+ * {@link markListboxElement}: `'option'` reads a value and its label, `'group'` walks the children.
+ */
+export declare type ListboxElementKind = 'option' | 'group';
+
+/**
+ * One option of a listbox: an entry of {@link UseListboxOptions.items} (data mode), or what an
+ * option registers (registration mode, {@link useListboxOption}).
+ */
+export declare interface ListboxItem {
+    /** Unique value within the listbox. */
+    value: string;
+    /** Display label (Combobox input text, Dropdown trigger text). */
+    label: string;
+    /** Text matched by typeahead and filters instead of `label`. */
+    textValue?: string;
+    /**
+     * Disabled options are rendered but skipped by navigation, unless
+     * {@link UseListboxOptions.disabledOptionsFocusable}, and never committed.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Hidden options are left out of navigation and rendering like filtered-out ones: never
+     * highlighted, reached by typeahead or committed with the keyboard (registered options render
+     * `hidden`). Their label stays known ({@link UseListboxResult.getItem}). In data mode (`items`)
+     * it is the item's own flag; a registered option is hidden by its own `hidden` attribute or by a
+     * hidden group around it.
+     * @default false
+     */
+    hidden?: boolean;
+}
+
+/**
+ * The Listbox's built-in texts, for localization: the announcements of a `multiselect` toggle.
+ * Each member is optional and falls back to its English default.
+ */
+export declare interface ListboxLabels {
+    /**
+     * Announced when a `multiselect` toggle selects an option; `count` is the number of values
+     * selected after the change.
+     * @default (label, count) => `${label} added, ${count} selected`
+     */
+    added?: (label: string, count: number) => string;
+    /**
+     * Announced when a `multiselect` toggle deselects an option; `count` is the number of values
+     * selected after the change.
+     * @default (label, count) => `${label} removed, ${count} selected`
+     */
+    removed?: (label: string, count: number) => string;
+}
+
+/** Props for the listbox element (see {@link UseListboxResult.getListboxProps}). */
+export declare interface ListboxListProps {
+    /** {@link UseListboxResult.listboxId}. */
+    id: string;
+    role: 'listbox';
+    /** With {@link UseListboxOptions.multiselect}. */
+    'aria-multiselectable'?: true;
+    /** `-1` in the combobox modes (focus stays on the combobox); `0` in standalone mode. */
+    tabIndex: 0 | -1;
+    /** The combobox modes: keeps focus on the combobox while options are clicked. */
+    onMouseDown?(event: React_2.MouseEvent): void;
+    /** Standalone mode: the active option's id while the list has focus and an option is active. */
+    'aria-activedescendant'?: string;
+    /**
+     * Standalone mode: the list element, which a pointer press on an option focuses. Merge it with
+     * your own ref (a press warns in development when it was dropped).
+     */
+    ref?: React_2.RefCallback<HTMLElement>;
+}
+
+/**
+ * Why {@link UseListboxOptions.onOpenChange} was called: `'keyboard'` (a key opens the listbox, or
+ * closes it without a commit), `'select'` (a commit closes it), `'escape'` or `'tab'` (Tab closes
+ * it, after committing the active option in single-select select-only mode).
+ */
+export declare type ListboxOpenChangeReason = 'keyboard' | 'select' | 'escape' | 'tab';
+
+/** Flat name of `Listbox.Option` for React Server Components. */
+export declare const ListboxOption: React_2.NamedExoticComponent<OptionProps>;
+
+/**
+ * Props for an option element (spread them onto the `<li>`; compose `onClick`, and `onMouseDown`
+ * in standalone mode, with yours).
+ */
+export declare interface ListboxOptionElementProps<E extends HTMLElement = HTMLElement> {
+    /**
+     * The option's stable id ({@link UseListboxResult.getOptionId}), which `aria-activedescendant`
+     * points at while the option is active.
+     */
+    id: string;
+    role: 'option';
+    'aria-selected': boolean;
+    /** While disabled. */
+    'aria-disabled'?: true;
+    /** While filtered out or hidden. */
+    hidden?: boolean;
+    /** While the option is active, for styling. */
+    'data-active'?: '';
+    /** While selected, for styling. */
+    'data-selected'?: '';
+    /** While disabled, for styling. */
+    'data-disabled'?: '';
+    /** Commits the option (a disabled one does nothing). */
+    onClick(event: React_2.MouseEvent<E>): void;
+    /** Makes the option under the pointer active (not a disabled one), without scrolling the list. */
+    onPointerMove(event: React_2.PointerEvent<E>): void;
+    /** Standalone mode only: the pointer press ({@link ListboxContextValue.press}). */
+    onMouseDown?(event: React_2.MouseEvent<E>): void;
+    /** Registers the element; it also sets the `ref` passed to {@link useListboxOption}. */
+    ref: React_2.RefCallback<E>;
+}
+
+/** Flat name of `Listbox.OptionGroup` for React Server Components. */
+export declare const ListboxOptionGroup: React_2.FC<OptionGroupProps>;
+
+/** Properties for the Listbox component. */
+export declare interface ListboxProps<M extends boolean = false> extends Omit<React_2.HTMLAttributes<HTMLUListElement>, 'onChange' | 'defaultValue'> {
+    /**
+     * Several options can be selected (Fluent's `multiselect`; List's `selectionMode="multiple"` is
+     * the other widget): the value is an array, options draw a checkbox, Space, Enter and a click
+     * toggle an option, and each toggle is announced. A non-literal `multiselect={flag}` is a type
+     * error: render two elements, one for each mode.
+     * @default false
+     */
+    multiselect?: M;
+    /**
+     * Controlled selected value (`''` for none), or with `multiselect` the selected values in
+     * selection order (Fluent's `selectedOptions`).
+     */
+    value?: M extends true ? readonly string[] : string;
+    /**
+     * Initial selected value for uncontrolled usage, which a form reset restores.
+     * @default '' (`[]` with `multiselect`)
+     */
+    defaultValue?: M extends true ? readonly string[] : string;
+    /**
+     * Called with the new value when it changes (a new array with `multiselect`; Fluent's
+     * `onOptionSelect`, under WaveUI's value/onValueChange naming). In single-select mode, selecting
+     * the selected option again changes nothing: the Listbox never deselects it.
+     */
+    onValueChange?: M extends true ? (value: string[]) => void : (value: string) => void;
+    /**
+     * Called after the active (highlighted) option changes — focus, arrow keys, typeahead, the
+     * pointer — and with `null` when focus leaves the list (a switch to another window keeps the
+     * active option). It reports what `aria-activedescendant` points at, from an effect once the
+     * change commits. Fluent's `onActiveOptionChange` reports neither the pointer (its options have
+     * no hover highlight) nor the loss of focus.
+     */
+    onActiveOptionChange?: (value: string | null) => void;
+    /**
+     * Takes the list out of the tab order (a click does not focus it either, as a disabled native
+     * `<select>`) and dims it: its options take no pointer input, nothing can be selected, and
+     * nothing is submitted or validated. Renders `aria-disabled` and `data-disabled`. An
+     * `aria-disabled` of your own without `disabled` is passed through as it is: the list stays
+     * interactive.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Focuses the list when it mounts in the browser (React focuses only form controls itself), not
+     * while `disabled`. Server-rendered HTML carries the `autofocus` attribute for the browser's own
+     * autofocus, so a hydrating list takes no focus, as React leaves a hydrated form control alone.
+     * @default false
+     */
+    autoFocus?: boolean;
+    /**
+     * Keeps disabled options in the arrow-key, Home/End, PageUp/PageDown and typeahead order (the
+     * option that is active on focus may then be a disabled one too); they still cannot be
+     * selected (Space, Enter and a click do nothing). Unlike Fluent, which always keeps disabled
+     * options reachable, WaveUI skips them by default.
+     * @default false
+     */
+    disabledOptionsFocusable?: boolean;
+    /** The `multiselect` toggle announcements, for localization. Unset members keep their English defaults. */
+    labels?: ListboxLabels;
+    /**
+     * Name of the value in form submissions (renders a hidden input inside the list; one per value
+     * with `multiselect`).
+     */
+    name?: string;
+    /** Id of the form the value belongs to, when the Listbox is outside it. */
+    form?: string;
+    /**
+     * A value is required to submit the form (native constraint validation); when validation finds
+     * it empty, focus moves to the list.
+     */
+    required?: boolean;
+    /**
+     * Called on a key press on the list, before the built-in keys; `event.preventDefault()` skips
+     * them.
+     */
+    onKeyDown?: React_2.KeyboardEventHandler<HTMLUListElement>;
+    /** Ref to the `<ul role="listbox">`. */
+    ref?: React_2.Ref<HTMLUListElement>;
+}
+
+/**
+ * Provides a listbox's context to its options, for a custom picker that renders its list without
+ * `ListboxSurface`: `<ListboxProvider value={listbox.context}><ul {...listbox.getListboxProps()}>…</ul></ListboxProvider>`.
+ */
+export declare function ListboxProvider({ value, children }: ListboxProviderProps): React_2.JSX.Element;
+
+export declare namespace ListboxProvider {
+    var displayName: string;
+}
+
+/** Props of {@link ListboxProvider}. */
+export declare interface ListboxProviderProps {
+    /** The context of a listbox: `useListbox(...).context`. */
+    value: ListboxContextValue;
+    /** The options (`Option`, `OptionGroup` or options of your own on `useListboxOption`). */
+    children?: React_2.ReactNode;
+}
+
+/**
+ * Second argument of {@link UseListboxOptions.onSelect}: the committed option and the event behind
+ * the commit.
+ */
+export declare interface ListboxSelectDetails {
+    /** The committed option. */
+    item: ListboxItem;
+    /** The key or click event behind the commit. */
+    event: Event;
+}
+
+/**
+ * The per-option state of a listbox ({@link ListboxContextValue.store}) and the contract of option
+ * components: {@link useListboxOption} is built on it, and so can an option component of your own
+ * be. `register` adds an option, `getIndex` gives its stable id, and the flags say how to draw it:
+ * subscribe with `useSyncExternalStore` and read one value (`() => store.isActive(value)`), so only
+ * the options whose answer changed re-render.
+ */
+export declare interface ListboxStore {
+    /** Calls `listener` after a flag of any option changed. Returns the unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Whether `value` is the active option, the one `aria-activedescendant` points at. */
+    isActive(value: string): boolean;
+    /** Whether `value` is selected. */
+    isSelected(value: string): boolean;
+    /** Whether `value` is filtered out or hidden: render its option `hidden`. */
+    isHidden(value: string): boolean;
+    /**
+     * The stable per-listbox index of `value`, assigned the first time the value is seen: the
+     * option's id is `${listboxId}-opt-${getIndex(value)}` ({@link UseListboxResult.getOptionId}),
+     * the same across filtering and remounts.
+     */
+    getIndex(value: string): number;
+    /**
+     * Registers an option and its element (registration mode): call it from a layout effect, as
+     * {@link useListboxOption} does, and call the returned function to unregister, when the option
+     * unmounts or before it registers a changed item. The options are ordered by their elements'
+     * DOM position. The registrations of a commit are published once from the listbox's layout
+     * effect (later ones once per microtask).
+     */
+    register(item: ListboxItem, element: React_2.RefObject<HTMLElement | null>): () => void;
+}
+
+/**
+ * The option list of a custom picker and the popup it opens in: a `<ul role="listbox">` with the
+ * options (spread from `listbox.getListboxProps()`), rendered `hidden` in place inside your
+ * picker while the list is not shown, so the options register and their ids exist from the first
+ * render, and in a portaled surface placed by {@link useListboxPopup} while it is, never in both.
+ * While the listbox is open with nothing to show, the surface shows `emptyContent` instead, if
+ * any. A press on the surface keeps focus on your combobox. It provides the listbox's context to
+ * the options, so it needs no {@link ListboxProvider}.
+ *
+ * @example
+ * <ListboxSurface
+ *   listbox={listbox}
+ *   layerId={layerId}
+ *   surfaceRef={surfaceRef}
+ *   floatingProps={floatingProps}
+ *   open={open}
+ *   expanded={expanded}
+ *   aria-labelledby={labelId}
+ * >
+ *   <Option value="georgia">Georgia</Option>
+ * </ListboxSurface>
+ */
+export declare function ListboxSurface(props: ListboxSurfaceProps): React_2.JSX.Element;
+
+export declare namespace ListboxSurface {
+    var displayName: string;
+}
+
+/**
+ * ListboxSurface: `root` on the portaled popup around the list, while it shows the list or the
+ * empty content; `list` on the `role="listbox"` list, also while it renders in place inside your
+ * picker. In Combobox, Dropdown and TagPicker these elements also carry the picker's own
+ * `surface` and `listbox` classes.
  */
-export declare type LinkProps<C extends React_2.ElementType = 'a'> = PolymorphicProps<C, LinkOwnProps>;
-
-/** @deprecated Use {@link LinkAppearance}. */
-export declare type LinkVariant = LinkAppearance;
+export declare const listboxSurfaceClassNames: {
+    readonly root: "wave-listbox-surface";
+    readonly list: "wave-listbox-surface__list";
+};
 
 /**
- * A vertical list of items, optionally selectable.
- *
- * - **Plain** (`selectable` false): `role="list"` with `listitem`s; item actions stay in the
- *   normal Tab order.
- * - **Selectable** (APG Listbox): `role="listbox"` with `option`s and one Tab stop (the first
- *   selected option, else the first option). ArrowUp/Down move focus (wrapping), Home/End jump to
- *   the ends, typeahead is on for more than 7 items, Enter/Space and clicks toggle selection (a
- *   Space typed within 500 ms of a typeahead character continues the search instead; with Ctrl,
- *   Alt or Meta, Enter and Space are left to the page).
- * - **Selectable with item actions** (APG Grid): `role="grid"` with `row`s (carrying
- *   `aria-selected`) and `gridcell`s for the content and the action. One Tab stop; Up/Down move
- *   between rows, Right/Left (mirrored in RTL) move into and out of the actions. A cell that holds
- *   a text-entry widget takes focus itself: Enter/F2 enter the widget, Escape returns to the cell.
- *   Clicks and keys that start inside an action, or inside a popup it opens (a Popover, a Menu),
- *   never toggle selection.
- * - **Switching semantics remounts the items.** Listbox/list and grid use different elements
- *   (`ul`/`li` and `div`), so when a selectable list gains its first item action, loses its last
- *   one, or `selectable` changes while items have actions, React remounts the items and their
- *   content: state inside them (an inline rename input's draft, an uncontrolled checkbox) is reset.
- *   Focus that is on an item or inside it when the list switches moves to the same item (by
- *   `value`, else by position; the next item when the focused one was removed), so the switch
- *   never drops it to `<body>`. This includes focus inside the last action when that action
- *   removes itself (an inline rename input that unmounts on Enter). An action that removes itself
- *   while focused without causing a switch drops focus, like any removed element. When the list
- *   may switch, keep such state in the parent (or keep an action on at least one item).
- * - Selection: `selectionMode` `'single'` (default) or `'multiple'`; controlled with
- *   `selectedItems` (or `selectedItem` in single mode) or uncontrolled with the `default*` props.
- *   Values of items that are no longer rendered are dropped from the reported selection.
- * - Sub-component: `List.Item` (also exported as `ListItem` for React Server Components).
- *
- * @example
- * <List selectable selectionMode="multiple" aria-label="Fruits" onSelectionChange={setFruits}>
- *   <List.Item value="apple">Apple</List.Item>
- *   <List.Item value="banana">Banana</List.Item>
- * </List>
+ * Props of {@link ListboxSurface}. The options of one listbox live in one list at a time, and this
+ * surface renders that list: render every option of the listbox inside it, never in a second list
+ * of your own, not even for an exit animation.
  */
-export declare const List: {
-    <M extends ListSelectionMode = "single">(props: ListProps<M>): React_2.ReactNode;
-    displayName: string;
-} & {
-    Item: {
-        ({ value, action, className, children, onClick, onKeyDown, ref, ...rest }: ListItemProps): React_2.JSX.Element;
-        displayName: string;
-    };
-};
+export declare interface ListboxSurfaceProps {
+    /** The listbox: the result of `useListbox` in select-only or editable mode. */
+    listbox: UseListboxResult;
+    /** `layerId` from {@link useListboxPopup}: the surface joins the popup's dismiss layer. */
+    layerId: string;
+    /** `surfaceRef` from {@link useListboxPopup}. */
+    surfaceRef: React_2.RefCallback<HTMLElement>;
+    /** `floatingProps` from {@link useListboxPopup}: the surface's placement. */
+    floatingProps: UseListboxPopupResult['floatingProps'];
+    /** The listbox is open (your open state). `emptyContent` shows only while it is. */
+    open: boolean;
+    /**
+     * The list is shown: the listbox is open and has options to show (`open &&
+     * listbox.items.length > 0`). The list then renders in the surface, and otherwise `hidden`, in
+     * place inside your picker. Set your combobox's `aria-expanded` to this value after spreading
+     * `getComboboxProps()`, which reports `open`, so the combobox is not announced as expanded while
+     * nothing is shown.
+     */
+    expanded: boolean;
+    /**
+     * Shown in the surface while the listbox is open but not expanded, such as a "No matches"
+     * message. `undefined` and `null` show no surface; any other value shows one, so `false` and
+     * `''` show an empty surface.
+     */
+    emptyContent?: React_2.ReactNode;
+    /** Names the list. Name it with this or `aria-labelledby`, usually your picker's label. */
+    'aria-label'?: string;
+    /** Ids of the elements that name the list, usually your picker's label. */
+    'aria-labelledby'?: string;
+    /**
+     * Options draw a check while selected (in a multi-select list, a checkbox square). Turn it off
+     * for a list that never shows selected options, such as the suggestions of a tag picker.
+     * @default true
+     */
+    showCheck?: boolean;
+    /**
+     * Classes merged last onto the list: they replace the list's own classes they conflict with,
+     * its maximum height included.
+     */
+    listClassName?: string;
+    /**
+     * Classes merged last onto the surface, the popup around the list: they replace its own
+     * classes they conflict with.
+     */
+    surfaceClassName?: string;
+    /** The options (`Option`, `OptionGroup` or options of your own on `useListboxOption`). */
+    children?: React_2.ReactNode;
+}
 
 /** List: `root` on the `<ul>` (the `role="grid"` element of a selectable list with actions). */
 export declare const listClassNames: {
@@ -4648,6 +5926,22 @@ export declare interface ListProps<M extends ListSelectionMode = ListSelectionMo
 /** Selection modes of {@link List}: the shared `SelectionMode` plus the deprecated `'multi'`. */
 export declare type ListSelectionMode = SelectionMode_2 | 'multi';
 
+/**
+ * Marks a component so {@link collectOptionLabels} recognises its elements: `'option'` (reads its
+ * `value` prop and its label: the `label` prop, else `textValue`, else its text children, as
+ * `Option`'s) or `'group'` (walks its `children`). Returns the component (function, `memo` or
+ * `forwardRef` components). Mark every option or group component of your own that is rendered in
+ * a listbox (`Option` and `OptionGroup` are marked): unmarked components are opaque to
+ * {@link collectOptionLabels}, so their labels are unknown on the server and in the first client
+ * render.
+ *
+ * @example
+ * // Option components of your own, built on useListboxOption:
+ * export const ColorOption = markListboxElement(ColorOptionImpl, 'option');
+ * export const ColorGroup = markListboxElement(ColorGroupImpl, 'group');
+ */
+export declare function markListboxElement<C extends object>(component: C, kind: ListboxElementKind): C;
+
 /**
  * A menu of actions (`role="menu"`), in one of two forms:
  *
@@ -6060,9 +7354,12 @@ export declare interface OpenChangeDetails<R extends string = string> {
 }
 
 /**
- * An option of a `Combobox`, `Dropdown` (and `TagPicker`'s generated list). Renders
- * `<li role="option">` with a stable id (`aria-activedescendant` target), `aria-selected`, a check
- * mark while selected and `data-active`/`data-selected`/`data-disabled` attributes for styling.
+ * An option of a listbox: a `Listbox`, `Combobox` or `Dropdown` (and `TagPicker`'s generated
+ * list), or a custom picker's list, rendered through `ListboxSurface` or under a
+ * `ListboxProvider`. Renders `<li role="option">` with a stable id (`aria-activedescendant`
+ * target), `aria-selected`, a check mark while selected (`checkIcon` replaces it; in a
+ * multi-select list it sits in a checkbox square) and `data-active`/`data-selected`/
+ * `data-disabled` attributes for styling.
  *
  * Options register with the surrounding listbox (in DOM order, groups included), so they can be
  * wrapped, grouped or rendered conditionally. The option is memoized: moving the highlight
@@ -6073,31 +7370,37 @@ export declare interface OpenChangeDetails<R extends string = string> {
  * use its data variant (`data-[active]:bg-…`, `data-[selected]:bg-…`). The active option keeps
  * its focus outline.
  *
- * Use it inside a `Combobox` or `Dropdown` only; it throws in development elsewhere.
+ * Use it inside a listbox only; it throws in development elsewhere.
  */
 declare const Option_2: React_2.NamedExoticComponent<OptionProps>;
 export { Option_2 as Option }
 
 /**
- * Option (also Combobox.Option and Dropdown.Option): `root` on the `role="option"` element;
- * `checkIcon` on the check `<svg>`; `content` on the content span.
+ * Option (also Combobox.Option, Dropdown.Option and Listbox.Option): `root` on the `role="option"`
+ * element; `indicator` on the checkbox square of a multi-select list; `checkIcon` on the check
+ * `<svg>`, or on the span of your `checkIcon` (inside the square in a multi-select list);
+ * `content` on the content span.
  */
 export declare const optionClassNames: {
     readonly root: "wave-option";
+    readonly indicator: "wave-option__indicator";
     readonly checkIcon: "wave-option__check-icon";
     readonly content: "wave-option__content";
 };
 
 /**
- * Groups options under a heading: `<li role="presentation">` with the heading and a
- * `<ul role="group" aria-labelledby>` of the options. Hidden while a filter (or their own `hidden`)
- * hides all its options, also options wrapped in a component or in nested groups.
+ * Groups options under an optional heading: `<li role="presentation">` with the heading and a
+ * `<ul role="group">` of the options, named by the heading (`label`) or by your `aria-label` or
+ * `aria-labelledby`, which win over it. Hidden while a filter (or their own `hidden`) hides all
+ * its options, also options wrapped in a component or in nested groups. Use it inside a listbox,
+ * as `Option`.
  */
 export declare const OptionGroup: React_2.FC<OptionGroupProps>;
 
 /**
- * OptionGroup (also Combobox.OptionGroup and Dropdown.OptionGroup): `root` on the group's entry
- * in the list; `label` on its heading; `list` on the `role="group"` list of its options.
+ * OptionGroup (also Combobox.OptionGroup, Dropdown.OptionGroup and Listbox.OptionGroup): `root`
+ * on the group's entry in the list; `label` on its heading (rendered only for a `label`); `list`
+ * on the `role="group"` list of its options.
  */
 export declare const optionGroupClassNames: {
     readonly root: "wave-option-group";
@@ -6105,10 +7408,28 @@ export declare const optionGroupClassNames: {
     readonly list: "wave-option-group__list";
 };
 
-/** Properties for the OptionGroup component used to group options. */
+/**
+ * Props of {@link OptionGroup}. `aria-label` and `aria-labelledby` go to the group's
+ * `role="group"` list; the other props go to its `<li role="presentation">` item.
+ */
 export declare interface OptionGroupProps extends React_2.LiHTMLAttributes<HTMLLIElement> {
-    /** Heading label for the option group (names the group). */
-    label: string;
+    /**
+     * The group's heading, which names the group. Keep it text (an icon next to the text is fine): a
+     * label cannot be interactive, since nothing in it is reachable inside a listbox. Without a
+     * label no heading renders; name the group with `aria-label` or `aria-labelledby` then. A group
+     * without a name logs a development warning.
+     */
+    label?: React_2.ReactNode;
+    /**
+     * Names the group's list in place of the label (the heading still shows). A prop that holds
+     * `undefined`, as from a wrapper that forwards it, leaves the label in charge.
+     */
+    'aria-label'?: string;
+    /**
+     * Ids of the elements that name the group's list, in place of the label (the heading still
+     * shows). A prop that holds `undefined` leaves the label in charge.
+     */
+    'aria-labelledby'?: string;
     /**
      * Hides the group and every option in it (see `Option`'s `hidden`): keyboard navigation and
      * typeahead skip its options.
@@ -6119,7 +7440,10 @@ export declare interface OptionGroupProps extends React_2.LiHTMLAttributes<HTMLL
     ref?: React_2.Ref<HTMLLIElement>;
 }
 
-/** Properties for the Option component used within Combobox and Dropdown. */
+/**
+ * Props of {@link Option}, an option of a listbox (Listbox, Combobox, Dropdown or a custom
+ * picker's list).
+ */
 export declare interface OptionProps extends Omit<React_2.LiHTMLAttributes<HTMLLIElement>, 'value'> {
     /** Value associated with this option. Unique within its listbox. */
     value: string;
@@ -6132,11 +7456,25 @@ export declare interface OptionProps extends Omit<React_2.LiHTMLAttributes<HTMLL
     /** Text matched by typeahead and filtering instead of the label. */
     textValue?: string;
     /**
-     * Whether the option is disabled: it stays visible but is skipped by keyboard navigation and
-     * cannot be selected.
+     * Whether the option is disabled: it stays in the list but can never be selected (a click, Enter
+     * and Space do nothing). Keyboard navigation and typeahead skip it, unless the listbox keeps
+     * disabled options focusable (`disabledOptionsFocusable`), where they reach it. It is drawn in
+     * the muted text colour, its check included: in a multi-select list the checkbox square takes
+     * that colour instead of the brand colour, checked or not.
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Replaces the check glyph that marks the option while it is selected (decorative,
+     * `aria-hidden`); in a multi-select list the glyph is drawn inside the option's 16px checkbox
+     * square. The check is a required indicator, the sign of the selection that does not rely on
+     * colour: `null` and `undefined` keep the default glyph, and so does a value that renders
+     * nothing (`false`, `''`, an empty array), which also logs a development warning. Unlike
+     * `Combobox.expandIcon`, a value that renders nothing does not hide the indicator (Fluent's
+     * `checkIcon={null}` removes it).
+     * @default a check mark
+     */
+    checkIcon?: Slot<'span'>;
     /**
      * Hides the option, like a native `<option hidden>`: it is not shown, keyboard navigation and
      * typeahead skip it, and it never becomes the active option. Its label stays known, so a
@@ -8444,6 +9782,14 @@ export declare interface StackOwnProps {
  */
 export declare type StackProps<C extends React_2.ElementType = 'div'> = PolymorphicProps<C, StackOwnProps>;
 
+/**
+ * The first day of `date`'s week, at local midnight; the time of day is dropped.
+ *
+ * @param firstDayOfWeek The weekday weeks start on (0 is Sunday).
+ * @default 0
+ */
+export declare function startOfWeek(date: Date, firstDayOfWeek?: DayOfWeek): Date;
+
 /** Semantic status used for alerts, messages, and status indicators. */
 export declare type Status = 'success' | 'warning' | 'error' | 'info';
 
@@ -8608,37 +9954,87 @@ export declare interface SwatchItem {
 }
 
 /**
- * A single-select grid of color swatches (`role="radiogroup"` of `role="radio"` buttons).
+ * A single-select set of color swatches: a radio group (the default row layout) or a grid of rows
+ * (`layout="grid"`).
  *
- * - **Keyboard** (APG radio group): one tab stop — the selected swatch, else the first. All four
- *   arrow keys move focus and select (Left/Right mirrored under `dir="rtl"`), wrapping at the
- *   ends; Home/End jump to the first/last swatch.
+ * - **Row layout** (APG radio group, `role="radiogroup"` of `role="radio"` buttons): one tab stop,
+ *   the selected swatch, else the first. All four arrow keys move focus and select (Left/Right
+ *   mirrored under `dir="rtl"`), wrapping at the ends; Home/End jump to the first/last swatch.
+ * - **Grid layout** (APG grid, `role="grid"` of `SwatchPicker.Row` rows whose cells hold the
+ *   swatch buttons, the selected one `aria-selected` and pressed): the arrow keys move focus only.
+ *   Left/Right go through the cells in reading order across rows (mirrored under `dir="rtl"`) and
+ *   stop at the grid's first and last cell; Up/Down go to the nearest enabled cell of the
+ *   previous/next row; Home/End to the first/last cell of the row, Ctrl+Home/End of the grid.
+ *   Space, Enter and a click select. One tab stop: the last focused cell, starting at the
+ *   selected swatch, else the first. `items`, and every run of children that are not rows, render
+ *   in a row of their own; rows do not wrap.
  * - **Selected indicator**: an offset ring in the foreground color (drawn on the page background,
  *   not on the swatch) plus a check glyph whose color is picked by the swatch's luminance, so the
  *   selection never relies on color alone.
- * - **Naming**: give the group a name with `aria-label`/`aria-labelledby` or render it inside a
+ * - **Naming**: give the picker a name with `aria-label`/`aria-labelledby` or render it inside a
  *   `Field`, and give every item a `label`; both are reported in development when missing.
  * - **Forms**: with `name` (or `required`) it takes part in native forms; a form reset restores
- *   `defaultValue`.
+ *   `defaultValue`. A required grid says so in its description (`labels.required`), since its
+ *   role does not allow `aria-required`.
+ * - **Composition**: `items` render as `ColorSwatch` elements before `children`. A `ColorSwatch`,
+ *   `ImageSwatch` or `EmptySwatch` rendered directly as a child lets you wrap it, for example in
+ *   a `Tooltip` with `relationship="label"` to name and describe it. A swatch rendered outside any
+ *   `SwatchPicker` throws in development. React Server Components use the flat `SwatchPickerRow`
+ *   name for `SwatchPicker.Row`.
  *
  * @example
  * <SwatchPicker aria-label="Accent color" items={[{ value: 'red', color: '#d13438', label: 'Red' }]} />
+ *
+ * @example
+ * <SwatchPicker layout="grid" aria-label="Accent color">
+ *   <SwatchPicker.Row>
+ *     <ColorSwatch value="red" color="#d13438" aria-label="Red" />
+ *     <ColorSwatch value="blue" color="#0f6cbd" aria-label="Blue" />
+ *   </SwatchPicker.Row>
+ *   <SwatchPicker.Row>
+ *     <ColorSwatch value="green" color="#107c10" aria-label="Green" />
+ *     <EmptySwatch onClick={openColorDialog} />
+ *   </SwatchPicker.Row>
+ * </SwatchPicker>
  */
 export declare const SwatchPicker: {
-    ({ items, value: valueProp, defaultValue, onValueChange, onChange, size, shape, name, required, form, className, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, onKeyDown, onFocus, ref, ...rest }: SwatchPickerProps): React_2.JSX.Element;
+    ({ items, value: valueProp, defaultValue, onValueChange, onChange, children, layout, focusMode, labels, size, shape, spacing, name, required, form, className, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, onKeyDown, onFocus, ref, ...rest }: SwatchPickerProps): React_2.JSX.Element;
     displayName: string;
+} & {
+    Row: {
+        ({ className, ref, ...rest }: SwatchPickerRowProps): React_2.JSX.Element;
+        displayName: string;
+    };
 };
 
-/** SwatchPicker: `root` on the `role="radiogroup"` element; `swatch` on each `role="radio"` button. */
+/**
+ * SwatchPicker: `root` on the picker element (`role="radiogroup"`, or `role="grid"` in the grid
+ * layout); `swatch` on the button of every swatch in it (`items`, and the `ColorSwatch`,
+ * `ImageSwatch` and `EmptySwatch` children, next to their own classes).
+ */
 export declare const swatchPickerClassNames: {
     readonly root: "wave-swatch-picker";
     readonly swatch: "wave-swatch-picker__swatch";
 };
 
+/** Built-in strings of the SwatchPicker component (C-NAMING). */
+export declare interface SwatchPickerLabels {
+    /**
+     * Said where the picker's role cannot carry `aria-required` (the grid layout, and the group of
+     * `focusMode="tab"`): a hidden text
+     * joined into the picker's description while it is required.
+     * @default 'Required'
+     */
+    required?: string;
+}
+
 /** Properties for the SwatchPicker component. */
 export declare interface SwatchPickerProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
-    /** The swatches to display, in order (a readonly array is accepted; it is never modified). */
-    items: readonly SwatchItem[];
+    /**
+     * The swatches to display, in order (a readonly array is accepted; it is never modified):
+     * rendered as `ColorSwatch` elements, before `children`.
+     */
+    items?: readonly SwatchItem[];
     /** Controlled selected swatch value (`''` = nothing selected). */
     value?: string;
     /** Initial selected value for uncontrolled usage (also what a form reset restores).
@@ -8652,11 +10048,46 @@ export declare interface SwatchPickerProps extends Omit<React_2.HTMLAttributes<H
      * @deprecated Use `onValueChange`.
      */
     onChange?: (value: string) => void;
-    /** Size of each swatch button (24, 32 or 40px).
+    /**
+     * Swatches rendered directly, in order, after `items` (e.g. `ColorSwatch`): read the picker's
+     * context, so they may be wrapped in a `Tooltip` or another element that forwards its own props.
+     * `SwatchPicker.Row` elements start rows; in the grid layout every run of other children (and
+     * `items`, with the children that follow them) renders in a row of its own. A `SwatchPicker.Row`
+     * must be a direct child or inside a Fragment: a wrapper component around a Row lands in an
+     * implicit row, and nested rows are reported in development.
+     */
+    children?: React_2.ReactNode;
+    /**
+     * `'row'`: a radio group whose arrow keys select (and wrap). `'grid'`: rows of cells
+     * (`SwatchPicker.Row`) whose arrow keys move focus in two dimensions without selecting; Space,
+     * Enter and a click select. Changing it while mounted remounts the swatches, so focus falls
+     * back to the page.
+     * @default 'row'
+     */
+    layout?: 'row' | 'grid';
+    /**
+     * `'arrow'`: one tab stop and arrow keys, with the radio group (row layout) or grid (grid
+     * layout) semantics. `'tab'`: every enabled swatch is its own tab stop and the arrow keys do
+     * nothing, so the picker is a `role="group"` of toggle buttons (`aria-pressed`, the selected
+     * one pressed) in both layouts; rows have no role, and Space, Enter and a click select
+     * (pressing the selected swatch again keeps it selected). The required hint (`labels.required`)
+     * applies, as the group cannot carry `aria-required`.
+     * @default 'arrow'
+     */
+    focusMode?: 'arrow' | 'tab';
+    /** Built-in strings, for localization. */
+    labels?: SwatchPickerLabels;
+    /** Size of each swatch button (20, 24, 32 or 40px). A 20px swatch passes the target-size bar
+     * through its spacing; a swatch's own `size` overrides this.
      * @default 'medium'
      */
     size?: SwatchPickerSize;
-    /** Shape of each swatch button.
+    /** Gap between swatches (and between rows): 4px or 8px. At `'small'` the focus outline's offset shrinks from 4px to
+     * 2px, so it does not cover the neighbour.
+     * @default 'medium'
+     */
+    spacing?: 'small' | 'medium';
+    /** Shape of each swatch button (a swatch's own `shape` overrides this).
      * @default 'circular'
      */
     shape?: Shape;
@@ -8665,16 +10096,61 @@ export declare interface SwatchPickerProps extends Omit<React_2.HTMLAttributes<H
      * (nothing while no swatch is selected).
      */
     name?: string;
-    /** A swatch must be selected before the form can be submitted (native validation). */
+    /**
+     * A swatch must be selected before the form can be submitted (native validation). The row
+     * layout says so with `aria-required`; the grid layout and tab mode, whose roles do not allow
+     * it, with the hidden `labels.required` text in the description (which a consumer
+     * `aria-required` alone also shows).
+     */
     required?: boolean;
     /** Id of the form the picker belongs to, when it is rendered outside that form. */
     form?: string;
-    /** Ref to the `role="radiogroup"` element. */
+    /**
+     * Ref to the root element: `role="radiogroup"`, `role="grid"` in the grid layout, or
+     * `role="group"` in tab mode.
+     */
+    ref?: React_2.Ref<HTMLDivElement>;
+}
+
+/**
+ * One row of swatches in a `SwatchPicker` (also exported as the flat `SwatchPickerRow`, for React
+ * Server Components). In the grid layout it is a `role="row"` element whose swatches are its
+ * cells; Up and Down move between rows, and the row does not wrap (a wrapped swatch would sit
+ * where Up and Down do not reach it): size it yourself. In the row layout and in tab mode
+ * (`focusMode="tab"`) it is a full-width line without a role, and its swatches stay radios of the
+ * one group (row layout) or toggle buttons. Place it as a direct child of the `SwatchPicker` or
+ * inside a Fragment: a wrapper component around a Row lands in an implicit row, and a Row inside
+ * a Row is reported in development. Outside a `SwatchPicker` it throws in development.
+ *
+ * @example
+ * <SwatchPicker layout="grid" aria-label="Accent color">
+ *   <SwatchPicker.Row>
+ *     <ColorSwatch value="red" color="#d13438" aria-label="Red" />
+ *     <ColorSwatch value="blue" color="#0f6cbd" aria-label="Blue" />
+ *   </SwatchPicker.Row>
+ * </SwatchPicker>
+ */
+export declare const SwatchPickerRow: {
+    ({ className, ref, ...rest }: SwatchPickerRowProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * SwatchPicker.Row: `root` on the row element (`role="row"` in the grid layout), also on the rows
+ * the picker adds around `items` and loose swatches.
+ */
+export declare const swatchPickerRowClassNames: {
+    readonly root: "wave-swatch-picker-row";
+};
+
+/** Properties for the SwatchPicker.Row component. */
+export declare interface SwatchPickerRowProps extends React_2.HTMLAttributes<HTMLDivElement> {
+    /** Ref to the row element. */
     ref?: React_2.Ref<HTMLDivElement>;
 }
 
-/** Size of the swatches. */
-export declare type SwatchPickerSize = Extract<Size, 'small' | 'medium' | 'large'>;
+/** Size of the swatches: 20, 24, 32 or 40px. */
+export declare type SwatchPickerSize = Extract<Size, 'extra-small' | 'small' | 'medium' | 'large'>;
 
 /**
  * An on/off toggle drawn as a `role="switch"` button inside a `<label>`.
@@ -9257,7 +10733,10 @@ export declare interface TagOwnProps {
  * surrounding form), Escape closes the list (and then clears the typed text). Backspace in the
  * empty input moves focus to the last tag; Backspace or Delete there removes it. Additions and
  * removals are announced ("Cherry removed, 2 selected"), and so is "No matches" for text that
- * matches no option.
+ * matches no option. `filter` replaces the match (it may keep options that do not contain the
+ * text, for a server-side search or a "Create …" entry), and `query`/`defaultQuery`/
+ * `onQueryChange` control the typed text, which resets to `''` when a tag is added, on Escape and
+ * on a form reset, and stays on a blur.
  *
  * The tags form a list named "Selected"; the input is described by a summary of the selected
  * labels ("Selected: Apple, Banana"). These built-in texts are English; `labels` localizes them.
@@ -9384,6 +10863,36 @@ export declare interface TagPickerProps extends Omit<React_2.HTMLAttributes<HTML
      * @default 'Select...'
      */
     placeholder?: string;
+    /**
+     * Whether an option matches the typed text (the query). Called with every listed option (its
+     * `value` and `label`; selected options are not listed) and the text whenever the text is not
+     * empty; an option it returns `false` for is filtered out. It may keep options that do not
+     * contain the text: `filter={() => true}` with `query` and `onQueryChange` leaves the matching
+     * to you (a server-side search that replaces `options`), and a filter that always keeps an
+     * option of your own gives a "Create …" entry. With a server-side search, keep the selected
+     * options in `options` (they are never listed): a selected value without an option shows its raw
+     * value as the tag label, with a development warning (the "Async search" story does this).
+     * @default a case-insensitive substring match on the option's `label`
+     */
+    filter?: (option: ListboxItem, query: string) => boolean;
+    /**
+     * Controlled query: the text typed since the last tag was added, which filters the options and
+     * shows in the input (hidden while `disabled` or `readOnly`).
+     */
+    query?: string;
+    /**
+     * Initial query for uncontrolled usage. A TagPicker that starts disabled or read-only starts
+     * without it (as it starts closed).
+     * @default ''
+     */
+    defaultQuery?: string;
+    /**
+     * Called with the new query when it changes: as the user types, and with `''` when it resets (a
+     * tag added, Escape on the closed list, a form reset, or `disabled` or `readOnly` turned on
+     * while text is typed). A blur or a close keeps the text. A TagPicker that mounts disabled or
+     * read-only reports nothing: it keeps a controlled query, which shows once it unlocks.
+     */
+    onQueryChange?: (query: string) => void;
     /**
      * Whether the tag picker is disabled: nothing can be added or removed, and the remove buttons
      * leave the tab order.
@@ -11172,6 +12681,94 @@ export declare interface TreeProps extends React_2.HTMLAttributes<HTMLDivElement
 /** Typography scale variant mapping to Fluent UI type ramp tokens. */
 export declare type TypographyVariant = 'caption-2' | 'caption-1' | 'body-1' | 'body-2' | 'subtitle-2' | 'subtitle-1' | 'title-3' | 'title-2' | 'title-1' | 'large-title' | 'display';
 
+/**
+ * The active (virtually focused) item of a composite that keeps DOM focus on one element and points
+ * `aria-activedescendant` at the active item: a combobox, a listbox that holds focus, a command
+ * palette. The state is React state, so the active id is derived during render (server HTML
+ * included) and nothing reads the DOM during render.
+ *
+ * - The moved-to item is dropped when it leaves `items` or while `enabled` is `false`, and does not
+ *   come back without a user action; `fallback` is active while nothing was moved to.
+ * - Keyboard and programmatic moves are scrolled into view (`{ block: 'nearest' }`); pointer moves
+ *   (`highlight`) and `setActiveValue(value, { scroll: false })` are not.
+ * - `onActiveValueChange` reports every change after the commit, once (StrictMode included).
+ *
+ * `useListbox` is built on it; use it directly for composites that are not listboxes.
+ *
+ * @example
+ * const ad = useActiveDescendant({ items: results.map((r) => r.id), getId: (id) => `cmd-${id}`, enabled: open });
+ * <input aria-activedescendant={ad.activeDescendantId} onKeyDown={(e) => { if (e.key === 'ArrowDown') ad.next(); }} />
+ */
+export declare function useActiveDescendant(options: UseActiveDescendantOptions): UseActiveDescendantResult;
+
+/** Options of {@link useActiveDescendant}. */
+export declare interface UseActiveDescendantOptions {
+    /** The values that can become active, in navigation order. */
+    items: readonly string[];
+    /** The DOM id of an item's element: the `aria-activedescendant` target. */
+    getId: (value: string) => string;
+    /**
+     * While `false`, no item is active and the moved-to item is forgotten (a closed popup, an
+     * unfocused list). A move made in the same update that enables the hook is kept.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * The active item while none was moved to, or after the moved-to item left `items` (the
+     * selected option, for example). Ignored when it is not in `items`.
+     * @default null
+     */
+    fallback?: string | null;
+    /** `next()` and `prev()` wrap at the ends. @default false */
+    loop?: boolean;
+    /**
+     * Whenever `items` changes while the hook is enabled (compared by content), its first item
+     * becomes active — also when the change comes with enabling (the keystroke that opens a
+     * filtered list). Enabling with unchanged items keeps the fallback. It wins over a move made in
+     * the same update.
+     * @default false
+     */
+    activateFirstOnChange?: boolean;
+    /** The element of an item, for scrolling it into view. @default document.getElementById(getId(value)) */
+    getElement?: (value: string) => HTMLElement | null;
+    /** Called after the active item changed (from an effect), `null` included. */
+    onActiveValueChange?: (value: string | null) => void;
+}
+
+/** Result of {@link useActiveDescendant}. The methods have stable identities. */
+export declare interface UseActiveDescendantResult {
+    /** The moved-to item, else the fallback; `null` while disabled. Derived during render. */
+    activeValue: string | null;
+    /** `getId(activeValue)`, or `undefined`: spread as `aria-activedescendant`. */
+    activeDescendantId: string | undefined;
+    /**
+     * Moves to `value`, or back to the fallback with `null`. The value is kept as it is; the next
+     * render drops it when it is not in that render's `items` or the hook is disabled, clearing any
+     * earlier move. Scrolled into view unless `scroll` is `false`.
+     */
+    setActiveValue: (value: string | null, options?: {
+        scroll?: boolean;
+    }) => void;
+    /**
+     * Moves to `value` for pointer movement, not scrolled into view; ignored while disabled, when
+     * `value` is not in `items` or is already active.
+     */
+    highlight: (value: string) => void;
+    /** Moves to the first item. */
+    first: () => void;
+    /** Moves to the last item. */
+    last: () => void;
+    /** The item after the active one (the first when none is active); wraps with `loop`. */
+    next: () => void;
+    /** The item before the active one (the last when none is active); wraps with `loop`. */
+    prev: () => void;
+    /**
+     * Moves `delta` items (PageDown: `move(10)`), clamped at the ends, never wrapping; from no active
+     * item, a positive delta goes to the first item and a negative one to the last.
+     */
+    move: (delta: number) => void;
+}
+
 /**
  * Returns {@link announce} and keeps the shared live regions alive while the caller is mounted
  * (they are created on mount and removed when the last caller unmounts).
@@ -11345,6 +12942,401 @@ export declare function useIsOverflowing(target: React_2.RefObject<HTMLElement |
  */
 export declare function useIsOverflowItemVisible(itemId: string): boolean;
 
+/**
+ * The listbox behaviour of Listbox, Combobox, Dropdown, TagPicker and TimePicker, and the base of a
+ * custom picker: one navigable option list drives the highlight, `aria-activedescendant` and the
+ * commit, so the highlighted option is always the one Enter selects. The highlight is
+ * {@link useActiveDescendant}'s.
+ *
+ * - **Items.** Data mode (`items`) or registration mode: `Option`s, or option components of your
+ *   own on {@link useListboxOption}, register inside the listbox's context (`context`, which
+ *   `ListboxSurface` and `ListboxProvider` provide) in DOM order, `OptionGroup`s included. The
+ *   registrations of one commit are published once from this hook's layout effect (which runs
+ *   after the options'); later additions/removals are published once per microtask. A keyed
+ *   reorder of the same options re-sorts them: the DOM order is re-checked after a commit of this
+ *   hook's component that moved option elements (a highlight move moves none, so it costs O(1))
+ *   and, while it is mounted, whenever option elements move (a `MutationObserver` on their
+ *   common ancestor) — so memoized options or hoisted elements that a wrapper component inside
+ *   the listbox reorders are re-sorted too, although neither the options nor this component
+ *   render. Options register even when filtered out or hidden (they render `hidden` and are not
+ *   navigable), so labels are always known — use {@link collectOptionLabels} for the display text
+ *   before registration (SSR/first render). `filter` is the navigability predicate, which a
+ *   picker builds from its query.
+ * - **Active option** is derived during render: the highlighted value, else the `autoHighlight`
+ *   fallback. The highlight is reset on close and after a single-select commit that closes the
+ *   listbox, and dropped once it is not navigable any more (filtered out, hidden, removed by an
+ *   update, or disabled without `disabledOptionsFocusable`), so it does not come back without a
+ *   user action when the option returns. With
+ *   `highlightOnFilter` the first option becomes active whenever the options change while open
+ *   (`useActiveDescendant`'s `activateFirstOnChange`). Editable: a text-editing key (printable
+ *   characters, Backspace/Delete, cut/paste/undo/redo) clears the highlight — visual focus
+ *   returns to the textbox (APG) — so Enter after typing never commits an option highlighted
+ *   before the edit; with `highlightOnFilter` the key makes the first option active instead.
+ * - **Ids** `${listboxId}-opt-${n}` are stable per value (across filtering and remounts between
+ *   an inline closed list and a portaled open list).
+ * - **Store.** Options read their active/selected/hidden flags through a store, so moving the
+ *   highlight re-renders only the old and the new option.
+ * - **Keys (APG).** Editable: ArrowDown/ArrowUp open (selected, else first/last) and move;
+ *   Alt+ArrowDown opens without moving; Alt+ArrowUp closes; Enter commits the active option (with
+ *   the listbox closed Enter is not prevented, so forms submit); Escape closes (closed + text:
+ *   `onClearDraft`); Tab closes; Home/End/printable keys stay with the input (text-editing keys
+ *   clear the highlight, see above). Select-only:
+ *   ArrowDown/ArrowUp/Home/End/typeahead open and position (a closed typeahead starts from the
+ *   selected option; characters typed with AltGr, i.e. Ctrl+Alt on Windows, count); PageUp/PageDown
+ *   jump 10; Enter/Space open or commit (always prevented on keydown, Space also on keyup, so a
+ *   `<button>` combobox is not clicked again; a Space typed within 500 ms of a typeahead character
+ *   continues the search instead); Alt+ArrowUp and Tab commit and close in single-select mode
+ *   (with `multiselect` they only close; Tab is not prevented); Escape closes. Standalone (the
+ *   list has focus; nothing opens or closes): ArrowDown/ArrowUp move (from no active option to
+ *   the first/last), Home/End, PageUp/PageDown (10) and typeahead move; Enter and Space commit
+ *   and keep the committed option active (a Space typed within 500 ms of a typeahead character
+ *   continues the search instead); Tab, Escape and Alt+Arrow keys are not handled and not
+ *   prevented, so the page and enclosing layers get them.
+ *   "Selected" means the first selected navigable option in list order. Disabled options are
+ *   skipped unless `disabledOptionsFocusable`, and never committed; hidden options are not
+ *   navigable at all.
+ * - The active option is scrolled into view (`{ block: 'nearest' }`) in a layout effect, except
+ *   after a pointer highlight or a pointer press (the list would scroll under the pointer).
+ *
+ * **Consumer contract** (Listbox, Combobox, Dropdown, TagPicker, TimePicker and custom pickers):
+ * - All options of a listbox live in a single container at a time (inline only while closed,
+ *   portaled only while open — never both, not even for an exit animation; `ListboxSurface` does
+ *   this). Options split over two containers are watched from `<body>` and registered twice
+ *   (development warns).
+ * - Spread `getComboboxProps()` onto the combobox element and attach **both** `onKeyDown` and
+ *   `onKeyUp` to it (compose them with your own handlers). `onKeyUp` is required for a
+ *   `<button>` combobox (select-only): without it the button's native click on Space keyup
+ *   toggles the listbox again after a keydown commit.
+ * - Registration mode: mark option and group components of your own with
+ *   {@link markListboxElement} (`Option` and `OptionGroup` are marked; memo components can be
+ *   marked too). {@link collectOptionLabels} walks only marked components, so without the marks
+ *   the server render and the first client render have no display text.
+ * - Display text: `getItem(value)?.label ?? collectOptionLabels(children).get(value)` (`?? value`
+ *   for freeform input only). Editable pickers pass `onClearDraft` for Escape on a closed list.
+ * - A popup list renders in `ListboxSurface`, placed and dismissed by `useListboxPopup`; a list
+ *   rendered without it gets the options' context from `ListboxProvider`.
+ * - Standalone mode (a listbox that holds focus): spread `getListboxProps()` onto the list and
+ *   merge its `ref` with yours (a pointer press on an option focuses the list through it), attach
+ *   `onKeyDown` to the list and pass the list's focus state as `open`. `getComboboxProps()` is not
+ *   used.
+ */
+export declare function useListbox(options: UseListboxOptions): UseListboxResult;
+
+/**
+ * An option of the surrounding listbox, for option components of your own: the listbox's context
+ * comes from `ListboxSurface` or `ListboxProvider` ({@link UseListboxResult.context}). Registers
+ * the option (registration mode) and its element, and reads its flags from the listbox store, so
+ * it re-renders only when its own active/selected/hidden state changes. Spread `optionProps` onto
+ * the `<li>` (`id`, `role="option"`, `aria-selected`, `aria-disabled`, `hidden`, and
+ * `data-active`/`data-selected`/`data-disabled` for styling) and compose its `onClick` — and in
+ * standalone mode its `onMouseDown`, the pointer press — with your own handlers. Mark the
+ * component with {@link markListboxElement}, so its label is known before it registers.
+ *
+ * Throws in development when used outside a listbox; in production it logs the error once and
+ * renders an inert option.
+ *
+ * @typeParam E The option element type (`HTMLLIElement` for an `<li>`), so `ref` needs no cast.
+ */
+export declare function useListboxOption<E extends HTMLElement = HTMLElement>(props: UseListboxOptionProps, ref?: React_2.Ref<E>): UseListboxOptionResult<E>;
+
+/**
+ * Props of {@link useListboxOption}. The option's position in the listbox follows its element's
+ * DOM position, also when the option is memoized and only moved (see {@link useListbox}).
+ */
+export declare interface UseListboxOptionProps {
+    /** The option's value, unique within the listbox. */
+    value: string;
+    /**
+     * Display label; falls back to `textValue`, then the element's text content, then `value`. The
+     * text content is re-read after every render of the option. Text that a child component changes
+     * from its own state (without the option re-rendering) is not seen; pass `label` or `textValue`
+     * for such options.
+     */
+    label?: string;
+    /** Text matched by typeahead and filters instead of the label. */
+    textValue?: string;
+    /**
+     * The option can never be committed; the keys skip it unless the listbox has
+     * {@link UseListboxOptions.disabledOptionsFocusable}.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * The option is hidden (its own `hidden` attribute, or a hidden group around it): it registers
+     * as a hidden item ({@link ListboxItem.hidden}), so it is not navigable, and
+     * `optionProps.hidden` is set from the first render (server included).
+     * @default false
+     */
+    hidden?: boolean;
+}
+
+/** Result of {@link useListboxOption}. */
+export declare interface UseListboxOptionResult<E extends HTMLElement = HTMLElement> {
+    /** The option's stable id. */
+    id: string;
+    /** Whether the option is selected. */
+    selected: boolean;
+    /** Whether the option is active (keyboard or pointer highlight). */
+    active: boolean;
+    /** Whether the option is disabled. */
+    disabled: boolean;
+    /** Filtered out, or hidden by its own props ({@link UseListboxOptionProps.hidden}). */
+    hidden: boolean;
+    /** Whether the surrounding listbox is {@link UseListboxOptions.multiselect}. */
+    multiselect: boolean;
+    /** Spread onto the option element (see {@link ListboxOptionElementProps}). */
+    optionProps: ListboxOptionElementProps<E>;
+}
+
+/** Options of {@link useListbox}. */
+export declare interface UseListboxOptions {
+    /**
+     * Whether the listbox is shown. You own the open state: `onOpenChange` asks you to change it.
+     * Standalone mode: whether the list has focus — an option is active only while it does.
+     */
+    open: boolean;
+    /**
+     * Called when a key (or a commit) wants to open or close the listbox. `details.reason` says why
+     * (`'keyboard'`, `'select'` — a commit that closes the list —, `'escape'` or `'tab'`) and
+     * `details.event` is the key or click event behind it. WaveUI always passes `details`; it is
+     * typed optional until 1.0 so that code which calls this prop itself keeps compiling. Never
+     * called in standalone mode.
+     */
+    onOpenChange?: (open: boolean, details?: OpenChangeDetails<ListboxOpenChangeReason>) => void;
+    /**
+     * `'editable'`: a text input combobox (Combobox, TagPicker, TimePicker).
+     * `'select-only'`: a button/div combobox without text entry (Dropdown).
+     * `'standalone'`: a listbox that holds focus itself (Listbox), with nothing to open or close:
+     * `open` is its focus state, the keys move and commit (a commit keeps the committed option
+     * active), Tab, Escape and Alt+Arrow keys are left to the page, `onOpenChange` is never called,
+     * and a pointer press on an option focuses the list and activates the option without scrolling
+     * (see {@link UseListboxResult.getListboxProps}).
+     */
+    mode: 'editable' | 'select-only' | 'standalone';
+    /**
+     * Several values can be selected: the list gets `aria-multiselectable`, and a commit keeps the
+     * listbox open on the committed option (your `onSelect` adds or removes the value).
+     * @default false
+     */
+    multiselect?: boolean;
+    /** The selected values (`[]` when nothing is selected). */
+    selectedValues: readonly string[];
+    /**
+     * Called when an option is committed: click, Enter/Space, and in single-select select-only mode
+     * also Tab and Alt+ArrowUp (with `multiselect` they close without committing). `details.item` is
+     * the committed option and `details.event` the key or click event behind the commit. WaveUI
+     * always passes `details`; it is typed optional until 1.0 so that code which calls this prop
+     * itself keeps compiling.
+     */
+    onSelect: (value: string, details?: ListboxSelectDetails) => void;
+    /**
+     * Data mode: the options, in list order. Omit it for registration mode, where the options
+     * register themselves in DOM order: `Option`s, or option components of your own on
+     * {@link useListboxOption}, rendered inside the listbox's context
+     * ({@link UseListboxResult.context}, which `ListboxSurface` and `ListboxProvider` provide).
+     */
+    items?: readonly ListboxItem[];
+    /**
+     * The navigability predicate: an item it returns `false` for is filtered out — left out of the
+     * keys, typeahead and {@link UseListboxResult.items}, never active, and rendered `hidden` as a
+     * registered option (its label stays known). It is never called for a hidden item, which stays
+     * out anyway. A picker builds it from its query, the text typed so far: by default, Combobox
+     * keeps the options whose `textValue ?? label` contains it, ignoring case, and a component with
+     * a `filter(option, query)` prop builds this predicate by binding its current query to it.
+     * Without it, every item that is not hidden is navigable.
+     */
+    filter?: (item: ListboxItem) => boolean;
+    /** Arrow keys wrap around at the ends. @default false */
+    loop?: boolean;
+    /**
+     * Printable characters move to the matching option (on by default in select-only and standalone
+     * mode).
+     * @default mode !== 'editable'
+     */
+    typeahead?: boolean;
+    /**
+     * Keeps disabled options in the arrow-key, Home/End, PageUp/PageDown and typeahead order: they
+     * still cannot be committed (Enter, Space and a click do nothing and the list stays open), and
+     * while one is active, Tab and Alt+ArrowUp in single-select select-only mode close the listbox
+     * without a commit. The `autoHighlight` fallback may then be a disabled option too.
+     * @default false
+     */
+    disabledOptionsFocusable?: boolean;
+    /**
+     * The option that is active while no option is highlighted: `'selected'` — the first selected
+     * navigable option in list order (not in `selectedValues` order), else the first option;
+     * `'first'` — the first option; `false` — none. A highlighted option that leaves the navigable
+     * set is dropped (the fallback takes over, also when the option returns); in editable mode a
+     * text-editing key clears the highlight.
+     * @default 'selected'
+     */
+    autoHighlight?: 'selected' | 'first' | false;
+    /**
+     * Whenever the options the keys reach (the navigable ones, the disabled ones only with
+     * `disabledOptionsFocusable`) change while open, compared by content — as when typing filters
+     * them — the first of them becomes active, also when the update that opens the listbox changes
+     * them (compared with those before opening, as the keystroke that opens a filtered list does).
+     * Opening with unchanged options keeps the `autoHighlight` start. It sets
+     * {@link useActiveDescendant}'s `activateFirstOnChange`. In editable mode every text-editing key
+     * while open makes the first option active as well, also when the options stay the same.
+     * @default false
+     */
+    highlightOnFilter?: boolean;
+    /**
+     * Called after the active (highlighted) option changes — arrow keys, typeahead, the pointer, a
+     * filter change, opening — and with `null` when the listbox closes. Passed straight through to
+     * {@link useActiveDescendant}'s `onActiveValueChange`.
+     */
+    onActiveValueChange?: (value: string | null) => void;
+    /** Prefix of the generated listbox id. @default 'listbox' */
+    idPrefix?: string;
+    /**
+     * Editable: Escape with the listbox closed and text in the input calls this (and prevents the
+     * default), so you can clear the typed text. Not handled when omitted.
+     */
+    onClearDraft?: () => void;
+}
+
+/**
+ * Dismissal and positioning of a custom picker's listbox popup, for {@link ListboxSurface}. The
+ * popup is dismissed by Escape, by a press outside your picker and its surface, and by focus
+ * leaving them (`onDismiss` says which). The surface opens below the anchor and as wide as it,
+ * flips above it when there is no room below, and is limited to the space available; its
+ * `data-side` and `data-align` attributes give the final placement.
+ *
+ * While the listbox is open with nothing to show (`surfaceOpen` is `false`), Escape is left to an
+ * enclosing layer, such as a Dialog around the picker. Let your combobox's key handler leave it
+ * too: on such an Escape, set your open state to `false` without calling `listbox.onKeyDown`,
+ * which handles Escape (and prevents its default) whenever the listbox is open. Do so only when
+ * `!event.nativeEvent.isComposing`, as Dropdown, Combobox and TagPicker do: an Escape that only
+ * cancels an IME composition must not close the listbox, and `listbox.onKeyDown` ignores such
+ * keys too.
+ *
+ * @example
+ * const expanded = open && listbox.items.length > 0;
+ * const { layerId, setReference, surfaceRef, floatingProps } = useListboxPopup({
+ *   open,
+ *   surfaceOpen: expanded,
+ *   onDismiss: () => setOpen(false),
+ *   rootRef,
+ *   anchorRef: buttonRef,
+ * });
+ * const buttonMergedRef = useMergedRefs(buttonRef, setReference);
+ */
+export declare function useListboxPopup(options: UseListboxPopupOptions): UseListboxPopupResult;
+
+/** Options of {@link useListboxPopup}. */
+export declare interface UseListboxPopupOptions {
+    /**
+     * The listbox is open (your open state). While it is, a press outside your picker and its
+     * surface, and focus leaving them, dismiss it.
+     */
+    open: boolean;
+    /**
+     * The surface is shown (the list, or the empty content of {@link ListboxSurface}): it is
+     * positioned, and Escape dismisses it. While the listbox is open with nothing shown (no options
+     * to show), Escape is left to an enclosing layer, such as a Dialog around the picker.
+     */
+    surfaceOpen: boolean;
+    /**
+     * Called when the popup should close: set your open state to `false`. `reason` is `'escape'`,
+     * `'outside-press'` or `'focus-outside'`.
+     */
+    onDismiss: (reason: DismissReason) => void;
+    /** Your picker's root element: presses and focus inside it are not outside the popup. */
+    rootRef: React_2.RefObject<HTMLElement | null>;
+    /**
+     * The combobox element, which anchors the popup's dismiss layer. Pass the element to
+     * `setReference` too (merged into its ref), which places the surface against it.
+     */
+    anchorRef: React_2.RefObject<HTMLElement | null>;
+}
+
+/**
+ * Result of {@link useListboxPopup}. Destructure it: `eslint-plugin-react-hooks` treats an object
+ * with a member passed to a `ref` prop as a ref, and rejects reading its other members during
+ * render (`react-hooks/refs`).
+ */
+export declare interface UseListboxPopupResult {
+    /** The popup's dismiss layer: pass it to {@link ListboxSurface}. */
+    layerId: string;
+    /**
+     * Ref callback for the element the surface is placed against: merge it into your combobox's ref.
+     */
+    setReference: (el: HTMLElement | null) => void;
+    /** Ref callback for the surface: pass it to {@link ListboxSurface}. */
+    surfaceRef: React_2.RefCallback<HTMLElement>;
+    /** The surface's `data-side`, `data-align` and position style: pass them to {@link ListboxSurface}. */
+    floatingProps: {
+        'data-side': string;
+        'data-align': string;
+        style: React_2.CSSProperties;
+    };
+}
+
+/** Result of {@link useListbox}. */
+export declare interface UseListboxResult {
+    /** Id of the listbox element. */
+    listboxId: string;
+    /**
+     * The active (highlighted) option, derived during render; `null` while closed (in standalone
+     * mode, while the list does not have focus).
+     */
+    activeValue: string | null;
+    /** `getOptionId(activeValue)` while open and an option is active. */
+    activeDescendantId: string | undefined;
+    /**
+     * The navigable items in DOM/data order: without filtered-out and hidden items; disabled ones
+     * are included (navigation skips them, unless
+     * {@link UseListboxOptions.disabledOptionsFocusable}).
+     */
+    items: ListboxItem[];
+    /** Unfiltered lookup (registered options or `items`), e.g. for the selected option's label. */
+    getItem(value: string): ListboxItem | undefined;
+    /** `${listboxId}-opt-${n}`; `n` is assigned the first time a value is seen and never changes. */
+    getOptionId(value: string): string;
+    /**
+     * Highlights `value` while open, scrolled into view like a keyboard highlight; `null` returns the
+     * highlight to the `autoHighlight` option. The value is checked in the next render: if it is not
+     * navigable then (disabled options count as not navigable unless
+     * {@link UseListboxOptions.disabledOptionsFocusable}), it is dropped like `null`, and the
+     * highlight returns to the `autoHighlight` option, or to none. A kept value is dropped when it
+     * leaves the navigable set later. A value set while closed survives only when the same update
+     * opens the listbox.
+     */
+    setActiveValue(value: string | null): void;
+    /**
+     * Attach to the combobox element (to the list in standalone mode). Ignores key events a handler
+     * of yours already prevented (compose yours first).
+     */
+    onKeyDown(event: React_2.KeyboardEvent): void;
+    /**
+     * Attach to the combobox element next to `onKeyDown`. Required for a `<button>` combobox
+     * (select-only): it prevents the Space keyup, so the native click does not toggle the listbox
+     * again after the keydown opened or committed.
+     */
+    onKeyUp(event: React_2.KeyboardEvent): void;
+    /**
+     * Props for the combobox element (spread them): its role, `aria-expanded`, `aria-controls`,
+     * `aria-haspopup`, `aria-activedescendant` while an option is active and, in editable mode,
+     * `aria-autocomplete`. Not used in standalone mode, where the list itself has focus.
+     */
+    getComboboxProps(): ListboxComboboxProps;
+    /**
+     * Props for the listbox element (spread them). The combobox modes: `tabIndex: -1` and an
+     * `onMouseDown` that keeps focus on the combobox while options are clicked. Standalone mode:
+     * `tabIndex: 0`, `aria-activedescendant` while an option is active, and a `ref` (merge it with
+     * yours: a pointer press on an option focuses the list through it), without `onMouseDown`.
+     * Both: `aria-multiselectable` with `multiselect`.
+     */
+    getListboxProps(): ListboxListProps;
+    /**
+     * The context of the listbox's options: `ListboxSurface` provides it; for a list you render
+     * yourself, pass it to `ListboxProvider` around the options.
+     */
+    context: ListboxContextValue;
+}
+
 /**
  * Merges several refs into one callback ref whose identity never changes (React 19 cleanup-aware,
  * like {@link mergeRefs}, which merges refs without a hook).