@primitiv-ui/react 0.1.38 → 0.1.40

package/dist/Slot/Slot.js

@@ -0,0 +1,210 @@
+"use client";
+/**
+ * Slot — a React composition utility following the asChild pattern.
+ *
+ * When a component renders `<Slot {...ownProps}>{child}</Slot>`, the child
+ * element is cloned with ownProps merged in:
+ * - Event handlers are **composed** (child's handler runs first, then Slot's).
+ * - `style` objects are shallow-merged (child wins on collisions).
+ * - `className` strings are concatenated.
+ * - All other props default to the child's value, with Slot providing the
+ *   fallback when the child doesn't specify one.
+ * - Refs from both sides are composed via {@link composeRefs}.
+ *
+ * This file is intentionally self-contained — no external dependencies
+ * beyond React itself.
+ */
+import { forwardRef, isValidElement, cloneElement, Children, } from "react";
+// ---------------------------------------------------------------------------
+// composeRefs
+// ---------------------------------------------------------------------------
+function setRef(ref, value) {
+    if (typeof ref === "function") {
+        ref(value);
+        return;
+    }
+    // Forcing this guard true dereferences a null/undefined ref (a child with no
+    // ref of its own), throwing during React's commit-phase ref assignment. The
+    // "no ref of its own" test catches it, but Stryker's vitest runner can't
+    // attribute that commit-phase throw (the Avatar/Slot-guard limitation) — not
+    // equivalent.
+    // Stryker disable next-line ConditionalExpression
+    if (ref !== null && ref !== undefined) {
+        ref.current = value;
+    }
+}
+/**
+ * Combines multiple refs into a single callback ref that sets all of them
+ * simultaneously. Handles function refs, object refs (`{ current }`), and
+ * `undefined` — any of which may be mixed freely, in any order, and any
+ * number of them.
+ *
+ * Used throughout the headless components whenever a sub-component owns an
+ * internal ref (for measuring, focus management, roving-tabindex, etc.)
+ * *and* needs to forward the consumer's own `ref` to the same DOM node —
+ * two refs, one element, one callback ref that satisfies both. `Slot`
+ * itself uses `composeRefs` internally to merge its `forwardedRef` with the
+ * child element's own ref (see {@link Slot}).
+ *
+ * @example Compose an internal ref with a consumer-supplied external ref:
+ * ```tsx
+ * const internalRef = useRef<HTMLButtonElement>(null);
+ * const composedRef = externalRef
+ *   ? composeRefs(internalRef, externalRef)
+ *   : internalRef;
+ *
+ * return <button ref={composedRef} />;
+ * ```
+ */
+export function composeRefs(...refs) {
+    return (node) => refs.forEach((ref) => setRef(ref, node));
+}
+// ---------------------------------------------------------------------------
+// mergeProps — follows the asChild composition pattern rules exactly
+// ---------------------------------------------------------------------------
+function getRef(element) {
+    // React 19 exposes ref via props; React ≤18 via element.ref
+    const { props, ref } = element;
+    // Stryker disable next-line ConditionalExpression: in React 19, element.ref
+    // returns the same ref as props.ref for real elements, so preferring props.ref
+    // vs. falling back to ref is indistinguishable at runtime — an equivalent
+    // mutant. The ternary stays for the React <=18 shape, where the two differ.
+    return props.ref !== undefined
+        ? props.ref
+        : ref;
+}
+function mergeProps(slotProps, childProps) {
+    // Child props override by default; event handlers and style/className are
+    // special-cased.
+    const merged = { ...childProps };
+    for (const key in childProps) {
+        const slotVal = slotProps[key];
+        const childVal = childProps[key];
+        const isEventHandler = /^on[A-Z]/.test(key);
+        if (isEventHandler) {
+            if (slotVal && childVal) {
+                // Both sides provide a handler — compose: child first, then slot.
+                merged[key] = (...args) => {
+                    childVal(...args);
+                    slotVal(...args);
+                };
+            }
+            else if (slotVal) {
+                merged[key] = slotVal;
+            }
+        }
+        else if (key === "style") {
+            merged[key] = { ...slotVal, ...childVal };
+        }
+        else if (key === "className") {
+            merged[key] = [slotVal, childVal].filter(Boolean).join(" ");
+        }
+    }
+    return { ...slotProps, ...merged };
+}
+// ---------------------------------------------------------------------------
+// Slot component
+// ---------------------------------------------------------------------------
+/**
+ * Renders its single child element with the Slot's own props merged in.
+ *
+ * `Slot` is the composition primitive behind every `asChild` prop in this
+ * library (`Button`, `Tabs.Trigger`, `Select.Root`, `Breadcrumb.Link`, and
+ * more). A component that normally renders its own DOM element (say,
+ * `<button>`) can instead delegate rendering to a single consumer-supplied
+ * element — typically a routing library's `<Link>` or a custom styled
+ * element — while preserving all of its own behaviour: ARIA attributes,
+ * data attributes, event handlers, and `ref` all still land on the
+ * rendered DOM node, just not the node `Slot` itself would have created.
+ * The pattern avoids an extra wrapper element in the DOM, which matters for
+ * layout (no unwanted `<button><a>...</a></button>` nesting) and for CSS
+ * selectors that expect a single element.
+ *
+ * **Usage shape** — every component using `Slot` follows the same
+ * branch:
+ *
+ * ```tsx
+ * if (asChild) {
+ *   return <Slot {...ownProps}>{children}</Slot>;
+ * }
+ * return <button {...ownProps}>{children}</button>;
+ * ```
+ *
+ * `ownProps` is the exact same object passed to both branches — `Slot`'s
+ * job is only to change *where* those props land, never to change what
+ * they are.
+ *
+ * **Prop-merging rules** (`Slot`'s own props are the "slot" side, the
+ * single child's own props are the "child" side):
+ * - **Event handlers** (any prop matching `/^on[A-Z]/`) compose — the
+ *   **child's** handler fires first, then the **slot's**. This is the
+ *   opposite composition direction, and a different merge strategy, from
+ *   the standalone {@link composeEventHandlers} helper (their-handler-first
+ *   with a `preventDefault()` veto) — the two are unrelated mechanisms
+ *   that happen to solve adjacent problems. `Slot`'s handlers always both
+ *   run; there is no opt-out.
+ * - **`style`** is shallow-merged — the child's style object wins on key
+ *   collisions, so a consumer's inline `style` can override individual
+ *   properties Slot would otherwise set.
+ * - **`className`** strings are concatenated (`"slotClass childClass"`),
+ *   so both the component's own class hooks and the consumer's class
+ *   survive.
+ * - **All other props** default to the child's value; Slot's value is only
+ *   used as a fallback when the child doesn't specify that prop at all
+ *   (key absent, or explicitly `undefined`).
+ * - **Refs** from both sides are composed via {@link composeRefs}, so
+ *   neither the component's internal ref nor the consumer's own ref on the
+ *   child element is lost.
+ *
+ * **Constraints.** Exactly one React element child is required — `Slot`
+ * throws `"Slot requires exactly one React element child."` for zero
+ * children or a non-element child (e.g. a plain string). The child must
+ * also accept a `ref` (a DOM element or a `forwardRef` component); passing
+ * a plain function component as the child silently drops the ref.
+ *
+ * **React version compatibility.** Slot reads the child's own ref from
+ * `element.props.ref` (React 19+) with a fallback to `element.ref`
+ * (React ≤18) so both runtime versions compose refs correctly.
+ *
+ * @extends HTMLElement
+ *
+ * @example Basic `asChild` branch inside a component
+ * ```tsx
+ * // Inside a component that normally renders <button>:
+ * if (asChild) {
+ *   return <Slot {...buttonProps}>{children}</Slot>;
+ * }
+ * return <button {...buttonProps}>{children}</button>;
+ * ```
+ *
+ * @example Consumer rendering a router link in place of the default element
+ * ```tsx
+ * <Button asChild onClick={trackClick}>
+ *   <RouterLink to="/settings" className="settings-link">
+ *     Settings
+ *   </RouterLink>
+ * </Button>
+ * // Rendered DOM: a single <a class="...settings-link"> — trackClick and the
+ * // link's own onClick both fire; no wrapping <button>.
+ * ```
+ */
+export const Slot = forwardRef(({ children, ...slotProps }, forwardedRef) => {
+    // Stryker disable next-line ConditionalExpression: forcing this guard false
+    // lets invalid children fall through to a *different* throw (the destructure
+    // in getRef below), which the error tests do catch — but Stryker's vitest
+    // runner does not attribute that React render-time throw to a covering test
+    // (the same limitation seen on Avatar's ref guard). The operator/block twins
+    // of this line are scored; only this variant can't be. Not equivalent.
+    if (Children.count(children) !== 1 || !isValidElement(children)) {
+        throw new Error("Slot requires exactly one React element child.");
+    }
+    const childRef = getRef(children);
+    const composedRef = forwardedRef
+        ? composeRefs(forwardedRef, childRef)
+        : childRef;
+    return cloneElement(children, {
+        ...mergeProps(slotProps, children.props),
+        ref: composedRef,
+    });
+});
+Slot.displayName = "Slot";

