@allxsmith/bestax-bulma 5.20.0 → 5.23.0

package/dist/types/components/Collapse.d.ts

@@ -6,14 +6,21 @@ import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
  * @extraProp {string} [className] - Additional CSS classes.
  */
 export interface CollapseProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
-    /** Controlled open state. If provided, component is controlled. */
+    /**
+     * Controlled open state. If provided, component is controlled, and the
+     * trigger only reports through `onOpenChange`. Inside a `Collapses` group, a
+     * Collapse that sets `open` stays yours: the group neither overrides it nor
+     * closes it when another item opens.
+     */
     open?: boolean;
-    /** Initial open state for uncontrolled usage. */
+    /** Initial open state for uncontrolled usage. Ignored inside a `Collapses` group, whose `defaultValue` decides. */
     defaultOpen?: boolean;
-    /** Callback when collapse opens. */
+    /** Called when the trigger opens the Collapse. Fires only while the Collapse keeps its own state: not when `open` is set, and not when a `Collapses` group manages it. `onOpenChange` reports in every mode. */
     onOpen?: () => void;
-    /** Callback when collapse closes. */
+    /** Called when the trigger closes the Collapse. Fires only while the Collapse keeps its own state: not when `open` is set, and not when a `Collapses` group manages it. `onOpenChange` reports in every mode. */
     onClose?: () => void;
+    /** Called with the state the trigger asks for (`true` to open) each time it is clicked or activated with Enter or Space, in every mode. Pair it with `open` to let the trigger drive a controlled Collapse. */
+    onOpenChange?: (open: boolean) => void;
     /** The clickable trigger element (header/button). */
     trigger?: React.ReactNode;
     /** Animation style, or `false` to disable. */
@@ -46,12 +53,9 @@ export interface CollapseProps extends Omit<React.HTMLAttributes<HTMLDivElement>
  * </Collapse>
  *
  * @example
- * // Controlled collapse
+ * // Controlled collapse, driven by its own trigger
  * const [isOpen, setIsOpen] = useState(false);
- * <Collapse
- *   open={isOpen}
- *   trigger={<button onClick={() => setIsOpen(!isOpen)}>Toggle</button>}
- * >
+ * <Collapse open={isOpen} onOpenChange={setIsOpen} trigger={<strong>Toggle</strong>}>
  *   <p>Content</p>
  * </Collapse>
  *

package/dist/types/components/Collapses.d.ts

@@ -0,0 +1,53 @@
+import React from 'react';
+import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
+/**
+ * Props shared by both modes of the Collapses component.
+ */
+interface CollapsesBaseProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color' | 'defaultValue' | 'onChange'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Joins the items into one block, with no gap between them and only the outer corners rounded. The joins show on `bordered` items. */
+    seamless?: boolean;
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /** The `Collapse` items. Each child element is one item, indexed from 0 in order, with the children of a fragment counted one by one. A child that sets its own `open` keeps it: the group leaves that item alone. */
+    children?: React.ReactNode;
+}
+/**
+ * Props for Collapses in single mode, the accordion: opening one item closes the others.
+ */
+export interface CollapsesSingleProps extends CollapsesBaseProps {
+    /**
+     * Lets items open independently. Without it, opening one item closes the others.
+     * @defaultValue false
+     */
+    multiple?: false;
+    /** Controlled open items: the index of the open item, or `null` for none. With `multiple`, an array of indexes. An index is a position among the children, so rendering an item conditionally or reordering them moves the open state onto a neighbour: render every item and hide one with `visibility="hidden"`, or keep `value` in step yourself. */
+    value?: number | null;
+    /** Open items for uncontrolled use, as an index or `null` (the default, none open). With `multiple`, an array of indexes, empty by default. Indexes are positions among the children, as for `value`. */
+    defaultValue?: number | null;
+    /** Called with the new open items each time a trigger asks for a change, whether or not `value` is set: an index or `null`, or with `multiple` an array of indexes in ascending order. Indexes are positions among the children, as for `value`. */
+    onChange?: (value: number | null) => void;
+}
+/**
+ * Props for Collapses with `multiple`: items open and close independently.
+ */
+export interface CollapsesMultipleProps extends CollapsesBaseProps {
+    /**
+     * Lets items open independently. Without it, opening one item closes the others.
+     * @defaultValue false
+     */
+    multiple: true;
+    /** Controlled open items: the index of the open item, or `null` for none. With `multiple`, an array of indexes. An index is a position among the children, so rendering an item conditionally or reordering them moves the open state onto a neighbour: render every item and hide one with `visibility="hidden"`, or keep `value` in step yourself. */
+    value?: number[];
+    /** Open items for uncontrolled use, as an index or `null` (the default, none open). With `multiple`, an array of indexes, empty by default. Indexes are positions among the children, as for `value`. */
+    defaultValue?: number[];
+    /** Called with the new open items each time a trigger asks for a change, whether or not `value` is set: an index or `null`, or with `multiple` an array of indexes in ascending order. Indexes are positions among the children, as for `value`. */
+    onChange?: (value: number[]) => void;
+}
+/**
+ * Props for the Collapses component, a discriminated union on `multiple`: the open items are an index (or `null`) in single mode and an array of indexes with `multiple`.
+ */
+export type CollapsesProps = CollapsesSingleProps | CollapsesMultipleProps;
+export declare const Collapses: React.FC<CollapsesProps> & {
+    Collapse: React.FC<import("./Collapse.js").CollapseProps>;
+};
+export default Collapses;

