@primitiv-ui/react 0.1.38 → 0.1.40

package/dist/Tabs/Tabs.js

@@ -0,0 +1,324 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { useDirection } from "../DirectionProvider/index.js";
+import { Slot, composeRefs } from "../Slot/index.js";
+import { useTabsRoot, useTabsContext, useTabsTrigger, useTabsContent, } from "./hooks/index.js";
+import { TabsProvider } from "./TabsContext.js";
+/**
+ * The root of a Tabs widget — owns the active value, provides context to
+ * descendants, and renders a single container `<div>`.
+ *
+ * Supports two state modes, statically discriminated at the type level so
+ * only one of the two shapes is accepted by TypeScript:
+ *
+ * - **Uncontrolled** — pass {@link TabsRootProps.defaultValue | `defaultValue`}
+ *   (or omit it and let the first click seed the state). The component
+ *   owns and updates the active value internally.
+ * - **Controlled** — pass {@link TabsRootProps.value | `value`} *and*
+ *   {@link TabsRootProps.onValueChange | `onValueChange`} together. The
+ *   parent owns the active value; the component defers every state change
+ *   back through the callback.
+ *
+ * An additional {@link TabsRootProps.onChange | `onChange({ index, name })`}
+ * callback fires on every user-driven activation (click or keyboard)
+ * independent of the control mode. Use it for analytics or side-effects
+ * that shouldn't re-enter the state update path.
+ *
+ * An imperative handle is exposed via `ref`, exposing
+ * {@link TabsImperativeApi.setActiveTab | `setActiveTab(value)`} for
+ * programmatic activation (e.g. restoring a remembered tab on mount, or
+ * reacting to a deep-linked hash):
+ *
+ * ```tsx
+ * const tabsRef = useRef<TabsImperativeApi>(null);
+ * tabsRef.current?.setActiveTab("settings");
+ * ```
+ *
+ * **Runtime validation.** If `value`/`defaultValue` doesn't match any
+ * registered `Tabs.Trigger`, a descriptive error is thrown during render
+ * and typos surface early in development.
+ *
+ * **Styling hooks.** `data-orientation="horizontal" | "vertical"` is set
+ * on the rendered container.
+ *
+ * **Reading direction.** `dir` (`"ltr"` / `"rtl"`) sets the arrow-key
+ * direction and the container's `dir` attribute. When omitted, it is
+ * inherited from the nearest {@link DirectionProvider}, falling back to
+ * `"ltr"` when there is no provider.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Tabs.Root defaultValue="overview">
+ *   <Tabs.List label="Account sections">
+ *     <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
+ *     <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
+ *   </Tabs.List>
+ *   <Tabs.Content value="overview">Dashboard...</Tabs.Content>
+ *   <Tabs.Content value="settings">Preferences...</Tabs.Content>
+ * </Tabs.Root>
+ * ```
+ *
+ * @example Controlled with an analytics hook
+ * ```tsx
+ * const [tab, setTab] = useState("overview");
+ *
+ * <Tabs.Root
+ *   value={tab}
+ *   onValueChange={setTab}
+ *   onChange={({ name, index }) => track("tab_view", { name, index })}
+ * >
+ *   ...
+ * </Tabs.Root>
+ * ```
+ *
+ * @example Vertical orientation + imperative API
+ * ```tsx
+ * const ref = useRef<TabsImperativeApi>(null);
+ *
+ * <Tabs.Root ref={ref} orientation="vertical" defaultValue="one">
+ *   ...
+ * </Tabs.Root>
+ *
+ * <button onClick={() => ref.current?.setActiveTab("two")}>Go to two</button>
+ * ```
+ */
+export const TabsRoot = forwardRef(function TabsRoot({ className = "", orientation = "horizontal", dir, activationMode = "automatic", defaultValue, value, onValueChange, onChange, lazyMount = false, ...rest }, ref) {
+    const resolvedDir = dir ?? useDirection();
+    const { contextValue } = useTabsRoot({
+        orientation,
+        dir: resolvedDir,
+        activationMode,
+        defaultValue,
+        value,
+        onValueChange,
+        onChange,
+        lazyMount,
+    }, ref);
+    return (_jsx(TabsProvider, { value: contextValue, children: _jsx("div", { dir: resolvedDir, className: className, "data-orientation": contextValue.orientation, ...rest }) }));
+});
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
+TabsRoot.displayName = "TabsRoot";
+/**
+ * The tablist — an accessible container for `Tabs.Trigger` elements.
+ *
+ * Renders a `<div role="tablist">` with `aria-orientation` inherited from
+ * the nearest {@link TabsRoot | `Tabs.Root`}. The
+ * {@link TabsListProps.label | `label`} prop is **required** and becomes
+ * the `aria-label` announced to assistive technology when the tablist
+ * receives focus — pick a short, human-readable description of the set of
+ * tabs (e.g. `"Account sections"`, not `"Tabs"`).
+ *
+ * **Styling hooks.** `data-orientation="horizontal" | "vertical"`.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Tabs.List label="Document sections">
+ *   <Tabs.Trigger value="title">Title</Tabs.Trigger>
+ *   <Tabs.Trigger value="body">Body</Tabs.Trigger>
+ * </Tabs.List>
+ * ```
+ */
+export function TabsList({ children, className = "", label, ariaLabelledBy, ...rest }) {
+    const { orientation } = useTabsContext();
+    return (_jsx("div", { role: "tablist", className: className, "aria-orientation": orientation, ...(label && {
+            "aria-label": label,
+        }), ...(ariaLabelledBy && {
+            "aria-labelledby": ariaLabelledBy,
+        }), "data-orientation": orientation, ...rest, children: children }));
+}
+/** @internal */
+TabsList.displayName = "TabsList";
+/**
+ * An individual tab button. Renders `<button role="tab">` with full ARIA
+ * linkage, roving tabindex, and keyboard navigation handled automatically.
+ *
+ * **Value linkage.** Each trigger is identified by a unique
+ * {@link TabsTriggerProps.value | `value`} string; the matching
+ * `Tabs.Content` must share the same value. The IDs used for
+ * `aria-controls` and `aria-labelledby` are derived from the root's
+ * `useId()` plus the trigger's `value`, so they're stable and unique even
+ * when multiple `Tabs` instances coexist on a page.
+ *
+ * **Keyboard support** (WAI-ARIA Tabs pattern):
+ *
+ * | Key                          | Behaviour                                          |
+ * | ---------------------------- | -------------------------------------------------- |
+ * | `ArrowRight` / `ArrowLeft`   | Move between triggers (horizontal)                 |
+ * | `ArrowDown`  / `ArrowUp`     | Move between triggers (vertical)                   |
+ * | `Home` / `End`               | Jump to first / last trigger                       |
+ * | `Enter` / `Space`            | Activate focused trigger (manual mode only)        |
+ *
+ * Movement **wraps** at the ends. In **automatic** activation mode (the default),
+ * focus movement immediately activates the panel. In **manual** mode, arrow keys
+ * move focus without switching the panel — `Enter` or `Space` confirms the
+ * selection. Use manual mode for panels that are expensive to render.
+ *
+ * **`asChild` prop.** Pass `asChild` to render an arbitrary child element
+ * instead of the default `<button>`. All tab ARIA attributes, event handlers,
+ * and the roving `tabIndex` are merged onto the child element following the
+ * Composition pattern:
+ * - Event handlers compose — the child's handler runs first, then the trigger's.
+ * - `style` is shallow-merged (child wins on collisions).
+ * - `className` strings are concatenated.
+ * - Refs from both sides are composed via `composeRefs`.
+ *
+ * The child **must** be a single React element that accepts a `ref`.
+ *
+ * **Styling hooks.**
+ * - `data-state="active" | "inactive"` on the rendered element.
+ * - `data-orientation="horizontal" | "vertical"`.
+ * - `data-disabled=""` when disabled (omitted otherwise), so CSS can target
+ *   `[data-disabled]` without the `:disabled` pseudo-class.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example Basic usage
+ * ```tsx
+ * <Tabs.Trigger value="account">Account</Tabs.Trigger>
+ * ```
+ *
+ * @example Icon + label
+ * ```tsx
+ * <Tabs.Trigger value="billing">
+ *   <CreditCardIcon aria-hidden />
+ *   <span>Billing</span>
+ * </Tabs.Trigger>
+ * ```
+ *
+ * @example asChild — render a router link with tab semantics
+ * ```tsx
+ * <Tabs.Trigger asChild value="settings">
+ *   <Link to="/settings">Settings</Link>
+ * </Tabs.Trigger>
+ * ```
+ */
+export function TabsTrigger({ ref: externalRef, children, className = "", value, onClick, disabled = false, asChild = false, ...rest }) {
+    const { buttonRef, triggerId, panelId, isActive, orientation, state, tabIndex, handleClick, handleKeyDown, } = useTabsTrigger({ value, onClick, disabled });
+    // Compose our internal ref with any external ref the consumer passes.
+    // The external ref is cast to match the internal ref's element type —
+    // RefObject<T> is invariant in React's types, but at runtime the callback
+    // receives whatever DOM element is actually rendered (button or asChild).
+    const composedRef = externalRef
+        ? composeRefs(buttonRef, externalRef)
+        : buttonRef;
+    const triggerProps = {
+        ref: composedRef,
+        role: "tab",
+        className,
+        id: triggerId,
+        "aria-controls": panelId,
+        "aria-selected": isActive,
+        "aria-disabled": disabled,
+        "data-disabled": disabled ? "" : undefined,
+        "data-orientation": orientation,
+        "data-state": state,
+        tabIndex,
+        onClick: handleClick,
+        onKeyDown: handleKeyDown,
+        ...rest,
+    };
+    if (asChild) {
+        return _jsx(Slot, { ...triggerProps, children: children });
+    }
+    return (_jsx("button", { type: "button", ...triggerProps, children: children }));
+}
+/** @internal */
+TabsTrigger.displayName = "TabsTrigger";
+/**
+ * A panel associated with a `Tabs.Trigger` of the same
+ * {@link TabsContentProps.value | `value`}.
+ *
+ * Renders `<div role="tabpanel">` with `aria-labelledby` pointing at the
+ * matching trigger, and uses the native `hidden` attribute to toggle
+ * visibility. Inactive panels remain **mounted** — this preserves
+ * component state (scroll position, form input, animation state) across
+ * tab switches. If you need true unmount semantics (e.g. to tear down
+ * expensive subscriptions), render the `Tabs.Content` conditionally
+ * yourself based on the active value.
+ *
+ * When {@link TabsRootProps.lazyMount | `lazyMount`} is set on
+ * `Tabs.Root`, a panel's children are withheld until the tab is first
+ * activated. After that first activation the children remain mounted
+ * across subsequent tab switches (lazy mount, not unmount-on-hide).
+ * The `<div role="tabpanel">` wrapper always renders so the ARIA
+ * relationship between trigger and panel is always present in the DOM.
+ *
+ * **Styling hooks.**
+ * - `data-state="active" | "inactive"`.
+ * - `data-orientation="horizontal" | "vertical"`.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Tabs.Content value="account">
+ *   <AccountForm />
+ * </Tabs.Content>
+ * ```
+ */
+export function TabsContent({ children, className = "", value, ...rest }) {
+    const { panelId, triggerId, orientation, isActive, state, tabIndex, shouldRender, } = useTabsContent({ value });
+    return (_jsx("div", { role: "tabpanel", className: className, id: panelId, "aria-labelledby": triggerId, "data-orientation": orientation, "data-state": state, hidden: !isActive, tabIndex: tabIndex, ...rest, children: shouldRender ? children : null }));
+}
+/** @internal */
+TabsContent.displayName = "TabsContent";
+/**
+ * Headless, accessible **Tabs** — a compound component implementing the
+ * WAI-ARIA Tabs pattern with zero styles.
+ *
+ * `Tabs` is both callable (it's an alias of {@link TabsRoot | `Tabs.Root`})
+ * and carries its sub-components as static properties. Prefer the
+ * namespaced form in application code for readability and grep-ability:
+ *
+ * - {@link TabsRoot | `Tabs.Root`} — state owner, context provider, imperative API holder.
+ * - {@link TabsList | `Tabs.List`} — `role="tablist"` container for triggers.
+ * - {@link TabsTrigger | `Tabs.Trigger`} — individual `role="tab"` button.
+ * - {@link TabsContent | `Tabs.Content`} — `role="tabpanel"` panel, linked to a trigger by `value`.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Tabs } from "@primitiv-ui/react";
+ *
+ * export function Demo() {
+ *   return (
+ *     <Tabs.Root defaultValue="a">
+ *       <Tabs.List label="Demo tabs">
+ *         <Tabs.Trigger value="a">First</Tabs.Trigger>
+ *         <Tabs.Trigger value="b">Second</Tabs.Trigger>
+ *       </Tabs.List>
+ *       <Tabs.Content value="a">First panel</Tabs.Content>
+ *       <Tabs.Content value="b">Second panel</Tabs.Content>
+ *     </Tabs.Root>
+ *   );
+ * }
+ * ```
+ *
+ * @example Styling with any system
+ * Because no styles ship with the component, target the rendered elements
+ * or the `data-state` / `data-orientation` hooks with whatever system you
+ * use (CSS, CSS-in-JS, Tailwind, design-token stylesheets, etc.):
+ *
+ * ```css
+ * [role="tab"][data-state="active"] { border-bottom: 2px solid currentColor; }
+ * [role="tabpanel"][data-state="inactive"] { display: none; }
+ * ```
+ *
+ * @see {@link TabsRoot} for state modes, validation behaviour, and the
+ *   imperative API.
+ * @see {@link TabsList} for the required `label` prop.
+ * @see {@link TabsTrigger} for the full keyboard-interaction table.
+ * @see {@link TabsContent} for panel lifecycle and unmount semantics.
+ */
+const TabsCompound = Object.assign(TabsRoot, {
+    Root: TabsRoot,
+    List: TabsList,
+    Trigger: TabsTrigger,
+    Content: TabsContent,
+});
+TabsCompound.displayName = "Tabs";
+export { TabsCompound as Tabs };

