@mond-design-system/react 4.12.0 → 5.1.0

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import * as react from 'react';
-import { CSSProperties, HTMLAttributes, JSX, ReactElement, Ref, ReactNode, ButtonHTMLAttributes, ElementType, ComponentPropsWithRef, MouseEventHandler, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, RefObject, KeyboardEvent } from 'react';
+import { CSSProperties, HTMLAttributes, JSX, ReactElement, Ref, ReactNode, ButtonHTMLAttributes, ElementType, ComponentPropsWithRef, MouseEventHandler, InputHTMLAttributes, HTMLInputTypeAttribute, TextareaHTMLAttributes, SelectHTMLAttributes, RefObject, MouseEvent, KeyboardEvent, PointerEvent, FocusEvent } from 'react';
+import { Placement } from '@floating-ui/dom';
 
 /**
  * Join class names, dropping anything falsy.
@@ -612,7 +613,18 @@ interface FieldProps {
 declare function Field({ label, children, hint, error, required, className }: FieldProps): ReactElement;
 
 type InputSize = "sm" | "md" | "lg";
-interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size"> {
+interface InputBaseProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size"> {
+    /** The native input type, passed straight through — the system adds no types
+        of its own, so `email`, `tel`, `url` and `number` behave as the platform
+        defines them, keyboard and validation included. Default "text".
+  
+        One type the component answers to: with `type="search"`, `onClear` takes
+        over the browser's own clear cross, so the field shows one clear
+        affordance rather than two. Without `onClear` the native cross is left
+        alone — there it is the only way to empty the field. */
+    type?: HTMLInputTypeAttribute;
+    /** Control height and type size. The icon slots, the gutter and the clear
+        button all step with it. Default "md". */
     size?: InputSize;
     /** Marks the value as failing validation — sets aria-invalid and the danger
         border. Inside a Field the field's error state does this already. */
@@ -624,20 +636,50 @@ interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size">
     iconRight?: ReactNode;
     ref?: Ref<HTMLInputElement>;
 }
+type ClearEnforcement = {
+    /** Raises a clear button in the trailing slot whenever the field holds
+        text, and runs when it is pressed. An uncontrolled field is emptied
+        for you; a controlled one is yours to empty here. Rules out
+        iconRight — they are the same slot. */
+    onClear: () => void;
+    /** Names that button, e.g. "Clear search". Required: the cross says
+        nothing to a screen reader, and the words are the app's — "Clear
+        search" and "Clear filter" are not interchangeable. */
+    clearLabel: string;
+    iconRight?: undefined;
+} | {
+    onClear?: undefined;
+    clearLabel?: undefined;
+};
+type InputProps = InputBaseProps & ClearEnforcement;
 /**
  * Single-line text input. Inside a Field it inherits id/description/invalid.
  *
+ * Sizes are `sm` / `md` / `lg`; the icon slots and the clear button step with
+ * them. `onClear` folds in what SearchField used to be — pair it with
+ * `type="search"` and it replaces the browser's own clear cross.
+ *
  * ```tsx
  * <Field label="Name">
  *   <Input value={name} onChange={(e) => setName(e.target.value)} />
  * </Field>
  *
  * <Input aria-label="Search" iconLeft={<Icon name="search" />} />
+ *
+ * <Input
+ *   type="search"
+ *   aria-label="Search sessions"
+ *   iconLeft={<Icon name="search" />}
+ *   value={query}
+ *   onChange={(e) => setQuery(e.target.value)}
+ *   clearLabel="Clear search"
+ *   onClear={() => setQuery("")}
+ * />
  * ```
  */
-declare function Input({ size, invalid, iconLeft, iconRight, className, ...rest }: InputProps): ReactElement;
+declare function Input({ size, invalid, iconLeft, iconRight, onClear, clearLabel, className, ref, ...rest }: InputProps): ReactElement;
 