package/dist/types/components/collapsesContext.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What a `Collapses` group hands the item it wraps: whether that item is open,
+ * and how to ask the group for a change.
+ *
+ * This module is internal. `index.ts` re-exports `Collapse` and `Collapses`
+ * whole, so the context lives here, where neither re-export reaches it.
+ */
+export interface CollapsesItemContextValue {
+    /** Whether the group has this item open. */
+    open: boolean;
+    /** Asks the group to open (`true`) or close (`false`) this item. */
+    setOpen: (open: boolean) => void;
+}
+/**
+ * `null` outside a group. A `Collapse` also resets it to `null` for its own
+ * subtree, so a Collapse nested in an item's content keeps its own state
+ * instead of answering to its ancestor's slot in the group.
+ */
+export declare const CollapsesItemContext: import("react").Context<CollapsesItemContextValue | null>;

package/dist/types/helpers/ClientOnly.d.ts

@@ -0,0 +1,40 @@
+import React from 'react';
+/**
+ * Props for the ClientOnly component.
+ */
+export interface ClientOnlyProps {
+    /**
+     * Content to render once the page has hydrated. A function is called only
+     * then, so an inline expression that reads `window`, `document` or
+     * `localStorage` never runs on the server.
+     */
+    children?: React.ReactNode | (() => React.ReactNode);
+    /**
+     * Rendered on the server and during hydration instead of `children`, such
+     * as a placeholder the same size as the content so the layout doesn't
+     * shift when it arrives.
+     * @defaultValue null
+     */
+    fallback?: React.ReactNode;
+}
+/**
+ * Renders its children only in the browser, after hydration, and a `fallback` until then, so content that depends on browser-only state doesn't cause a hydration mismatch.
+ *
+ * The server render and the hydrating client render both show `fallback`,
+ * which keeps them identical; the children replace it in the commit that
+ * follows. In an app without server rendering the children show on the first
+ * render.
+ *
+ * @function
+ * @param {ClientOnlyProps} props - Props for the ClientOnly component.
+ * @returns The children once hydrated, otherwise the fallback.
+ *
+ * @example
+ * // The server's time zone is not the reader's.
+ * <ClientOnly fallback={<Skeleton variant="lines" lines={1} />}>
+ *   {() => (
+ *     <p>Times are shown in {Intl.DateTimeFormat().resolvedOptions().timeZone}.</p>
+ *   )}
+ * </ClientOnly>
+ */
+export declare function ClientOnly({ children, fallback }: ClientOnlyProps): React.JSX.Element;

package/dist/types/helpers/inertProps.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+/**
+ * The prop that makes an element inert, spelled for the React in use, or
+ * nothing when `inert` is false.
+ *
+ * Both majors must render `inert=""`, and each warns on the other's spelling
+ * and then drops the attribute. React 19 treats `inert` as a boolean and
+ * rejects the empty string. React 18 does not know the attribute, so it
+ * passes a string through and rejects `true`.
+ */
+export declare const inertProps: (inert: boolean, major?: number) => React.HTMLAttributes<HTMLElement>;

