@mortenbrudvik/waveui 0.8.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`.
  *
@@ -1116,9 +1414,12 @@ export declare interface CarouselProps extends React_2.HTMLAttributes<HTMLDivEle
  *   `labelPosition="before"` (the root carries `data-label-position`). The box lines up with the
  *   first line of a label that wraps or has a second line. `children` are not rendered (a
  *   development warning says so).
+ * - `size` (`medium`, `large`) and `shape` (`square`, `circular`) set the box's dimensions and
+ *   corners; the root carries `data-size` and `data-shape`. Checkbox does not read a surrounding
+ *   `Field`'s size or a `WaveProvider`'s input defaults.
  */
 export declare const Checkbox: {
-    ({ checked: checkedProp, defaultChecked, indeterminate, onCheckedChange, onChange, disabled, disabledFocusable, label, labelPosition, name, value, required, form, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, "aria-errormessage": ariaErrorMessage, "aria-details": ariaDetails, "aria-disabled": ariaDisabled, autoFocus, tabIndex, onClick, onFocus, onBlur, onKeyDown, onKeyUp, controlRef, className, children, ref, ...rest }: CheckboxProps): React_2.JSX.Element;
+    ({ checked: checkedProp, defaultChecked, indeterminate, onCheckedChange, onChange, disabled, disabledFocusable, label, labelPosition, size, shape, name, value, required, form, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, "aria-errormessage": ariaErrorMessage, "aria-details": ariaDetails, "aria-disabled": ariaDisabled, autoFocus, tabIndex, onClick, onFocus, onBlur, onKeyDown, onKeyUp, controlRef, className, children, ref, ...rest }: CheckboxProps): React_2.JSX.Element;
     displayName: string;
 };
 
@@ -1188,6 +1489,18 @@ export declare interface CheckboxProps extends Omit<React_2.HTMLAttributes<HTMLL
      * @default 'after'
      */
     labelPosition?: CheckboxLabelPosition;
+    /**
+     * Size of the box: an 18px box (the 0.7 look) or a 22px box with a bigger glyph. Unlike the
+     * text controls and pickers, Checkbox does not read a surrounding Field's size or a
+     * WaveProvider's input defaults: this prop is the only source of its size.
+     * @default 'medium'
+     */
+    size?: CheckboxSize;
+    /**
+     * Shape of the box: square corners (the 0.7 look) or a circular, round box.
+     * @default 'square'
+     */
+    shape?: CheckboxShape;
     /**
      * Form field name. With a name, the checkbox takes part in native form submission: it submits
      * `name=value` while checked.
@@ -1217,6 +1530,12 @@ export declare interface CheckboxProps extends Omit<React_2.HTMLAttributes<HTMLL
     ref?: React_2.Ref<HTMLLabelElement>;
 }
 
+/** Shape of the box: square corners (the 0.7 look) or a circular, round box. */
+export declare type CheckboxShape = Extract<Shape, 'square' | 'circular'>;
+
+/** Size of the box: an 18px box (the 0.7 look) or a 22px box with a bigger glyph. */
+export declare type CheckboxSize = Extract<Size, 'medium' | 'large'>;
+
 /**
  * Checked items of a menu or toolbar, per group `name`: `{ sort: ['date'], view: ['ruler', 'grid'] }`.
  * A checkbox or switch item (or a toolbar toggle) is checked while its `value` is in
@@ -1258,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
@@ -1751,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
@@ -1758,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`,
@@ -1769,19 +2186,20 @@ 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,
+ * then `WaveProvider inputDefaults.appearance`, else `'outline'`; both render as `data-size` and
+ * `data-appearance` on the root `<div>`. The listbox keeps its size.
  *
  * 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
@@ -1800,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.
@@ -1817,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. */
@@ -1826,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;
@@ -1859,23 +2322,91 @@ 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.
      * @default false
      */
     disabled?: boolean;