package/dist/Slot/composeEventHandlers.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Returns an event handler that runs the consumer-supplied handler first,
+ * then the library's own handler — unless the consumer called
+ * `event.preventDefault()`, in which case the library handler is skipped.
+ *
+ * This is the standard composition pattern used throughout headless
+ * components to let consumers attach their own listeners onto a
+ * sub-component's *own* native event props (e.g. `Tabs.Trigger`'s
+ * `onClick`, `Modal.Overlay`'s `onClick`) without clobbering the
+ * component's own behaviour, while still giving them an opt-out via
+ * `preventDefault()`. Wrap it around the component's internal handler at
+ * the point the prop is consumed:
+ *
+ * ```tsx
+ * const handleClick = composeEventHandlers(onClick, () => {
+ *   // the component's own behaviour, e.g. activating a tab
+ * });
+ * ```
+ *
+ * **Not the same mechanism as {@link Slot}.** `Slot`'s own prop-merging
+ * (used for the `asChild` pattern) also composes event handlers, but with
+ * the *opposite* order (child fires first, then Slot) and *no*
+ * `preventDefault()` opt-out — both handlers always run there. Reach for
+ * `composeEventHandlers` when a component owns a native DOM prop directly;
+ * reach for `Slot` when delegating rendering to a consumer-supplied
+ * element via `asChild`. The two are never used together on the same prop.
+ *
+ * @example Consumer logs every click; component still closes the modal
+ * afterwards:
+ * ```tsx
+ * <Modal.Overlay onClick={(e) => console.log("overlay clicked")} />
+ * ```
+ *
+ * @example Consumer vetoes the component's behaviour:
+ * ```tsx
+ * <Modal.Overlay onClick={(e) => {
+ *   if (formIsDirty) e.preventDefault(); // don't close
+ * }} />
+ * ```
+ *
+ * @example Opting out of the veto — always run our handler too
+ * ```tsx
+ * const handleClick = composeEventHandlers(onClick, ourHandler, {
+ *   checkForDefaultPrevented: false,
+ * });
+ * ```
+ */
+export declare function composeEventHandlers<E>(theirHandler: ((event: E) => void) | undefined, ourHandler: (event: E) => void, { checkForDefaultPrevented }?: {
+    checkForDefaultPrevented?: boolean;
+}): (event: E) => void;

