@reopt-ai/opt-ui-primitives 1.5.1 → 1.5.2

package/dist/index.d.cts

@@ -85,10 +85,37 @@ declare function useRovingTabindex(options?: RovingTabindexOptions): {
 //#region src/hooks/use-floating.d.ts
 /** Why an overlay's open state changed, forwarded to `onOpenChange`. */
 type DismissReason = "escape-key" | "outside-press" | "ancestor-scroll";
-/** Dismissal behavior. `true` enables outside-press + escape-key. */
+/**
+ * Dismissal behavior. `true` enables outside-press + escape-key.
+ *
+ * ## Which dismissals to delegate — the overlay policy
+ *
+ * Delegating to floating-ui's `useDismiss` gets shadow-DOM-safe,
+ * reference-aware document listeners for free, so it is the default choice.
+ * An overlay keeps a dismissal for ITSELF only when closing also has to move
+ * focus, because the keydown handler is where the focus target is known:
+ *
+ * | Overlay           | outsidePress | escapeKey | why                                    |
+ * | ----------------- | ------------ | --------- | -------------------------------------- |
+ * | Popover           | delegated    | delegated | `FloatingFocusManager` restores focus   |
+ * | Tooltip           | n/a          | delegated | never holds focus                       |
+ * | Menu              | delegated    | OWN       | Escape must refocus the trigger         |
+ * | Select / Combobox | delegated    | OWN       | Escape keeps focus on trigger/input     |
+ *
+ * `outsidePress` is delegated everywhere: the press target should receive
+ * focus, so no overlay needs to intervene. When adding an overlay, follow this
+ * table rather than inventing a third pattern — and if a new one is genuinely
+ * needed, add a row here.
+ */
 type DismissConfig = boolean | {
+  /** Close on a press outside the reference/floating elements. */
   outsidePress?: boolean;
+  /**
+   * Close on Escape. Set `false` when the overlay handles Escape itself
+   * because it also has to restore focus — see the table above.
+   */
   escapeKey?: boolean;
+  /** Close when an ancestor scroller scrolls. Off by default. */
   ancestorScroll?: boolean;
 };
 /** Physical side a popup is placed on, derived from the resolved placement. */
@@ -389,9 +416,34 @@ declare const Radio: import("react").ForwardRefExoticComponent<RadioProps & impo
 /** Where a portaled overlay mounts: an element, an element id, or body. */
 type PortalRoot = HTMLElement | string | null;
 //#endregion
+//#region src/internal/render-element.d.ts
+/**
+ * The `render` prop contract: swap the element a part renders while keeping all
+ * of its behavior, props and refs. Either a React element to clone, or a
+ * function receiving the merged props.
+ */
+type RenderProp = ReactElement | ((props: Record<string, unknown>) => ReactElement);
+//#endregion
 //#region src/primitives/tooltip.d.ts
-/** Props for `TooltipProvider`. */
-interface TooltipProviderProps {
+/** Props for `TooltipGroup`. */
+interface TooltipGroupProps {
+  children: ReactNode;
+  /**
+   * How long after a tooltip in this group closes its siblings still open
+   * INSTANTLY (no show delay). Default 300ms. Set 0 to disable skipping.
+   */
+  skipDelay?: number;
+}
+/**
+ * Groups sibling tooltips so moving between them does not re-pay the show
+ * delay — the APG/desktop convention for toolbars and icon rows, where waiting
+ * 700ms per button makes the row feel broken.
+ *
+ * Optional: a `TooltipProvider` outside any group keeps its own delay.
+ */
+declare function TooltipGroup({ children, skipDelay }: TooltipGroupProps): React$1.JSX.Element;
+/** Props for `TooltipRoot`. */
+interface TooltipRootProps {
   children: ReactNode;
   timeout?: number;
   showTimeout?: number;
@@ -403,8 +455,27 @@ interface TooltipProviderProps {
   /** Portal mount target (element or element id). Defaults to document.body. */
   portalRoot?: PortalRoot;
 }
-/** Renders the `TooltipProvider` component. */
-declare function TooltipProvider({ children, timeout, showTimeout, hideTimeout, placement, animated, portal, portalRoot }: TooltipProviderProps): React$1.JSX.Element;
+/**
+ * Owns ONE tooltip: its open state, delays, placement and portal.
+ *
+ * Wrap several of these in a {@link TooltipGroup} to share a skip-delay window.
+ */
+declare function TooltipRoot({ children, timeout, showTimeout, hideTimeout, placement, animated, portal, portalRoot }: TooltipRootProps): React$1.JSX.Element;
+/**
+ * Props for `TooltipProvider`.
+ *
+ * @deprecated Use `TooltipRootProps`.
+ */
+type TooltipProviderProps = TooltipRootProps;
+/**
+ * A single tooltip.
+ *
+ * @deprecated Renamed to {@link TooltipRoot}. Despite the name this component
+ * never provided anything to a subtree of tooltips — it IS one tooltip. The
+ * delay-sharing provider is {@link TooltipGroup}. Kept as an alias for
+ * back-compat; scheduled for removal in the next major.
+ */
+declare const TooltipProvider: typeof TooltipRoot;
 /** Props for `TooltipAnchor`. */
 interface TooltipAnchorProps extends ComponentPropsWithoutRef<"div"> {
   /** Render a custom element instead of a wrapper div. The element receives tooltip props. */
@@ -412,9 +483,12 @@ interface TooltipAnchorProps extends ComponentPropsWithoutRef<"div"> {
 }
 declare const TooltipAnchor: React$1.ForwardRefExoticComponent<TooltipAnchorProps & React$1.RefAttributes<HTMLDivElement>>;
 /** Props for `Tooltip`. */
-interface TooltipProps extends ComponentPropsWithoutRef<"div"> {}
+interface TooltipProps extends ComponentPropsWithoutRef<"div"> {
+  /** Render a custom element instead of the default `div`. */
+  render?: RenderProp;
+}
 /** Renders the `Tooltip` component. */
-declare function Tooltip({ children, onMouseEnter, onMouseLeave, ...props }: TooltipProps): React$1.JSX.Element | null;
+declare function Tooltip({ children, onMouseEnter, onMouseLeave, render, ...props }: TooltipProps): React$1.JSX.Element | null;
 //#endregion
 //#region src/primitives/popover.d.ts
 /** Props for `PopoverRoot`. */
@@ -448,9 +522,12 @@ declare function PopoverRoot({ children, open: controlledOpen, defaultOpen, onOp
 interface PopoverTriggerProps extends ComponentPropsWithoutRef<"button"> {}
 declare const PopoverTrigger: import("react").ForwardRefExoticComponent<PopoverTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
 /** Props for `PopoverContent`. */
-interface PopoverContentProps extends ComponentPropsWithoutRef<"div"> {}
+interface PopoverContentProps extends ComponentPropsWithoutRef<"div"> {
+  /** Render a custom element instead of the default `div`. */
+  render?: RenderProp;
+}
 /** Renders the `PopoverContent` component. */
-declare function PopoverContent({ children, ...props }: PopoverContentProps): import("react").JSX.Element | null;
+declare function PopoverContent({ children, render, ...props }: PopoverContentProps): import("react").JSX.Element | null;
 /** Props for `PopoverClose`. */
 interface PopoverCloseProps extends ComponentPropsWithoutRef<"button"> {}
 declare const PopoverClose: import("react").ForwardRefExoticComponent<PopoverCloseProps & import("react").RefAttributes<HTMLButtonElement>>;
@@ -468,6 +545,12 @@ interface SelectRootProps {
   setValue?: (value: string | string[]) => void;
   /** Allow selecting more than one option. The value becomes a `string[]`. */
   multiple?: boolean;
+  /**
+   * Present the current value without allowing changes. Unlike `disabled` the
+   * trigger stays focusable and the listbox still OPENS and can be browsed —
+   * only committing a new value is blocked. Reflected as `aria-readonly`.
+   */
+  readOnly?: boolean;
   /** Form field name. Renders hidden input(s) so the value submits with a form. */
   name?: string;
   open?: boolean;
@@ -482,7 +565,7 @@ interface SelectRootProps {
   portalRoot?: PortalRoot;
 }
 /** Renders the `SelectRoot` component. */
-declare function SelectRoot({ children, value: controlledValue, defaultValue, onValueChange, setValue: setValueDeprecated, multiple, name, open: controlledOpen, onOpenChange, setOpen: setOpenDeprecated, animated, portal, portalRoot }: SelectRootProps): import("react").JSX.Element;
+declare function SelectRoot({ children, value: controlledValue, defaultValue, onValueChange, setValue: setValueDeprecated, multiple, readOnly, name, open: controlledOpen, onOpenChange, setOpen: setOpenDeprecated, animated, portal, portalRoot }: SelectRootProps): import("react").JSX.Element;
 /** Props for `SelectLabel`. */
 interface SelectLabelProps extends ComponentPropsWithoutRef<"label"> {}
 /** Renders the `SelectLabel` component. */
@@ -491,9 +574,12 @@ declare function SelectLabel(props: SelectLabelProps): import("react").JSX.Eleme
 interface SelectTriggerProps extends ComponentPropsWithoutRef<"button"> {}
 declare const SelectTrigger: import("react").ForwardRefExoticComponent<SelectTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
 /** Props for `SelectPopover`. */
-interface SelectPopoverProps extends ComponentPropsWithoutRef<"div"> {}
+interface SelectPopoverProps extends ComponentPropsWithoutRef<"div"> {
+  /** Render a custom element instead of the default `div`. */
+  render?: RenderProp;
+}
 /** Renders the `SelectPopover` component. */
-declare function SelectPopover({ children, ...props }: SelectPopoverProps): import("react").JSX.Element | null;
+declare function SelectPopover({ children, render, ...props }: SelectPopoverProps): import("react").JSX.Element | null;
 /** Props for `SelectItem`. */
 interface SelectItemProps extends ComponentPropsWithoutRef<"div"> {
   value: string;
@@ -512,6 +598,13 @@ interface ComboboxRootProps {
   onValueChange?: (value: string) => void;
   /** @deprecated Use `onValueChange`. */
   setValue?: (value: string) => void;
+  /**
+   * Present the current value without allowing changes. Unlike `disabled` the
+   * input stays focusable and the listbox still OPENS and can be browsed —
+   * only editing the query and committing a new value are blocked. Reflected
+   * as the input's native `readonly` plus `aria-readonly`.
+   */
+  readOnly?: boolean;
   open?: boolean;
   /** Called when the open state changes. */
   onOpenChange?: (open: boolean) => void;
@@ -524,14 +617,17 @@ interface ComboboxRootProps {
   portalRoot?: PortalRoot;
 }
 /** Renders the `ComboboxRoot` component. */
-declare function ComboboxRoot({ children, value: controlledValue, defaultValue, onValueChange, setValue: setValueDeprecated, open: controlledOpen, onOpenChange, setOpen: setOpenDeprecated, animated, portal, portalRoot }: ComboboxRootProps): import("react").JSX.Element;
+declare function ComboboxRoot({ children, value: controlledValue, defaultValue, onValueChange, setValue: setValueDeprecated, readOnly, open: controlledOpen, onOpenChange, setOpen: setOpenDeprecated, animated, portal, portalRoot }: ComboboxRootProps): import("react").JSX.Element;
 /** Props for `ComboboxInput`. */
 interface ComboboxInputProps extends Omit<ComponentPropsWithoutRef<"input">, "value" | "onChange"> {}
 declare const ComboboxInput: import("react").ForwardRefExoticComponent<ComboboxInputProps & import("react").RefAttributes<HTMLInputElement>>;
 /** Props for `ComboboxPopover`. */
-interface ComboboxPopoverProps extends ComponentPropsWithoutRef<"div"> {}
+interface ComboboxPopoverProps extends ComponentPropsWithoutRef<"div"> {
+  /** Render a custom element instead of the default `div`. */
+  render?: RenderProp;
+}
 /** Renders the `ComboboxPopover` component. */
-declare function ComboboxPopover({ children, ...props }: ComboboxPopoverProps): import("react").JSX.Element | null;
+declare function ComboboxPopover({ children, render, ...props }: ComboboxPopoverProps): import("react").JSX.Element | null;
 /** Props for `ComboboxItem`. */
 interface ComboboxItemProps extends ComponentPropsWithoutRef<"div"> {
   value: string;
@@ -588,7 +684,15 @@ interface CommandGroupProps extends ComponentPropsWithoutRef<"div"> {
 declare function CommandGroup({ heading, children, ...props }: CommandGroupProps): import("react").JSX.Element;
 /** Props for `CommandSeparator`. */
 interface CommandSeparatorProps extends ComponentPropsWithoutRef<"div"> {}
-/** Renders the `CommandSeparator` component. */
+/**
+ * Renders the `CommandSeparator` component.
+ *
+ * Rendered with `role="presentation"`: the separator is a child of
+ * `CommandList` (`role="listbox"`), whose only permitted children are `option`
+ * and `group`. A real `role="separator"` there fails
+ * `aria-required-children` and corrupts the option count announced by screen
+ * readers. (Menu separators keep `role="separator"` — `menu` permits it.)
+ */
 declare function CommandSeparator(props: CommandSeparatorProps): import("react").JSX.Element;
 /** Props for `CommandItem`. */
 interface CommandItemProps extends Omit<ComponentPropsWithoutRef<"div">, "onSelect"> {
@@ -646,9 +750,12 @@ declare function MenuRoot({ children, open: controlledOpen, onOpenChange, setOpe
 interface MenuTriggerProps extends ComponentPropsWithoutRef<"button"> {}
 declare const MenuTrigger: import("react").ForwardRefExoticComponent<MenuTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
 /** Props for `MenuPopover`. */
-interface MenuPopoverProps extends ComponentPropsWithoutRef<"div"> {}
+interface MenuPopoverProps extends ComponentPropsWithoutRef<"div"> {
+  /** Render a custom element instead of the default `div`. */
+  render?: RenderProp;
+}
 /** Renders the `MenuPopover` component. */
-declare function MenuPopover({ children, onKeyDown, ...props }: MenuPopoverProps): import("react").JSX.Element | null;
+declare function MenuPopover({ children, onKeyDown, render, ...props }: MenuPopoverProps): import("react").JSX.Element | null;
 /** Props for `MenuItem`. */
 interface MenuItemProps extends ComponentPropsWithoutRef<"div"> {
   disabled?: boolean;
@@ -907,9 +1014,18 @@ interface AccordionTriggerProps extends ComponentPropsWithoutRef<"button"> {}
 /** Renders the `AccordionTrigger` component. */
 declare function AccordionTrigger({ onClick, disabled, ...props }: AccordionTriggerProps): import("react").JSX.Element;
 /** Props for `AccordionContent`. */
-interface AccordionContentProps extends ComponentPropsWithoutRef<"div"> {}
+interface AccordionContentProps extends ComponentPropsWithoutRef<"div"> {
+  /**
+   * When collapsed, keep the content in the DOM as `hidden="until-found"`
+   * (instead of unmounting) so browser find-in-page can reveal it. Chromium
+   * progressive enhancement; disables the enter/leave animation for this
+   * content. On reveal a `beforematch` event expands the item so state stays
+   * consistent.
+   */
+  hiddenUntilFound?: boolean;
+}
 /** Renders the `AccordionContent` component. */
-declare function AccordionContent({ style, ...props }: AccordionContentProps): import("react").JSX.Element | null;
+declare function AccordionContent({ hiddenUntilFound, style, ...props }: AccordionContentProps): import("react").JSX.Element | null;
 //#endregion
 //#region src/form/form-store.d.ts
 /** Field name → error message map. Keys can be dot-paths (e.g. "items.0"). */
@@ -1148,4 +1264,4 @@ interface FormGroupLabelProps extends ComponentPropsWithoutRef<"legend"> {}
 /** Renders the `FormGroupLabel` component. */
 declare function FormGroupLabel(props: FormGroupLabelProps): import("react").JSX.Element;
 //#endregion
-export { AccordionContent, type AccordionContentProps, AccordionItem, type AccordionItemProps, AccordionRoot, type AccordionRootProps, AccordionTrigger, type AccordionTriggerProps, AlertDialogPanel, type AlertDialogPanelProps, type Align, Button, type ButtonProps, Checkbox, type CheckboxProps, ComboboxGroup, ComboboxGroupLabel, type ComboboxGroupLabelProps, type ComboboxGroupProps, ComboboxInput, type ComboboxInputProps, ComboboxItem, type ComboboxItemProps, ComboboxPopover, type ComboboxPopoverProps, ComboboxRoot, type ComboboxRootProps, CommandEmpty, type CommandEmptyProps, CommandGroup, type CommandGroupProps, CommandInput, type CommandInputProps, CommandItem, type CommandItemProps, CommandList, type CommandListProps, CommandRoot, type CommandRootProps, CommandSeparator, type CommandSeparatorProps, Composite, CompositeItem, type CompositeItemProps, type CompositeProps, CompositeProvider, type CompositeProviderProps, CompositeRow, type CompositeRowProps, DialogDescription, type DialogDescriptionProps, DialogDisclosure, type DialogDisclosureProps, DialogDismiss, type DialogDismissProps, DialogHeading, type DialogHeadingProps, DialogPanel, type DialogPanelProps, DialogRoot, type DialogRootProps, DisclosureContent, type DisclosureContentProps, DisclosureRoot, type DisclosureRootProps, DisclosureTrigger, type DisclosureTriggerProps, type FocusableWhenDisabledOptions, type FocusableWhenDisabledProps, FormCheckbox, type FormCheckboxProps, FormControl, type FormControlProps, FormDescription, type FormDescriptionProps, FormError, type FormErrorProps, type FormErrors, FormField, type FormFieldProps, FormGroup, FormGroupLabel, type FormGroupLabelProps, type FormGroupProps, FormInput, type FormInputProps, FormLabel, type FormLabelProps, FormProvider, FormPush, type FormPushProps, FormRadio, FormRadioGroup, type FormRadioGroupProps, type FormRadioProps, FormRemove, type FormRemoveProps, FormReset, type FormResetProps, FormRoot, type FormRootProps, FormSelect, type FormSelectProps, type FormStoreInstance, type FormStoreOptions, FormSubmit, type FormSubmitProps, FormSwitch, type FormSwitchProps, FormTextarea, type FormTextareaProps, MenuButtonArrow, type MenuButtonArrowProps, MenuItem, MenuItemCheckbox, type MenuItemCheckboxProps, type MenuItemProps, MenuItemRadio, type MenuItemRadioProps, MenuPopover, type MenuPopoverProps, MenuRoot, type MenuRootProps, MenuSeparator, type MenuSeparatorProps, MenuTrigger, type MenuTriggerProps, MenubarContainer, type MenubarContainerProps, MenubarRoot, type MenubarRootProps, Meter, type MeterProps, type OffsetArgs, type OffsetValue, PopoverClose, type PopoverCloseProps, PopoverContent, type PopoverContentProps, PopoverRoot, type PopoverRootProps, PopoverTrigger, type PopoverTriggerProps, Progress, type ProgressProps, Radio, RadioGroupRoot, type RadioGroupRootProps, type RadioProps, type RovingTabindexOptions, SelectItem, type SelectItemProps, SelectLabel, type SelectLabelProps, SelectPopover, type SelectPopoverProps, SelectRoot, type SelectRootProps, SelectTrigger, type SelectTriggerProps, Separator, type SeparatorProps, type Side, Switch, type SwitchProps, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, TabsRoot, type TabsRootProps, Toggle, ToggleGroup, type ToggleGroupProps, type ToggleProps, ToolbarButton, type ToolbarButtonProps, ToolbarContainer, type ToolbarContainerProps, ToolbarRoot, type ToolbarRootProps, ToolbarSeparator, type ToolbarSeparatorProps, Tooltip, TooltipAnchor, type TooltipAnchorProps, type TooltipProps, TooltipProvider, type TooltipProviderProps, type UseFloatingOptions, type ValidateOn, useCommandState, useControllableState, useDialogClose, useEnterLeave, useFieldValue, useFloating, useFocusVisible, useFocusableWhenDisabled, useFormContext, useFormStore, useId, useMenubarContext, useRadioGroupContext, useRovingTabindex, useScrollActiveDescendantIntoView };
+export { AccordionContent, type AccordionContentProps, AccordionItem, type AccordionItemProps, AccordionRoot, type AccordionRootProps, AccordionTrigger, type AccordionTriggerProps, AlertDialogPanel, type AlertDialogPanelProps, type Align, Button, type ButtonProps, Checkbox, type CheckboxProps, ComboboxGroup, ComboboxGroupLabel, type ComboboxGroupLabelProps, type ComboboxGroupProps, ComboboxInput, type ComboboxInputProps, ComboboxItem, type ComboboxItemProps, ComboboxPopover, type ComboboxPopoverProps, ComboboxRoot, type ComboboxRootProps, CommandEmpty, type CommandEmptyProps, CommandGroup, type CommandGroupProps, CommandInput, type CommandInputProps, CommandItem, type CommandItemProps, CommandList, type CommandListProps, CommandRoot, type CommandRootProps, CommandSeparator, type CommandSeparatorProps, Composite, CompositeItem, type CompositeItemProps, type CompositeProps, CompositeProvider, type CompositeProviderProps, CompositeRow, type CompositeRowProps, DialogDescription, type DialogDescriptionProps, DialogDisclosure, type DialogDisclosureProps, DialogDismiss, type DialogDismissProps, DialogHeading, type DialogHeadingProps, DialogPanel, type DialogPanelProps, DialogRoot, type DialogRootProps, DisclosureContent, type DisclosureContentProps, DisclosureRoot, type DisclosureRootProps, DisclosureTrigger, type DisclosureTriggerProps, type FocusableWhenDisabledOptions, type FocusableWhenDisabledProps, FormCheckbox, type FormCheckboxProps, FormControl, type FormControlProps, FormDescription, type FormDescriptionProps, FormError, type FormErrorProps, type FormErrors, FormField, type FormFieldProps, FormGroup, FormGroupLabel, type FormGroupLabelProps, type FormGroupProps, FormInput, type FormInputProps, FormLabel, type FormLabelProps, FormProvider, FormPush, type FormPushProps, FormRadio, FormRadioGroup, type FormRadioGroupProps, type FormRadioProps, FormRemove, type FormRemoveProps, FormReset, type FormResetProps, FormRoot, type FormRootProps, FormSelect, type FormSelectProps, type FormStoreInstance, type FormStoreOptions, FormSubmit, type FormSubmitProps, FormSwitch, type FormSwitchProps, FormTextarea, type FormTextareaProps, MenuButtonArrow, type MenuButtonArrowProps, MenuItem, MenuItemCheckbox, type MenuItemCheckboxProps, type MenuItemProps, MenuItemRadio, type MenuItemRadioProps, MenuPopover, type MenuPopoverProps, MenuRoot, type MenuRootProps, MenuSeparator, type MenuSeparatorProps, MenuTrigger, type MenuTriggerProps, MenubarContainer, type MenubarContainerProps, MenubarRoot, type MenubarRootProps, Meter, type MeterProps, type OffsetArgs, type OffsetValue, PopoverClose, type PopoverCloseProps, PopoverContent, type PopoverContentProps, PopoverRoot, type PopoverRootProps, PopoverTrigger, type PopoverTriggerProps, Progress, type ProgressProps, Radio, RadioGroupRoot, type RadioGroupRootProps, type RadioProps, type RovingTabindexOptions, SelectItem, type SelectItemProps, SelectLabel, type SelectLabelProps, SelectPopover, type SelectPopoverProps, SelectRoot, type SelectRootProps, SelectTrigger, type SelectTriggerProps, Separator, type SeparatorProps, type Side, Switch, type SwitchProps, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, TabsRoot, type TabsRootProps, Toggle, ToggleGroup, type ToggleGroupProps, type ToggleProps, ToolbarButton, type ToolbarButtonProps, ToolbarContainer, type ToolbarContainerProps, ToolbarRoot, type ToolbarRootProps, ToolbarSeparator, type ToolbarSeparatorProps, Tooltip, TooltipAnchor, type TooltipAnchorProps, TooltipGroup, type TooltipGroupProps, type TooltipProps, TooltipProvider, type TooltipProviderProps, TooltipRoot, type TooltipRootProps, type UseFloatingOptions, type ValidateOn, useCommandState, useControllableState, useDialogClose, useEnterLeave, useFieldValue, useFloating, useFocusVisible, useFocusableWhenDisabled, useFormContext, useFormStore, useId, useMenubarContext, useRadioGroupContext, useRovingTabindex, useScrollActiveDescendantIntoView };

package/dist/index.d.ts

@@ -85,10 +85,37 @@ declare function useRovingTabindex(options?: RovingTabindexOptions): {
 //#region src/hooks/use-floating.d.ts
 /** Why an overlay's open state changed, forwarded to `onOpenChange`. */
 type DismissReason = "escape-key" | "outside-press" | "ancestor-scroll";
-/** Dismissal behavior. `true` enables outside-press + escape-key. */
+/**
+ * Dismissal behavior. `true` enables outside-press + escape-key.
+ *
+ * ## Which dismissals to delegate — the overlay policy
+ *
+ * Delegating to floating-ui's `useDismiss` gets shadow-DOM-safe,
+ * reference-aware document listeners for free, so it is the default choice.
+ * An overlay keeps a dismissal for ITSELF only when closing also has to move
+ * focus, because the keydown handler is where the focus target is known:
+ *
+ * | Overlay           | outsidePress | escapeKey | why                                    |
+ * | ----------------- | ------------ | --------- | -------------------------------------- |
+ * | Popover           | delegated    | delegated | `FloatingFocusManager` restores focus   |
+ * | Tooltip           | n/a          | delegated | never holds focus                       |
+ * | Menu              | delegated    | OWN       | Escape must refocus the trigger         |
+ * | Select / Combobox | delegated    | OWN       | Escape keeps focus on trigger/input     |
+ *
+ * `outsidePress` is delegated everywhere: the press target should receive
+ * focus, so no overlay needs to intervene. When adding an overlay, follow this
+ * table rather than inventing a third pattern — and if a new one is genuinely
+ * needed, add a row here.
+ */
 type DismissConfig = boolean | {
+  /** Close on a press outside the reference/floating elements. */
   outsidePress?: boolean;
+  /**
+   * Close on Escape. Set `false` when the overlay handles Escape itself
+   * because it also has to restore focus — see the table above.
+   */
   escapeKey?: boolean;
+  /** Close when an ancestor scroller scrolls. Off by default. */
   ancestorScroll?: boolean;
 };
 /** Physical side a popup is placed on, derived from the resolved placement. */
@@ -389,9 +416,34 @@ declare const Radio: import("react").ForwardRefExoticComponent<RadioProps & impo
 /** Where a portaled overlay mounts: an element, an element id, or body. */
 type PortalRoot = HTMLElement | string | null;
 //#endregion
+//#region src/internal/render-element.d.ts
+/**
+ * The `render` prop contract: swap the element a part renders while keeping all
+ * of its behavior, props and refs. Either a React element to clone, or a
+ * function receiving the merged props.
+ */
+type RenderProp = ReactElement | ((props: Record<string, unknown>) => ReactElement);
+//#endregion
 //#region src/primitives/tooltip.d.ts
-/** Props for `TooltipProvider`. */
-interface TooltipProviderProps {
+/** Props for `TooltipGroup`. */
+interface TooltipGroupProps {
+  children: ReactNode;
+  /**
+   * How long after a tooltip in this group closes its siblings still open
+   * INSTANTLY (no show delay). Default 300ms. Set 0 to disable skipping.
+   */
+  skipDelay?: number;
+}
+/**
+ * Groups sibling tooltips so moving between them does not re-pay the show
+ * delay — the APG/desktop convention for toolbars and icon rows, where waiting
+ * 700ms per button makes the row feel broken.
+ *
+ * Optional: a `TooltipProvider` outside any group keeps its own delay.
+ */
+declare function TooltipGroup({ children, skipDelay }: TooltipGroupProps): React$1.JSX.Element;
+/** Props for `TooltipRoot`. */
+interface TooltipRootProps {
   children: ReactNode;
   timeout?: number;
   showTimeout?: number;
@@ -403,8 +455,27 @@ interface TooltipProviderProps {
   /** Portal mount target (element or element id). Defaults to document.body. */
   portalRoot?: PortalRoot;
 }
-/** Renders the `TooltipProvider` component. */
-declare function TooltipProvider({ children, timeout, showTimeout, hideTimeout, placement, animated, portal, portalRoot }: TooltipProviderProps): React$1.JSX.Element;
+/**
+ * Owns ONE tooltip: its open state, delays, placement and portal.
+ *
+ * Wrap several of these in a {@link TooltipGroup} to share a skip-delay window.
+ */
+declare function TooltipRoot({ children, timeout, showTimeout, hideTimeout, placement, animated, portal, portalRoot }: TooltipRootProps): React$1.JSX.Element;
+/**
+ * Props for `TooltipProvider`.
+ *
+ * @deprecated Use `TooltipRootProps`.
+ */
+type TooltipProviderProps = TooltipRootProps;
+/**
+ * A single tooltip.
+ *
+ * @deprecated Renamed to {@link TooltipRoot}. Despite the name this component
+ * never provided anything to a subtree of tooltips — it IS one tooltip. The
+ * delay-sharing provider is {@link TooltipGroup}. Kept as an alias for
+ * back-compat; scheduled for removal in the next major.
+ */
+declare const TooltipProvider: typeof TooltipRoot;
 /** Props for `TooltipAnchor`. */
 interface TooltipAnchorProps extends ComponentPropsWithoutRef<"div"> {
   /** Render a custom element instead of a wrapper div. The element receives tooltip props. */
@@ -412,9 +483,12 @@ interface TooltipAnchorProps extends ComponentPropsWithoutRef<"div"> {
 }
 declare const TooltipAnchor: React$1.ForwardRefExoticComponent<TooltipAnchorProps & React$1.RefAttributes<HTMLDivElement>>;
 /** Props for `Tooltip`. */
-interface TooltipProps extends ComponentPropsWithoutRef<"div"> {}
+interface TooltipProps extends ComponentPropsWithoutRef<"div"> {
+  /** Render a custom element instead of the default `div`. */
+  render?: RenderProp;
+}
 /** Renders the `Tooltip` component. */
-declare function Tooltip({ children, onMouseEnter, onMouseLeave, ...props }: TooltipProps): React$1.JSX.Element | null;
+declare function Tooltip({ children, onMouseEnter, onMouseLeave, render, ...props }: TooltipProps): React$1.JSX.Element | null;
 //#endregion
 //#region src/primitives/popover.d.ts
 /** Props for `PopoverRoot`. */
@@ -448,9 +522,12 @@ declare function PopoverRoot({ children, open: controlledOpen, defaultOpen, onOp
 interface PopoverTriggerProps extends ComponentPropsWithoutRef<"button"> {}
 declare const PopoverTrigger: import("react").ForwardRefExoticComponent<PopoverTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
 /** Props for `PopoverContent`. */
-interface PopoverContentProps extends ComponentPropsWithoutRef<"div"> {}
+interface PopoverContentProps extends ComponentPropsWithoutRef<"div"> {
+  /** Render a custom element instead of the default `div`. */
+  render?: RenderProp;
+}
 /** Renders the `PopoverContent` component. */
-declare function PopoverContent({ children, ...props }: PopoverContentProps): import("react").JSX.Element | null;
+declare function PopoverContent({ children, render, ...props }: PopoverContentProps): import("react").JSX.Element | null;
 /** Props for `PopoverClose`. */
 interface PopoverCloseProps extends ComponentPropsWithoutRef<"button"> {}
 declare const PopoverClose: import("react").ForwardRefExoticComponent<PopoverCloseProps & import("react").RefAttributes<HTMLButtonElement>>;
@@ -468,6 +545,12 @@ interface SelectRootProps {
   setValue?: (value: string | string[]) => void;
   /** Allow selecting more than one option. The value becomes a `string[]`. */
   multiple?: boolean;
+  /**
+   * Present the current value without allowing changes. Unlike `disabled` the
+   * trigger stays focusable and the listbox still OPENS and can be browsed —
+   * only committing a new value is blocked. Reflected as `aria-readonly`.
+   */
+  readOnly?: boolean;
   /** Form field name. Renders hidden input(s) so the value submits with a form. */
   name?: string;
   open?: boolean;
@@ -482,7 +565,7 @@ interface SelectRootProps {
   portalRoot?: PortalRoot;
 }
 /** Renders the `SelectRoot` component. */
-declare function SelectRoot({ children, value: controlledValue, defaultValue, onValueChange, setValue: setValueDeprecated, multiple, name, open: controlledOpen, onOpenChange, setOpen: setOpenDeprecated, animated, portal, portalRoot }: SelectRootProps): import("react").JSX.Element;
+declare function SelectRoot({ children, value: controlledValue, defaultValue, onValueChange, setValue: setValueDeprecated, multiple, readOnly, name, open: controlledOpen, onOpenChange, setOpen: setOpenDeprecated, animated, portal, portalRoot }: SelectRootProps): import("react").JSX.Element;
 /** Props for `SelectLabel`. */
 interface SelectLabelProps extends ComponentPropsWithoutRef<"label"> {}
 /** Renders the `SelectLabel` component. */
@@ -491,9 +574,12 @@ declare function SelectLabel(props: SelectLabelProps): import("react").JSX.Eleme
 interface SelectTriggerProps extends ComponentPropsWithoutRef<"button"> {}
 declare const SelectTrigger: import("react").ForwardRefExoticComponent<SelectTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
 /** Props for `SelectPopover`. */
-interface SelectPopoverProps extends ComponentPropsWithoutRef<"div"> {}
+interface SelectPopoverProps extends ComponentPropsWithoutRef<"div"> {
+  /** Render a custom element instead of the default `div`. */
+  render?: RenderProp;
+}
 /** Renders the `SelectPopover` component. */
-declare function SelectPopover({ children, ...props }: SelectPopoverProps): import("react").JSX.Element | null;
+declare function SelectPopover({ children, render, ...props }: SelectPopoverProps): import("react").JSX.Element | null;
 /** Props for `SelectItem`. */
 interface SelectItemProps extends ComponentPropsWithoutRef<"div"> {
   value: string;
@@ -512,6 +598,13 @@ interface ComboboxRootProps {
   onValueChange?: (value: string) => void;
   /** @deprecated Use `onValueChange`. */
   setValue?: (value: string) => void;
+  /**
+   * Present the current value without allowing changes. Unlike `disabled` the
+   * input stays focusable and the listbox still OPENS and can be browsed —
+   * only editing the query and committing a new value are blocked. Reflected
+   * as the input's native `readonly` plus `aria-readonly`.
+   */
+  readOnly?: boolean;
   open?: boolean;
   /** Called when the open state changes. */
   onOpenChange?: (open: boolean) => void;
@@ -524,14 +617,17 @@ interface ComboboxRootProps {
   portalRoot?: PortalRoot;
 }
 /** Renders the `ComboboxRoot` component. */
-declare function ComboboxRoot({ children, value: controlledValue, defaultValue, onValueChange, setValue: setValueDeprecated, open: controlledOpen, onOpenChange, setOpen: setOpenDeprecated, animated, portal, portalRoot }: ComboboxRootProps): import("react").JSX.Element;
+declare function ComboboxRoot({ children, value: controlledValue, defaultValue, onValueChange, setValue: setValueDeprecated, readOnly, open: controlledOpen, onOpenChange, setOpen: setOpenDeprecated, animated, portal, portalRoot }: ComboboxRootProps): import("react").JSX.Element;
 /** Props for `ComboboxInput`. */
 interface ComboboxInputProps extends Omit<ComponentPropsWithoutRef<"input">, "value" | "onChange"> {}
 declare const ComboboxInput: import("react").ForwardRefExoticComponent<ComboboxInputProps & import("react").RefAttributes<HTMLInputElement>>;
 /** Props for `ComboboxPopover`. */
-interface ComboboxPopoverProps extends ComponentPropsWithoutRef<"div"> {}
+interface ComboboxPopoverProps extends ComponentPropsWithoutRef<"div"> {
+  /** Render a custom element instead of the default `div`. */
+  render?: RenderProp;
+}
 /** Renders the `ComboboxPopover` component. */
-declare function ComboboxPopover({ children, ...props }: ComboboxPopoverProps): import("react").JSX.Element | null;
+declare function ComboboxPopover({ children, render, ...props }: ComboboxPopoverProps): import("react").JSX.Element | null;
 /** Props for `ComboboxItem`. */
 interface ComboboxItemProps extends ComponentPropsWithoutRef<"div"> {
   value: string;
@@ -588,7 +684,15 @@ interface CommandGroupProps extends ComponentPropsWithoutRef<"div"> {
 declare function CommandGroup({ heading, children, ...props }: CommandGroupProps): import("react").JSX.Element;
 /** Props for `CommandSeparator`. */
 interface CommandSeparatorProps extends ComponentPropsWithoutRef<"div"> {}
-/** Renders the `CommandSeparator` component. */
+/**
+ * Renders the `CommandSeparator` component.
+ *
+ * Rendered with `role="presentation"`: the separator is a child of
+ * `CommandList` (`role="listbox"`), whose only permitted children are `option`
+ * and `group`. A real `role="separator"` there fails
+ * `aria-required-children` and corrupts the option count announced by screen
+ * readers. (Menu separators keep `role="separator"` — `menu` permits it.)
+ */
 declare function CommandSeparator(props: CommandSeparatorProps): import("react").JSX.Element;
 /** Props for `CommandItem`. */
 interface CommandItemProps extends Omit<ComponentPropsWithoutRef<"div">, "onSelect"> {
@@ -646,9 +750,12 @@ declare function MenuRoot({ children, open: controlledOpen, onOpenChange, setOpe
 interface MenuTriggerProps extends ComponentPropsWithoutRef<"button"> {}
 declare const MenuTrigger: import("react").ForwardRefExoticComponent<MenuTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
 /** Props for `MenuPopover`. */
-interface MenuPopoverProps extends ComponentPropsWithoutRef<"div"> {}
+interface MenuPopoverProps extends ComponentPropsWithoutRef<"div"> {
+  /** Render a custom element instead of the default `div`. */
+  render?: RenderProp;
+}
 /** Renders the `MenuPopover` component. */
-declare function MenuPopover({ children, onKeyDown, ...props }: MenuPopoverProps): import("react").JSX.Element | null;
+declare function MenuPopover({ children, onKeyDown, render, ...props }: MenuPopoverProps): import("react").JSX.Element | null;
 /** Props for `MenuItem`. */
 interface MenuItemProps extends ComponentPropsWithoutRef<"div"> {
   disabled?: boolean;
@@ -907,9 +1014,18 @@ interface AccordionTriggerProps extends ComponentPropsWithoutRef<"button"> {}
 /** Renders the `AccordionTrigger` component. */
 declare function AccordionTrigger({ onClick, disabled, ...props }: AccordionTriggerProps): import("react").JSX.Element;
 /** Props for `AccordionContent`. */
-interface AccordionContentProps extends ComponentPropsWithoutRef<"div"> {}
+interface AccordionContentProps extends ComponentPropsWithoutRef<"div"> {
+  /**
+   * When collapsed, keep the content in the DOM as `hidden="until-found"`
+   * (instead of unmounting) so browser find-in-page can reveal it. Chromium
+   * progressive enhancement; disables the enter/leave animation for this
+   * content. On reveal a `beforematch` event expands the item so state stays
+   * consistent.
+   */
+  hiddenUntilFound?: boolean;
+}
 /** Renders the `AccordionContent` component. */
-declare function AccordionContent({ style, ...props }: AccordionContentProps): import("react").JSX.Element | null;
+declare function AccordionContent({ hiddenUntilFound, style, ...props }: AccordionContentProps): import("react").JSX.Element | null;
 //#endregion
 //#region src/form/form-store.d.ts
 /** Field name → error message map. Keys can be dot-paths (e.g. "items.0"). */
@@ -1148,4 +1264,4 @@ interface FormGroupLabelProps extends ComponentPropsWithoutRef<"legend"> {}
 /** Renders the `FormGroupLabel` component. */
 declare function FormGroupLabel(props: FormGroupLabelProps): import("react").JSX.Element;
 //#endregion
-export { AccordionContent, type AccordionContentProps, AccordionItem, type AccordionItemProps, AccordionRoot, type AccordionRootProps, AccordionTrigger, type AccordionTriggerProps, AlertDialogPanel, type AlertDialogPanelProps, type Align, Button, type ButtonProps, Checkbox, type CheckboxProps, ComboboxGroup, ComboboxGroupLabel, type ComboboxGroupLabelProps, type ComboboxGroupProps, ComboboxInput, type ComboboxInputProps, ComboboxItem, type ComboboxItemProps, ComboboxPopover, type ComboboxPopoverProps, ComboboxRoot, type ComboboxRootProps, CommandEmpty, type CommandEmptyProps, CommandGroup, type CommandGroupProps, CommandInput, type CommandInputProps, CommandItem, type CommandItemProps, CommandList, type CommandListProps, CommandRoot, type CommandRootProps, CommandSeparator, type CommandSeparatorProps, Composite, CompositeItem, type CompositeItemProps, type CompositeProps, CompositeProvider, type CompositeProviderProps, CompositeRow, type CompositeRowProps, DialogDescription, type DialogDescriptionProps, DialogDisclosure, type DialogDisclosureProps, DialogDismiss, type DialogDismissProps, DialogHeading, type DialogHeadingProps, DialogPanel, type DialogPanelProps, DialogRoot, type DialogRootProps, DisclosureContent, type DisclosureContentProps, DisclosureRoot, type DisclosureRootProps, DisclosureTrigger, type DisclosureTriggerProps, type FocusableWhenDisabledOptions, type FocusableWhenDisabledProps, FormCheckbox, type FormCheckboxProps, FormControl, type FormControlProps, FormDescription, type FormDescriptionProps, FormError, type FormErrorProps, type FormErrors, FormField, type FormFieldProps, FormGroup, FormGroupLabel, type FormGroupLabelProps, type FormGroupProps, FormInput, type FormInputProps, FormLabel, type FormLabelProps, FormProvider, FormPush, type FormPushProps, FormRadio, FormRadioGroup, type FormRadioGroupProps, type FormRadioProps, FormRemove, type FormRemoveProps, FormReset, type FormResetProps, FormRoot, type FormRootProps, FormSelect, type FormSelectProps, type FormStoreInstance, type FormStoreOptions, FormSubmit, type FormSubmitProps, FormSwitch, type FormSwitchProps, FormTextarea, type FormTextareaProps, MenuButtonArrow, type MenuButtonArrowProps, MenuItem, MenuItemCheckbox, type MenuItemCheckboxProps, type MenuItemProps, MenuItemRadio, type MenuItemRadioProps, MenuPopover, type MenuPopoverProps, MenuRoot, type MenuRootProps, MenuSeparator, type MenuSeparatorProps, MenuTrigger, type MenuTriggerProps, MenubarContainer, type MenubarContainerProps, MenubarRoot, type MenubarRootProps, Meter, type MeterProps, type OffsetArgs, type OffsetValue, PopoverClose, type PopoverCloseProps, PopoverContent, type PopoverContentProps, PopoverRoot, type PopoverRootProps, PopoverTrigger, type PopoverTriggerProps, Progress, type ProgressProps, Radio, RadioGroupRoot, type RadioGroupRootProps, type RadioProps, type RovingTabindexOptions, SelectItem, type SelectItemProps, SelectLabel, type SelectLabelProps, SelectPopover, type SelectPopoverProps, SelectRoot, type SelectRootProps, SelectTrigger, type SelectTriggerProps, Separator, type SeparatorProps, type Side, Switch, type SwitchProps, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, TabsRoot, type TabsRootProps, Toggle, ToggleGroup, type ToggleGroupProps, type ToggleProps, ToolbarButton, type ToolbarButtonProps, ToolbarContainer, type ToolbarContainerProps, ToolbarRoot, type ToolbarRootProps, ToolbarSeparator, type ToolbarSeparatorProps, Tooltip, TooltipAnchor, type TooltipAnchorProps, type TooltipProps, TooltipProvider, type TooltipProviderProps, type UseFloatingOptions, type ValidateOn, useCommandState, useControllableState, useDialogClose, useEnterLeave, useFieldValue, useFloating, useFocusVisible, useFocusableWhenDisabled, useFormContext, useFormStore, useId, useMenubarContext, useRadioGroupContext, useRovingTabindex, useScrollActiveDescendantIntoView };
+export { AccordionContent, type AccordionContentProps, AccordionItem, type AccordionItemProps, AccordionRoot, type AccordionRootProps, AccordionTrigger, type AccordionTriggerProps, AlertDialogPanel, type AlertDialogPanelProps, type Align, Button, type ButtonProps, Checkbox, type CheckboxProps, ComboboxGroup, ComboboxGroupLabel, type ComboboxGroupLabelProps, type ComboboxGroupProps, ComboboxInput, type ComboboxInputProps, ComboboxItem, type ComboboxItemProps, ComboboxPopover, type ComboboxPopoverProps, ComboboxRoot, type ComboboxRootProps, CommandEmpty, type CommandEmptyProps, CommandGroup, type CommandGroupProps, CommandInput, type CommandInputProps, CommandItem, type CommandItemProps, CommandList, type CommandListProps, CommandRoot, type CommandRootProps, CommandSeparator, type CommandSeparatorProps, Composite, CompositeItem, type CompositeItemProps, type CompositeProps, CompositeProvider, type CompositeProviderProps, CompositeRow, type CompositeRowProps, DialogDescription, type DialogDescriptionProps, DialogDisclosure, type DialogDisclosureProps, DialogDismiss, type DialogDismissProps, DialogHeading, type DialogHeadingProps, DialogPanel, type DialogPanelProps, DialogRoot, type DialogRootProps, DisclosureContent, type DisclosureContentProps, DisclosureRoot, type DisclosureRootProps, DisclosureTrigger, type DisclosureTriggerProps, type FocusableWhenDisabledOptions, type FocusableWhenDisabledProps, FormCheckbox, type FormCheckboxProps, FormControl, type FormControlProps, FormDescription, type FormDescriptionProps, FormError, type FormErrorProps, type FormErrors, FormField, type FormFieldProps, FormGroup, FormGroupLabel, type FormGroupLabelProps, type FormGroupProps, FormInput, type FormInputProps, FormLabel, type FormLabelProps, FormProvider, FormPush, type FormPushProps, FormRadio, FormRadioGroup, type FormRadioGroupProps, type FormRadioProps, FormRemove, type FormRemoveProps, FormReset, type FormResetProps, FormRoot, type FormRootProps, FormSelect, type FormSelectProps, type FormStoreInstance, type FormStoreOptions, FormSubmit, type FormSubmitProps, FormSwitch, type FormSwitchProps, FormTextarea, type FormTextareaProps, MenuButtonArrow, type MenuButtonArrowProps, MenuItem, MenuItemCheckbox, type MenuItemCheckboxProps, type MenuItemProps, MenuItemRadio, type MenuItemRadioProps, MenuPopover, type MenuPopoverProps, MenuRoot, type MenuRootProps, MenuSeparator, type MenuSeparatorProps, MenuTrigger, type MenuTriggerProps, MenubarContainer, type MenubarContainerProps, MenubarRoot, type MenubarRootProps, Meter, type MeterProps, type OffsetArgs, type OffsetValue, PopoverClose, type PopoverCloseProps, PopoverContent, type PopoverContentProps, PopoverRoot, type PopoverRootProps, PopoverTrigger, type PopoverTriggerProps, Progress, type ProgressProps, Radio, RadioGroupRoot, type RadioGroupRootProps, type RadioProps, type RovingTabindexOptions, SelectItem, type SelectItemProps, SelectLabel, type SelectLabelProps, SelectPopover, type SelectPopoverProps, SelectRoot, type SelectRootProps, SelectTrigger, type SelectTriggerProps, Separator, type SeparatorProps, type Side, Switch, type SwitchProps, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, TabsRoot, type TabsRootProps, Toggle, ToggleGroup, type ToggleGroupProps, type ToggleProps, ToolbarButton, type ToolbarButtonProps, ToolbarContainer, type ToolbarContainerProps, ToolbarRoot, type ToolbarRootProps, ToolbarSeparator, type ToolbarSeparatorProps, Tooltip, TooltipAnchor, type TooltipAnchorProps, TooltipGroup, type TooltipGroupProps, type TooltipProps, TooltipProvider, type TooltipProviderProps, TooltipRoot, type TooltipRootProps, type UseFloatingOptions, type ValidateOn, useCommandState, useControllableState, useDialogClose, useEnterLeave, useFieldValue, useFloating, useFocusVisible, useFocusableWhenDisabled, useFormContext, useFormStore, useId, useMenubarContext, useRadioGroupContext, useRovingTabindex, useScrollActiveDescendantIntoView };