package/dist/types/helpers/portal.d.ts

@@ -1,3 +1,4 @@
+import React from 'react';
 /**
  * Resolves a portal target: an `HTMLElement` is used directly, a non-empty
  * `string` is treated as a `document.querySelector` selector (falling back to
@@ -13,3 +14,64 @@
  * @returns The resolved DOM node to portal into.
  */
 export declare function resolvePortalContainer(container?: string | HTMLElement): HTMLElement;
+/**
+ * Props for the Portal component.
+ */
+export interface PortalProps {
+    /** Content to render into the container. */
+    children?: React.ReactNode;
+    /**
+     * Where the content goes: an element, or a `document.querySelector`
+     * selector. Omitted, empty, or a selector that matches nothing, it goes to
+     * `document.body`. A selector is looked up again on each render, so the
+     * content follows the target when it changes. Moving to another target
+     * remounts the children and resets their state, which includes a selector
+     * that only starts matching after the content has shown in `document.body`.
+     * Render the target first, or pass the element once you have it.
+     */
+    container?: string | HTMLElement;
+    /**
+     * Render the children in place instead, on the server as well as the
+     * client. Lets a component that portals only sometimes keep a single code
+     * path.
+     * @defaultValue false
+     */
+    disabled?: boolean;
+}
+/**
+ * Renders its children into another part of the page, `document.body` unless `container` says otherwise, so floating content escapes an ancestor's `overflow`, `transform` or stacking context.
+ *
+ * React's server renderer can't render a portal, so `Portal` renders nothing
+ * on the server and during hydration, and mounts its children in the commit
+ * that follows. The first client render then matches the server markup. In an app
+ * without server rendering it portals on the first render.
+ *
+ * React context, such as `ConfigProvider`'s class prefix, reaches the
+ * portaled children, and their React events bubble through the React tree.
+ * CSS inheritance follows the DOM instead: a scoped (non-`isRoot`) `Theme`
+ * sets its variables on a wrapper element the portaled content has left, so
+ * that content sees the page-level theme. Point `container` at an element
+ * inside the themed area to keep it.
+ *
+ * Tab order and focus follow the DOM too. Content portaled from inside a
+ * focus trap is no longer inside the trapped element, so the trap neither
+ * reaches it nor holds focus there: render nested overlays inside the
+ * trapped element, or give them a trap of their own.
+ *
+ * @function
+ * @param {PortalProps} props - Props for the Portal component.
+ * @returns The portal, the children in place when `disabled`, or nothing
+ * before hydration.
+ *
+ * @example
+ * <Portal>
+ *   <div className="box">Rendered at the end of document.body</div>
+ * </Portal>
+ *
+ * @example
+ * // Into a dedicated overlay root
+ * <Portal container="#overlays">
+ *   <CommandPalette />
+ * </Portal>
+ */
+export declare function Portal({ children, container, disabled }: PortalProps): React.JSX.Element | null;

package/dist/types/helpers/shadowDom.d.ts

@@ -49,6 +49,8 @@ export declare function getActiveElementInTree(node: Node | null | undefined): E
  * opener sits in. A closed shadow root cannot be entered, so focus inside one
  * reads as its host.
  *
+ * @param doc - The document to start from: the component's own, when it may
+ * render into one other than the page's (an iframe's). Defaults to `document`.
  * @returns The focused element, or `null` when the document has none.
  */
-export declare function getDeepestActiveElement(): Element | null;
+export declare function getDeepestActiveElement(doc?: Document): Element | null;

package/dist/types/helpers/useFocusTrap.d.ts