package/dist/Slot/composeEventHandlers.js

@@ -0,0 +1,57 @@
+"use client";
+/**
+ * Returns an event handler that runs the consumer-supplied handler first,
+ * then the library's own handler — unless the consumer called
+ * `event.preventDefault()`, in which case the library handler is skipped.
+ *
+ * This is the standard composition pattern used throughout headless
+ * components to let consumers attach their own listeners onto a
+ * sub-component's *own* native event props (e.g. `Tabs.Trigger`'s
+ * `onClick`, `Modal.Overlay`'s `onClick`) without clobbering the
+ * component's own behaviour, while still giving them an opt-out via
+ * `preventDefault()`. Wrap it around the component's internal handler at
+ * the point the prop is consumed:
+ *
+ * ```tsx
+ * const handleClick = composeEventHandlers(onClick, () => {
+ *   // the component's own behaviour, e.g. activating a tab
+ * });
+ * ```
+ *
+ * **Not the same mechanism as {@link Slot}.** `Slot`'s own prop-merging
+ * (used for the `asChild` pattern) also composes event handlers, but with
+ * the *opposite* order (child fires first, then Slot) and *no*
+ * `preventDefault()` opt-out — both handlers always run there. Reach for
+ * `composeEventHandlers` when a component owns a native DOM prop directly;
+ * reach for `Slot` when delegating rendering to a consumer-supplied
+ * element via `asChild`. The two are never used together on the same prop.
+ *
+ * @example Consumer logs every click; component still closes the modal
+ * afterwards:
+ * ```tsx
+ * <Modal.Overlay onClick={(e) => console.log("overlay clicked")} />
+ * ```
+ *
+ * @example Consumer vetoes the component's behaviour:
+ * ```tsx
+ * <Modal.Overlay onClick={(e) => {
+ *   if (formIsDirty) e.preventDefault(); // don't close
+ * }} />
+ * ```
+ *
+ * @example Opting out of the veto — always run our handler too
+ * ```tsx
+ * const handleClick = composeEventHandlers(onClick, ourHandler, {
+ *   checkForDefaultPrevented: false,
+ * });
+ * ```
+ */
+export function composeEventHandlers(theirHandler, ourHandler, { checkForDefaultPrevented = true } = {}) {
+    return function handleEvent(event) {
+        theirHandler?.(event);
+        if (!checkForDefaultPrevented ||
+            !event.defaultPrevented) {
+            ourHandler(event);
+        }
+    };
+}