package/dist/Tabs/TabsContext.d.ts

@@ -0,0 +1,11 @@
+import type { Context, Provider } from "react";
+import { TabsContextValue } from "./types.js";
+/** Strict React context carrying the {@link TabsContextValue} from `Tabs.Root`
+ * to its descendants. `null` when read outside a `Tabs.Root`. */
+export declare const TabsContext: Context<TabsContextValue | null>;
+/** Reads the {@link TabsContextValue}; throws when used outside a `Tabs.Root`. */
+export declare const useTabsContext: () => TabsContextValue;
+/** Provider component for {@link TabsContext}, used by `Tabs.Root` to supply the
+ * {@link TabsContextValue} to its descendants. */
+declare const TabsProvider: Provider<TabsContextValue | null>;
+export { TabsProvider };

package/dist/Tabs/TabsContext.js

@@ -0,0 +1,12 @@
+"use client";
+import { createStrictContext } from "../utils/index.js";
+const tabsContextPair = createStrictContext("Component must be rendered as a child of Tabs.Root", "TabsContext");
+/** Strict React context carrying the {@link TabsContextValue} from `Tabs.Root`
+ * to its descendants. `null` when read outside a `Tabs.Root`. */
+export const TabsContext = tabsContextPair[0];
+/** Reads the {@link TabsContextValue}; throws when used outside a `Tabs.Root`. */
+export const useTabsContext = tabsContextPair[1];
+/** Provider component for {@link TabsContext}, used by `Tabs.Root` to supply the
+ * {@link TabsContextValue} to its descendants. */
+const TabsProvider = TabsContext.Provider;
+export { TabsProvider };