+    /**
+     * 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.
+     */
+    size?: CoreSize;
+    /**
+     * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
+     * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
+     * label). Default: `WaveProvider inputDefaults.appearance`, else `'outline'`.
+     */
+    appearance?: InputAppearance;
     /**
      * Whether the typed text is itself the value. Without it, typing only filters the options (the
      * 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?: boolean;
-    /** Name of the value in form submissions (renders a hidden input). */
+    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
+     */
+    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;
@@ -1890,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,
@@ -1901,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;
@@ -1916,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>;
@@ -2047,6 +2587,12 @@ export declare interface CompoundButtonOwnProps {
  */
 export declare type CompoundButtonProps<C extends React_2.ElementType = 'button'> = PolymorphicProps<C, CompoundButtonOwnProps>;
 
+/**
+ * The three-step size of text inputs, pickers, Field and Label (Fluent's field sizes): `small`
+ * (24px tall), `medium` (32px) and `large` (40px).
+ */
+export declare type CoreSize = Extract<Size, 'small' | 'medium' | 'large'>;
+
 /**
  * A small pill showing a count (unread messages, notifications), or with `dot` a small dot
  * without a number. Renders nothing for a count of 0 (unless `showZero`) or less, and
@@ -2503,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"`.
@@ -2516,6 +3067,10 @@ export declare interface DataGridUncontrolledSortProps extends NoDeprecatedSortP
  *   clear button that disappears.
  * - Every emitted date is local midnight. The calendar opens on the month of the selected date or
  *   today, clamped into `minDate`/`maxDate`.
+ * - **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, then `WaveProvider inputDefaults.appearance`, else `'outline'`; both render as
+ *   `data-size` and `data-appearance` on the root `<div>`. The calendar keeps its size.
  * - The input (`controlRef`) receives `id`, `aria-label`, `aria-labelledby`, `aria-describedby`,
  *   `aria-invalid`, `aria-required`, `aria-errormessage`, `aria-details`, `tabIndex`,
  *   `autoFocus`, `onFocus`/`onBlur`/`onKeyDown`/`onKeyUp` and the text input attributes
@@ -2538,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";
@@ -2552,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'
      */
@@ -2575,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
@@ -2657,6 +3226,18 @@ export declare interface DatePickerProps extends Omit<React_2.HTMLAttributes<HTM
      * @default false
      */
     disabled?: boolean;
+    /**
+     * 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
+     * calendar keeps its size.
+     */
+    size?: CoreSize;
+    /**
+     * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
+     * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
+     * label). Default: `WaveProvider inputDefaults.appearance`, else `'outline'`.
+     */
+    appearance?: InputAppearance;
     /**
      * Makes the input read-only: the calendar does not open and the value cannot change. Turning it
      * (or `disabled`) on while the user is typing drops the typed text.
@@ -2673,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.
@@ -2726,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.
@@ -3032,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.
  *
@@ -3342,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`
@@ -3351,19 +4004,20 @@ 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,
+ * then `WaveProvider inputDefaults.appearance`, else `'outline'`; both render as `data-size` and
+ * `data-appearance` on the root `<div>`. The listbox keeps its size.
  *
  * 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
@@ -3380,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.
@@ -3389,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. */
@@ -3398,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;
@@ -3427,19 +4125,58 @@ 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)`).
      * @default false
      */
     disabled?: boolean;
-    /** Name of the value in form submissions (renders a hidden input). */
+    /**
+     * 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; the multi-select value text and clear button follow it.
+     */
+    size?: CoreSize;
+    /**
+     * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
+     * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
+     * label). Default: `WaveProvider inputDefaults.appearance`, else `'outline'`.
+     */
+    appearance?: InputAppearance;
+    /**
+     * 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;
@@ -3447,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>;
@@ -3470,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.
@@ -3483,6 +4286,17 @@ export declare interface DropdownProps extends Omit<React_2.HTMLAttributes<HTMLD
  * - `orientation="horizontal"` puts the label in a start column beside the control, with the
  *   message and the hint below the control. The label lines up with the first line of the
  *   control (a Checkbox, Switch or RadioGroup gets 6px of padding above and below for it).
+ * - `size` sets the label's type ramp and, in the horizontal layout, its top padding and the
+ *   padding that lines a Checkbox, Switch or RadioGroup row up with it, so the label's first
+ *   line keeps lining up with a 24, 32 or 40px control. The message and the hint stay small.
+ *   Controls inside read the prop from `FieldContext` as their own default `size` (their own
+ *   `size` wins); the Field's own label falls back to `WaveProvider inputDefaults.size`, else
+ *   `medium`, and the root always renders that resolved value as `data-size`.
+ * - `label` also takes a `Label` or `InfoLabel` element, which renders in place of Field's own
+ *   `<label>` with the Field's wiring (see `label`); an InfoLabel's info button sits next to the
+ *   label text, outside the `<label>`, so the control is named by the text alone. A group control
+ *   (RadioGroup, your own `<div role="radiogroup">`) is named through `aria-labelledby` pointing
+ *   at that `<label>`.
  * - Provides `FieldContext`: the library's inputs (Input, Select, Textarea, Slider, SearchBox,
  *   Checkbox, Switch, RadioGroup, Rating, SpinButton, pickers, …) read it wherever they are inside
  *   the Field and are named by the label, described by the message and the hint and marked
@@ -3543,6 +4357,13 @@ export declare interface DropdownProps extends Omit<React_2.HTMLAttributes<HTMLD
  * </Field>
  *
  * @example
+ * // An InfoLabel as the label: the input is named "Password", the info button
+ * // "Password Information".
+ * <Field label={<InfoLabel info="Use 12 characters or more.">Password</InfoLabel>} required>
+ *   <Input type="password" />
+ * </Field>
+ *
+ * @example
  * // A wrapper component goes inside a plain element.
  * <Field label="Name" required>
  *   <div>
@@ -3553,7 +4374,7 @@ export declare interface DropdownProps extends Omit<React_2.HTMLAttributes<HTMLD
  * </Field>
  */
 export declare const Field: {
-    ({ label, hint, error, validationState, validationMessage, validationMessageIcon, orientation, required, htmlFor, className, children, ref, ...rest }: FieldProps): React_2.JSX.Element;
+    ({ label, hint, error, validationState, validationMessage, validationMessageIcon, orientation, size, required, htmlFor, className, children, ref, ...rest }: FieldProps): React_2.JSX.Element;
     displayName: string;
 };
 
@@ -3621,6 +4442,12 @@ export declare interface FieldContextValue {
      * `errorId` is set only while that message is an error.
      */
     validationMessageId?: string;
+    /**
+     * The Field's own `size` prop, when set: the default size of the text inputs and pickers inside
+     * it (their own `size` wins). Absent when the Field has no `size` (the controls then fall back to
+     * `WaveProvider inputDefaults`) and in contexts built before 0.9.
+     */
+    size?: CoreSize;
 }
 
 /**
@@ -3683,6 +4510,18 @@ export declare interface FieldProps extends React_2.HTMLAttributes<HTMLDivElemen
     /**
      * Label displayed above the control (beside it with `orientation="horizontal"`); names the
      * control.
+     *
+     * A `Label` or `InfoLabel` element passed as `label` renders in place of Field's own `<label>`,
+     * never inside it, and names the control by its label text alone (an InfoLabel's info button
+     * sits next to the `<label>`, outside it). Field always points it at the control (`htmlFor`),
+     * and gives it the Field's label id, `required`, label `size` and `weight="semibold"` (the look
+     * of Field's own label), each only where the element leaves it unset; Field's layout classes go
+     * before the element's `className`, so the element's classes win. The element's own `htmlFor`
+     * is read like the Field's `htmlFor` (which wins over it): it becomes the control's id when the
+     * control has none, and one that points at another element is replaced, with a development
+     * warning. Field shows no asterisk of its own next to such an element: the element shows its
+     * `required` indicator. Only the element itself is recognized, not one inside a Fragment, an
+     * array or another element.
      */
     label?: React_2.ReactNode;
     /** Hint shown below the control, after any validation message; describes the control. */
@@ -3725,6 +4564,12 @@ export declare interface FieldProps extends React_2.HTMLAttributes<HTMLDivElemen
      * @default 'vertical'
      */
     orientation?: Orientation;
+    /**
+     * The label's size and the default `size` of the text inputs and pickers inside the Field
+     * (their own `size` wins; choice controls keep theirs). The message and the hint stay small.
+     * @default `WaveProvider` `inputDefaults.size`, else `'medium'`.
+     */
+    size?: CoreSize;
     /**
      * Whether the field is required: shows a decorative asterisk next to the label, sets
      * `aria-required`, and turns on native constraint validation. `<input>`, `<select>`,
@@ -3737,13 +4582,21 @@ export declare interface FieldProps extends React_2.HTMLAttributes<HTMLDivElemen
     required?: boolean;
     /**
      * The id of the control the label points at, when the control has no `id` of its own
-     * (default: a generated id).
+     * (default: the `htmlFor` of a `Label` or `InfoLabel` element passed as `label`, else a
+     * generated id).
      */
     htmlFor?: string;
     /** Ref to the root `<div>`. */
     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.
  *
@@ -3816,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.
  *
@@ -3973,50 +4850,215 @@ export declare interface ImageProps extends React_2.ImgHTMLAttributes<HTMLImageE
 export declare type ImageShape = Shape;
 
 /**
- * A label with an info button that reveals additional information (a "toggletip").
+ * 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).
+ *
+ * - **Naming.** The button is named "Information" (`aria-label`, which localizes it). Next to a
+ *   heading or other text, pass `aria-labelledby` with that text's id and the button's own `id`:
+ *   the button is then named "‹text› Information", so several info buttons on a page are told
+ *   apart. The note (`role="note"`) is labelled like the button: by the same `aria-labelledby`
+ *   ids, else by the button. The button has `aria-expanded`, and `aria-controls` while the note is
+ *   open, but no `aria-haspopup`: a note is none of the popup kinds it names.
+ * - **Opening.** A click pins the note open, and a click on a pinned note closes it. With
+ *   `openOnHover` (the default) a mouse pointer resting on the button opens it after 250 ms, and
+ *   it closes 250 ms after the pointer has left the button and the note (a pointer moving
+ *   diagonally from the button into the note keeps it open; touch and pen never hover); keyboard
+ *   focus on the button opens it too, while focus that comes from a pointer press waits for the
+ *   click. A hover close moves no focus, and a note that keyboard focus opened or keeps never
+ *   closes because of pointer movement. Opening never moves focus. Escape, a press outside and
+ *   focus moving outside the button and the note close it; Escape returns focus to the button when
+ *   it was in the note, and a dismissed note opens again on keyboard focus only once focus has
+ *   left both.
+ * - **Tab path.** The note is portaled, but it keeps its place right after the button in the
+ *   keyboard order: Tab from the open button enters the note's first element (a link in it), Tab
+ *   past its last element continues after the button, and Shift+Tab from its first element
+ *   returns to the button.
+ * - **One copy of `info`.** While the note is closed, `info` renders next to the button in an
+ *   element that is not displayed and describes the button (`aria-describedby`), so it is in the
+ *   server HTML and is read when the button takes focus. While the note is shown, `info` renders
+ *   only inside it, in an unnamed element that describes the button. `info` is never in the
+ *   document twice, so content with ids or effects is safe; it remounts each time the note opens
+ *   and closes, so state inside it starts over and its effects run again.
+ * - **Structure.** The button is the root element: `ref`, `className`, `style` and every other
+ *   attribute go to it, the consumer's handlers first. The description and the note render next
+ *   to it, never inside it. Its box is 24×24px at every `size` and renders `data-size`. The note
+ *   mounts through the presence core: it carries `data-presence`, `data-state` (`open`, and
+ *   `closed` while it exits, `inert`) and the `data-wave-infolabel-surface` marker; it ships no
+ *   motion of its own.
+ *
+ * Fluent's InfoButton takes the same `info` and `size`. It opens on click only
+ * (`openOnHover={false}` here), renders its note in place, and moves focus into the note; this one
+ * keeps focus on the button and renders the note in a portal. Fluent's `popover` props and a
+ * controlled open state are not offered.
  *
- * - The info button is a `<button type="button">` named `infoButtonLabel` ("Information"). The
- *   info text is rendered inline in a `hidden` element and linked with `aria-describedby`, so it is
- *   announced from the first render (also after server rendering), whether the popup is open or not.
- * - The visual popup is portaled only while open. It is `aria-hidden` because it duplicates the
- *   description, and it holds no focusable content, so focus stays on the button.
- * - Opens on keyboard focus (not on focus that comes from a pointer press), on hover after a
- *   short delay (the popup itself can be hovered) and on click. A click pins it: a click while it is
- *   open because of hover or focus keeps it open, a click on a pinned popup closes it.
- * - Closes on Escape, on a press outside, when focus moves elsewhere and — unless pinned — when
- *   the pointer leaves or the button loses focus (WCAG 1.4.13). A popup opened by hover that then
- *   receives keyboard focus stays open while the button keeps focus, even after the pointer leaves.
+ * @example
+ * <h2 id="billing">Billing</h2>
+ * <InfoButton
+ *   id="billing-info"
+ *   aria-labelledby="billing billing-info"
+ *   info={<>Invoices are sent monthly. <a href="/help/billing">Learn more</a></>}
+ * />
+ */
+export declare const InfoButton: {
+    ({ info, size: sizeProp, openOnHover, id: idProp, type, "aria-label": ariaLabelProp, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, className, disabled, onClick, onFocus, onBlur, onKeyDown, onPointerDown, onMouseDown, onPointerEnter, onPointerMove, onPointerLeave, ref, ...rest }: InfoButtonProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * InfoButton: `root` on the `<button>`; `info` on the `role="note"` popup that shows your `info`
+ * (Fluent's `info` slot, the popover surface); `beak` on its arrow.
+ */
+export declare const infoButtonClassNames: {
+    readonly root: "wave-info-button";
+    readonly info: "wave-info-button__info";
+    readonly beak: "wave-info-button__beak";
+};
+
+/** Properties for the InfoButton component. */
+export declare interface InfoButtonProps extends Omit<React_2.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+    /**
+     * The information the note shows: text, links or other content. It also describes the button
+     * (`aria-describedby`), from the server HTML on. It is rendered once: next to the button, not
+     * displayed, while the note is closed, and inside the note while it is shown.
+     */
+    info: React_2.ReactNode;
+    /**
+     * Size of the glyph: 12, 16 or 20px. The button box stays 24×24px at every size, with negative
+     * margins above and below, so it never makes a row that centres its items (as InfoLabel does)
+     * taller.
+     * @default 'medium'
+     */
+    size?: CoreSize;
+    /**
+     * Open the note when a mouse pointer rests on the button (after 250 ms; it closes 250 ms after
+     * the pointer has left the button and the note, touch and pen never hover), and when the button
+     * receives keyboard focus. `false` opens it only on a click, and so on Enter and Space (Fluent's
+     * InfoButton opens on click only). A click always toggles the note: it pins a note that hover or
+     * keyboard focus opened, and closes a pinned one.
+     * @default true
+     */
+    openOnHover?: boolean;
+    /**
+     * Accessible name of the button, and of the note, which is labelled like the button. Localize it
+     * here. With `aria-labelledby` listing the id of your text and the button's own `id`, the name is
+     * your text followed by this one ("Billing Information").
+     * @default 'Information'
+     */
+    'aria-label'?: string;
+    /** Ref to the button. */
+    ref?: React_2.Ref<HTMLButtonElement>;
+}
+
+/**
+ * A label followed by a button that reveals more information about it (Fluent's InfoLabel): the
+ * label renders in a real `<label htmlFor>`, and the button shows `info` — text, links or other
+ * rich content — in a note next to it, rendered once whether the note is open or closed (see
+ * `InfoButton`, which owns that note and its opening, closing and Tab order).
+ *
+ * - `children` is the label content; `label` is a deprecated alias (a warning fires once, and
+ *   `children` wins when both are given).
+ * - `htmlFor`, `required`, `size`, `weight` and `disabled` route to the `<label>`; `disabled` dims
+ *   only the label text, and the info button stays usable.
+ * - The button is named "‹label text› ‹infoButtonLabel›" through `aria-labelledby`, which points
+ *   at the `<label>` and at the button's own id (whose `aria-label` supplies the second half), so
+ *   several InfoLabels on a page are told apart; `infoButtonLabel` localizes that second half.
+ *   `openOnHover` and `size` reach the button too.
+ * - No `controlRef`: InfoLabel is a label, not a form control, so C-ROUTING's composite-control
+ *   routing does not apply to it; a layout that needs the button's own element renders `InfoButton`
+ *   next to a `Label` instead.
  *
  * @example
- * <InfoLabel label="Password" info="Use at least 8 characters." />
+ * <InfoLabel info="Use at least 8 characters.">Password</InfoLabel>
  */
 export declare const InfoLabel: {
-    ({ label, info, infoButtonLabel, className, ref, ...props }: InfoLabelProps): React_2.JSX.Element;
+    ({ children, label, info, infoButtonLabel, openOnHover, id, htmlFor, required, size, weight, disabled, className, ref, ...rest }: InfoLabelProps): React_2.JSX.Element;
     displayName: string;
 };
 
-/** InfoLabel: `root` on the outer span; `infoButton` on the info button; `info` on its popup. */
+/**
+ * InfoLabel: `root` on the outer span; `label` on its Label (which also carries Label's root);
+ * `infoButton` on its InfoButton (which also carries InfoButton's root); `info` on the popup, the
+ * InfoButton's note (which also carries InfoButton's `info`).
+ */
 export declare const infoLabelClassNames: {
     readonly root: "wave-info-label";
+    readonly label: "wave-info-label__label";
     readonly infoButton: "wave-info-label__info-button";
     readonly info: "wave-info-label__info";
 };
 
 /** Properties for the InfoLabel component. */
-export declare interface InfoLabelProps extends React_2.HTMLAttributes<HTMLSpanElement> {
-    /** Primary label text to display. */
-    label: string;
+export declare interface InfoLabelProps extends Omit<React_2.HTMLAttributes<HTMLSpanElement>, 'children'>, Pick<LabelProps, 'htmlFor' | 'required' | 'size' | 'weight' | 'disabled'> {
+    /** The label content (Fluent's `children`). */
+    children?: React_2.ReactNode;
     /**
-     * Additional information about the label. It describes the info button
-     * (`aria-describedby`, available from the first render) and is shown in a popup on hover,
-     * keyboard focus or click.
+     * The label content.
+     * @deprecated Use `children`.
      */
-    info: string;
+    label?: React_2.ReactNode;
+    /** The information the info button's note shows: text, links or other rich content. */
+    info: React_2.ReactNode;
     /**
-     * Accessible name of the info button. Localise it here.
+     * Accessible name of the info button: the second half of its name, after the label text
+     * ("Password Information"). Localize it here.
      * @default 'Information'
      */
     infoButtonLabel?: string;
+    /**
+     * Opens the note on a mouse hover, after a short delay, and on keyboard focus, next to a click
+     * (see `InfoButton`'s `openOnHover`, which this passes through unchanged).
+     * @default true
+     */
+    openOnHover?: boolean;
     /** Ref to the root `<span>`. */
     ref?: React_2.Ref<HTMLSpanElement>;
 }
@@ -4027,6 +5069,12 @@ export declare interface InfoLabelProps extends React_2.HTMLAttributes<HTMLSpanE
  * optional error message. Inside a `Field` it picks up the label, hint, error, `required` (native
  * attribute) and invalid state automatically.
  *
+ * `size` resolves from its own prop, then the surrounding `Field`'s `size`, then
+ * `WaveProvider inputDefaults.size`, else `'medium'`; `appearance` from its own prop, then
+ * `WaveProvider inputDefaults.appearance`, else `'outline'`; both render as `data-size` and
+ * `data-appearance` on the element that draws the field (the `<input>`, or the wrapper with slot
+ * content).
+ *
  * Every prop reaches the `<input>`, except with slot content: then a bordered `<span>` wrapper
  * draws the field and receives `className`, `style` and `hidden` (`ref` stays on the input).
  *
@@ -4036,10 +5084,16 @@ export declare interface InfoLabelProps extends React_2.HTMLAttributes<HTMLSpanE
  * </Field>
  */
 export declare const Input: {
-    ({ error, errorMessageProps, contentBefore, contentAfter, onChange, onValueChange, className, ref, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, "aria-errormessage": ariaErrorMessage, required, ...props }: InputProps): React_2.JSX.Element;
+    ({ error, errorMessageProps, size: sizeProp, htmlSize, appearance: appearanceProp, contentBefore, contentAfter, onChange, onValueChange, className, ref, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, "aria-errormessage": ariaErrorMessage, required, ...props }: InputProps): React_2.JSX.Element;
     displayName: string;
 };
 
+/**
+ * Look of a text input or picker: `outline` (a full border), `underline` (a bottom stroke only),
+ * `filled-darker` or `filled-lighter` (a fill without a visible stroke).
+ */
+export declare type InputAppearance = 'outline' | 'underline' | 'filled-darker' | 'filled-lighter';
+
 /**
  * Input: `root` on the `<input>`, or, with `contentBefore` or `contentAfter` content, on the
  * wrapper that draws the field; `input` on the `<input>` (also when it is the root);
@@ -4054,6 +5108,14 @@ export declare const inputClassNames: {
     readonly errorMessage: "wave-input__error-message";
 };
 
+/** Default size and appearance of the text inputs and pickers in a subtree. */
+export declare interface InputDefaults {
+    /** Default `size` of Input, Textarea, Select, SearchBox, SpinButton and the pickers. */
+    size?: CoreSize;
+    /** Default `appearance` of the same controls. */
+    appearance?: InputAppearance;
+}
+
 /**
  * Props of the error message element that {@link Input}, `Select` and `Textarea` render after the
  * control for a string `error` (`id`, `className`, `role`, data attributes, …).
@@ -4066,7 +5128,7 @@ export declare interface InputErrorMessageProps extends React_2.HTMLAttributes<H
 }
 
 /** Properties for the Input component. */
-export declare interface InputProps extends React_2.InputHTMLAttributes<HTMLInputElement> {
+export declare interface InputProps extends Omit<React_2.InputHTMLAttributes<HTMLInputElement>, 'size'> {
     /**
      * Validation error.
      * - A non-empty string renders the message in a `role="alert"` element **after** the field (a
@@ -4084,6 +5146,24 @@ export declare interface InputProps extends React_2.InputHTMLAttributes<HTMLInpu
     error?: string | boolean;
     /** Props of the error message element (`id`, `className`, …) rendered for a string `error`. */
     errorMessageProps?: InputErrorMessageProps;
+    /**
+     * Size of the field: `small` (24px tall), `medium` (32px) or `large` (40px). Default: the
+     * surrounding Field's `size`, else `WaveProvider inputDefaults.size`, else `'medium'`.
+     *
+     * A number is the native `size` attribute (the visible width in characters), as in 0.8: it
+     * still renders, warns once in development and is removed in 1.0. Use `htmlSize` for it.
+     * A string of digits only (`size="20"` from untyped code) counts as that number. Any other value
+     * outside the three sizes renders as if `size` were not set.
+     */
+    size?: CoreSize | number;
+    /** The native `size` attribute: the visible width of the field in characters. */
+    htmlSize?: number;
+    /**
+     * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
+     * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
+     * label). Default: `WaveProvider inputDefaults.appearance`, else `'outline'`.
+     */
+    appearance?: InputAppearance;
     /**
      * Slot rendered before the input text (e.g., an icon). With content in either slot, a bordered
      * `<span>` around the input draws the field: it receives `className`, `style` and `hidden`,
@@ -4102,9 +5182,12 @@ export declare interface InputProps extends React_2.InputHTMLAttributes<HTMLInpu
     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
- * asterisk is decorative (`aria-hidden`). `Field` renders its own label; use `Label` for custom
+ * indicator is decorative (`aria-hidden`). `Field` renders its own label; use `Label` for custom
  * layouts.
  *
  * @example
@@ -4131,11 +5214,12 @@ export declare type LabelPosition = 'before' | 'after' | 'above' | 'below';
 
 /** Properties for the Label component. */
 export declare interface LabelProps extends React_2.LabelHTMLAttributes<HTMLLabelElement> {
-    /** Whether to show a required indicator asterisk (hidden from assistive technology; mark the
-     * control itself `required`).
+    /** Whether to show a required indicator. `true` shows a decorative asterisk; other content
+     * replaces it (for example a `(required)` text). Decorative (`aria-hidden`), so it must not be
+     * focusable; mark the control itself `required`.
      * @default false
      */
-    required?: boolean;
+    required?: boolean | React_2.ReactNode;
     /** Whether the label is visually dimmed.
      * @default false
      */
@@ -4143,7 +5227,7 @@ export declare interface LabelProps extends React_2.LabelHTMLAttributes<HTMLLabe
     /** Text size of the label: `small` = caption-1, `medium` = body-1, `large` = body-2.
      * @default 'medium'
      */
-    size?: Extract<Size, 'small' | 'medium' | 'large'>;
+    size?: CoreSize;
     /** Font weight of the label (the shared `TextWeight` vocabulary).
      * @default 'regular'
      */
@@ -4276,6 +5360,475 @@ export declare const List: {
     };
 };
 
+/**
+ * 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 const listboxSurfaceClassNames: {
+    readonly root: "wave-listbox-surface";
+    readonly list: "wave-listbox-surface__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 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: {
     readonly root: "wave-list";
@@ -4373,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:
  *
@@ -5785,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
@@ -5798,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";
@@ -5830,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.
@@ -5844,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;
@@ -5857,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
@@ -6852,29 +8465,51 @@ export declare interface RadioItemProps extends Omit<React_2.ButtonHTMLAttribute
 /**
  * A star rating input (`role="radiogroup"` of `role="radio"` stars).
  *
- * - One tab stop (the chosen star, else the first). Keys choose relative to the current rating and
- *   move focus to the chosen star, as in 0.4: Right/Up one star more, Left/Down one fewer
- *   (Left/Right mirrored under `dir="rtl"`), Home/End the first/last star. From an empty rating,
- *   Right/Up/Home choose 1 star. Keys at the ends (and Left/Down while empty) emit nothing.
- * - The keyboard cannot clear a rating: Left/Down stop at 1 star (APG radio group; 0.4 went down
+ * - One tab stop (the radio of the chosen value, else the first). Keys choose relative to the
+ *   current rating and move focus to the chosen radio, as in 0.4: Right/Up one `step` more (a
+ *   star, or half a star), Left/Down one fewer (Left/Right mirrored under `dir="rtl"`), Home the
+ *   smallest value (`step`) and End `max`. From an empty rating, Right/Up/Home choose `step`.
+ *   Keys at the ends (and Left/Down while empty) emit nothing.
+ * - The keyboard cannot clear a rating: Left/Down stop at `step` (APG radio group; 0.4 went down
  *   to 0). Only a controlled `value={0}` (or a form reset while `defaultValue` is 0) clears it.
+ * - `step={0.5}` offers half stars. Each star stays one pointer target, which chooses by the
+ *   pointer's position (its half from the inline start, else its full value) and then focuses
+ *   the radio it chose; it holds two transparent radios ("2.5 stars", "3 stars") for the
+ *   keyboard and screen readers, and draws the focus ring of either. A controlled value between
+ *   two steps checks no radio and is drawn as the step below it; the keys move it to the next or
+ *   previous step.
  * - `onValueChange` (and the deprecated `onChange` alias) fire only when the rating changes, so
  *   choosing the current star again calls neither.
- * - Hovering previews a value; the preview never outlives the hover or a disabled state.
+ * - Hovering previews a value (half stars preview by the pointer's position); the preview never
+ *   outlives the hover or a disabled state.
+ * - `color` colors the filled stars (`marigold`, the default, `brand` or `neutral`; the root
+ *   carries `data-color`); `iconFilled` and `iconOutline` replace the star glyphs, as a pair.
  * - Inside a `Field` it is named by the Field label (instead of the default "Rating") and
- *   described by its hint and error. The stars are named "1 star", "2 stars", …; `labels`
- *   localizes these names.
+ *   described by its hint and error. The stars are named "1 star", "2 stars", … (and a half value
+ *   "2.5 stars"); `labels` localizes these names.
  * - With `name` (or `required`) it takes part in native forms; a form reset restores
  *   `defaultValue`.
+ * - The stars are generated from `max`. Children that render content replace them: one
+ *   `Rating.Item` per value from 1 to `max`, chosen, previewed, roved and named as the generated
+ *   stars are (`max` still sets the key range and the star names).
+ *
+ * Sub-component: `Rating.Item` (the same component as `RatingDisplay.Item`). React Server
+ * Components import its flat name `RatingItem` (dotted access needs a client file).
  */
 export declare const Rating: {
-    ({ value: valueProp, defaultValue, onValueChange, onChange, max, size, disabled, name, required, form, labels, className, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, onKeyDown, onFocus, onMouseLeave, ref, ...rest }: RatingProps): React_2.JSX.Element;
+    ({ value: valueProp, defaultValue, onValueChange, onChange, max, step: stepProp, size, color, iconFilled, iconOutline, disabled, name, required, form, labels, className, children, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, onKeyDown, onFocus, onMouseLeave, ref, ...rest }: RatingProps): React_2.JSX.Element;
     displayName: string;
+} & {
+    Item: {
+        ({ value, iconFilled, iconOutline, className, ref, ...rest }: RatingItemProps): React_2.JSX.Element;
+        displayName: string;
+    };
 };
 
 /**
- * Rating: `root` on the `role="radiogroup"` element; `star` on each `role="radio"` button; `icon`
- * on each star `<svg>`.
+ * Rating: `root` on the `role="radiogroup"` element; `star` on each star (a RatingItem: the
+ * `role="radio"` button, or with `step={0.5}` the span around its two radios); `icon` on each
+ * star glyph (the default `<svg>`, or the span of your `iconFilled`/`iconOutline`).
  */
 export declare const ratingClassNames: {
     readonly root: "wave-rating";
@@ -6882,6 +8517,9 @@ export declare const ratingClassNames: {
     readonly icon: "wave-rating__icon";
 };
 
+/** Color of a rating's filled stars. */
+export declare type RatingColor = 'neutral' | 'brand' | 'marigold';
+
 /**
  * A read-only star rating (`role="img"` named "Rating: <value> out of <max>"). A fractional value
  * is drawn with a partly filled star, so the stars and the name show the same value.
@@ -6891,15 +8529,29 @@ export declare const ratingClassNames: {
  *   stars (the root carries `data-compact`). Without them only the stars show.
  * - The value (up to one decimal) and the count are formatted with `locale`, in the text and in
  *   the name; `labels` localizes the name. Pass `locale` when rendering on the server.
+ * - `color` colors the filled stars (`marigold`, the default, `brand` or `neutral`; the root
+ *   carries `data-color`); `iconFilled` and `iconOutline` replace the star glyphs, as a pair.
+ * - The stars are generated from `max`. Children that render content replace them: one
+ *   `RatingDisplay.Item` per value from 1 to `max`. A `compact` display ignores them.
+ *
+ * Sub-component: `RatingDisplay.Item` (the same component as `Rating.Item`). React Server
+ * Components import its flat name `RatingDisplayItem`, or `RatingItem` (dotted access needs a
+ * client file).
  */
 export declare const RatingDisplay: {
-    ({ value, max, size, showValue, count, compact, locale, labels, className, ref, ...rest }: RatingDisplayProps): React_2.JSX.Element;
+    ({ value, max, size, color, iconFilled, iconOutline, showValue, count, compact, locale, labels, className, children, ref, ...rest }: RatingDisplayProps): React_2.JSX.Element;
     displayName: string;
+} & {
+    Item: {
+        ({ value, iconFilled, iconOutline, className, ref, ...rest }: RatingItemProps): React_2.JSX.Element;
+        displayName: string;
+    };
 };
 
 /**
- * RatingDisplay: `root` on the `role="img"` element; `star` on each star span; `icon` on the star
- * `<svg>` elements; `value` on the value span; `count` on the count span.
+ * RatingDisplay: `root` on the `role="img"` element; `star` on each star span (a RatingItem, and
+ * the one star of `compact`); `icon` on the star glyphs; `value` on the value span; `count` on the
+ * count span.
  */
 export declare const ratingDisplayClassNames: {
     readonly root: "wave-rating-display";
@@ -6909,6 +8561,15 @@ export declare const ratingDisplayClassNames: {
     readonly count: "wave-rating-display__count";
 };
 
+/**
+ * Flat name of `RatingDisplay.Item` for React Server Components (the same component as
+ * `RatingItem`).
+ */
+export declare const RatingDisplayItem: {
+    ({ value, iconFilled, iconOutline, className, ref, ...rest }: RatingItemProps): React_2.JSX.Element;
+    displayName: string;
+};
+
 /** Built-in texts of RatingDisplay, for localization. */
 export declare interface RatingDisplayLabels {
     /**
@@ -6924,7 +8585,7 @@ export declare interface RatingDisplayLabels {
 }
 
 /** Properties for the RatingDisplay (read-only) component. */
-export declare interface RatingDisplayProps extends React_2.HTMLAttributes<HTMLDivElement> {
+export declare interface RatingDisplayProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'color'> {
     /**
      * Rating value to display. A fraction is drawn as a partly filled star (`4.6` fills 60% of the
      * fifth star), so the stars show the value the accessible name reports.
@@ -6938,6 +8599,36 @@ export declare interface RatingDisplayProps extends React_2.HTMLAttributes<HTMLD
      * @default 'medium'
      */
     size?: Size;
+    /**
+     * Color of the filled stars: `marigold` (default), `brand` or `neutral`; unfilled stars keep a
+     * 3:1 outline. Fluent's default is `neutral`. A value outside the three (from untyped code)
+     * renders as `marigold`; the root carries `data-color` with the resolved value.
+     * @default 'marigold'
+     */
+    color?: RatingColor;
+    /**
+     * The glyph of a filled star. `iconFilled` and `iconOutline` are the glyphs of a filled and an
+     * unfilled star, as a pair; decorative. Fluent's RatingDisplay takes one `icon`; here a filled
+     * and an unfilled star must differ by shape, not by color alone.
+     *
+     * - Each glyph is sized by `size` (an SVG child fills the star) and takes the star's color
+     *   (paint it with `currentColor`). A partly filled star clips the filled glyph over the
+     *   unfilled one from the inline start, and the `compact` star is the filled glyph.
+     * - `null`, `undefined` and a value that renders nothing draw the default star. A value that
+     *   renders nothing, and a pair with only one of the two set, log a development warning.
+     * - A `<button>` or `Button` element (or a slot object whose `as` is one) is not nested in the
+     *   star: its children become the glyph (the default star when they render nothing), its props
+     *   are dropped, and a development warning says so (in place of the warning for a value that
+     *   renders nothing).
+     * - A `RatingDisplay.Item` that sets its own pair draws that one instead.
+     */
+    iconFilled?: Slot<'span'>;
+    /**
+     * The glyph of an unfilled star, as a pair with `iconFilled` (its rules apply); decorative.
+     * Fluent's RatingDisplay takes one `icon`; here a filled and an unfilled star must differ by
+     * shape, not by color alone.
+     */
+    iconOutline?: Slot<'span'>;
     /**
      * Shows the value as text after the stars, formatted with `locale` (up to one decimal).
      * @default false
@@ -6962,25 +8653,105 @@ export declare interface RatingDisplayProps extends React_2.HTMLAttributes<HTMLD
     locale?: string;
     /** Built-in texts, for localization. */
     labels?: RatingDisplayLabels;
+    /**
+     * Custom stars: one `RatingDisplay.Item` per value from 1 to `max`, in place of the generated
+     * stars (when the children render content). A `compact` display ignores them.
+     */
+    children?: React_2.ReactNode;
     /** Ref to the root element. */
     ref?: React_2.Ref<HTMLDivElement>;
 }
 
+/**
+ * One star of a `Rating` or a `RatingDisplay`, drawn from its root: pass one per value from 1 to
+ * `max` as the root's children, in place of the stars it generates.
+ *
+ * - In a `Rating` it is a `role="radio"` button named by the root's `labels.star` ("2 stars"),
+ *   chosen, previewed and roved as a generated star is. With the root's `step={0.5}` it is a star
+ *   `<span>`, one pointer target that chooses by the pointer's position, holding two transparent
+ *   radios: its half value, then its full value ("1.5 stars", "2 stars"). In a `RatingDisplay` it
+ *   is a star filled, partly filled or empty by the root's value.
+ * - It draws the root's `color` and glyph pair, or its own `iconFilled`/`iconOutline` pair when it
+ *   sets one.
+ * - `className`, `style`, `data-*`, the other attributes, the handlers and `ref` go to that star
+ *   element, the consumer's handlers first. The role, name, checked state and tab stop of its
+ *   radio (or radios) come from the root.
+ * - At `step={1}` the consumer's `onClick` and `onMouseEnter` compose onto the radio itself, so a
+ *   `preventDefault()` in either vetoes that star's own activation or hover preview. At
+ *   `step={0.5}` `onClick` and `onPointerMove` compose onto the star `<span>` instead: its two
+ *   radios run their own `onClick` first and choose their own value directly (Space, Enter, a
+ *   screen reader, or `radio.click()`), before the click bubbles to the span's composed handler,
+ *   so a `preventDefault()` there vetoes only a pointer-chosen value, never a keyboard or
+ *   assistive-technology activation.
+ * - Outside a `Rating` or `RatingDisplay` it throws in development.
+ */
+export declare const RatingItem: {
+    ({ value, iconFilled, iconOutline, className, ref, ...rest }: RatingItemProps): React_2.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * RatingItem (also Rating.Item, RatingDisplay.Item and RatingDisplayItem): `root` on the star
+ * element (the `role="radio"` button in a Rating, the span around its two radios with
+ * `step={0.5}`, the star span in a RatingDisplay), which also carries its rating's `star` class;
+ * `icon` on each glyph it draws (the default `<svg>`, or the span of an `iconFilled`/`iconOutline`
+ * glyph), which also carries its rating's `icon` class.
+ */
+export declare const ratingItemClassNames: {
+    readonly root: "wave-rating-item";
+    readonly icon: "wave-rating-item__icon";
+};
+
+/** Properties for the RatingItem component (`Rating.Item`, `RatingDisplay.Item`). */
+export declare interface RatingItemProps extends Omit<React_2.HTMLAttributes<HTMLElement>, 'role' | 'aria-checked' | 'aria-label' | 'aria-labelledby' | 'tabIndex' | 'children' | 'onChange'> {
+    /**
+     * The star's full value, from 1 to the root's `max`: the rating it chooses (with the root's
+     * `step={0.5}` also its half, `value - 0.5`), or shows.
+     */
+    value: number;
+    /**
+     * The glyph of this star when filled, as a pair with `iconOutline`, following the rules of the
+     * root's `iconFilled` (a button is unwrapped, its children becoming the glyph, and a value or
+     * button children that render nothing draw the default star). An item that sets either glyph
+     * of the pair (`null` included) draws its own pair instead of its root's, and a glyph it leaves
+     * unset is the default star (a development warning says so).
+     */
+    iconFilled?: Slot<'span'>;
+    /**
+     * The glyph of this star when unfilled, as a pair with `iconFilled`, following the rules of the
+     * root's `iconOutline` (a button is unwrapped, its children becoming the glyph, and a value or
+     * button children that render nothing draw the default star). An item that sets either glyph
+     * of the pair (`null` included) draws its own pair instead of its root's, and a glyph it leaves
+     * unset is the default star (a development warning says so).
+     */
+    iconOutline?: Slot<'span'>;
+    /**
+     * Ref to the star element: the `role="radio"` button in a Rating, the star `<span>` in a Rating
+     * with `step={0.5}` and in a RatingDisplay.
+     */
+    ref?: React_2.Ref<HTMLElement>;
+}
+
 /**
  * The Rating's built-in star names, for localization. Each member is optional and falls back to
  * its English default.
  */
 export declare interface RatingLabels {
     /**
-     * Accessible name of the star that chooses `value` (1 to `max`).
+     * Accessible name of the radio that chooses `value`: a whole star (1 to `max`), and with
+     * `step={0.5}` a half value too ("2.5 stars").
      * @default (value) => value === 1 ? '1 star' : `${value} stars`
      */
     star?: (value: number, max: number) => string;
 }
 
 /** Properties for the Rating component. */
-export declare interface RatingProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
-    /** Controlled rating value (`0` = no rating). */
+export declare interface RatingProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue' | 'color'> {
+    /**
+     * Controlled rating value (`0` = no rating): a whole number of stars, or with `step={0.5}` a
+     * multiple of 0.5. A value between two steps (2.7) checks no radio, is drawn as the step below
+     * it (2.5) and holds the tab stop there; the keys move it to the next or previous step.
+     */
     value?: number;
     /** Initial rating for uncontrolled usage (also the value a form reset restores).
      * @default 0
@@ -6998,10 +8769,50 @@ export declare interface RatingProps extends Omit<React_2.HTMLAttributes<HTMLDiv
      * @default 5
      */
     max?: number;
+    /**
+     * The grain of the rating: `1` (whole stars) or `0.5` (half stars). With `0.5`, each star stays
+     * one pointer target of at least 24×24px (a larger `size` keeps a larger one): the half is
+     * chosen by the pointer's position over it (the half at the inline start, which mirrors under
+     * `dir="rtl"`), and two transparent radios per star, the half value then the full value, serve
+     * the keyboard and screen readers. The keys then move by half a star. A value other than `0.5`
+     * (from untyped code) counts as `1`. RatingDisplay has no `step`: it draws any fraction.
+     * @default 1
+     */
+    step?: 0.5 | 1;
     /** Size of the star icons. Every size keeps a target of at least 24×24px.
      * @default 'medium'
      */
     size?: Size;
+    /**
+     * Color of the filled stars: `marigold` (default), `brand` or `neutral`; unfilled stars keep a
+     * 3:1 outline. Fluent's default is `neutral`. A value outside the three (from untyped code)
+     * renders as `marigold`; the root carries `data-color` with the resolved value.
+     * @default 'marigold'
+     */
+    color?: RatingColor;
+    /**
+     * The glyph of a filled star. `iconFilled` and `iconOutline` are the glyphs of a filled and an
+     * unfilled star, as a pair; decorative. Fluent's RatingDisplay takes one `icon`; here a filled
+     * and an unfilled star must differ by shape, not by color alone.
+     *
+     * - Each glyph is sized by `size` (an SVG child fills the star) and takes the star's color
+     *   (paint it with `currentColor`). A half-filled star (`step={0.5}`) clips the filled glyph
+     *   over the unfilled one from the inline start.
+     * - `null`, `undefined` and a value that renders nothing draw the default star. A value that
+     *   renders nothing, and a pair with only one of the two set, log a development warning.
+     * - A `<button>` or `Button` element (or a slot object whose `as` is one) is not nested in the
+     *   star: its children become the glyph (the default star when they render nothing), its props
+     *   are dropped, and a development warning says so (in place of the warning for a value that
+     *   renders nothing).
+     * - A `Rating.Item` that sets its own pair draws that one instead.
+     */
+    iconFilled?: Slot<'span'>;
+    /**
+     * The glyph of an unfilled star, as a pair with `iconFilled` (its rules apply); decorative.
+     * Fluent's RatingDisplay takes one `icon`; here a filled and an unfilled star must differ by
+     * shape, not by color alone.
+     */
+    iconOutline?: Slot<'span'>;
     /** Whether the rating is disabled and non-interactive.
      * @default false
      */
@@ -7016,10 +8827,16 @@ export declare interface RatingProps extends Omit<React_2.HTMLAttributes<HTMLDiv
     /** Id of the form the rating belongs to, when it is rendered outside that form. */
     form?: string;
     /**
-     * Names of the stars ("1 star", "2 stars", …), for localization. The group's own name is
-     * `aria-label` (default "Rating"). Unset members keep their English defaults.
+     * Names of the stars ("1 star", "2 stars", …, and "2.5 stars" for a half value), for
+     * localization. The group's own name is `aria-label` (default "Rating"). Unset members keep
+     * their English defaults.
      */
     labels?: RatingLabels;
+    /**
+     * Custom stars: one `Rating.Item` per value from 1 to `max`, in place of the generated stars
+     * (when the children render content). `max` still sets the key range and the star names.
+     */
+    children?: React_2.ReactNode;
     /** Ref to the `role="radiogroup"` element. */
     ref?: React_2.Ref<HTMLDivElement>;
 }
@@ -7110,12 +8927,16 @@ export declare interface RovingContainerProps {
  *   the label, hint, error and required state automatically.
  * - **Forms**: with `name` the text is submitted with the form; a form reset restores
  *   `defaultValue`.
+ * - **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, then `WaveProvider inputDefaults.appearance`, else `'outline'`; both render as
+ *   `data-size` and `data-appearance` on the root `<div>`.
  *
  * @example
  * <SearchBox aria-label="Search files" value={query} onValueChange={setQuery} />
  */
 export declare const SearchBox: {
-    ({ value: controlledValue, defaultValue, onValueChange, onChange, onClear, placeholder, disabled, contentBefore, contentAfter, dismiss, className, ref, controlRef, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, "aria-errormessage": ariaErrorMessage, "aria-details": ariaDetails, required, name, form, readOnly, autoComplete, autoFocus, autoCapitalize, autoCorrect, inputMode, enterKeyHint, spellCheck, maxLength, minLength, pattern, tabIndex, onFocus, onBlur, onKeyDown, onKeyUp, onMouseDown, hidden, ...rest }: SearchBoxProps): React_2.JSX.Element;
+    ({ value: controlledValue, defaultValue, onValueChange, onChange, onClear, placeholder, disabled, size: sizeProp, appearance: appearanceProp, contentBefore, contentAfter, dismiss, className, ref, controlRef, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, "aria-errormessage": ariaErrorMessage, "aria-details": ariaDetails, required, name, form, readOnly, autoComplete, autoFocus, autoCapitalize, autoCorrect, inputMode, enterKeyHint, spellCheck, maxLength, minLength, pattern, tabIndex, onFocus, onBlur, onKeyDown, onKeyUp, onMouseDown, hidden, ...rest }: SearchBoxProps): React_2.JSX.Element;
     displayName: string;
 };
 
@@ -7166,6 +8987,17 @@ export declare interface SearchBoxProps extends Omit<React_2.HTMLAttributes<HTML
     placeholder?: string;
     /** Whether the search box is disabled and non-interactive. */
     disabled?: boolean;
+    /**
+     * Size of the field: `small` (24px tall), `medium` (32px) or `large` (40px). Default: the
+     * surrounding Field's `size`, else `WaveProvider inputDefaults.size`, else `'medium'`.
+     */
+    size?: CoreSize;
+    /**
+     * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
+     * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
+     * label). Default: `WaveProvider inputDefaults.appearance`, else `'outline'`.
+     */
+    appearance?: InputAppearance;
     /**
      * Slot rendered before the text (replaces the default search icon). It takes the room it needs;
      * the text starts after it. A value that renders nothing (`null`, `false`, `''`, an empty array
@@ -7218,6 +9050,11 @@ export declare interface SearchBoxProps extends Omit<React_2.HTMLAttributes<HTML
  * `Field` label, `aria-label` or `aria-labelledby`. Inside a `Field` it picks up the label, hint,
  * error, `required` (native attribute) and invalid state automatically.
  *
+ * `size` resolves from its own prop, then the surrounding `Field`'s `size`, then
+ * `WaveProvider inputDefaults.size`, else `'medium'`; `appearance` from its own prop, then
+ * `WaveProvider inputDefaults.appearance`, else `'outline'`; both render as `data-size` and
+ * `data-appearance` on the `<select>`.
+ *
  * @example
  * <Field label="Country" required>
  *   <Select defaultValue="">
@@ -7227,7 +9064,7 @@ export declare interface SearchBoxProps extends Omit<React_2.HTMLAttributes<HTML
  * </Field>
  */
 export declare const Select: {
-    ({ error, errorMessageProps, className, children, ref, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, "aria-errormessage": ariaErrorMessage, required, ...props }: SelectProps): React_2.JSX.Element;
+    ({ error, errorMessageProps, size: sizeProp, htmlSize, appearance: appearanceProp, className, children, ref, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, "aria-errormessage": ariaErrorMessage, required, ...props }: SelectProps): React_2.JSX.Element;
     displayName: string;
 };
 
@@ -7242,7 +9079,7 @@ declare type SelectionMode_2 = 'single' | 'multiple';
 export { SelectionMode_2 as SelectionMode }
 
 /** Properties for the Select component. */
-export declare interface SelectProps extends React_2.SelectHTMLAttributes<HTMLSelectElement> {
+export declare interface SelectProps extends Omit<React_2.SelectHTMLAttributes<HTMLSelectElement>, 'size'> {
     /**
      * Validation error.
      * - A non-empty string renders the message in a `role="alert"` element **after** the select
@@ -7259,6 +9096,24 @@ export declare interface SelectProps extends React_2.SelectHTMLAttributes<HTMLSe
     error?: string | boolean;
     /** Props of the error message element (`id`, `className`, …) rendered for a string `error`. */
     errorMessageProps?: InputErrorMessageProps;
+    /**
+     * Size of the field: `small` (24px tall), `medium` (32px) or `large` (40px). Default: the
+     * surrounding Field's `size`, else `WaveProvider inputDefaults.size`, else `'medium'`.
+     *
+     * A number is the native `size` attribute (the number of visible rows), as in 0.8: it still
+     * renders, warns once in development and is removed in 1.0. Use `htmlSize` for it.
+     * A string of digits only (`size="20"` from untyped code) counts as that number. Any other value
+     * outside the three sizes renders as if `size` were not set.
+     */
+    size?: CoreSize | number;
+    /** The native `size` attribute: the number of visible rows. */
+    htmlSize?: number;
+    /**
+     * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
+     * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
+     * label). Default: `WaveProvider inputDefaults.appearance`, else `'outline'`.
+     */
+    appearance?: InputAppearance;
     /** Ref to the `<select>` element. */
     ref?: React_2.Ref<HTMLSelectElement>;
 }
@@ -7357,11 +9212,14 @@ export declare interface SkeletonProps extends React_2.HTMLAttributes<HTMLDivEle
  * The fill follows the value through the `--wave-slider-progress` variable on the input (also in
  * the server HTML), including the browser's snapping to `step` and a form reset.
  *
+ * `size` (`small`, `medium`) sets the thumb and rail dimensions; the input carries `data-size`.
+ * Slider does not read a surrounding `Field`'s size or a `WaveProvider`'s input defaults.
+ *
  * @example
  * <Slider label="Volume" min={0} max={100} value={volume} onValueChange={setVolume} />
  */
 export declare const Slider: {
-    ({ className, style, label, value, defaultValue, min, max, step, form, onChange, onValueChange, ref, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, required, ...props }: SliderProps): React_2.JSX.Element;
+    ({ className, style, label, value, defaultValue, min, max, step, size: sizeProp, form, onChange, onValueChange, ref, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, required, ...props }: SliderProps): React_2.JSX.Element;
     displayName: string;
 };
 
@@ -7371,7 +9229,7 @@ export declare const sliderClassNames: {
 };
 
 /** Properties for the Slider component. */
-export declare interface SliderProps extends Omit<React_2.InputHTMLAttributes<HTMLInputElement>, 'type'> {
+export declare interface SliderProps extends Omit<React_2.InputHTMLAttributes<HTMLInputElement>, 'type' | 'size'> {
     /** Controlled slider value. */
     value?: number;
     /** Initial value for uncontrolled usage. */
@@ -7391,10 +9249,25 @@ export declare interface SliderProps extends Omit<React_2.InputHTMLAttributes<HT
      * `Field`, leave it out so the Field's label names the slider.
      */
     label?: string;
+    /**
+     * Size of the thumb and rail: the 0.7 20px thumb on a 4px rail, or a small 16px thumb on a 2px
+     * rail in a 24px-tall input. Unlike the text controls and pickers, Slider does not read a
+     * surrounding `Field`'s size or a `WaveProvider`'s input defaults: this prop is the only source
+     * of its size.
+     *
+     * `SliderProps` inherited the native HTML `size` attribute, which a range input ignores anyway.
+     * A number is deprecated: it renders nothing (not even the native attribute), is reported once
+     * in development, and is a type error from 1.0.
+     * @default 'medium'
+     */
+    size?: SliderSize | number;
     /** Ref to the `<input type="range">` element. */
     ref?: React_2.Ref<HTMLInputElement>;
 }
 
+/** Size of the thumb and rail: a small 16px thumb on a 2px rail, or the 0.7 20px thumb on a 4px rail. */
+export declare type SliderSize = Extract<Size, 'small' | 'medium'>;
+
 /**
  * Slot definition — a customisable sub-element of a component. Accepts:
  *
@@ -7442,14 +9315,26 @@ export declare type SortDirection = 'ascending' | 'descending';
  * A numeric input with decrement/increment buttons (APG spinbutton pattern).
  *
  * - **Keyboard** on the input: ArrowUp/ArrowDown step by `step`, PageUp/PageDown by `largeStep`
- *   (default ten steps), Home/End jump to `min`/`max` when they are finite. The −/+ buttons are
- *   not tab stops and never take focus, so focus stays on the spinbutton and screen readers
- *   announce the new value.
+ *   (default ten steps), Home/End jump to `min`/`max` when they are finite (Shift+Home and
+ *   Shift+End keep their native text-selection instead). The −/+ buttons are not tab stops and
+ *   never take focus, so focus stays on the spinbutton and screen readers announce the new
+ *   value.
+ * - **Pointer** on the −/+ buttons (mouse, touch or pen): a short press steps once, on release
+ *   (its click), never on the press alone, so a finger that starts a scroll on a button changes
+ *   nothing. Holding a button repeats the step: the first after 300ms, then faster, every 80ms
+ *   after about a second (Fluent's timing). A hold stops when the button is released, the
+ *   pointer leaves it or the press turns into a scroll, at the bound, when the window loses
+ *   focus, and when the spin button becomes disabled or read-only. Only the primary button of a
+ *   primary pointer holds: a second finger, a secondary button or a Ctrl+press with a mouse (the
+ *   secondary click on macOS) neither starts a hold nor ends one. A click without a press (a
+ *   screen reader, `element.click()`) steps once. The buttons open no context menu (a long press
+ *   on touch would), show no iOS callout, and allow no text selection or double-tap zoom.
  * - **Typing** edits a draft: the value is parsed, clamped and committed on blur or Enter
  *   (Escape reverts). Text that is not a number is flagged with `aria-invalid` and reverted on
  *   blur. Steps (keys and buttons) start from the typed number, and the −/+ buttons are disabled
  *   when that number is at `min`/`max`. Steps are rounded to the precision of `step` and of the
- *   value, so `0.1 + 0.2` is `0.3`.
+ *   value, so `0.1 + 0.2` is `0.3`; `precision` rounds every committed value, typed or stepped,
+ *   to a fixed number of decimals instead, without padding it (pad with `displayValue`).
  * - **Routing**: `id`, ARIA, native input attributes and focus/keyboard handlers go to the
  *   `<input role="spinbutton">`; `className`, `style`, `data-*`, other handlers and `ref` stay on
  *   the root (`controlRef` reaches the input). Inside a `Field` it picks up the label, hint, error
@@ -7457,16 +9342,119 @@ export declare type SortDirection = 'ascending' | 'descending';
  *   or use a label (development warning otherwise).
  * - **Forms**: with `name` the committed value is submitted; `required` makes the input natively
  *   required; a form reset restores `defaultValue`.
+ * - **Empty values**: `allowEmpty` lets the value become `null` (an empty field). Clearing the
+ *   text and committing it (blur or Enter) sets the value to `null`, uncontrolled too; stepping
+ *   up or down from an empty value starts at 0 and clamps to the nearest bound. `required` (its
+ *   own, or a required Field's) still blocks submitting an empty value: the check runs on the
+ *   `HiddenInput` that carries the committed value, not on the shown text, so it keeps working
+ *   even when the shown text is not empty.
+ * - **Display text**: `displayValue` shows formatted text (`$1.00`) for the value while the field
+ *   is not being edited, and as its `aria-valuetext`; while the field has focus and can be
+ *   edited it shows the plain number instead, so typing still edits the number (a consumer
+ *   `aria-valuetext` always wins). It applies only while `value` is controlled: an uncontrolled
+ *   spin button ignores it and warns once in development.
+ * - **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, then `WaveProvider inputDefaults.appearance`, else `'outline'`; both render as
+ *   `data-size` and `data-appearance` on the root. SpinButton takes every size the other fields
+ *   do, and unlike 0.7 its root is now exactly as tall as theirs, with its step buttons and
+ *   input taking up that height; sizing the root wider widens the input instead of leaving
+ *   empty space inside it. The step buttons keep a 1px separator from the input only in
+ *   `outline`; the other appearances have none.
  * - The −/+ buttons are named "Decrement"/"Increment"; `labels` localizes the names.
  *
  * @example
  * <SpinButton aria-label="Quantity" min={1} max={10} value={qty} onValueChange={setQty} />
  */
 export declare const SpinButton: {
-    ({ value: valueProp, defaultValue, onValueChange, onChange, min, max, step, largeStep, disabled, name, form, labels, className, hidden, ref, controlRef, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, "aria-errormessage": ariaErrorMessage, "aria-details": ariaDetails, "aria-valuetext": ariaValueText, required, readOnly, placeholder, maxLength, spellCheck, autoComplete, autoFocus, inputMode, enterKeyHint, tabIndex, onFocus, onBlur, onKeyDown, onKeyUp, ...rest }: SpinButtonProps): React_2.JSX.Element;
+    (props: SpinButtonProps | SpinButtonAllowEmptyProps): React_2.ReactNode;
     displayName: string;
 };
 
+/** SpinButton props with `allowEmpty`: the value may be `null` (an empty field). */
+export declare interface SpinButtonAllowEmptyProps extends SpinButtonBaseProps {
+    /** The value may be `null`: clearing the text and committing it empties the field. */
+    allowEmpty: true;
+    /** Controlled value; `null` is an empty field. */
+    value?: number | null;
+    /** Initial value for uncontrolled usage (also what a form reset restores).
+     * @default null
+     */
+    defaultValue?: number | null;
+    /** Called with the new value when it changes, `null` when the field is emptied. */
+    onValueChange?: (value: number | null) => void;
+    /** Not available with `allowEmpty` (the deprecated alias of `onValueChange`). */
+    onChange?: never;
+}
+
+/**
+ * Properties every SpinButton mode shares (every member of {@link SpinButtonProps} and
+ * {@link SpinButtonAllowEmptyProps} except the value members, which differ between them).
+ */
+export declare interface SpinButtonBaseProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue' | keyof SpinButtonInputProps>, SpinButtonInputProps {
+    /** Minimum allowed value.
+     * @default -Infinity
+     */
+    min?: number;
+    /** Maximum allowed value.
+     * @default Infinity
+     */
+    max?: number;
+    /** Step of the increment/decrement buttons and of ArrowUp/ArrowDown.
+     * @default 1
+     */
+    step?: number;
+    /** Step of PageUp/PageDown.
+     * @default step * 10
+     */
+    largeStep?: number;
+    /**
+     * Decimals every committed value is rounded to, typed or stepped (0–20); the number is not
+     * padded (use `displayValue` for `1.00`). Default: steps round to the decimals of `step` and
+     * the value, typed values are kept as typed.
+     */
+    precision?: number;
+    /** Whether the spin button is disabled and non-interactive. */
+    disabled?: boolean;
+    /** Form field name. With a name, the committed value is submitted with the form. */
+    name?: string;
+    /** Id of the form the spin button belongs to, when it is rendered outside that form. */
+    form?: string;
+    /**
+     * Names of the −/+ step buttons (not tab stops, but in the accessibility tree), for
+     * localization. Unset members keep their English defaults.
+     */
+    labels?: SpinButtonLabels;
+    /**
+     * Text shown for the value while the field is not being edited, and its `aria-valuetext` (a
+     * `$1.00` for 1). While the field has focus and can be edited it shows the plain number, so
+     * typing edits the number. Applies only while `value` is controlled (update it with the
+     * value); Fluent's `displayValue`.
+     */
+    displayValue?: string;
+    /**
+     * Size of the field: `small` (24px tall), `medium` (32px) or `large` (40px). Default: the
+     * surrounding Field's `size`, else `WaveProvider inputDefaults.size`, else `'medium'`.
+     *
+     * SpinButton is 24, 32 or 40px tall like every field; its buttons are square-ish, 24, 32 or
+     * 40px wide.
+     */
+    size?: CoreSize;
+    /**
+     * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
+     * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a
+     * visible label). Default: `WaveProvider inputDefaults.appearance`, else `'outline'`.
+     *
+     * The step buttons keep a 1px separator from the input only in `outline`; the other
+     * appearances have none.
+     */
+    appearance?: InputAppearance;
+    /** Ref to the root `<div>`. */
+    ref?: React_2.Ref<HTMLDivElement>;
+    /** Ref to the `<input role="spinbutton">` (the focusable control). */
+    controlRef?: React_2.Ref<HTMLInputElement>;
+}
+
 /**
  * SpinButton: `root` on the outer element; `decrementButton` on the − button; `input` on the
  * `role="spinbutton"` input; `incrementButton` on the + button.
@@ -7499,8 +9487,14 @@ export declare interface SpinButtonLabels {
     decrement?: string;
 }
 
-/** Properties for the SpinButton component. */
-export declare interface SpinButtonProps extends Omit<React_2.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue' | keyof SpinButtonInputProps>, SpinButtonInputProps {
+/** SpinButton props with a number value (the 0.7 shape). */
+export declare interface SpinButtonProps extends SpinButtonBaseProps {
+    /**
+     * Allows an empty value (`null`). Takes the literal `true`: a `boolean` variable fits neither
+     * member of the props, so branch the JSX or spread `{ allowEmpty: true, value }`.
+     * @default false
+     */
+    allowEmpty?: false;
     /** Controlled numeric value. */
     value?: number;
     /** Initial value for uncontrolled usage (also what a form reset restores).
@@ -7518,37 +9512,6 @@ export declare interface SpinButtonProps extends Omit<React_2.HTMLAttributes<HTM
      * @deprecated Use `onValueChange`. (`onChange` is reserved for native change events.)
      */
     onChange?: (value: number) => void;
-    /** Minimum allowed value.
-     * @default -Infinity
-     */
-    min?: number;
-    /** Maximum allowed value.
-     * @default Infinity
-     */
-    max?: number;
-    /** Step of the increment/decrement buttons and of ArrowUp/ArrowDown.
-     * @default 1
-     */
-    step?: number;
-    /** Step of PageUp/PageDown.
-     * @default step * 10
-     */
-    largeStep?: number;
-    /** Whether the spin button is disabled and non-interactive. */
-    disabled?: boolean;
-    /** Form field name. With a name, the committed value is submitted with the form. */
-    name?: string;
-    /** Id of the form the spin button belongs to, when it is rendered outside that form. */
-    form?: string;
-    /**
-     * Names of the −/+ step buttons (not tab stops, but in the accessibility tree), for
-     * localization. Unset members keep their English defaults.
-     */
-    labels?: SpinButtonLabels;
-    /** Ref to the root `<div>`. */
-    ref?: React_2.Ref<HTMLDivElement>;
-    /** Ref to the `<input role="spinbutton">` (the focusable control). */
-    controlRef?: React_2.Ref<HTMLInputElement>;
 }
 
 /**
@@ -7819,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';
 
@@ -7983,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).
@@ -8027,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;
@@ -8040,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>`.
@@ -8069,9 +10170,11 @@ export declare type SwatchPickerSize = Extract<Size, 'small' | 'medium' | 'large
  *   `labelPosition` (the root carries `data-label-position`). Beside the label, the switch lines
  *   up with the first line of a label that wraps or has a second line. `children` are not
  *   rendered (a development warning says so).