@@ -0,0 +1,74 @@
+import type { RefObject } from 'react';
+/**
+ * Options for `useFocusTrap`.
+ */
+export interface UseFocusTrapOptions {
+    /**
+     * Whether the trap is on. Turning it on moves focus into the container;
+     * turning it off (or unmounting) releases Tab and restores focus.
+     * @defaultValue true
+     */
+    active?: boolean;
+    /**
+     * The element to focus when the trap turns on. Without it, or while it
+     * points at nothing, focus goes to the first tab stop inside the container,
+     * and to the container itself when there is none.
+     */
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    /**
+     * Where focus goes when the trap turns off. `true` returns it to the element
+     * that had focus when the trap turned on; a ref sends it to that element
+     * instead; `false` leaves it alone. Focus is only moved while the trap still
+     * holds it, so a click that already put focus somewhere else outside the
+     * container keeps it there.
+     *
+     * `true` reads focus after the container's content has mounted, so content
+     * that focuses itself as it mounts (an `autoFocus` input) hides the element
+     * that opened it. And some browsers don't focus a button when it is
+     * clicked. For a panel opened from a button, pass the button's ref.
+     * @defaultValue true
+     */
+    restoreFocus?: boolean | RefObject<HTMLElement | null>;
+}
+/**
+ * Keeps keyboard focus inside a container while it is active: focus moves in
+ * when the trap turns on, Tab and Shift+Tab wrap between the first and last
+ * tab stops, and focus goes back where it came from when the trap turns off.
+ *
+ * Tab stops are what the browser's Tab visits, in document order: links,
+ * form controls, frames, media with controls, a `<details>` summary, editable
+ * regions, anything with `tabIndex={0}`, and the content of open shadow
+ * roots. Hidden, disabled, inert and `tabIndex={-1}` elements are skipped,
+ * and a radio group counts once. Give the container `tabIndex={-1}` so it can
+ * hold focus itself when nothing inside can. The trap listens on the
+ * container, so a trap nested inside another handles Tab first and the outer
+ * one stands aside.
+ *
+ * The trap is about Tab. If a Tab it let through still takes focus out (a
+ * browser can leave out a stop the page has, such as links when its settings
+ * say to), it sends focus back to the other end. A pointer or a script moving
+ * focus out is left alone, because pulling focus back from a click is modal
+ * behaviour, and a modal also has to block the page behind it, which `Modal`
+ * does. Content the container renders through a portal lives elsewhere in
+ * the DOM, so it is outside the trap: render nested overlays inside the
+ * container, or give them a trap of their own.
+ *
+ * The container has to be in the DOM when the trap turns on. The trap waits
+ * for hydration, so a container that only appears once the page has
+ * hydrated, the way portaled content does, still has it attach in the commit
+ * where the container appears.
+ *
+ * @function useFocusTrap
+ * @param containerRef - Ref to the element focus stays inside.
+ * @param options - When the trap is on, and where focus starts and ends.
+ *
+ * @example
+ * const panelRef = useRef<HTMLDivElement>(null);
+ * useFocusTrap(panelRef, { active: isOpen });
+ * return isOpen ? (
+ *   <div ref={panelRef} role="dialog" aria-label="Filters" tabIndex={-1}>
+ *     …
+ *   </div>
+ * ) : null;
+ */
+export declare function useFocusTrap(containerRef: RefObject<HTMLElement | null>, options?: UseFocusTrapOptions): void;

package/dist/types/helpers/useIsHydrated.d.ts

@@ -6,6 +6,11 @@
  * DOM-only behaviour (such as portalling) past hydration so the first client
  * render matches the server markup instead of tripping hydration recovery.
  *
+ * Only a component that hydrates ever sees `false` on the client. One that
+ * mounts later (after a route change, or in an app with no server rendering)
+ * gets `true` on its first render, so it pays for no extra render. It
+ * subscribes to nothing, so no later render flips it back.
+ *
  * @function useIsHydrated
  * @returns `true` once the hydrating render has completed, otherwise `false`.
  */

package/dist/types/index.d.ts

@@ -15,6 +15,7 @@ export * from './components/Panel.js';
 export * from './components/Tabs.js';
 export * from './components/Loading.js';
 export * from './components/Collapse.js';
+export * from './components/Collapses.js';
 export * from './components/Tooltip.js';
 export * from './components/Steps.js';
 export * from './components/Sidebar.js';
@@ -106,6 +107,13 @@ export * from './helpers/mergeBulmaStyles.js';
 export * from './helpers/useBulmaClasses.js';
 export * from './helpers/Theme.js';
 export * from './helpers/Config.js';