-interface PasswordInputProps extends Omit<InputProps, "type"> {
+interface PasswordInputProps extends Omit<InputProps, "type" | "onClear" | "clearLabel" | "iconRight"> {
     /** Names the reveal button while the password is hidden, e.g. "Show password".
         Required: the button carries no visible text, so this is the only thing a
         screen reader has, and it is the app's language rather than the system's. */
@@ -820,26 +862,6 @@ interface SegmentedControlProps<T extends string = string> {
  */
 declare function SegmentedControl<T extends string = string>({ label, options, value, onChange, disabled, fullWidth, size, bare, repick, className, }: SegmentedControlProps<T>): ReactElement;
 
-interface SearchFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size" | "value" | "onChange"> {
-    /** Accessible name. */
-    label: string;
-    /** Names the clear button, e.g. "Clear search". Required: the button is a
-        glyph, so this is all a screen reader has, and the words are the app's. */
-    clearLabel: string;
-    value: string;
-    /** Receives the new text — "" when cleared. */
-    onChange: (value: string) => void;
-    ref?: Ref<HTMLInputElement>;
-}
-/**
- * Controlled search input with a clear affordance once there is text.
- *
- * ```tsx
- * <SearchField label="Search sessions" clearLabel="Clear search" value={query} onChange={setQuery} />
- * ```
- */
-declare function SearchField({ label, clearLabel, value, onChange, className, ...rest }: SearchFieldProps): ReactElement;
-
 interface ScrollerLabels {
     previous: string;
     next: string;
@@ -1334,6 +1356,141 @@ declare function SheetFooter({ children }: {
     children: ReactNode;
 }): react.JSX.Element;
 
+type PopoverPlacement = Placement;
+interface PopoverProps {
+    open: boolean;
+    onClose: () => void;
+    /** The trigger the panel hangs off. It stays interactive while open. */
+    anchorRef: RefObject<HTMLElement | null>;
+    /** Accessible name of the panel. */
+    label: string;
+    /** Side it prefers. It flips and slides to stay on screen. Default "bottom-start". */
+    placement?: PopoverPlacement;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * Anchored, non-modal surface. The page behind it stays live and scrollable
+ * and the panel travels with the anchor; a press outside, Escape, or the
+ * trigger itself dismisses it.
+ *
+ * Modal by contrast: reach for Modal when the answer must come before anything
+ * else, and for Sheet when the content is a task rather than a detail — a
+ * form with its own header and footer belongs in one of those, not here.
+ *
+ * ```tsx
+ * const anchor = useRef<HTMLButtonElement>(null);
+ * const [open, setOpen] = useState(false);
+ * <Button ref={anchor} aria-expanded={open} onClick={() => setOpen((v) => !v)}>
+ *   Equipment
+ * </Button>
+ * <Popover open={open} onClose={() => setOpen(false)} anchorRef={anchor} label="Equipment">
+ *   <PopoverBody>…</PopoverBody>
+ * </Popover>
+ * ```
+ */
+declare function Popover({ open, onClose, anchorRef, label, placement, className, children, }: PopoverProps): react.ReactPortal | null;
+type PopoverHeaderProps = {
+    children: ReactNode;
+} & ({
+    /** Renders a close button after the title. Wire it to the popover's own onClose. */
+    onClose: () => void;
+    /** Accessible name of the close button (localise). */
+    closeLabel: string;
+} | {
+    onClose?: undefined;
+    closeLabel?: undefined;
+});
+declare function PopoverHeader({ children, onClose, closeLabel }: PopoverHeaderProps): react.JSX.Element;
+declare function PopoverBody({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function PopoverFooter({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+
+type MenuPlacement = Placement;
+/** What Menu needs to be able to put on its trigger. */
+type MenuTriggerProps = {
+    ref?: Ref<HTMLElement> | undefined;
+    "aria-haspopup"?: "menu" | undefined;
+    "aria-expanded"?: boolean | undefined;
+    onClick?: ((event: MouseEvent<HTMLElement>) => void) | undefined;
+    onKeyDown?: ((event: KeyboardEvent<HTMLElement>) => void) | undefined;
+};
+interface MenuProps {
+    /** Accessible name of the menu — what the list of actions is *for*. */
+    label: string;
+    /** The control that opens it. Gets the ref, the ARIA and the key handling. */
+    trigger: ReactElement<MenuTriggerProps>;
+    /** Side it prefers. It flips and slides to stay on screen. Default "bottom-end". */
+    placement?: MenuPlacement;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * A button that opens a short list of actions (APG's menu button).
+ *
+ * Open state is the menu's own: a list of actions has no meaning outside the
+ * button that opened it, so unlike Modal, Sheet and Popover there is nothing
+ * for a caller to hold. Reach for Popover instead the moment the panel holds
+ * anything but actions — a form, a filter, a list of things to read.
+ *
+ * ```tsx
+ * <Menu label="Heat actions" trigger={<Button variant="ghost">Actions</Button>}>
+ *   <MenuItem onSelect={edit}>Edit</MenuItem>
+ *   <MenuItem onSelect={remove} tone="danger">Delete</MenuItem>
+ * </Menu>
+ * ```
+ */
+declare function Menu({ label, trigger, placement, className, children }: MenuProps): react.JSX.Element;
+interface MenuItemProps {
+    /** What the action does. The menu closes itself around it. */
+    onSelect: () => void;
+    disabled?: boolean;
+    /** "danger" for an action that destroys something. Default "default". */
+    tone?: "default" | "danger";
+    children: ReactNode;
+}
+declare function MenuItem({ onSelect, disabled, tone, children }: MenuItemProps): react.JSX.Element;
+
+type TooltipPlacement = Placement;
+/** What Tooltip needs to be able to put on its trigger. */
+type TriggerProps = {
+    ref?: Ref<HTMLElement> | undefined;
+    "aria-describedby"?: string | undefined;
+    onPointerEnter?: ((event: PointerEvent<HTMLElement>) => void) | undefined;
+    onPointerLeave?: ((event: PointerEvent<HTMLElement>) => void) | undefined;
+    onFocus?: ((event: FocusEvent<HTMLElement>) => void) | undefined;
+    onBlur?: ((event: FocusEvent<HTMLElement>) => void) | undefined;
+};
+interface TooltipProps {
+    /** The label. Plain text — nothing here is reachable by pointer or key. */
+    content: ReactNode;
+    /** Side it prefers. It flips and slides to stay on screen. Default "top". */
+    placement?: TooltipPlacement;
+    /** Pointer dwell in ms. Keyboard focus ignores it. Default 400. */
+    delayMs?: number;
+    /** The control being labelled. Gets the ref and the handlers. */
+    children: ReactElement<TriggerProps>;
+}
+/**
+ * A name for a control that shows only its glyph, on hover and on focus.
+ *
+ * It describes; it does not hold anything. There is nothing to click inside
+ * it and focus never moves into it, so anything the reader has to act on —
+ * a link, a button, a form — belongs in a Popover instead. A control whose
+ * label is *only* here still needs an aria-label of its own: this is the
+ * accessible description, not the accessible name.
+ *
+ * ```tsx
+ * <Tooltip content="Remove from heat">
+ *   <Button variant="ghost" aria-label="Remove from heat"><Icon name="x" /></Button>
+ * </Tooltip>
+ * ```
+ */
+declare function Tooltip({ content, placement, delayMs, children, }: TooltipProps): react.JSX.Element;
+
 type ConfirmDialogTone = "default" | "danger" | "warning";
 interface ConfirmDialogProps<T = void> {
     /** The row in question, or null when nothing is being asked. Held by the
@@ -1881,14 +2038,23 @@ declare function Breadcrumb({ items, label, linkAs, className, ...rest }: Breadc
 interface UseOverlayOptions {
     open: boolean;
     onClose: () => void;
+    /**
+     * Freeze the page behind the surface. Default true.
+     *
+     * False for anchored surfaces: a popover is pinned to a trigger that scrolls
+     * with the page, so locking the page would strand it over content the reader
+     * can no longer reach, and locking it *and* letting the popover follow the
+     * anchor are the same gesture answered two ways.
+     */
+    lockScroll?: boolean;
 }
 /**
  * Shared modal-surface behaviour: focus capture and restore, Escape to
  * close, Tab cycling inside the panel, body scroll lock. Attach the
  * returned ref to the dialog element (it needs tabIndex={-1}).
  *
- * Anchor-positioned overlays (Tooltip/Popover) will extend this hook with
- * a floating-ui middleware pass; the options object leaves room for that.
+ * Popover uses it too, with `lockScroll: false`; where it sits on the screen
+ * is a separate question, answered by useAnchoredPosition.
  */
 declare function useOverlay<T extends HTMLElement>(options: UseOverlayOptions): RefObject<T | null>;
 
@@ -1958,4 +2124,4 @@ interface RovingGroupOptions {
  */
 declare function useRovingGroup(ref: RefObject<HTMLElement | null>, { selector, orientation }: RovingGroupOptions): (event: KeyboardEvent<HTMLElement>) => void;
 
-export { AppBar, type AppBarProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeTone, Breadcrumb, type BreadcrumbProps, Button, type ButtonProps, type ButtonShape, type ButtonSize, type ButtonVariant, type CSSVars, Card, CardBody, type CardBodyProps, CardFooter, CardHeader, type CardProps, type CardSectionProps, type CardVariant, type CarouselPager, type CarouselSlide, Checkbox, type CheckboxProps, Chip, ChipBar, type ChipBarGap, type ChipBarProps, ChipGroup, type ChipGroupGap, type ChipGroupProps, type ChipProps, type ChipVariant, ConfirmDialog, type ConfirmDialogProps, type ConfirmDialogTone, Container, type ContainerProps, type ContainerWidth, CountButton, type CountButtonProps, type CountButtonTone, type Crumb, type DataColumn, DataTable, type DataTableProps, type DataTableSelectionLabels, DateTimePicker, type DateTimePickerLabels, type DateTimePickerProps, Divider, type DividerProps, EmptyState, type EmptyStateProps, Field, type FieldContextValue, type FieldProps, FileDrop, type FileDropProps, Heading, type HeadingLevel, type HeadingProps, type HeadingTone, Icon, type IconProps, IconProvider, type IconProviderProps, type IconRender, type IconRenderProps, type IconSize, ImageCarousel, type ImageCarouselLabels, type ImageCarouselProps, Inline, type InlineAlign, type InlineGap, type InlineJustify, type InlineProps, Input, type InputProps, type InputSize, Lightbox, type LightboxLabels, type LightboxProps, Link, type LinkProps, type LinkVariant, ListGroup, type ListGroupProps, ListItem, type ListItemProps, MediaPlaceholder, type MediaPlaceholderProps, Modal, ModalBody, ModalFooter, ModalHeader, type ModalProps, type OverlayHistory, OverlayHistoryContext, PasswordInput, type PasswordInputProps, type Presence, ProgressBar, type ProgressBarProps, Radio, type RadioProps, type RovingGroupOptions, Screen, ScreenContent, type ScreenContentProps, Scroller, type ScrollerLabels, type ScrollerProps, SearchField, type SearchFieldProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, type SegmentedControlSize, Select, type SelectProps, type SelectSize, Sheet, SheetBody, SheetFooter, SheetHeader, type SheetProps, SideNav, SideNavGroup, type SideNavGroupProps, SideNavItem, type SideNavItemProps, type SideNavProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackGap, type StackProps, Switch, type SwitchProps, Tab, TabBar, TabBarAction, type TabBarActionProps, TabBarItem, type TabBarItemProps, type TabBarProps, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, Tag, type TagProps, type TagTone, Text, type TextProps, type TextTone, type TextVariant, Textarea, type TextareaProps, type ToastAction, type ToastOptions, ToastProvider, type ToastProviderProps, type ToastTone, UploadProgress, type UploadProgressLabels, type UploadProgressProps, type UploadStatus, type UseOverlayOptions, type VideoCaptions, type VideoChapter, VideoPlayer, type VideoPlayerLabels, type VideoPlayerProps, VisuallyHidden, type VisuallyHiddenProps, cx, useFieldContext, useOverlay, usePresence, useRovingGroup, useToast };
+export { AppBar, type AppBarProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeTone, Breadcrumb, type BreadcrumbProps, Button, type ButtonProps, type ButtonShape, type ButtonSize, type ButtonVariant, type CSSVars, Card, CardBody, type CardBodyProps, CardFooter, CardHeader, type CardProps, type CardSectionProps, type CardVariant, type CarouselPager, type CarouselSlide, Checkbox, type CheckboxProps, Chip, ChipBar, type ChipBarGap, type ChipBarProps, ChipGroup, type ChipGroupGap, type ChipGroupProps, type ChipProps, type ChipVariant, ConfirmDialog, type ConfirmDialogProps, type ConfirmDialogTone, Container, type ContainerProps, type ContainerWidth, CountButton, type CountButtonProps, type CountButtonTone, type Crumb, type DataColumn, DataTable, type DataTableProps, type DataTableSelectionLabels, DateTimePicker, type DateTimePickerLabels, type DateTimePickerProps, Divider, type DividerProps, EmptyState, type EmptyStateProps, Field, type FieldContextValue, type FieldProps, FileDrop, type FileDropProps, Heading, type HeadingLevel, type HeadingProps, type HeadingTone, Icon, type IconProps, IconProvider, type IconProviderProps, type IconRender, type IconRenderProps, type IconSize, ImageCarousel, type ImageCarouselLabels, type ImageCarouselProps, Inline, type InlineAlign, type InlineGap, type InlineJustify, type InlineProps, Input, type InputProps, type InputSize, Lightbox, type LightboxLabels, type LightboxProps, Link, type LinkProps, type LinkVariant, ListGroup, type ListGroupProps, ListItem, type ListItemProps, MediaPlaceholder, type MediaPlaceholderProps, Menu, MenuItem, type MenuItemProps, type MenuPlacement, type MenuProps, Modal, ModalBody, ModalFooter, ModalHeader, type ModalProps, type OverlayHistory, OverlayHistoryContext, PasswordInput, type PasswordInputProps, Popover, PopoverBody, PopoverFooter, PopoverHeader, type PopoverHeaderProps, type PopoverPlacement, type PopoverProps, type Presence, ProgressBar, type ProgressBarProps, Radio, type RadioProps, type RovingGroupOptions, Screen, ScreenContent, type ScreenContentProps, Scroller, type ScrollerLabels, type ScrollerProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, type SegmentedControlSize, Select, type SelectProps, type SelectSize, Sheet, SheetBody, SheetFooter, SheetHeader, type SheetProps, SideNav, SideNavGroup, type SideNavGroupProps, SideNavItem, type SideNavItemProps, type SideNavProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackGap, type StackProps, Switch, type SwitchProps, Tab, TabBar, TabBarAction, type TabBarActionProps, TabBarItem, type TabBarItemProps, type TabBarProps, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, Tag, type TagProps, type TagTone, Text, type TextProps, type TextTone, type TextVariant, Textarea, type TextareaProps, type ToastAction, type ToastOptions, ToastProvider, type ToastProviderProps, type ToastTone, Tooltip, type TooltipPlacement, type TooltipProps, UploadProgress, type UploadProgressLabels, type UploadProgressProps, type UploadStatus, type UseOverlayOptions, type VideoCaptions, type VideoChapter, VideoPlayer, type VideoPlayerLabels, type VideoPlayerProps, VisuallyHidden, type VisuallyHiddenProps, cx, useFieldContext, useOverlay, usePresence, useRovingGroup, useToast };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as react from 'react';
-import { CSSProperties, HTMLAttributes, JSX, ReactElement, Ref, ReactNode, ButtonHTMLAttributes, ElementType, ComponentPropsWithRef, MouseEventHandler, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, RefObject, KeyboardEvent } from 'react';
+import { CSSProperties, HTMLAttributes, JSX, ReactElement, Ref, ReactNode, ButtonHTMLAttributes, ElementType, ComponentPropsWithRef, MouseEventHandler, InputHTMLAttributes, HTMLInputTypeAttribute, TextareaHTMLAttributes, SelectHTMLAttributes, RefObject, MouseEvent, KeyboardEvent, PointerEvent, FocusEvent } from 'react';
+import { Placement } from '@floating-ui/dom';
 
 /**
  * Join class names, dropping anything falsy.
@@ -612,7 +613,18 @@ interface FieldProps {
 declare function Field({ label, children, hint, error, required, className }: FieldProps): ReactElement;
 
 type InputSize = "sm" | "md" | "lg";
-interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size"> {
+interface InputBaseProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size"> {
+    /** The native input type, passed straight through — the system adds no types
+        of its own, so `email`, `tel`, `url` and `number` behave as the platform
+        defines them, keyboard and validation included. Default "text".
+  
+        One type the component answers to: with `type="search"`, `onClear` takes
+        over the browser's own clear cross, so the field shows one clear
+        affordance rather than two. Without `onClear` the native cross is left
+        alone — there it is the only way to empty the field. */
+    type?: HTMLInputTypeAttribute;
+    /** Control height and type size. The icon slots, the gutter and the clear
+        button all step with it. Default "md". */
     size?: InputSize;
     /** Marks the value as failing validation — sets aria-invalid and the danger
         border. Inside a Field the field's error state does this already. */
@@ -624,20 +636,50 @@ interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size">
     iconRight?: ReactNode;
     ref?: Ref<HTMLInputElement>;
 }
+type ClearEnforcement = {
+    /** Raises a clear button in the trailing slot whenever the field holds
+        text, and runs when it is pressed. An uncontrolled field is emptied
+        for you; a controlled one is yours to empty here. Rules out
+        iconRight — they are the same slot. */
+    onClear: () => void;
+    /** Names that button, e.g. "Clear search". Required: the cross says
+        nothing to a screen reader, and the words are the app's — "Clear
+        search" and "Clear filter" are not interchangeable. */
+    clearLabel: string;
+    iconRight?: undefined;
+} | {
+    onClear?: undefined;
+    clearLabel?: undefined;
+};
+type InputProps = InputBaseProps & ClearEnforcement;
 /**
  * Single-line text input. Inside a Field it inherits id/description/invalid.
  *
+ * Sizes are `sm` / `md` / `lg`; the icon slots and the clear button step with
+ * them. `onClear` folds in what SearchField used to be — pair it with
+ * `type="search"` and it replaces the browser's own clear cross.
+ *
  * ```tsx
  * <Field label="Name">
  *   <Input value={name} onChange={(e) => setName(e.target.value)} />
  * </Field>
  *
  * <Input aria-label="Search" iconLeft={<Icon name="search" />} />
+ *
+ * <Input
+ *   type="search"
+ *   aria-label="Search sessions"
+ *   iconLeft={<Icon name="search" />}
+ *   value={query}
+ *   onChange={(e) => setQuery(e.target.value)}
+ *   clearLabel="Clear search"
+ *   onClear={() => setQuery("")}
+ * />
  * ```
  */
-declare function Input({ size, invalid, iconLeft, iconRight, className, ...rest }: InputProps): ReactElement;
+declare function Input({ size, invalid, iconLeft, iconRight, onClear, clearLabel, className, ref, ...rest }: InputProps): ReactElement;
 
-interface PasswordInputProps extends Omit<InputProps, "type"> {
+interface PasswordInputProps extends Omit<InputProps, "type" | "onClear" | "clearLabel" | "iconRight"> {
     /** Names the reveal button while the password is hidden, e.g. "Show password".
         Required: the button carries no visible text, so this is the only thing a
         screen reader has, and it is the app's language rather than the system's. */
@@ -820,26 +862,6 @@ interface SegmentedControlProps<T extends string = string> {
  */
 declare function SegmentedControl<T extends string = string>({ label, options, value, onChange, disabled, fullWidth, size, bare, repick, className, }: SegmentedControlProps<T>): ReactElement;
 
-interface SearchFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size" | "value" | "onChange"> {
-    /** Accessible name. */
-    label: string;
-    /** Names the clear button, e.g. "Clear search". Required: the button is a
-        glyph, so this is all a screen reader has, and the words are the app's. */
-    clearLabel: string;
-    value: string;
-    /** Receives the new text — "" when cleared. */
-    onChange: (value: string) => void;
-    ref?: Ref<HTMLInputElement>;
-}
-/**
- * Controlled search input with a clear affordance once there is text.
- *
- * ```tsx
- * <SearchField label="Search sessions" clearLabel="Clear search" value={query} onChange={setQuery} />
- * ```
- */
-declare function SearchField({ label, clearLabel, value, onChange, className, ...rest }: SearchFieldProps): ReactElement;
-
 interface ScrollerLabels {
     previous: string;
     next: string;
@@ -1334,6 +1356,141 @@ declare function SheetFooter({ children }: {
     children: ReactNode;
 }): react.JSX.Element;
 
+type PopoverPlacement = Placement;
+interface PopoverProps {
+    open: boolean;
+    onClose: () => void;
+    /** The trigger the panel hangs off. It stays interactive while open. */
+    anchorRef: RefObject<HTMLElement | null>;
+    /** Accessible name of the panel. */
+    label: string;
+    /** Side it prefers. It flips and slides to stay on screen. Default "bottom-start". */
+    placement?: PopoverPlacement;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * Anchored, non-modal surface. The page behind it stays live and scrollable
+ * and the panel travels with the anchor; a press outside, Escape, or the
+ * trigger itself dismisses it.
+ *
+ * Modal by contrast: reach for Modal when the answer must come before anything
+ * else, and for Sheet when the content is a task rather than a detail — a
+ * form with its own header and footer belongs in one of those, not here.
+ *
+ * ```tsx
+ * const anchor = useRef<HTMLButtonElement>(null);
+ * const [open, setOpen] = useState(false);
+ * <Button ref={anchor} aria-expanded={open} onClick={() => setOpen((v) => !v)}>
+ *   Equipment
+ * </Button>
+ * <Popover open={open} onClose={() => setOpen(false)} anchorRef={anchor} label="Equipment">
+ *   <PopoverBody>…</PopoverBody>
+ * </Popover>
+ * ```
+ */
+declare function Popover({ open, onClose, anchorRef, label, placement, className, children, }: PopoverProps): react.ReactPortal | null;
+type PopoverHeaderProps = {
+    children: ReactNode;
+} & ({
+    /** Renders a close button after the title. Wire it to the popover's own onClose. */
+    onClose: () => void;
+    /** Accessible name of the close button (localise). */
+    closeLabel: string;
+} | {
+    onClose?: undefined;
+    closeLabel?: undefined;
+});
+declare function PopoverHeader({ children, onClose, closeLabel }: PopoverHeaderProps): react.JSX.Element;
+declare function PopoverBody({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function PopoverFooter({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+
+type MenuPlacement = Placement;
+/** What Menu needs to be able to put on its trigger. */
+type MenuTriggerProps = {
+    ref?: Ref<HTMLElement> | undefined;
+    "aria-haspopup"?: "menu" | undefined;
+    "aria-expanded"?: boolean | undefined;
+    onClick?: ((event: MouseEvent<HTMLElement>) => void) | undefined;
+    onKeyDown?: ((event: KeyboardEvent<HTMLElement>) => void) | undefined;
+};
+interface MenuProps {
+    /** Accessible name of the menu — what the list of actions is *for*. */
+    label: string;
+    /** The control that opens it. Gets the ref, the ARIA and the key handling. */
+    trigger: ReactElement<MenuTriggerProps>;
+    /** Side it prefers. It flips and slides to stay on screen. Default "bottom-end". */
+    placement?: MenuPlacement;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * A button that opens a short list of actions (APG's menu button).
+ *
+ * Open state is the menu's own: a list of actions has no meaning outside the
+ * button that opened it, so unlike Modal, Sheet and Popover there is nothing
+ * for a caller to hold. Reach for Popover instead the moment the panel holds
+ * anything but actions — a form, a filter, a list of things to read.
+ *
+ * ```tsx
+ * <Menu label="Heat actions" trigger={<Button variant="ghost">Actions</Button>}>
+ *   <MenuItem onSelect={edit}>Edit</MenuItem>
+ *   <MenuItem onSelect={remove} tone="danger">Delete</MenuItem>
+ * </Menu>
+ * ```
+ */
+declare function Menu({ label, trigger, placement, className, children }: MenuProps): react.JSX.Element;
+interface MenuItemProps {
+    /** What the action does. The menu closes itself around it. */
+    onSelect: () => void;
+    disabled?: boolean;
+    /** "danger" for an action that destroys something. Default "default". */
+    tone?: "default" | "danger";
+    children: ReactNode;
+}
+declare function MenuItem({ onSelect, disabled, tone, children }: MenuItemProps): react.JSX.Element;
+
+type TooltipPlacement = Placement;
+/** What Tooltip needs to be able to put on its trigger. */
+type TriggerProps = {
+    ref?: Ref<HTMLElement> | undefined;
+    "aria-describedby"?: string | undefined;
+    onPointerEnter?: ((event: PointerEvent<HTMLElement>) => void) | undefined;
+    onPointerLeave?: ((event: PointerEvent<HTMLElement>) => void) | undefined;
+    onFocus?: ((event: FocusEvent<HTMLElement>) => void) | undefined;
+    onBlur?: ((event: FocusEvent<HTMLElement>) => void) | undefined;
+};
+interface TooltipProps {
+    /** The label. Plain text — nothing here is reachable by pointer or key. */
+    content: ReactNode;
+    /** Side it prefers. It flips and slides to stay on screen. Default "top". */
+    placement?: TooltipPlacement;
+    /** Pointer dwell in ms. Keyboard focus ignores it. Default 400. */
+    delayMs?: number;
+    /** The control being labelled. Gets the ref and the handlers. */
+    children: ReactElement<TriggerProps>;
+}
+/**
+ * A name for a control that shows only its glyph, on hover and on focus.
+ *
+ * It describes; it does not hold anything. There is nothing to click inside
+ * it and focus never moves into it, so anything the reader has to act on —
+ * a link, a button, a form — belongs in a Popover instead. A control whose
+ * label is *only* here still needs an aria-label of its own: this is the
+ * accessible description, not the accessible name.
+ *
+ * ```tsx
+ * <Tooltip content="Remove from heat">
+ *   <Button variant="ghost" aria-label="Remove from heat"><Icon name="x" /></Button>
+ * </Tooltip>
+ * ```
+ */
+declare function Tooltip({ content, placement, delayMs, children, }: TooltipProps): react.JSX.Element;
+
 type ConfirmDialogTone = "default" | "danger" | "warning";
 interface ConfirmDialogProps<T = void> {
     /** The row in question, or null when nothing is being asked. Held by the
@@ -1881,14 +2038,23 @@ declare function Breadcrumb({ items, label, linkAs, className, ...rest }: Breadc
 interface UseOverlayOptions {
     open: boolean;
     onClose: () => void;
+    /**
+     * Freeze the page behind the surface. Default true.
+     *
+     * False for anchored surfaces: a popover is pinned to a trigger that scrolls
+     * with the page, so locking the page would strand it over content the reader
+     * can no longer reach, and locking it *and* letting the popover follow the
+     * anchor are the same gesture answered two ways.
+     */
+    lockScroll?: boolean;
 }
 /**
  * Shared modal-surface behaviour: focus capture and restore, Escape to
  * close, Tab cycling inside the panel, body scroll lock. Attach the
  * returned ref to the dialog element (it needs tabIndex={-1}).
  *
- * Anchor-positioned overlays (Tooltip/Popover) will extend this hook with
- * a floating-ui middleware pass; the options object leaves room for that.
+ * Popover uses it too, with `lockScroll: false`; where it sits on the screen
+ * is a separate question, answered by useAnchoredPosition.
  */
 declare function useOverlay<T extends HTMLElement>(options: UseOverlayOptions): RefObject<T | null>;
 
@@ -1958,4 +2124,4 @@ interface RovingGroupOptions {
  */
 declare function useRovingGroup(ref: RefObject<HTMLElement | null>, { selector, orientation }: RovingGroupOptions): (event: KeyboardEvent<HTMLElement>) => void;
 
-export { AppBar, type AppBarProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeTone, Breadcrumb, type BreadcrumbProps, Button, type ButtonProps, type ButtonShape, type ButtonSize, type ButtonVariant, type CSSVars, Card, CardBody, type CardBodyProps, CardFooter, CardHeader, type CardProps, type CardSectionProps, type CardVariant, type CarouselPager, type CarouselSlide, Checkbox, type CheckboxProps, Chip, ChipBar, type ChipBarGap, type ChipBarProps, ChipGroup, type ChipGroupGap, type ChipGroupProps, type ChipProps, type ChipVariant, ConfirmDialog, type ConfirmDialogProps, type ConfirmDialogTone, Container, type ContainerProps, type ContainerWidth, CountButton, type CountButtonProps, type CountButtonTone, type Crumb, type DataColumn, DataTable, type DataTableProps, type DataTableSelectionLabels, DateTimePicker, type DateTimePickerLabels, type DateTimePickerProps, Divider, type DividerProps, EmptyState, type EmptyStateProps, Field, type FieldContextValue, type FieldProps, FileDrop, type FileDropProps, Heading, type HeadingLevel, type HeadingProps, type HeadingTone, Icon, type IconProps, IconProvider, type IconProviderProps, type IconRender, type IconRenderProps, type IconSize, ImageCarousel, type ImageCarouselLabels, type ImageCarouselProps, Inline, type InlineAlign, type InlineGap, type InlineJustify, type InlineProps, Input, type InputProps, type InputSize, Lightbox, type LightboxLabels, type LightboxProps, Link, type LinkProps, type LinkVariant, ListGroup, type ListGroupProps, ListItem, type ListItemProps, MediaPlaceholder, type MediaPlaceholderProps, Modal, ModalBody, ModalFooter, ModalHeader, type ModalProps, type OverlayHistory, OverlayHistoryContext, PasswordInput, type PasswordInputProps, type Presence, ProgressBar, type ProgressBarProps, Radio, type RadioProps, type RovingGroupOptions, Screen, ScreenContent, type ScreenContentProps, Scroller, type ScrollerLabels, type ScrollerProps, SearchField, type SearchFieldProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, type SegmentedControlSize, Select, type SelectProps, type SelectSize, Sheet, SheetBody, SheetFooter, SheetHeader, type SheetProps, SideNav, SideNavGroup, type SideNavGroupProps, SideNavItem, type SideNavItemProps, type SideNavProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackGap, type StackProps, Switch, type SwitchProps, Tab, TabBar, TabBarAction, type TabBarActionProps, TabBarItem, type TabBarItemProps, type TabBarProps, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, Tag, type TagProps, type TagTone, Text, type TextProps, type TextTone, type TextVariant, Textarea, type TextareaProps, type ToastAction, type ToastOptions, ToastProvider, type ToastProviderProps, type ToastTone, UploadProgress, type UploadProgressLabels, type UploadProgressProps, type UploadStatus, type UseOverlayOptions, type VideoCaptions, type VideoChapter, VideoPlayer, type VideoPlayerLabels, type VideoPlayerProps, VisuallyHidden, type VisuallyHiddenProps, cx, useFieldContext, useOverlay, usePresence, useRovingGroup, useToast };
+export { AppBar, type AppBarProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeTone, Breadcrumb, type BreadcrumbProps, Button, type ButtonProps, type ButtonShape, type ButtonSize, type ButtonVariant, type CSSVars, Card, CardBody, type CardBodyProps, CardFooter, CardHeader, type CardProps, type CardSectionProps, type CardVariant, type CarouselPager, type CarouselSlide, Checkbox, type CheckboxProps, Chip, ChipBar, type ChipBarGap, type ChipBarProps, ChipGroup, type ChipGroupGap, type ChipGroupProps, type ChipProps, type ChipVariant, ConfirmDialog, type ConfirmDialogProps, type ConfirmDialogTone, Container, type ContainerProps, type ContainerWidth, CountButton, type CountButtonProps, type CountButtonTone, type Crumb, type DataColumn, DataTable, type DataTableProps, type DataTableSelectionLabels, DateTimePicker, type DateTimePickerLabels, type DateTimePickerProps, Divider, type DividerProps, EmptyState, type EmptyStateProps, Field, type FieldContextValue, type FieldProps, FileDrop, type FileDropProps, Heading, type HeadingLevel, type HeadingProps, type HeadingTone, Icon, type IconProps, IconProvider, type IconProviderProps, type IconRender, type IconRenderProps, type IconSize, ImageCarousel, type ImageCarouselLabels, type ImageCarouselProps, Inline, type InlineAlign, type InlineGap, type InlineJustify, type InlineProps, Input, type InputProps, type InputSize, Lightbox, type LightboxLabels, type LightboxProps, Link, type LinkProps, type LinkVariant, ListGroup, type ListGroupProps, ListItem, type ListItemProps, MediaPlaceholder, type MediaPlaceholderProps, Menu, MenuItem, type MenuItemProps, type MenuPlacement, type MenuProps, Modal, ModalBody, ModalFooter, ModalHeader, type ModalProps, type OverlayHistory, OverlayHistoryContext, PasswordInput, type PasswordInputProps, Popover, PopoverBody, PopoverFooter, PopoverHeader, type PopoverHeaderProps, type PopoverPlacement, type PopoverProps, type Presence, ProgressBar, type ProgressBarProps, Radio, type RadioProps, type RovingGroupOptions, Screen, ScreenContent, type ScreenContentProps, Scroller, type ScrollerLabels, type ScrollerProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, type SegmentedControlSize, Select, type SelectProps, type SelectSize, Sheet, SheetBody, SheetFooter, SheetHeader, type SheetProps, SideNav, SideNavGroup, type SideNavGroupProps, SideNavItem, type SideNavItemProps, type SideNavProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackGap, type StackProps, Switch, type SwitchProps, Tab, TabBar, TabBarAction, type TabBarActionProps, TabBarItem, type TabBarItemProps, type TabBarProps, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, Tag, type TagProps, type TagTone, Text, type TextProps, type TextTone, type TextVariant, Textarea, type TextareaProps, type ToastAction, type ToastOptions, ToastProvider, type ToastProviderProps, type ToastTone, Tooltip, type TooltipPlacement, type TooltipProps, UploadProgress, type UploadProgressLabels, type UploadProgressProps, type UploadStatus, type UseOverlayOptions, type VideoCaptions, type VideoChapter, VideoPlayer, type VideoPlayerLabels, type VideoPlayerProps, VisuallyHidden, type VisuallyHiddenProps, cx, useFieldContext, useOverlay, usePresence, useRovingGroup, useToast };