+ * - `size` (`small`, `medium`) sets the track and thumb dimensions; the root carries `data-size`.
+ *   Switch does not read a surrounding `Field`'s size or a `WaveProvider`'s input defaults.
  */
 export declare const Switch: {
-    ({ checked: checkedProp, defaultChecked, onCheckedChange, onChange, disabled, disabledFocusable, label, labelPosition, name, value, required, form, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, "aria-errormessage": ariaErrorMessage, "aria-details": ariaDetails, "aria-disabled": ariaDisabled, autoFocus, tabIndex, onClick, onFocus, onBlur, onKeyDown, onKeyUp, controlRef, className, children, ref, ...rest }: SwitchProps): React_2.JSX.Element;
+    ({ checked: checkedProp, defaultChecked, onCheckedChange, onChange, disabled, disabledFocusable, label, labelPosition, size, name, value, required, form, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, "aria-errormessage": ariaErrorMessage, "aria-details": ariaDetails, "aria-disabled": ariaDisabled, autoFocus, tabIndex, onClick, onFocus, onBlur, onKeyDown, onKeyUp, controlRef, className, children, ref, ...rest }: SwitchProps): React_2.JSX.Element;
     displayName: string;
 };
 
@@ -8134,6 +10237,14 @@ export declare interface SwitchProps extends Omit<React_2.HTMLAttributes<HTMLLab
      * @default 'after'
      */
     labelPosition?: SwitchLabelPosition;