package/dist/Tabs/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export * from './useTabsRoot.js';
+export * from './useTabsContent.js';
+export * from './useTabsContext.js';
+export * from './useTabsTrigger.js';

package/dist/Tabs/hooks/index.js

@@ -0,0 +1,4 @@
+export * from './useTabsRoot.js';
+export * from './useTabsContent.js';
+export * from './useTabsContext.js';
+export * from './useTabsTrigger.js';

package/dist/Tabs/hooks/useTabsContent.d.ts

@@ -0,0 +1,10 @@
+import { TabsContentProps } from "../types.js";
+export declare function useTabsContent({ value }: Pick<TabsContentProps, "value">): {
+    panelId: string;
+    triggerId: string;
+    orientation: import("../types.js").TabsOrientation;
+    isActive: boolean;
+    state: string;
+    tabIndex: number;
+    shouldRender: boolean;
+};

package/dist/Tabs/hooks/useTabsContent.js

@@ -0,0 +1,27 @@
+"use client";
+import { useEffect, useState } from "react";
+import { getTriggerAndPanelIds } from "../utils.js";
+import { useTabsContext } from "./index.js";
+export function useTabsContent({ value }) {
+    const { orientation, activeValue, tabsId, lazyMount } = useTabsContext();
+    const isActive = activeValue === value;
+    const { triggerId, panelId } = getTriggerAndPanelIds(tabsId, value);
+    const state = isActive ? "active" : "inactive";
+    const tabIndex = isActive ? 0 : -1;
+    // Track whether this panel has ever been active. Starts true for the
+    // default active panel; flips once on first activation for all others.
+    // The mount effect below sets `activated` for the active panel within the
+    // same commit, so the initialiser's value is only ever observable as a
+    // pre-effect first-paint flash (not reproducible in jsdom); for inactive
+    // panels the initialiser's `false` and a mutated `undefined` are both falsy.
+    // Stryker disable next-line ArrowFunction: equivalent under the test env — see above.
+    const [activated, setActivated] = useState(() => isActive);
+    useEffect(() => {
+        if (isActive)
+            setActivated(true);
+    }, [isActive]);
+    // When lazyMount is off children always render; when on they render only
+    // after the tab has been activated for the first time.
+    const shouldRender = !lazyMount || activated;
+    return { panelId, triggerId, orientation, isActive, state, tabIndex, shouldRender };
+}