package/dist/Slot/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./Slot.js";
+export * from "./composeEventHandlers.js";
+export * from "./types.js";

package/dist/Slot/index.js

@@ -0,0 +1,3 @@
+export * from "./Slot.js";
+export * from "./composeEventHandlers.js";
+export * from "./types.js";

package/dist/Slot/types.d.ts

@@ -0,0 +1,20 @@
+import { HTMLAttributes, ReactNode } from "react";
+/**
+ * Props for {@link Slot} — all native `HTMLAttributes` (event handlers,
+ * `style`, `className`, `aria-*`, `data-*`, ...), merged onto the single
+ * child element rather than rendered onto an element `Slot` creates
+ * itself. See {@link Slot} for the exact prop-merging rules (event
+ * handlers compose child-first, `style` shallow-merges child-wins,
+ * `className` concatenates, everything else defaults to the child).
+ *
+ * @extends HTMLElement
+ */
+export type SlotProps = HTMLAttributes<HTMLElement> & {
+    /**
+     * The element to clone `Slot`'s props onto. Must be exactly one valid
+     * React element that accepts a `ref` — passing zero children, more than
+     * one, or a non-element (e.g. a plain string) throws
+     * `"Slot requires exactly one React element child."`.
+     */
+    children?: ReactNode;
+};

package/dist/Slot/types.js

@@ -0,0 +1 @@
+export {};

package/dist/SplitButton/SplitButton.d.ts

