@trinityui/design-system 2.11.0 → 2.13.0

package/dist/accessibility.d.ts

@@ -4,6 +4,9 @@
  *
  * @module accessibility
  */
+/**
+ * @deprecated since 2.13.0; removed in v3.0 with `useFocusTrap`. See MIGRATION.md.
+ */
 export interface UseFocusTrapOptions {
     /** Whether the focus trap is active */
     enabled?: boolean;
@@ -14,6 +17,9 @@ export interface UseFocusTrapOptions {
     /** Whether to include tab navigation wrapping */
     wrapFocus?: boolean;
 }
+/**
+ * @deprecated since 2.13.0; removed in v3.0 with `useFocusTrap`. See MIGRATION.md.
+ */
 export interface UseFocusTrapReturn {
     /** Ref to attach to the container element */
     containerRef: React.RefObject<HTMLDivElement | null>;
@@ -27,11 +33,51 @@ export interface UseFocusTrapReturn {
 /**
  * Hook to trap focus within a container element.
  * Useful for modals, dialogs, and dropdown menus.
+ *
+ * @deprecated since 2.13.0; removed in v3.0. MUI's focus trap is the one to
+ * use: `Dialog`, `Popover`, `Menu` and a temporary `Drawer` trap focus
+ * themselves, and `FocusTrap` from `@mui/material/Unstable_TrapFocus` covers
+ * a custom surface. This hook only traps after an imperative `activate()`,
+ * and it skips `position: fixed` elements. In development it warns once per
+ * session, from a mount effect. See MIGRATION.md.
  */
 export declare const useFocusTrap: ({ enabled, initialFocus, returnFocus, wrapFocus, }?: UseFocusTrapOptions) => UseFocusTrapReturn;
+/**
+ * The CSS media query for users who prefer reduced motion. Use it as a key in
+ * `sx` or `styled` styles to stop an animation or transition:
+ *
+ * ```tsx
+ * import { REDUCED_MOTION_QUERY } from '@trinityui/design-system';
+ *
+ * <Box
+ *   sx={(theme) => ({
+ *     animation: `${pulse} ${theme.transitions.duration.complex}ms infinite alternate`,
+ *     [REDUCED_MOTION_QUERY]: { animation: 'none' },
+ *   })}
+ * />
+ * ```
+ *
+ * It tests the same media feature as `useReducedMotion`. Prefer it for CSS
+ * motion: the browser applies it from the first paint, also in
+ * server-rendered markup, while the hook returns `false` until hydration has
+ * finished.
+ *
+ * @since 2.13.0
+ */
+export declare const REDUCED_MOTION_QUERY: "@media (prefers-reduced-motion: reduce)";
 /**
  * Hook to detect user's reduced motion preference.
  * Use this to disable animations for users who have requested reduced motion.
+ * For CSS animations and transitions, prefer `REDUCED_MOTION_QUERY` in `sx`.
+ *
+ * Safe for server rendering and hydration (ADR-27). The server render and the
+ * hydration render return `false`, so the hydrated markup matches the server's;
+ * React then re-renders straight after hydration with the user's preference.
+ * A render on the client without server markup returns the preference on its
+ * first render. Later changes of the preference re-render the component.
+ *
+ * @returns `true` when the user prefers reduced motion
+ *   (`prefers-reduced-motion: reduce`), otherwise `false`.
  */
 export declare const useReducedMotion: () => boolean;
 import React from 'react';
@@ -41,14 +87,171 @@ export interface SkipLinkProps {
     targetId: string;
     /** Link text */
     label?: string;
-    /** Custom styles */
+    /**
+     * Custom styles, merged after the skip link's own. The object, array and
+     * function forms all work (array and function since 2.13.0).
+     */
     sx?: SxProps<Theme>;
 }
 /**
  * Skip Link - Provides keyboard users a way to skip navigation.
  * Should be the first focusable element on the page.
+ *
+ * Hidden until it receives focus; then it shows at the inline start of the
+ * viewport (the left in LTR, the right in RTL), above app chrome and every
+ * overlay on the theme's `skipLink` layer role (`zIndex.tooltip + 1`, ADR-03-R12). Activating it (click, Enter or Space) moves
+ * focus to the element with `targetId`.
  */
 export declare const SkipLink: React.FC<SkipLinkProps>;
+/**
+ * How urgently a screen reader reads an announcement: `'polite'` waits until
+ * the user is idle, `'assertive'` interrupts.
+ *
+ * @since 2.13.0
+ */
+export type AnnouncePoliteness = 'polite' | 'assertive';
+/**
+ * Announces a short message to screen readers, for example "Saved" or
+ * "3 results". `politeness` defaults to `'polite'`. An empty message clears
+ * the region and cancels a pending message of that politeness.
+ *
+ * @since 2.13.0
+ */
+export type AnnounceFn = (message: string, politeness?: AnnouncePoliteness) => void;
+/**
+ * Props for `LiveRegionProvider`.
+ *
+ * @since 2.13.0
+ */
+export interface LiveRegionProviderProps {
+    /** The content whose announcements this provider reads out. */
+    children?: React.ReactNode;
+    /**
+     * Milliseconds after which an announced message is removed from its
+     * region, so a screen reader that revisits the page does not find stale
+     * text. Pass `Infinity` to keep each message until the next one.
+     * @default 7000
+     */
+    clearAfterMs?: number;
+}
+/**
+ * Mounts one polite and one assertive live region, visually hidden, after its
+ * children. `useAnnounce` inside it announces through these regions; nested
+ * providers work, and the nearest one wins.
+ *
+ * The regions are siblings after the children, never inside them, so the
+ * provider can wrap a live container (a `role="log"` chat thread) without
+ * nesting live regions. Wrap overlay content in its own provider: MUI hides
+ * everything outside an open modal with `aria-hidden`, including the
+ * document-level regions `useAnnounce` falls back to, and screen readers may
+ * ignore content outside an `aria-modal` dialog.
+ *
+ * A message is written 50 ms after the call (the region is emptied first, so
+ * a repeated message is read again), the latest message per politeness wins,
+ * and it is cleared after `clearAfterMs`. Every timer is cleared on unmount.
+ * The provider renders no text of its own.
+ *
+ * ```tsx
+ * <LiveRegionProvider>
+ *   <SaveButton />
+ * </LiveRegionProvider>
+ *
+ * function SaveButton() {
+ *   const announce = useAnnounce();
+ *   return <Button onClick={() => save().then(() => announce('Saved'))}>Save</Button>;
+ * }
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare function LiveRegionProvider({ children, clearAfterMs, }: LiveRegionProviderProps): React.JSX.Element;
+/**
+ * @internal Test-only: cancels the document-level timers and removes the
+ * document-level regions, so the next announcement starts fresh (mirrors
+ * `__resetDevWarnings` in warnDeprecated.ts). Not exported from any package entry.
+ */
+export declare function __resetDocumentLiveRegion(): void;
+/**
+ * Returns a stable function that announces a message to screen readers
+ * through the nearest `LiveRegionProvider`.
+ *
+ * Without a provider it uses a pair of document-level regions, created at
+ * the end of `document.body` on the first call (never during render, and
+ * never on a server). Their timers belong to the page, not to the calling
+ * component, so a message announced just before the component unmounts (a
+ * deleted row announcing "Deleted") is still read. Inside an open MUI modal
+ * these regions are hidden by `aria-hidden`, so overlay content needs its own
+ * `LiveRegionProvider`.
+ *
+ * ```tsx
+ * const announce = useAnnounce();
+ * announce('Copied');
+ * announce('Upload failed', 'assertive');
+ * ```
+ *
+ * The toolkit has no built-in strings: pass text from your own strings or
+ * `labels` prop.
+ *
+ * @since 2.13.0
+ */
+export declare function useAnnounce(): AnnounceFn;
+/**
+ * Options for `liveRegionProps`.
+ *
+ * @since 2.13.0
+ */
+export interface LiveRegionPropsOptions {
+    /**
+     * The container's role. `'log'` for a chat thread or activity feed,
+     * `'status'` for a status message, `'alert'` for an urgent message.
+     * `'alert'` implies `politeness: 'assertive'` (ADR-32 (3)).
+     */
+    role?: 'log' | 'status' | 'alert';
+    /**
+     * `aria-live`. Defaults to `'assertive'` with `role: 'alert'`, else
+     * `'polite'`. With `role: 'alert'` it is always `'assertive'`.
+     */
+    politeness?: AnnouncePoliteness;
+    /** `aria-relevant`: which changes are read, for example `'additions'` for a log. */
+    relevant?: React.AriaAttributes['aria-relevant'];
+    /** `aria-atomic`: read the whole container on a change (`true`) or only the change (`false`). */
+    atomic?: boolean;
+    /** `aria-busy`: `true` while the content is still arriving (streaming); emitted only when `true`. */
+    busy?: boolean;
+}
+/**
+ * The attributes `liveRegionProps` returns, ready to spread on an element.
+ *
+ * @since 2.13.0
+ */
+export interface LiveRegionAttributes {
+    role?: 'log' | 'status' | 'alert';
+    'aria-live': AnnouncePoliteness;
+    'aria-relevant'?: React.AriaAttributes['aria-relevant'];
+    'aria-atomic'?: boolean;
+    'aria-busy'?: true;
+}
+/**
+ * Attributes for a live *container*: an element whose own content changes
+ * and should be read, such as a chat log or a streaming answer. For a short
+ * transient message ("Saved"), use `useAnnounce` instead.
+ *
+ * `aria-live` is always set. Every other attribute appears only when its
+ * option is passed, so replacing hand-written attributes keeps the DOM
+ * identical:
+ *
+ * ```tsx
+ * <Box {...liveRegionProps({ role: 'log', politeness: 'polite', relevant: 'additions' })}>
+ *   {messages.map((message) => <Message key={message.id} {...message} />)}
+ * </Box>
+ * ```
+ *
+ * Do not nest live containers, and do not put a `LiveRegionProvider` inside
+ * one: wrap the container with the provider instead.
+ *
+ * @since 2.13.0
+ */
+export declare function liveRegionProps(options?: LiveRegionPropsOptions): LiveRegionAttributes;
 export interface UseAriaLiveOptions {
     /** Politeness level */
     politeness?: 'polite' | 'assertive' | 'off';
@@ -57,44 +260,182 @@ export interface UseAriaLiveOptions {
     /** Relevance filter */
     relevant?: 'additions' | 'removals' | 'text' | 'all';
 }
+/**
+ * Options for one `useAriaLive` announcement.
+ *
+ * @since 2.13.0
+ */
+export interface UseAriaLiveAnnounceOptions {
+    /** Read this message with this politeness instead of the hook's. */
+    politeness?: AnnouncePoliteness;
+}
 export interface UseAriaLiveReturn {
-    /** Announce a message */
-    announce: (message: string) => void;
-    /** Clear the current announcement */
+    /**
+     * Announce a message.
+     *
+     * When `ariaProps` is spread on a mounted element (your own region), the
+     * message is written there: `message` empties at once and takes the new
+     * text 50 ms later, so a repeated message is read again. Otherwise the
+     * message goes through `useAnnounce` (the nearest `LiveRegionProvider`, or
+     * the document-level regions), and `message` still follows it.
+     *
+     * Only one announcement is pending at a time: a newer call replaces a
+     * pending one (the last call wins), and a pending update of `message` is
+     * dropped when the component unmounts. With `politeness: 'off'` nothing is
+     * announced.
+     *
+     * `options.politeness` (since 2.13.0) reads this message with another
+     * politeness. When it differs from your region's, the message goes through
+     * `useAnnounce` and your region is left as it is.
+     */
+    announce: (message: string, options?: UseAriaLiveAnnounceOptions) => void;
+    /**
+     * Clear the current announcement and cancel a pending one. When the hook
+     * announces through `useAnnounce`, the region it uses is emptied too.
+     */
     clear: () => void;
     /** Current message */
     message: string;
-    /** ARIA attributes to spread */
+    /**
+     * ARIA attributes to spread on the element that renders `message`. The
+     * `ref` (since 2.13.0) tells the hook that you render the region; keep it
+     * (merge your own ref with `useForkRef` from `@mui/utils`), or messages
+     * are announced twice. `role` is omitted when `politeness` is `'off'`.
+     */
     ariaProps: {
-        role: 'status' | 'alert';
+        role?: 'status' | 'alert';
         'aria-live': 'polite' | 'assertive' | 'off';
         'aria-atomic': boolean;
         'aria-relevant'?: 'additions' | 'removals' | 'text' | 'all';
+        ref: React.RefCallback<HTMLElement>;
     };
 }
 /**
  * Hook for managing ARIA live regions.
  * Useful for announcing dynamic content changes to screen readers.
+ *
+ * Two ways to use it:
+ *
+ * - Call `announce` and render nothing: the message is read through the
+ *   nearest `LiveRegionProvider`, or the document-level regions
+ *   (`useAnnounce`). For new code, prefer `useAnnounce` itself.
+ * - Render `message` inside an element that spreads `ariaProps` and stays
+ *   mounted: that element is the live region, and nothing else announces the
+ *   message.
+ *
+ * At most one update of `message` is pending at a time: `announce` and
+ * `clear` cancel the pending one, and unmounting cancels it, so no state
+ * update runs after unmount.
  */
 export declare const useAriaLive: ({ politeness, atomic, relevant, }?: UseAriaLiveOptions) => UseAriaLiveReturn;
-export interface VisuallyHiddenProps {
-    /** Content to hide visually but keep accessible */
-    children: React.ReactNode;
-    /** HTML element to render as */
+/**
+ * The visually-hidden styles: the content stays in the accessibility tree and
+ * in the tab order, but takes no space and paints nothing. This object is the
+ * single source of these styles. `VisuallyHidden` renders them, and you can
+ * apply them to an element that cannot be a `VisuallyHidden`, for example a
+ * native radio input inside a styled label:
+ *
+ * ```tsx
+ * import { visuallyHiddenSx } from '@trinityui/design-system';
+ *
+ * <Box
+ *   component="label"
+ *   sx={{ '&:has(input:focus-visible)': { outline: '2px solid', outlineColor: 'primary.main', outlineOffset: 2 } }}
+ * >
+ *   <Box component="input" type="radio" name="size" value="m" sx={visuallyHiddenSx} />
+ *   Medium
+ * </Box>
+ * ```
+ *
+ * The object is frozen. Spread it, or pass it first in an `sx` array, to add
+ * styles: `sx={[visuallyHiddenSx, { zIndex: 1 }]}`. Overriding a hiding
+ * property (`position`, `width`, `height`, `margin`, `overflow`, `clip`,
+ * `whiteSpace`) can make the content visible.
+ *
+ * The values are byte-identical to the inline `sx` `VisuallyHidden` used
+ * before 2.13.0, so its generated class has not changed.
+ *
+ * @since 2.13.0
+ */
+export declare const visuallyHiddenSx: Readonly<React.CSSProperties>;
+/**
+ * Props for `VisuallyHidden`. Every standard HTML attribute (`className`,
+ * `style`, `role`, `aria-*`, `data-*`, event handlers, …) is forwarded to the
+ * rendered element. Attribute forwarding, the optional `children`, `id` and
+ * `sx` are available since 2.13.0.
+ */
+export interface VisuallyHiddenProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+    /**
+     * Content to hide visually but keep accessible. Optional, so a void
+     * element such as `as="input"` can be rendered.
+     */
+    children?: React.ReactNode;
+    /**
+     * HTML element to render as.
+     * @default 'span'
+     */
     as?: React.ElementType;
+    /**
+     * Id of the rendered element. Set it to make the hidden text the target of
+     * `aria-describedby` or `aria-labelledby` on another element.
+     * @since 2.13.0
+     */
+    id?: string;
+    /**
+     * Extra styles, merged after the visually-hidden styles. The object, array
+     * and function forms all work. Overriding a hiding property (`position`,
+     * `width`, `height`, `margin`, `overflow`, `clip`, `whiteSpace`) can make
+     * the content visible.
+     * @since 2.13.0
+     */
+    sx?: SxProps<Theme>;
 }
 /**
  * Visually Hidden - Hides content visually while keeping it accessible.
- * Useful for providing additional context to screen readers.
+ * Useful for providing additional context to screen readers. Its styles are
+ * `visuallyHiddenSx`.
+ *
+ * The ref and all other props are forwarded to the rendered element, so it
+ * can be the target of an ARIA relationship:
+ *
+ * ```tsx
+ * const hintId = React.useId();
+ * <Button aria-describedby={hintId}>Delete</Button>
+ * <VisuallyHidden id={hintId}>Deletes the file permanently</VisuallyHidden>
+ * ```
+ *
+ * The ref is typed `HTMLSpanElement`, the default element. With `as` set to
+ * another element, the ref receives that element, so cast it as needed. Ref
+ * forwarding is available since 2.13.0.
  */
-export declare const VisuallyHidden: React.FC<VisuallyHiddenProps>;
+export declare const VisuallyHidden: React.ForwardRefExoticComponent<VisuallyHiddenProps & React.RefAttributes<HTMLSpanElement>>;
 export type NavigationDirection = 'horizontal' | 'vertical' | 'both';
 export interface UseRovingTabIndexOptions {
-    /** List of item refs */
+    /**
+     * List of item refs, in order. An item whose element is `disabled` or
+     * `aria-disabled="true"` is skipped by the arrow keys, Home and End, and
+     * never keeps the tab stop: right after each commit of the component that
+     * calls the hook, a tab stop on a disabled item passes to the nearest
+     * enabled one (forward first), before the browser paints. The server render
+     * and the first client render cannot see the elements, so they use
+     * `currentIndex` as given.
+     */
     items: React.RefObject<HTMLElement | null>[];
-    /** Current focused index */
+    /**
+     * Index of the item that owns the tab stop. Whenever this value changes,
+     * the tab stop moves to that item (focus does not move). It is clamped to
+     * the list. The arrow keys also move the tab stop; to control it, pass
+     * `onIndexChange` and feed the reported index back, otherwise setting the
+     * value it already had (after the arrow keys moved away) changes nothing.
+     * @default 0
+     */
     currentIndex?: number;
-    /** Navigation direction */
+    /**
+     * Navigation axis: `'vertical'` uses ArrowUp and ArrowDown, `'horizontal'`
+     * ArrowLeft and ArrowRight (swapped when the theme direction is `'rtl'`),
+     * `'both'` uses all four.
+     * @default 'vertical'
+     */
     direction?: NavigationDirection;
     /** Whether navigation wraps */
     wrap?: boolean;
@@ -112,8 +453,245 @@ export interface UseRovingTabIndexReturn {
     getTabIndex: (index: number) => 0 | -1;
 }
 /**
- * Hook for implementing roving tabindex keyboard navigation.
- * Useful for lists, tabs, and other navigable components.
+ * Options for the registry form of {@link useRovingTabIndex}: the form you get
+ * when you pass no `items` array. Items register themselves through
+ * `getItemProps(id)`, so the hook tracks them by id rather than by index.
+ *
+ * @typeParam Id - The type of the item ids, `string` by default.
+ * @since 2.13.0
+ */
+export interface UseRovingTabIndexRegistryOptions<Id extends string | number = string> {
+    /**
+     * Not part of the registry form. An options object with a defined `items`
+     * selects the legacy refs-array form, at runtime and in the types, so the
+     * registry options never carry one. An explicit `items: undefined` is the
+     * registry form.
+     */
+    items?: never;
+    /**
+     * The axis the arrow keys move along. `'vertical'` uses ArrowUp and
+     * ArrowDown, `'horizontal'` uses ArrowLeft and ArrowRight. Home and End
+     * always move to the first and last enabled item. The other arrow pair is
+     * left to the consumer (a tree uses it to expand and collapse).
+     */
+    orientation: 'horizontal' | 'vertical';
+    /**
+     * The id that should own the tab stop. Whenever this value changes, the tab
+     * stop moves to that item. Focus does not move; call `focusItem` for that.
+     * Keyboard and pointer focus still move the tab stop, and every such move is
+     * reported through `onActiveIdChange`, a move back onto this item included;
+     * pass the reported id back to keep the two in sync.
+     * Once items have registered, an id that is not registered falls back to the
+     * first enabled item, and a disabled one to the next enabled item after it;
+     * `defaultActiveId` and the selected item are not consulted. If the item
+     * this id names registers or becomes enabled later, and the user has not
+     * moved the tab stop in the meantime, the tab stop moves to it then.
+     * Before any item has registered (the server render and the first client
+     * render), this id owns the tab stop only if it names an enabled item that
+     * is rendered; otherwise the markup has no tab stop until the items
+     * register. A disabled or unrendered id does not fall back to
+     * `defaultActiveId` there.
+     * Omit it, or pass `null`, to let the hook choose (see `defaultActiveId`).
+     */
+    activeId?: Id | null;
+    /**
+     * The item that owns the tab stop until the user or `activeId` moves it. It
+     * applies only while `activeId` is omitted or `null`. When it is omitted, or
+     * names an item that is missing or disabled, the first enabled item
+     * registered with `selected: true` owns the tab stop, otherwise the first
+     * enabled item.
+     * Before any item has registered (the server render and the first client
+     * render) there is no such fallback: `activeId`, else this id, owns the tab
+     * stop only if it names an enabled item that is rendered, and otherwise the
+     * markup has no tab stop until the items register (a disabled `activeId`
+     * does not fall back to this id). For exactly one tab stop in the server
+     * markup, pass an id that names an enabled, rendered item.
+     */
+    defaultActiveId?: Id | null;
+    /**
+     * Called after the tab stop moves from one item to another: through the
+     * arrow keys, Home or End, focus (click or Tab), `setActiveId`, `focusItem`,
+     * because the active item was removed or disabled, or because the item that
+     * `activeId` names registered or became enabled after the option changed.
+     * A move onto the item `activeId` names is reported too when the user made
+     * it. It is not called for the first tab stop after the items register, or
+     * for a move in the same render as a change of the `activeId` option (you
+     * made that change, so you already know the id).
+     */
+    onActiveIdChange?: (id: Id) => void;
+    /**
+     * Whether the arrow keys wrap from the last item to the first and back.
+     * @default true
+     */
+    wrap?: boolean;
+    /**
+     * Text direction. With `'rtl'` and `orientation: 'horizontal'`, ArrowLeft
+     * moves to the next item and ArrowRight to the previous one. Defaults to
+     * the theme's `direction`, so a theme created with `'rtl'` needs nothing
+     * more.
+     * @default theme.direction
+     */
+    direction?: 'ltr' | 'rtl';
+}
+/**
+ * Options for one item in the registry form of {@link useRovingTabIndex},
+ * passed as the second argument of `getItemProps`.
+ *
+ * @since 2.13.0
+ */
+export interface UseRovingTabIndexItemOptions {
+    /**
+     * The item is skipped by the arrow keys, Home and End, and never owns the
+     * tab stop. A `disabled` attribute or `aria-disabled="true"` on the item
+     * element counts as well once the item has registered; before that (the
+     * server render and the first client render) only this option is seen.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * The item is selected in your own state. When `defaultActiveId` is not
+     * given, the first enabled selected item is the default tab stop (the APG
+     * rule for listboxes, trees and tabs).
+     * @default false
+     */
+    selected?: boolean;
+    /**
+     * Your own ref to the item element. It is merged into the returned `ref`,
+     * so do not also pass it to the element.
+     */
+    ref?: React.Ref<HTMLElement>;
+}
+/**
+ * What the registry form of {@link useRovingTabIndex} returns.
+ *
+ * @typeParam Id - The type of the item ids, `string` by default.
+ * @since 2.13.0
+ */
+export interface UseRovingTabIndexRegistryReturn<Id extends string | number = string> {
+    /**
+     * The id of the item that owns the tab stop (`tabIndex` 0) in this render,
+     * or `null` when no enabled item is registered and no fallback applies.
+     */
+    activeId: Id | null;
+    /**
+     * Moves the tab stop to `id` without moving focus. With `{ focus: true }`
+     * it behaves like `focusItem`.
+     */
+    setActiveId: (id: Id, options?: {
+        focus?: boolean;
+    }) => void;
+    /**
+     * Props for the container element (the `toolbar`, `listbox`, `tree`, ...).
+     * They handle the arrow keys, Home and End for this container's items, and
+     * keep the tab stop on the item that receives focus. Pass your own
+     * `onKeyDown`, `onFocus` and `ref` through here rather than on the element:
+     * your handlers run first, and calling `event.preventDefault()` in your
+     * `onKeyDown` stops the hook from handling that key. Inline handlers get
+     * their parameter types from here (`onKeyDown: (event) => ...`). Every other
+     * prop you pass is returned unchanged.
+     */
+    getContainerProps: <P extends object = Record<never, never>>(userProps?: P & {
+        /** Runs before the hook's own focus handling. */
+        onFocus?: React.FocusEventHandler<HTMLElement>;
+        /** Runs before the hook's own key handling; `event.preventDefault()` opts the key out. */
+        onKeyDown?: React.KeyboardEventHandler<HTMLElement>;
+        /** Your container ref, merged with the hook's own. */
+        ref?: React.Ref<HTMLElement>;
+    }) => Omit<P, 'onFocus' | 'onKeyDown' | 'ref'> & {
+        /** Moves the tab stop to the registered item that receives focus. */
+        onFocus: React.FocusEventHandler<HTMLElement>;
+        /** Handles the arrow keys of `orientation`, Home and End. Keys pressed with Alt, Ctrl, Meta or Shift are ignored. */
+        onKeyDown: React.KeyboardEventHandler<HTMLElement>;
+        /** Merges your container ref with the hook's own. */
+        ref: React.RefCallback<HTMLElement>;
+    };
+    /**
+     * Props for one item. Spread both on the item element: the `ref` registers
+     * it, and `tabIndex` is 0 for the tab stop and -1 for every other item.
+     * Calling it for each item while rendering is safe; no hook runs per item.
+     * Each `id` must be unique within this hook and render on one element.
+     * Items are ordered by their position in the document, and must not contain
+     * one another (render a nested group next to its parent item, not inside
+     * it).
+     */
+    getItemProps: (id: Id, options?: UseRovingTabIndexItemOptions) => {
+        /** Registers the element under `id` while it is mounted. */
+        ref: React.RefCallback<HTMLElement>;
+        /** 0 for the item that owns the tab stop, -1 for the others. */
+        tabIndex: 0 | -1;
+    };
+    /**
+     * Moves focus to the item `id` and makes it the tab stop. Does nothing when
+     * the item is not mounted or is disabled.
+     */
+    focusItem: (id: Id) => void;
+}
+/**
+ * Roving tabindex for composite widgets (toolbar, listbox, tree, grid, radio
+ * group): the group is one Tab stop, and the arrow keys move focus inside it
+ * (WAI-ARIA APG, "Keyboard Navigation Inside Components"). Prefer a native or
+ * MUI widget that already does this (`RadioGroup`, `MenuList`, `Tabs`).
+ *
+ * **Registry form** (since 2.13.0; no `items`, or `items: undefined`): spread
+ * `getContainerProps()` on the container and
+ * `getItemProps(id, { disabled, selected })` on each item.
+ * Arrow keys along `orientation`, Home and End move focus between the enabled
+ * items in document order; disabled items are skipped. The tab stop follows
+ * focus. Before the user moves it, it is the item `activeId` names (an id
+ * that is not registered falls back to the first enabled item, a disabled one
+ * to the next enabled item after it); without `activeId`, it is
+ * `defaultActiveId`, otherwise the first enabled selected item, otherwise the
+ * first enabled item. Before any item has registered (the server render and
+ * the first client render), `activeId`, else `defaultActiveId`, is the tab
+ * stop only if it names an enabled, rendered item; otherwise the markup has
+ * no tab stop until the items register. Built on `useRovingTabIndexRoot` from
+ * `@mui/utils`.
+ *
+ * ```tsx
+ * const roving = useRovingTabIndex({ orientation: 'horizontal' });
+ * <div role="toolbar" aria-label="Formatting" {...roving.getContainerProps()}>
+ *   {tools.map((tool) => (
+ *     <button key={tool.id} type="button" disabled={tool.disabled}
+ *       {...roving.getItemProps(tool.id, { disabled: tool.disabled })}>
+ *       {tool.label}
+ *     </button>
+ *   ))}
+ * </div>
+ * ```
+ *
+ * Horizontal arrows follow the text direction: `direction` (registry form),
+ * else the theme's `direction`.
+ *
+ * **Legacy form** (`items`, an array of refs): the same signature as earlier
+ * releases. You attach `handleKeyDown` and read `getTabIndex(index)`. Since
+ * 2.13.0 it skips disabled items (also at Home and End), moves the tab stop
+ * when `currentIndex` changes, clamps it when the list shrinks, and swaps
+ * ArrowLeft and ArrowRight in an RTL theme. Prefer the registry form for new
+ * code.
+ *
+ * The form is fixed on the first render. Switching between them on a mounted
+ * component throws; remount it (change its `key`) instead.
+ *
+ * Types: the id type comes from the options only. It is `string` unless they
+ * say otherwise: a number in `activeId` or `defaultActiveId` gives `number`,
+ * string and number ids together give `string | number`, and an
+ * `onActiveIdChange` that accepts only a narrower type (a `number` handler,
+ * an `(id: TabId) => void` handler, or the setter of `useState<TabId>` passed
+ * with `activeId: tab`) gives that type. A value alone does not narrow them:
+ * a literal such as `defaultActiveId: 'apple'`, or `activeId: tab` typed
+ * `TabId` with no callback, gives `string`. Ids passed only to
+ * `getItemProps`, `focusItem` or `setActiveId` do not count, so pass the
+ * type: `useRovingTabIndex<number>({ orientation: 'horizontal' })`. A type
+ * argument also narrows, for example `useRovingTabIndex<TabId>(...)`; pass
+ * one when a literal default meets a narrower handler, which otherwise types
+ * the ids as that literal. The legacy signature is declared last, so
+ * `ReturnType<typeof useRovingTabIndex>` and
+ * `Parameters<typeof useRovingTabIndex>` still describe the legacy form; name
+ * the registry types (`UseRovingTabIndexRegistryReturn`, ...) directly.
  */
-export declare const useRovingTabIndex: ({ items, currentIndex, direction, wrap, onIndexChange, }: UseRovingTabIndexOptions) => UseRovingTabIndexReturn;
+export declare function useRovingTabIndex(options: UseRovingTabIndexRegistryOptions<string>): UseRovingTabIndexRegistryReturn<string>;
+export declare function useRovingTabIndex(options: UseRovingTabIndexRegistryOptions<number>): UseRovingTabIndexRegistryReturn<number>;
+export declare function useRovingTabIndex<Id extends string | number>(options: UseRovingTabIndexRegistryOptions<Id>): UseRovingTabIndexRegistryReturn<Id>;
+export declare function useRovingTabIndex<Id extends string | number>(options: UseRovingTabIndexRegistryOptions<NoInfer<Id>>): UseRovingTabIndexRegistryReturn<Id>;
+export declare function useRovingTabIndex(options: UseRovingTabIndexOptions): UseRovingTabIndexReturn;
 //# sourceMappingURL=accessibility.d.ts.map