package/dist/Tabs/hooks/useTabsContext.d.ts

@@ -0,0 +1 @@
+export { useTabsContext } from "../TabsContext.js";

package/dist/Tabs/hooks/useTabsContext.js

@@ -0,0 +1 @@
+export { useTabsContext } from "../TabsContext.js";

package/dist/Tabs/hooks/useTabsRoot.d.ts

@@ -0,0 +1,21 @@
+import { Ref } from "react";
+import type { TabsRootProps, TabsImperativeApi } from "../types.js";
+export declare function useTabsRoot({ orientation, dir, activationMode, defaultValue, value, onValueChange, onChange, lazyMount, }: // `TabsRoot` always resolves these four before calling the hook, so they
+Omit<TabsRootProps, "className"> & Required<Pick<TabsRootProps, "orientation" | "dir" | "activationMode" | "lazyMount">>, ref: Ref<TabsImperativeApi>): {
+    contextValue: {
+        orientation: "horizontal" | "vertical";
+        dir: "ltr" | "rtl";
+        activationMode: "manual" | "automatic";
+        tabsId: string;
+        activeValue: string | undefined;
+        isControlled: boolean;
+        setActiveValue: (next: string) => void;
+        onValueChange: ((value: string) => void) | undefined;
+        onChange: (({ index, name }: import("../types.js").TabMetadata) => void) | undefined;
+        lazyMount: boolean;
+        registerTrigger: (triggerValue: string, element: HTMLButtonElement | null, disabled?: boolean) => void;
+        triggerValues: string[];
+        disabledTriggerValues: Set<string>;
+        focusTrigger: (triggerValue: string) => void;
+    };
+};