+export { ClientOnly } from './helpers/ClientOnly.js';
+export type { ClientOnlyProps } from './helpers/ClientOnly.js';
+export { useIsHydrated } from './helpers/useIsHydrated.js';
+export { Portal } from './helpers/portal.js';
+export type { PortalProps } from './helpers/portal.js';
+export { useFocusTrap } from './helpers/useFocusTrap.js';
+export type { UseFocusTrapOptions } from './helpers/useFocusTrap.js';
 export * from './layout/Container.js';
 export * from './layout/Footer.js';
 export * from './layout/Hero.js';

package/dist/types-cjs/components/Collapse.d.ts

@@ -6,14 +6,21 @@ import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
  * @extraProp {string} [className] - Additional CSS classes.
  */
 export interface CollapseProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
-    /** Controlled open state. If provided, component is controlled. */
+    /**
+     * Controlled open state. If provided, component is controlled, and the
+     * trigger only reports through `onOpenChange`. Inside a `Collapses` group, a
+     * Collapse that sets `open` stays yours: the group neither overrides it nor
+     * closes it when another item opens.
+     */
     open?: boolean;
-    /** Initial open state for uncontrolled usage. */
+    /** Initial open state for uncontrolled usage. Ignored inside a `Collapses` group, whose `defaultValue` decides. */
     defaultOpen?: boolean;
-    /** Callback when collapse opens. */
+    /** Called when the trigger opens the Collapse. Fires only while the Collapse keeps its own state: not when `open` is set, and not when a `Collapses` group manages it. `onOpenChange` reports in every mode. */
     onOpen?: () => void;
-    /** Callback when collapse closes. */
+    /** Called when the trigger closes the Collapse. Fires only while the Collapse keeps its own state: not when `open` is set, and not when a `Collapses` group manages it. `onOpenChange` reports in every mode. */
     onClose?: () => void;
+    /** Called with the state the trigger asks for (`true` to open) each time it is clicked or activated with Enter or Space, in every mode. Pair it with `open` to let the trigger drive a controlled Collapse. */
+    onOpenChange?: (open: boolean) => void;
     /** The clickable trigger element (header/button). */
     trigger?: React.ReactNode;
     /** Animation style, or `false` to disable. */
@@ -46,12 +53,9 @@ export interface CollapseProps extends Omit<React.HTMLAttributes<HTMLDivElement>
  * </Collapse>
  *
  * @example
- * // Controlled collapse
+ * // Controlled collapse, driven by its own trigger
  * const [isOpen, setIsOpen] = useState(false);
- * <Collapse
- *   open={isOpen}
- *   trigger={<button onClick={() => setIsOpen(!isOpen)}>Toggle</button>}
- * >
+ * <Collapse open={isOpen} onOpenChange={setIsOpen} trigger={<strong>Toggle</strong>}>
  *   <p>Content</p>
  * </Collapse>
  *

package/dist/types-cjs/components/Collapses.d.ts