@@ -0,0 +1,286 @@
+import { type ReactElement } from "react";
+import { SplitButtonActionProps, SplitButtonItemProps, SplitButtonMenuProps, SplitButtonRootProps, SplitButtonSeparatorProps, SplitButtonTriggerProps } from "./types.js";
+/**
+ * The root of a SplitButton — renders the `role="group"` element that binds
+ * the primary action and the menu trigger into one widget, and owns the
+ * menu's open state by rendering a {@link Dropdown | `Dropdown.Root`} around
+ * it.
+ *
+ * **Two controls, one widget.** A split button is *not* a `Select`: the left
+ * half performs an action immediately, the right half opens a menu of related
+ * alternatives. Both halves stay independently tabbable — that is correct for
+ * two genuinely separate commands, and deliberately *not* a roving tabstop.
+ *
+ * **Open state.** Identical to `Dropdown.Root`'s: uncontrolled via
+ * `defaultOpen`, or controlled via `open` + `onOpenChange`, statically
+ * discriminated at the type level. `dir` is forwarded too, so submenus
+ * composed from `Dropdown.Sub` invert their arrow keys in RTL.
+ *
+ * **Styling hooks.** `data-split-button=""`, `data-state="open" | "closed"`
+ * tracking the menu, and `data-disabled=""` when the group is disabled.
+ *
+ * **`asChild` composition.** Pass `asChild` to render a consumer-supplied
+ * element as the group instead of `<div>`.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <SplitButton>
+ *   <SplitButton.Action onClick={squashAndMerge}>
+ *     Squash and merge
+ *   </SplitButton.Action>
+ *   <SplitButton.Trigger>
+ *     <ChevronDown aria-hidden="true" />
+ *     <VisuallyHidden>More merge options</VisuallyHidden>
+ *   </SplitButton.Trigger>
+ *   <SplitButton.Menu>
+ *     <SplitButton.Item onSelect={mergeCommit}>
+ *       Create a merge commit
+ *     </SplitButton.Item>
+ *     <SplitButton.Item onSelect={rebase}>Rebase and merge</SplitButton.Item>
+ *   </SplitButton.Menu>
+ * </SplitButton>
+ * ```
+ *
+ * @example Controlled menu, whole widget disabled
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <SplitButton open={open} onOpenChange={setOpen} disabled={saving}>
+ *   ...
+ * </SplitButton>
+ * ```
+ */
+export declare function SplitButtonRoot({ defaultOpen, open, onOpenChange, dir, disabled, children, ref, ...rest }: SplitButtonRootProps): ReactElement;
+export declare namespace SplitButtonRoot {
+    var displayName: string;
+}
+/**
+ * The primary half — a `<button type="button">` that performs the default
+ * action immediately on click. It is **not** the menu trigger and carries no
+ * `aria-haspopup`.
+ *
+ * **Keyboard.** `ArrowDown` opens the menu and moves focus to its first item,
+ * the standard split-button affordance for reaching the alternatives without
+ * tabbing past the action. Every other key falls through, and a consumer's own
+ * `onKeyDown` runs first.
+ *
+ * **Accessible naming.** This element's `id` is component-owned (hence
+ * `Omit`-ted from the props) because
+ * {@link SplitButtonTrigger | `SplitButton.Trigger`} references it to build
+ * its own accessible name — give the action a visible text label and the
+ * chevron half is named for free.
+ *
+ * **Disabled.** Sets native `disabled` plus `data-disabled=""` when either
+ * this prop or the group's `disabled` is set; the two are OR-ed, so the group
+ * can never be overridden back to enabled.
+ *
+ * **`asChild` composition.** Renders the consumer's element instead of
+ * `<button>` — e.g. a router link. `type="button"` is **not** forwarded in
+ * this mode; the child owns its own type semantics.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <SplitButton.Action onClick={squashAndMerge}>
+ *   Squash and merge
+ * </SplitButton.Action>
+ * ```
+ *
+ * @example asChild — the action navigates instead of firing a handler
+ * ```tsx
+ * <SplitButton.Action asChild>
+ *   <a href="/merge">Squash and merge</a>
+ * </SplitButton.Action>
+ * ```
+ */
+export declare function SplitButtonAction({ asChild, children, disabled, onKeyDown, ref, ...rest }: SplitButtonActionProps): ReactElement;
+export declare namespace SplitButtonAction {
+    var displayName: string;
+}
+/**
+ * The menu half — a `<button type="button">` carrying `aria-haspopup="menu"`,
+ * `aria-expanded` and `aria-controls`, all inherited from
+ * {@link Dropdown | `Dropdown.Trigger`}.
+ *
+ * **Accessible name, derived.** A chevron-only control has no text of its own,
+ * so unless you pass `aria-label` or `aria-labelledby` the trigger defaults to
+ * `aria-labelledby="<its own id> <the action's id>"`. Self-reference is valid
+ * in `aria-labelledby` and resolves to the element's own contents, so a
+ * visually-hidden "More options" inside the trigger yields
+ * *"More options, Squash and merge"* rather than an unlabelled button or a
+ * second control with the same name as the action. Passing either ARIA
+ * attribute yourself opts out entirely.
+ *
+ * **Disabled.** OR-ed with the group's `disabled`, exactly like
+ * {@link SplitButtonAction | `SplitButton.Action`}.
+ *
+ * **Styling hooks.** `data-split-button-trigger=""`, plus `data-disabled=""`.
+ * Its `id` is component-owned (`Omit`-ted from the props) because the derived
+ * name references it.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example Derived name — chevron plus hidden text
+ * ```tsx
+ * <SplitButton.Trigger>
+ *   <ChevronDown aria-hidden="true" />
+ *   <VisuallyHidden>More merge options</VisuallyHidden>
+ * </SplitButton.Trigger>
+ * ```
+ *
+ * @example Explicit name — opts out of the derivation
+ * ```tsx
+ * <SplitButton.Trigger aria-label="More merge options">
+ *   <ChevronDown aria-hidden="true" />
+ * </SplitButton.Trigger>
+ * ```
+ */
+export declare function SplitButtonTrigger({ "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled, ...rest }: SplitButtonTriggerProps): ReactElement;
+export declare namespace SplitButtonTrigger {
+    var displayName: string;
+}
+/**
+ * The menu panel of alternative actions — a `role="menu"` native
+ * `popover="auto"` element delegating wholly to
+ * {@link Dropdown | `Dropdown.Content`}: arrow-key navigation, Home/End,
+ * typeahead, Escape-to-close-and-restore-focus, and light dismiss all come
+ * from there.
+ *
+ * Anything valid inside a `Dropdown.Content` is valid here — `Dropdown.Group`,
+ * `Dropdown.Label`, `Dropdown.CheckboxItem`, `Dropdown.Sub` — because Root
+ * provides the same Dropdown context. `SplitButton` re-exports only the two
+ * parts a split button's menu almost always needs
+ * ({@link SplitButtonItem | `Item`} and
+ * {@link SplitButtonSeparator | `Separator`}); reach for `Dropdown.*` directly
+ * for the rest.
+ *
+ * **Styling hook.** `data-split-button-menu=""`, alongside Dropdown's own.
+ *
+ * @extends HTMLMenuElement
+ *
+ * @example
+ * ```tsx
+ * <SplitButton.Menu>
+ *   <SplitButton.Item onSelect={mergeCommit}>Create a merge commit</SplitButton.Item>
+ *   <SplitButton.Separator />
+ *   <SplitButton.Item disabled>Rebase and merge</SplitButton.Item>
+ * </SplitButton.Menu>
+ * ```
+ */
+export declare function SplitButtonMenu(props: SplitButtonMenuProps): ReactElement;
+export declare namespace SplitButtonMenu {
+    var displayName: string;
+}
+/**
+ * One alternative action in the menu — a `role="menuitem"` row, delegating
+ * wholly to {@link Dropdown | `Dropdown.Item`}. Fires `onSelect` with a
+ * cancellable event and auto-closes the menu; call `event.preventDefault()`
+ * to keep it open. `disabled` rows get `aria-disabled` and are skipped by
+ * arrow navigation and typeahead.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <SplitButton.Item onSelect={() => merge("rebase")}>
+ *   Rebase and merge
+ * </SplitButton.Item>
+ * ```
+ */
+export declare function SplitButtonItem(props: SplitButtonItemProps): ReactElement;
+export declare namespace SplitButtonItem {
+    var displayName: string;
+}
+/**
+ * A `role="separator"` divider between groups of alternatives, delegating
+ * wholly to {@link Dropdown | `Dropdown.Separator`}. Skipped by focus and
+ * typeahead.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <SplitButton.Separator />
+ * ```
+ */
+export declare function SplitButtonSeparator(props: SplitButtonSeparatorProps): ReactElement;
+export declare namespace SplitButtonSeparator {
+    var displayName: string;
+}
+/** Type of the {@link SplitButton} compound: the root callable plus its
+ * attached sub-components. */
+export type TSplitButtonCompound = typeof SplitButtonRoot & {
+    Root: typeof SplitButtonRoot;
+    Action: typeof SplitButtonAction;
+    Trigger: typeof SplitButtonTrigger;
+    Menu: typeof SplitButtonMenu;
+    Item: typeof SplitButtonItem;
+    Separator: typeof SplitButtonSeparator;
+};
+/**
+ * Headless, accessible **SplitButton** — one primary action paired with a menu
+ * of related alternatives, bound into a single `role="group"` widget. Zero
+ * styles ship.
+ *
+ * A split button is an **actions** control, not a value control: clicking the
+ * left half runs the default action immediately, and the right half opens a
+ * menu of alternatives (which may run their own action, or re-point what the
+ * primary half does). If what you need is "which option is currently
+ * selected?", reach for {@link Select} instead.
+ *
+ * `SplitButton` is a composition over {@link Dropdown} — Root renders a
+ * `Dropdown.Root` and every menu part delegates to Dropdown's, so all the menu
+ * keyboard/focus/light-dismiss behaviour is Dropdown's, tested once. What this
+ * component adds on top is the coordination between the two halves that
+ * Dropdown alone cannot provide:
+ *
+ * - the `role="group"` boundary that makes them read as one widget;
+ * - the trigger's accessible name, derived from the primary action;
+ * - `disabled` propagating from the group to both halves;
+ * - `ArrowDown` on the action opening the menu.
+ *
+ * `SplitButton` is both callable (an alias of `SplitButton.Root`) and carries
+ * its sub-components as static properties:
+ *
+ * - {@link SplitButtonRoot | `SplitButton.Root`} — the `role="group"` element
+ *   and the menu's state owner.
+ * - {@link SplitButtonAction | `SplitButton.Action`} — the primary half.
+ * - {@link SplitButtonTrigger | `SplitButton.Trigger`} — the menu half.
+ * - {@link SplitButtonMenu | `SplitButton.Menu`} — the menu panel.
+ * - {@link SplitButtonItem | `SplitButton.Item`} — one alternative action.
+ * - {@link SplitButtonSeparator | `SplitButton.Separator`} — a divider.
+ *
+ * **Both halves are tabbable.** They are two separate commands, so each is its
+ * own tab stop — this is not a roving-tabindex widget, and should not become
+ * one.
+ *
+ * @example
+ * ```tsx
+ * import { SplitButton, VisuallyHidden } from "@primitiv-ui/react";
+ *
+ * <SplitButton>
+ *   <SplitButton.Action onClick={squashAndMerge}>
+ *     Squash and merge
+ *   </SplitButton.Action>
+ *   <SplitButton.Trigger>
+ *     <ChevronDown aria-hidden="true" />
+ *     <VisuallyHidden>More merge options</VisuallyHidden>
+ *   </SplitButton.Trigger>
+ *   <SplitButton.Menu>
+ *     <SplitButton.Item onSelect={mergeCommit}>
+ *       Create a merge commit
+ *     </SplitButton.Item>
+ *     <SplitButton.Item onSelect={rebase}>Rebase and merge</SplitButton.Item>
+ *   </SplitButton.Menu>
+ * </SplitButton>
+ * ```
+ *
+ * @see {@link SplitButtonRoot} for open-state modes and the group anatomy.
+ * @see {@link SplitButtonTrigger} for how the derived accessible name works.
+ * @see {@link Dropdown} for everything the menu itself does.
+ */
+declare const SplitButtonCompound: TSplitButtonCompound;
+export { SplitButtonCompound as SplitButton };