package/dist/Tabs/hooks/useTabsRoot.js

@@ -0,0 +1,97 @@
+"use client";
+import { useCallback, useId, useEffect, useImperativeHandle, useMemo, } from "react";
+import { useCollection, useControllableState } from "../../hooks/index.js";
+export function useTabsRoot({ orientation, dir, activationMode, defaultValue, value, onValueChange, onChange, lazyMount, }, ref) {
+    const tabsId = useId();
+    // Tabs intentionally does NOT pass onValueChange to useControllableState:
+    // in uncontrolled mode the existing public contract fires only `onChange`
+    // (with the {index, name} payload), not `onValueChange`. Tabs.Trigger
+    // therefore branches on isControlled and calls onValueChange directly in
+    // the controlled path; the hook's setter is the uncontrolled-mode setState.
+    const [activeValue, setActiveValue, isControlled] = useControllableState(value, defaultValue);
+    const { register: registerTriggerBase, itemsRef: triggersRef, keys: triggerValues, } = useCollection();
+    const registerTrigger = useCallback((triggerValue, element, 
+    // The default is only reached by the cleanup call `registerTrigger(value,
+    // null)`, where `element` is null and `disabled` is discarded — so its
+    // value is never observable.
+    // Stryker disable next-line BooleanLiteral
+    disabled = false) => {
+        registerTriggerBase(triggerValue, element ? { element, disabled } : null);
+    }, 
+    // `registerTriggerBase` is a stable useCollection callback, so emptying this
+    // array yields the identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
+    [registerTriggerBase]);
+    const disabledTriggerValues = useMemo(() => new Set(Array.from(triggersRef.current.entries())
+        .filter(([, meta]) => meta.disabled)
+        .map(([v]) => v)), 
+    // triggerValues is a fresh array on every register call, so the memo
+    // re-runs whenever any trigger mounts, unmounts, or toggles disabled.
+    [triggerValues, triggersRef]);
+    const focusTrigger = useCallback((triggerValue) => {
+        // `triggerValue` is always sourced from the navigable set (registered
+        // triggers), so a value that reaches here has a live entry.
+        // Stryker disable next-line OptionalChaining: unreachable given that invariant.
+        triggersRef.current.get(triggerValue)?.element.focus();
+    }, 
+    // `triggersRef` is a stable RefObject, so emptying this array yields the
+    // identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
+    [triggersRef]);
+    useEffect(() => {
+        if (triggerValues.length > 0 &&
+            activeValue !== undefined &&
+            !triggerValues.includes(activeValue)) {
+            throw new Error(`Invalid active tab value: "${activeValue}". Valid values are: [${triggerValues.join(", ")}]`);
+        }
+    }, [activeValue, triggerValues]);
+    // Imperative API
+    useImperativeHandle(ref, () => ({
+        setActiveTab: (newValue) => {
+            if (!triggerValues.includes(newValue)) {
+                throw new Error(`Invalid tab value: ${newValue}`);
+            }
+            if (isControlled) {
+                // Controlled mode requires `onValueChange` (discriminated-union prop
+                // type), so the optional call can never no-op in valid usage.
+                // Stryker disable next-line OptionalChaining: unreachable — controlled requires onValueChange.
+                onValueChange?.(newValue);
+            }
+            else {
+                setActiveValue(newValue);
+            }
+        },
+    }), [isControlled, setActiveValue, onValueChange, triggerValues]);
+    const contextValue = useMemo(() => ({
+        orientation,
+        dir,
+        activationMode,
+        tabsId,
+        activeValue,
+        isControlled,
+        setActiveValue,
+        onValueChange,
+        onChange,
+        lazyMount,
+        registerTrigger,
+        triggerValues,
+        disabledTriggerValues,
+        focusTrigger,
+    }), [
+        orientation,
+        dir,
+        activationMode,
+        tabsId,
+        activeValue,
+        isControlled,
+        setActiveValue,
+        onValueChange,
+        onChange,
+        lazyMount,
+        registerTrigger,
+        triggerValues,
+        disabledTriggerValues,
+        focusTrigger,
+    ]);
+    return { contextValue };
+}