@@ -0,0 +1,53 @@
+import React from 'react';
+import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
+/**
+ * Props shared by both modes of the Collapses component.
+ */
+interface CollapsesBaseProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color' | 'defaultValue' | 'onChange'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Joins the items into one block, with no gap between them and only the outer corners rounded. The joins show on `bordered` items. */
+    seamless?: boolean;
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /** The `Collapse` items. Each child element is one item, indexed from 0 in order, with the children of a fragment counted one by one. A child that sets its own `open` keeps it: the group leaves that item alone. */
+    children?: React.ReactNode;
+}
+/**
+ * Props for Collapses in single mode, the accordion: opening one item closes the others.
+ */
+export interface CollapsesSingleProps extends CollapsesBaseProps {
+    /**
+     * Lets items open independently. Without it, opening one item closes the others.
+     * @defaultValue false
+     */
+    multiple?: false;
+    /** Controlled open items: the index of the open item, or `null` for none. With `multiple`, an array of indexes. An index is a position among the children, so rendering an item conditionally or reordering them moves the open state onto a neighbour: render every item and hide one with `visibility="hidden"`, or keep `value` in step yourself. */
+    value?: number | null;
+    /** Open items for uncontrolled use, as an index or `null` (the default, none open). With `multiple`, an array of indexes, empty by default. Indexes are positions among the children, as for `value`. */
+    defaultValue?: number | null;
+    /** Called with the new open items each time a trigger asks for a change, whether or not `value` is set: an index or `null`, or with `multiple` an array of indexes in ascending order. Indexes are positions among the children, as for `value`. */
+    onChange?: (value: number | null) => void;
+}
+/**
+ * Props for Collapses with `multiple`: items open and close independently.
+ */
+export interface CollapsesMultipleProps extends CollapsesBaseProps {
+    /**
+     * Lets items open independently. Without it, opening one item closes the others.
+     * @defaultValue false
+     */
+    multiple: true;
+    /** Controlled open items: the index of the open item, or `null` for none. With `multiple`, an array of indexes. An index is a position among the children, so rendering an item conditionally or reordering them moves the open state onto a neighbour: render every item and hide one with `visibility="hidden"`, or keep `value` in step yourself. */
+    value?: number[];
+    /** Open items for uncontrolled use, as an index or `null` (the default, none open). With `multiple`, an array of indexes, empty by default. Indexes are positions among the children, as for `value`. */
+    defaultValue?: number[];
+    /** Called with the new open items each time a trigger asks for a change, whether or not `value` is set: an index or `null`, or with `multiple` an array of indexes in ascending order. Indexes are positions among the children, as for `value`. */
+    onChange?: (value: number[]) => void;
+}
+/**
+ * Props for the Collapses component, a discriminated union on `multiple`: the open items are an index (or `null`) in single mode and an array of indexes with `multiple`.
+ */
+export type CollapsesProps = CollapsesSingleProps | CollapsesMultipleProps;
+export declare const Collapses: React.FC<CollapsesProps> & {
+    Collapse: React.FC<import("./Collapse.js").CollapseProps>;
+};
+export default Collapses;

package/dist/types-cjs/components/collapsesContext.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What a `Collapses` group hands the item it wraps: whether that item is open,
+ * and how to ask the group for a change.
+ *
+ * This module is internal. `index.ts` re-exports `Collapse` and `Collapses`
+ * whole, so the context lives here, where neither re-export reaches it.
+ */
+export interface CollapsesItemContextValue {
+    /** Whether the group has this item open. */
+    open: boolean;
+    /** Asks the group to open (`true`) or close (`false`) this item. */
+    setOpen: (open: boolean) => void;
+}
+/**
+ * `null` outside a group. A `Collapse` also resets it to `null` for its own
+ * subtree, so a Collapse nested in an item's content keeps its own state
+ * instead of answering to its ancestor's slot in the group.
+ */
+export declare const CollapsesItemContext: import("react").Context<CollapsesItemContextValue | null>;

package/dist/types-cjs/helpers/ClientOnly.d.ts

@@ -0,0 +1,40 @@
+import React from 'react';
+/**
+ * Props for the ClientOnly component.
+ */
+export interface ClientOnlyProps {
+    /**
+     * Content to render once the page has hydrated. A function is called only
+     * then, so an inline expression that reads `window`, `document` or
+     * `localStorage` never runs on the server.
+     */
+    children?: React.ReactNode | (() => React.ReactNode);
+    /**
+     * Rendered on the server and during hydration instead of `children`, such
+     * as a placeholder the same size as the content so the layout doesn't
+     * shift when it arrives.
+     * @defaultValue null
+     */
+    fallback?: React.ReactNode;
+}
+/**
+ * Renders its children only in the browser, after hydration, and a `fallback` until then, so content that depends on browser-only state doesn't cause a hydration mismatch.
+ *
+ * The server render and the hydrating client render both show `fallback`,
+ * which keeps them identical; the children replace it in the commit that
+ * follows. In an app without server rendering the children show on the first
+ * render.
+ *
+ * @function
+ * @param {ClientOnlyProps} props - Props for the ClientOnly component.
+ * @returns The children once hydrated, otherwise the fallback.
+ *
+ * @example
+ * // The server's time zone is not the reader's.
+ * <ClientOnly fallback={<Skeleton variant="lines" lines={1} />}>
+ *   {() => (
+ *     <p>Times are shown in {Intl.DateTimeFormat().resolvedOptions().timeZone}.</p>
+ *   )}
+ * </ClientOnly>
+ */
+export declare function ClientOnly({ children, fallback }: ClientOnlyProps): React.JSX.Element;