+    /**
+     * Size of the track: the 0.7 40x20 track with a 14px thumb, or a small 32x16 track with a 10px
+     * thumb and a 24px-tall pointer target. Unlike the text controls and pickers, Switch does not
+     * read a surrounding Field's size or a WaveProvider's input defaults: this prop is the only
+     * source of its size.
+     * @default 'medium'
+     */
+    size?: SwitchSize;
     /**
      * Form field name. With a name, the switch takes part in native form submission: it submits
      * `name=value` while on.
@@ -8163,6 +10274,9 @@ export declare interface SwitchProps extends Omit<React_2.HTMLAttributes<HTMLLab
     ref?: React_2.Ref<HTMLLabelElement>;
 }
 
+/** Size of the track: a 32x16 track with a 10px thumb, or the 0.7 40x20 track with a 14px thumb. */
+export declare type SwitchSize = Extract<Size, 'small' | 'medium'>;
+
 /**
  * A non-interactive data table with an optional striped body. The table sits in a horizontally
  * scrollable wrapper; while it scrolls, the wrapper is a focusable region (named by
@@ -8619,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.
@@ -8634,6 +10751,12 @@ export declare interface TagOwnProps {
  * Selected values without a matching option are shown with their raw value. The open list renders
  * only in the browser: an open list (`defaultOpen`, `open`) is closed in the server HTML and opens
  * once the picker has hydrated.
+ *
+ * **Size and appearance**: `size` resolves from its own prop, then the surrounding `Field`'s
+ * `size`, then `WaveProvider inputDefaults.size`, else `'medium'` (a Field or provider `small`
+ * gives `'medium'` too, since TagPicker has no `small`); `appearance` from its own prop, then
+ * `WaveProvider inputDefaults.appearance`, else `'outline'`; both render as `data-size` and
+ * `data-appearance` on the root `<div>`. The option list keeps its size.
  */
 export declare const TagPicker: {
     (props: TagPickerProps): React_2.JSX.Element;
@@ -8740,12 +10863,55 @@ 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.
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Size of the tags and the field: `medium` (the 0.7 look), `large` or `extra-large` (Fluent's
+     * union; TagPicker has no `small`). Default: the surrounding Field's `size`, else `WaveProvider
+     * inputDefaults.size`, else `'medium'`; a Field or provider `small` gives `'medium'` too. The
+     * option list keeps its size.
+     */
+    size?: TagPickerSize;
+    /**
+     * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
+     * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
+     * label). Default: `WaveProvider inputDefaults.appearance`, else `'outline'`.
+     */
+    appearance?: InputAppearance;
     /** Name of the values in form submissions (one hidden input per value). */
     name?: string;
     /** Id of the form the values belong to, when the TagPicker is outside it. */
@@ -8793,6 +10959,9 @@ export declare interface TagPickerProps extends Omit<React_2.HTMLAttributes<HTML
     ref?: React_2.Ref<HTMLDivElement>;
 }
 
+/** Sizes of TagPicker (Fluent's): medium (the 0.7 look), large and extra-large. */
+export declare type TagPickerSize = Extract<Size, 'medium' | 'large' | 'extra-large'>;
+
 /**
  * Props of {@link Tag} rendered as `C` (default `'span'`). `TagProps` without a type argument is
  * the 0.4 name.
@@ -8975,13 +11144,18 @@ export { Text_2 as Text }
  * bottom border while focused). Inside a `Field` it picks up the label, hint, error, `required`
  * (native attribute) and invalid state automatically.
  *
+ * `size` resolves from its own prop, then the surrounding `Field`'s `size`, then
+ * `WaveProvider inputDefaults.size`, else `'medium'`; `appearance` from its own prop, then
+ * `WaveProvider inputDefaults.appearance`, else `'outline'`; both render as `data-size` and
+ * `data-appearance` on the textarea element.
+ *
  * @example
  * <Field label="Description" hint="Markdown is supported">
  *   <Textarea rows={4} />
  * </Field>
  */
 export declare const Textarea: {
-    ({ error, errorMessageProps, className, ref, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, "aria-errormessage": ariaErrorMessage, required, ...props }: TextareaProps): React_2.JSX.Element;
+    ({ error, errorMessageProps, size: sizeProp, appearance: appearanceProp, className, ref, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, "aria-errormessage": ariaErrorMessage, required, ...props }: TextareaProps): React_2.JSX.Element;
     displayName: string;
 };
 
@@ -9009,6 +11183,18 @@ export declare interface TextareaProps extends React_2.TextareaHTMLAttributes<HT
     error?: string | boolean;
     /** Props of the error message element (`id`, `className`, …) rendered for a string `error`. */
     errorMessageProps?: InputErrorMessageProps;
+    /**
+     * Size of the field, a minimum height with its type ramp: `small` (64px, Caption 1 text),
+     * `medium` (80px, Body 1) or `large` (96px, Body 2). Default: the surrounding Field's `size`,
+     * else `WaveProvider inputDefaults.size`, else `'medium'`.
+     */
+    size?: CoreSize;
+    /**
+     * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
+     * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
+     * label). Default: `WaveProvider inputDefaults.appearance`, else `'outline'`.
+     */
+    appearance?: InputAppearance;
     /** Ref to the `<textarea>` element. */
     ref?: React_2.Ref<HTMLTextAreaElement>;
 }
@@ -9076,6 +11262,10 @@ export declare type TextWeight = 'regular' | 'semibold' | 'bold';
  *   picker instead of to the clear button that disappears.
  * - The value is `HH:mm` (24-hour) whatever the display `format`; values off the `step` grid or
  *   outside the bounds are still displayed in `format`.
+ * - **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, then `WaveProvider inputDefaults.appearance`, else `'outline'`; both render as
+ *   `data-size` and `data-appearance` on the root `<div>`. The time list keeps its size.
  * - The input (`controlRef`) receives `id`, `aria-label`, `aria-labelledby`, `aria-describedby`,
  *   `aria-invalid`, `aria-required`, `aria-errormessage`, `aria-details`, `tabIndex`,
  *   `autoFocus`, `onFocus`/`onBlur`/`onKeyDown`/`onKeyUp` and the text input attributes
@@ -9204,6 +11394,18 @@ export declare interface TimePickerProps extends Omit<React_2.HTMLAttributes<HTM
      * @default false
      */
     disabled?: boolean;
+    /**
+     * 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 time
+     * list keeps its size.
+     */
+    size?: CoreSize;
+    /**
+     * Look of the field: `outline` (a full border), `underline` (a bottom stroke only),
+     * `filled-darker` or `filled-lighter` (a fill without a visible stroke: give the field a visible
+     * label). Default: `WaveProvider inputDefaults.appearance`, else `'outline'`.
+     */
+    appearance?: InputAppearance;
     /**
      * Makes the input read-only: the list does not open and the value cannot change. Turning it (or
      * `disabled`) on while the user is typing drops the typed text.
@@ -10479,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).
@@ -10652,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).
@@ -11015,6 +13700,8 @@ export declare interface WaveContextValue {
     themeClassName: string;
     /** Element portaled overlays render into; `null` means `document.body`. */
     portalContainer: HTMLElement | null;
+    /** The merged input defaults of the providers above (`{}` outside a provider). */
+    inputDefaults: InputDefaults;
     /** `false` when no {@link WaveProvider} is above the caller (the defaults are returned). */
     hasProvider: boolean;
 }
@@ -11038,9 +13725,12 @@ export declare type WaveDir = 'ltr' | 'rtl';
  *   enclosing provider, so `<WaveProvider theme="light">` inside an RTL app is a light panel that
  *   stays right-to-left and keeps the app's portal container. At the top level the defaults are
  *   `'light'`, `'ltr'` and `document.body`.
+ * - `inputDefaults` nests differently: a nested provider's defined keys override the enclosing
+ *   provider's, and an omitted key is inherited, so setting only `appearance` in a nested provider
+ *   keeps the enclosing provider's `size`.
  */
 export declare const WaveProvider: {
-    ({ theme: themeProp, dir: dirProp, portalContainer: portalContainerProp, children, className, ref, ...rest }: WaveProviderProps): React_2.JSX.Element;
+    ({ theme: themeProp, dir: dirProp, portalContainer: portalContainerProp, inputDefaults: inputDefaultsProp, children, className, ref, ...rest }: WaveProviderProps): React_2.JSX.Element;
     displayName: string;
 };
 
@@ -11068,6 +13758,14 @@ export declare interface WaveProviderProps extends React_2.HTMLAttributes<HTMLDi
      * @default the enclosing WaveProvider's container, else document.body
      */
     portalContainer?: HTMLElement | null;
+    /**
+     * Default `size` and `appearance` of the text inputs and pickers in the subtree (Input,
+     * Textarea, Select, SearchBox, SpinButton, Combobox, Dropdown, DatePicker, TimePicker,
+     * TagPicker). Their own props and a Field's `size` win. A nested provider merges its keys over
+     * the enclosing provider's; an omitted key is inherited.
+     * @default the enclosing WaveProvider's defaults, else none (`medium`, `outline`)
+     */
+    inputDefaults?: InputDefaults;
     /** Content rendered inside the themed container. */
     children: React_2.ReactNode;
     /** Ref to the themed root `<div>`. */