package/dist/Tabs/hooks/useTabsTrigger.d.ts

@@ -0,0 +1,13 @@
+import { MouseEvent } from "react";
+import { TabsTriggerProps } from "../types.js";
+export declare function useTabsTrigger({ value, onClick, disabled, }: Pick<TabsTriggerProps, "value" | "onClick" | "disabled">): {
+    buttonRef: import("react").RefObject<HTMLButtonElement | null>;
+    triggerId: string;
+    panelId: string;
+    isActive: boolean;
+    orientation: import("../types.js").TabsOrientation;
+    state: string;
+    tabIndex: number;
+    handleClick: (e: MouseEvent<HTMLButtonElement>) => void;
+    handleKeyDown: (e: import("react").KeyboardEvent<HTMLElement>) => void;
+};

package/dist/Tabs/hooks/useTabsTrigger.js

@@ -0,0 +1,83 @@
+"use client";
+import { useRef, useEffect, useCallback, } from "react";
+import { useRovingTabindex } from "../../hooks/index.js";
+import { getTriggerAndPanelIds } from "../utils.js";
+import { useTabsContext } from "./useTabsContext.js";
+export function useTabsTrigger({ value, onClick, disabled, }) {
+    const { orientation, dir, activationMode, activeValue, isControlled, setActiveValue, onValueChange, onChange, tabsId, registerTrigger, triggerValues, disabledTriggerValues, focusTrigger, } = useTabsContext();
+    const isActive = activeValue === value;
+    const { triggerId, panelId } = getTriggerAndPanelIds(tabsId, value);
+    const buttonRef = useRef(null);
+    const state = isActive ? "active" : "inactive";
+    // When no tab is active (no defaultValue/value provided), the first registered
+    // trigger acts as the roving-tabindex home base so the tablist stays reachable
+    // via keyboard Tab navigation.
+    const isFirst = triggerValues[0] === value;
+    const tabIndex = isActive || (activeValue === undefined && isFirst) ? 0 : -1;
+    useEffect(() => {
+        registerTrigger(value, buttonRef.current, disabled);
+        return () => registerTrigger(value, null);
+    }, [value, disabled, registerTrigger]);
+    const activateTab = useCallback((newValue, index) => {
+        if (activeValue === newValue)
+            return;
+        if (isControlled) {
+            // Controlled mode requires `onValueChange` (discriminated-union prop
+            // type), so the optional call can never no-op in valid usage.
+            // Stryker disable next-line OptionalChaining: unreachable — controlled requires onValueChange.
+            onValueChange?.(newValue);
+        }
+        else {
+            setActiveValue(newValue);
+        }
+        onChange?.({ index, name: newValue });
+    }, [activeValue, isControlled, onValueChange, setActiveValue, onChange]);
+    // Note: this composition is deliberately bespoke and does NOT use the
+    // shared composeEventHandlers from ../../Slot. It runs the library's
+    // activation BEFORE the consumer's onClick, and offers no preventDefault
+    // veto path — both differ from the shared util's contract. Switching to
+    // composeEventHandlers here would be an observable behaviour change for
+    // consumers (handler ordering and preventDefault semantics).
+    function handleClick(e) {
+        const index = triggerValues.indexOf(value);
+        if (!disabled) {
+            activateTab(value, index);
+        }
+        onClick?.(e);
+    }
+    // Tabs deliberately leaves disabled values in `navigable` so arrow keys
+    // *land* on disabled tabs (focus moves there) without activating them —
+    // that's the Tabs-specific keyboard contract, distinct from RadioGroup
+    // and Accordion which both skip disabled siblings entirely.
+    const { handleKeyDown } = useRovingTabindex({
+        orientation,
+        dir,
+        navigable: triggerValues,
+        currentKey: value,
+        includeHomeEnd: true,
+        includeActivate: true,
+        onNavigate: (targetValue, action) => {
+            const isDisabled = disabledTriggerValues.has(targetValue);
+            // Automatic mode activates on any navigation; manual mode activates only
+            // on an explicit activation key (Enter/Space). Since the mode is always
+            // "automatic" or "manual", `automatic || isActivationKey` captures both.
+            const shouldActivate = !isDisabled &&
+                (activationMode === "automatic" || action === "activate");
+            if (shouldActivate) {
+                activateTab(targetValue, triggerValues.indexOf(targetValue));
+            }
+            focusTrigger(targetValue);
+        },
+    });
+    return {
+        buttonRef,
+        triggerId,
+        panelId,
+        isActive,
+        orientation,
+        state,
+        tabIndex,
+        handleClick,
+        handleKeyDown,
+    };
+}

package/dist/Tabs/index.d.ts

@@ -0,0 +1,3 @@
+export * from './Tabs.js';
+export * from './TabsContext.js';
+export * from './types.js';

package/dist/Tabs/index.js

@@ -0,0 +1,3 @@
+export * from './Tabs.js';
+export * from './TabsContext.js';
+export * from './types.js';