package/dist/types-cjs/helpers/inertProps.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+/**
+ * The prop that makes an element inert, spelled for the React in use, or
+ * nothing when `inert` is false.
+ *
+ * Both majors must render `inert=""`, and each warns on the other's spelling
+ * and then drops the attribute. React 19 treats `inert` as a boolean and
+ * rejects the empty string. React 18 does not know the attribute, so it
+ * passes a string through and rejects `true`.
+ */
+export declare const inertProps: (inert: boolean, major?: number) => React.HTMLAttributes<HTMLElement>;

package/dist/types-cjs/helpers/portal.d.ts

@@ -1,3 +1,4 @@
+import React from 'react';
 /**
  * Resolves a portal target: an `HTMLElement` is used directly, a non-empty
  * `string` is treated as a `document.querySelector` selector (falling back to
@@ -13,3 +14,64 @@
  * @returns The resolved DOM node to portal into.
  */
 export declare function resolvePortalContainer(container?: string | HTMLElement): HTMLElement;
+/**
+ * Props for the Portal component.
+ */
+export interface PortalProps {
+    /** Content to render into the container. */
+    children?: React.ReactNode;
+    /**
+     * Where the content goes: an element, or a `document.querySelector`
+     * selector. Omitted, empty, or a selector that matches nothing, it goes to
+     * `document.body`. A selector is looked up again on each render, so the
+     * content follows the target when it changes. Moving to another target
+     * remounts the children and resets their state, which includes a selector
+     * that only starts matching after the content has shown in `document.body`.
+     * Render the target first, or pass the element once you have it.
+     */
+    container?: string | HTMLElement;
+    /**
+     * Render the children in place instead, on the server as well as the
+     * client. Lets a component that portals only sometimes keep a single code
+     * path.
+     * @defaultValue false
+     */
+    disabled?: boolean;
+}
+/**
+ * Renders its children into another part of the page, `document.body` unless `container` says otherwise, so floating content escapes an ancestor's `overflow`, `transform` or stacking context.
+ *
+ * React's server renderer can't render a portal, so `Portal` renders nothing
+ * on the server and during hydration, and mounts its children in the commit
+ * that follows. The first client render then matches the server markup. In an app
+ * without server rendering it portals on the first render.
+ *
+ * React context, such as `ConfigProvider`'s class prefix, reaches the
+ * portaled children, and their React events bubble through the React tree.
+ * CSS inheritance follows the DOM instead: a scoped (non-`isRoot`) `Theme`
+ * sets its variables on a wrapper element the portaled content has left, so
+ * that content sees the page-level theme. Point `container` at an element
+ * inside the themed area to keep it.
+ *
+ * Tab order and focus follow the DOM too. Content portaled from inside a
+ * focus trap is no longer inside the trapped element, so the trap neither
+ * reaches it nor holds focus there: render nested overlays inside the
+ * trapped element, or give them a trap of their own.
+ *
+ * @function
+ * @param {PortalProps} props - Props for the Portal component.
+ * @returns The portal, the children in place when `disabled`, or nothing
+ * before hydration.
+ *
+ * @example
+ * <Portal>
+ *   <div className="box">Rendered at the end of document.body</div>
+ * </Portal>
+ *
+ * @example
+ * // Into a dedicated overlay root
+ * <Portal container="#overlays">
+ *   <CommandPalette />
+ * </Portal>
+ */
+export declare function Portal({ children, container, disabled }: PortalProps): React.JSX.Element | null;

package/dist/types-cjs/helpers/shadowDom.d.ts

@@ -49,6 +49,8 @@ export declare function getActiveElementInTree(node: Node | null | undefined): E
  * opener sits in. A closed shadow root cannot be entered, so focus inside one
  * reads as its host.
  *
+ * @param doc - The document to start from: the component's own, when it may
+ * render into one other than the page's (an iframe's). Defaults to `document`.
  * @returns The focused element, or `null` when the document has none.
  */
-export declare function getDeepestActiveElement(): Element | null;
+export declare function getDeepestActiveElement(doc?: Document): Element | null;