@versini/ui-tabs 1.1.0

package/README.md

@@ -0,0 +1,128 @@
+# @versini/ui-tabs
+
+[![npm version](https://img.shields.io/npm/v/@versini/ui-tabs?style=flat-square)](https://www.npmjs.com/package/@versini/ui-tabs)
+![npm package minimized gzipped size](<https://img.shields.io/bundlejs/size/%40versini%2Fui-tabs?style=flat-square&label=size%20(gzip)>)
+
+> An accessible, zero-layout-shift React tabs component built with TypeScript and TailwindCSS.
+
+The Tabs component provides a fully WAI-ARIA-compliant tab set: keyboard navigation, roving tabindex, automatic/manual activation, horizontal/vertical orientation, and a no-layout-shift active state (the active tab can go bold without nudging its neighbors). It is hand-rolled with no third-party runtime dependency to keep the bundle small.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [API](#api)
+- [Accessibility](#accessibility)
+
+## Features
+
+- **♿ Fully accessible**: `tablist` / `tab` / `tabpanel` roles, `aria-selected`, `aria-controls`/`aria-labelledby`, roving tabindex, arrow / Home / End keys, automatic or manual activation.
+- **📐 No layout shift**: the active tab goes bold without shifting surrounding tabs (an invisible bold twin reserves the width).
+- **🧭 Orientation**: `horizontal` (default) or `vertical`.
+- **🎨 Surface-aware theming**: `mode` (`system` | `light` | `dark` | `alt-system`) keeps text readable even on a surface whose lightness differs from the ambient theme.
+- **🎛️ Controlled & uncontrolled**: `value` / `onValueChange` or `defaultValue`.
+- **🪶 Tiny**: no Radix, only `clsx` + three small `@versini/ui-hooks`.
+- **🧪 Type safe**: generic over the tab value (`Tabs<Value extends string>`), so your tab keys stay narrowed.
+
+## Installation
+
+```bash
+npm install @versini/ui-tabs
+```
+
+> **Note**: This component requires TailwindCSS and the `@versini/ui-styles` plugin for proper styling. See the [installation documentation](https://versini-org.github.io/ui-components/?path=/docs/getting-started-installation--docs) for complete setup instructions.
+
+## Usage
+
+```tsx
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@versini/ui-tabs";
+
+type TabKey = "details" | "history" | "settings";
+
+export const Example = () => (
+	<Tabs<TabKey> defaultValue="details">
+		<TabsList aria-label="Parcel views">
+			<TabsTrigger value="details">Details</TabsTrigger>
+			<TabsTrigger value="history">History</TabsTrigger>
+			<TabsTrigger value="settings">Settings</TabsTrigger>
+		</TabsList>
+		<TabsContent value="details">Details panel</TabsContent>
+		<TabsContent value="history">History panel</TabsContent>
+		<TabsContent value="settings">Settings panel</TabsContent>
+	</Tabs>
+);
+```
+
+### Controlled
+
+```tsx
+const [value, setValue] = useState<TabKey>("details");
+
+<Tabs<TabKey> value={value} onValueChange={setValue}>
+	{/* ... */}
+</Tabs>;
+```
+
+> **Note**: In uncontrolled mode with no `defaultValue`, the first enabled tab is auto-selected after mount and `onValueChange` fires once to report it. Pass `defaultValue` (or use controlled `value`) to avoid the mount-time callback.
+
+### Navigation / trigger-only
+
+`TabsList` + `TabsTrigger` work without any `TabsContent` (e.g. route-driven tabs). In that mode no `aria-controls` is emitted, so it stays valid ARIA. Keep your panel content in your own switch when it needs its own state or lazy loading; only the active `TabsContent` is mounted, so panels with unsaved local state should not live inside `TabsContent` (a `forceMount` opt-in is planned).
+
+## API
+
+### `Tabs<Value extends string = string>`
+
+| Prop             | Type                                   | Default          |
+|------------------|----------------------------------------|------------------|
+| `value`          | `Value`                                | (controlled)     |
+| `defaultValue`   | `Value`                                | first enabled trigger |
+| `onValueChange`  | `(value: Value) => void`               | —                |
+| `orientation`    | `"horizontal" \| "vertical"`           | `"horizontal"`   |
+| `activationMode` | `"automatic" \| "manual"`              | `"automatic"`    |
+| `size`           | `"small" \| "medium" \| "large"`       | `"medium"`       |
+| `mode`           | `"system" \| "light" \| "dark" \| "alt-system"` | `"system"` |
+| `className`      | `string`                               | —                |
+
+### `TabsList`
+
+`role="tablist"`. Owns keyboard navigation. Pass `aria-label` or `aria-labelledby` to give the tablist an accessible name (required by APG; a dev warning fires if missing). Extra props are forwarded.
+
+### `TabsTrigger<Value extends string = string>`
+
+`role="tab"`. Props: `value` (required, unique within a `Tabs`), `disabled`, plus standard button attributes. Labels may be any non-interactive node (text, icon + text); the no-shift twin duplicates the label, so labels must not contain focusable or `id`-bearing elements.
+
+### `TabsContent<Value extends string = string>`
+
+`role="tabpanel"`. Props: `value` (required), plus standard div attributes. Renders only when active and a matching trigger exists.
+
+## Accessibility
+
+Implements the [WAI-ARIA APG Tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/):
+
+- Roving tabindex: exactly one trigger is in the tab order; arrow keys move between tabs (wrapping, skipping disabled), Home/End jump to first/last.
+- `automatic` activation selects on focus; `manual` requires Enter/Space.
+- Activation keeps focus on the trigger; `Tab` moves to the active panel.
+- `aria-controls` is emitted only on the active trigger (whose panel is mounted), avoiding dangling references. APG's example wires it on every tab; this component intentionally deviates because inactive panels are unmounted.
+- The active panel is `tabIndex={0}`.
+
+### Theming and `mode`
+
+Text color must match the **surface** the tabs sit on, which is not always the
+ambient theme. Because dark mode is driven by `prefers-color-scheme`, the `dark:`
+variant follows the OS, not the local surface — so a light card inside a
+dark-mode app would otherwise get light text on a light background (unreadable).
+
+- `mode="system"` (default) — follow the ambient theme. Use when the tabs sit on
+  the page surface (which follows the OS).
+- `mode="light"` — force dark text. Use on a **light** surface regardless of OS.
+- `mode="dark"` — force light text. Use on a **dark** surface regardless of OS.
+- `mode="alt-system"` — invert the ambient theme.
+
+```tsx
+// A light card that stays light even when the OS is in dark mode:
+<div className="bg-surface-light">
+	<Tabs defaultValue="a" mode="light">…</Tabs>
+</div>
+```

package/dist/components/index.d.ts

@@ -0,0 +1,160 @@
+import { JSX } from 'react/jsx-runtime';
+
+export declare type ActivationMode = "automatic" | "manual";
+
+export declare type Mode = "dark" | "light" | "system" | "alt-system";
+
+export declare type Orientation = "horizontal" | "vertical";
+
+export declare type Size = "small" | "medium" | "large";
+
+/**
+ * Tabs root. Owns the active value (controlled or uncontrolled), the
+ * trigger/panel registries, and the shared context.
+ *
+ * Invariants (referenced by name in the code comments and the test suite):
+ *  1. Unique values — trigger `value`s must be unique within a Tabs; duplicates
+ *     are unsupported and dev-warn (no runtime de-dup).
+ *  2. Exactly one tabbable trigger — `tabIndex=0` goes to the active trigger if
+ *     it matches one (even when disabled, see 5), else the first enabled, else
+ *     the first; all others get `tabIndex=-1`.
+ *  3. Default resolution — uncontrolled with no `defaultValue` activates the
+ *     first non-disabled trigger after registration, via a layout effect.
+ *  4. No-match active value — if the active value matches no trigger, no panel
+ *     renders; invariant 2 still keeps the tablist keyboard-reachable.
+ *  5. Disabled-but-active — selection is independent of `disabled`; a disabled
+ *     trigger that is the active value stays selected and tabbable.
+ *  6. All disabled — arrow/Home/End are no-ops; the first trigger stays tabbable.
+ *  7. Dynamic add/remove — in uncontrolled mode, removing/disabling the active
+ *     trigger recovers to the nearest enabled trigger (next, else previous), and
+ *     focus follows if it was inside the tablist.
+ *  8. Orphans — an orphan TabsContent (no matching trigger) never renders; an
+ *     orphan TabsTrigger (no matching panel) renders without `aria-controls`.
+ *  9. DOM-order traversal — triggers register in DOM order (compareDocumentPosition)
+ *     so keyboard navigation matches visual order.
+ */
+export declare function Tabs<Value extends string = string>({ children, value, defaultValue, onValueChange, orientation, activationMode, size, mode, className, }: TabsProps<Value>): JSX.Element;
+
+export declare namespace Tabs {
+    var displayName: string;
+}
+
+export declare const TABS_CLASSNAME = "av-tabs";
+
+export declare const TABS_CONTENT_CLASSNAME = "av-tabs-content";
+
+export declare const TABS_LIST_CLASSNAME = "av-tabs-list";
+
+export declare const TABS_TRIGGER_CLASSNAME = "av-tabs-trigger";
+
+export declare function TabsContent<Value extends string = string>({ value, children, className, ...rest }: TabsContentProps<Value>): JSX.Element | null;
+
+export declare namespace TabsContent {
+    var displayName: string;
+}
+
+export declare type TabsContentProps<Value extends string = string> = {
+    /**
+     * The value of the trigger this panel belongs to.
+     */
+    value: Value;
+    /**
+     * The panel content.
+     */
+    children: React.ReactNode;
+    /**
+     * The classes to apply to the panel element.
+     */
+    className?: string;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+export declare const TabsList: {
+    ({ children, className, onKeyDown, ...rest }: TabsListProps): JSX.Element;
+    displayName: string;
+};
+
+export declare type TabsListProps = {
+    /**
+     * The TabsTrigger children.
+     */
+    children: React.ReactNode;
+    /**
+     * The classes to apply to the tablist element.
+     */
+    className?: string;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+export declare type TabsProps<Value extends string = string> = {
+    /**
+     * The TabsList and TabsContent children.
+     */
+    children: React.ReactNode;
+    /**
+     * The controlled active tab value.
+     */
+    value?: Value;
+    /**
+     * The initially active tab value (uncontrolled). When omitted, the first
+     * non-disabled trigger becomes active after mount.
+     */
+    defaultValue?: Value;
+    /**
+     * Callback fired when the active tab changes.
+     */
+    onValueChange?: (value: Value) => void;
+    /**
+     * The orientation of the tab list.
+     * @default "horizontal"
+     */
+    orientation?: Orientation;
+    /**
+     * Whether tabs activate on focus ("automatic") or require Enter/Space
+     * ("manual").
+     * @default "automatic"
+     */
+    activationMode?: ActivationMode;
+    /**
+     * The size of the triggers.
+     * @default "medium"
+     */
+    size?: Size;
+    /**
+     * How tab/panel text adapts to its surface. Use `"light"`/`"dark"` to force
+     * colors for a surface whose lightness differs from the ambient theme (e.g.
+     * a light card inside a dark-mode page); `"system"` follows the ambient theme,
+     * `"alt-system"` inverts it.
+     * @default "system"
+     */
+    mode?: Mode;
+    /**
+     * The classes to apply to the root element.
+     */
+    className?: string;
+};
+
+export declare function TabsTrigger<Value extends string = string>({ value, children, disabled, className, onClick, ...rest }: TabsTriggerProps<Value>): JSX.Element;
+
+export declare namespace TabsTrigger {
+    var displayName: string;
+}
+
+export declare type TabsTriggerProps<Value extends string = string> = {
+    /**
+     * The unique value identifying this tab. Must be unique within a Tabs.
+     */
+    value: Value;
+    /**
+     * The tab label (text, icon + text, any non-interactive node).
+     */
+    children: React.ReactNode;
+    /**
+     * Whether the trigger is disabled (excluded from keyboard traversal).
+     */
+    disabled?: boolean;
+    /**
+     * The classes to apply to the trigger button.
+     */
+    className?: string;
+} & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "value">;
+
+export { }

package/dist/components/index.js

@@ -0,0 +1,585 @@
+/*!
+  @versini/ui-tabs v1.1.0
+  © 2026 gizmette.com
+*/
+
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useUncontrolled } from "@versini/ui-hooks/use-uncontrolled";
+import { useUniqueId } from "@versini/ui-hooks/use-unique-id";
+import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import clsx from "clsx";
+
+const TABS_CLASSNAME = "av-tabs";
+const TABS_LIST_CLASSNAME = "av-tabs-list";
+const TABS_TRIGGER_CLASSNAME = "av-tabs-trigger";
+const TABS_CONTENT_CLASSNAME = "av-tabs-content";
+
+
+
+
+
+
+/* v8 ignore start - default context values are fallbacks, never used directly */ const TabsContext = createContext({
+    value: undefined,
+    tabbableValue: undefined,
+    setValue: ()=>{},
+    orientation: "horizontal",
+    activationMode: "automatic",
+    size: "medium",
+    mode: "system",
+    baseId: "",
+    registerTrigger: ()=>{},
+    unregisterTrigger: ()=>{},
+    getTriggers: ()=>[],
+    registerPanel: ()=>{},
+    unregisterPanel: ()=>{},
+    hasPanel: ()=>false
+}); /* v8 ignore stop */ 
+
+
+/**
+ * `useLayoutEffect` in the browser, `useEffect` on the server — avoids React's
+ * "useLayoutEffect does nothing on the server" warning during SSR while keeping
+ * the synchronous, pre-paint timing in the browser.
+ */ /* v8 ignore start - useEffect fallback only runs during SSR (window undefined) */ const useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect; /* v8 ignore stop */ 
+
+
+
+
+/**
+ * Deterministic, SSR-safe ids linking a trigger to its panel. The trigger's
+ * `aria-controls` and the panel's `id` (and the panel's `aria-labelledby` and
+ * the trigger's `id`) MUST match, so both components derive ids through these
+ * helpers rather than inlining the template — divergence would silently break
+ * the accessibility wiring.
+ */ const getTabId = (baseId, value)=>`${baseId}-tab-${value}`;
+const getPanelId = (baseId, value)=>`${baseId}-panel-${value}`;
+/**
+ * Theme-aware text color. `light`/`dark` force the color for a surface whose
+ * lightness differs from the ambient theme (e.g. a light card in dark mode);
+ * `system` follows the ambient theme, `alt-system` inverts it.
+ */ const getModeTextClasses = ({ mode })=>{
+    return clsx({
+        "text-copy-dark": mode === "light",
+        "text-copy-light": mode === "dark",
+        "text-copy-dark dark:text-copy-light": mode === "system",
+        "text-copy-light dark:text-copy-dark": mode === "alt-system"
+    });
+};
+const getTabsClasses = ({ className, orientation })=>{
+    return clsx(TABS_CLASSNAME, orientation === "vertical" ? "flex flex-row gap-4" : "flex flex-col gap-2", className);
+};
+const getTabsListClasses = ({ orientation })=>{
+    return clsx(TABS_LIST_CLASSNAME, "flex", orientation === "vertical" ? "flex-col border-l border-border-medium" : "flex-row gap-2 border-b border-border-medium");
+};
+const getTabsTriggerSizeClasses = ({ size })=>{
+    return clsx({
+        "text-xs px-2 py-1": size === "small",
+        "text-sm px-4 py-2": size === "medium",
+        "text-base px-5 py-2.5": size === "large"
+    });
+};
+const getTabsTriggerClasses = ({ size, orientation, active, mode })=>{
+    const borderSide = orientation === "vertical" ? "border-l-2" : "border-b-2";
+    return clsx(TABS_TRIGGER_CLASSNAME, "relative cursor-pointer bg-transparent transition-colors outline-none", // High-contrast text that matches the surface (via mode). The active state
+    // is conveyed by the indicator border + bold weight, never by dimming the
+    // resting text. Matches clubroad's full-contrast inactive tabs.
+    getModeTextClasses({
+        mode
+    }), "focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-focus-dark", "disabled:cursor-not-allowed disabled:opacity-50", getTabsTriggerSizeClasses({
+        size
+    }), borderSide, active ? "border-action-light" : "border-transparent");
+};
+const getTabsContentClasses = ({ className, mode })=>{
+    return clsx(TABS_CONTENT_CLASSNAME, // Theme-aware text so panel content stays readable on the actual surface
+    // (consumers can still override via className).
+    getModeTextClasses({
+        mode
+    }), "outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-focus-dark", className);
+};
+
+
+
+
+
+
+
+
+/** Nearest enabled trigger to `fromIndex`: scan forward (next), then backward (previous). */ const findNearestEnabledIndex = (triggers, fromIndex)=>{
+    const count = triggers.length;
+    const start = Math.min(Math.max(fromIndex, 0), count);
+    for(let i = start; i < count; i++){
+        if (!triggers[i].disabled) {
+            return i;
+        }
+    }
+    for(let i = start - 1; i >= 0; i--){
+        if (!triggers[i].disabled) {
+            return i;
+        }
+    }
+    return -1;
+};
+/**
+ * Tabs root. Owns the active value (controlled or uncontrolled), the
+ * trigger/panel registries, and the shared context.
+ *
+ * Invariants (referenced by name in the code comments and the test suite):
+ *  1. Unique values — trigger `value`s must be unique within a Tabs; duplicates
+ *     are unsupported and dev-warn (no runtime de-dup).
+ *  2. Exactly one tabbable trigger — `tabIndex=0` goes to the active trigger if
+ *     it matches one (even when disabled, see 5), else the first enabled, else
+ *     the first; all others get `tabIndex=-1`.
+ *  3. Default resolution — uncontrolled with no `defaultValue` activates the
+ *     first non-disabled trigger after registration, via a layout effect.
+ *  4. No-match active value — if the active value matches no trigger, no panel
+ *     renders; invariant 2 still keeps the tablist keyboard-reachable.
+ *  5. Disabled-but-active — selection is independent of `disabled`; a disabled
+ *     trigger that is the active value stays selected and tabbable.
+ *  6. All disabled — arrow/Home/End are no-ops; the first trigger stays tabbable.
+ *  7. Dynamic add/remove — in uncontrolled mode, removing/disabling the active
+ *     trigger recovers to the nearest enabled trigger (next, else previous), and
+ *     focus follows if it was inside the tablist.
+ *  8. Orphans — an orphan TabsContent (no matching trigger) never renders; an
+ *     orphan TabsTrigger (no matching panel) renders without `aria-controls`.
+ *  9. DOM-order traversal — triggers register in DOM order (compareDocumentPosition)
+ *     so keyboard navigation matches visual order.
+ */ function Tabs({ children, value, defaultValue, onValueChange, orientation = "horizontal", activationMode = "automatic", size = "medium", mode = "system", className }) {
+    const [activeValue, setActiveValue] = useUncontrolled({
+        value,
+        defaultValue,
+        onChange: onValueChange
+    });
+    const baseId = useUniqueId("av-tabs-");
+    const triggersRef = useRef([]);
+    const panelsRef = useRef(new Set());
+    const focusWithinRef = useRef(false);
+    // Last known index of the active trigger, used to recover to the *nearest*
+    // trigger when the active one is removed (its value is gone from the registry,
+    // but this ref still holds the slot it occupied).
+    const lastActiveIndexRef = useRef(0);
+    // Bumped whenever a trigger/panel registers or unregisters; it is a dependency
+    // of the context memo so consumers re-render and recompute roving tabIndex /
+    // aria-controls from the (mutable) registries.
+    const [registrationVersion, setRegistrationVersion] = useState(0);
+    const bumpVersion = useCallback(()=>setRegistrationVersion((version)=>version + 1), []);
+    // Stable activation setter (useUncontrolled returns a fresh setter each render
+    // in uncontrolled mode; a ref keeps `setValue`'s identity stable so the context
+    // memo is not invalidated on every render).
+    const setActiveRef = useRef(setActiveValue);
+    setActiveRef.current = setActiveValue;
+    const setValue = useCallback((next)=>{
+        setActiveRef.current(next);
+    }, []);
+    const getTriggers = useCallback(()=>triggersRef.current, []);
+    const registerTrigger = useCallback((registration)=>{
+        const existingIndex = triggersRef.current.findIndex((trigger)=>trigger.element === registration.element);
+        /* v8 ignore start - re-registration of the same element on re-render */ if (existingIndex >= 0) {
+            triggersRef.current[existingIndex] = registration;
+            bumpVersion();
+            return;
+        }
+        /* v8 ignore stop */ if (triggersRef.current.some((trigger)=>trigger.value === registration.value)) {
+            console.warn(`[ui-tabs] Duplicate TabsTrigger value "${registration.value}". Trigger values must be unique within a Tabs.`);
+        }
+        // Insert in DOM order so keyboard traversal matches visual order.
+        const insertIndex = triggersRef.current.findIndex((trigger)=>trigger.element.compareDocumentPosition(registration.element) & Node.DOCUMENT_POSITION_PRECEDING);
+        if (insertIndex !== -1) {
+            triggersRef.current.splice(insertIndex, 0, registration);
+        } else {
+            triggersRef.current.push(registration);
+        }
+        bumpVersion();
+    }, [
+        bumpVersion
+    ]);
+    const unregisterTrigger = useCallback((element)=>{
+        triggersRef.current = triggersRef.current.filter((trigger)=>trigger.element !== element);
+        bumpVersion();
+    }, [
+        bumpVersion
+    ]);
+    const registerPanel = useCallback((panelValue)=>{
+        panelsRef.current.add(panelValue);
+        bumpVersion();
+    }, [
+        bumpVersion
+    ]);
+    const unregisterPanel = useCallback((panelValue)=>{
+        panelsRef.current.delete(panelValue);
+        bumpVersion();
+    }, [
+        bumpVersion
+    ]);
+    const hasPanel = useCallback((panelValue)=>panelsRef.current.has(panelValue), []);
+    const handleRootFocus = useCallback(()=>{
+        focusWithinRef.current = true;
+    }, []);
+    const handleRootBlur = useCallback((event)=>{
+        // Keep the flag when focus is lost to <body> (e.g. the focused trigger
+        // unmounts) so recovery can restore it; only clear when focus genuinely
+        // moves to an element outside this Tabs.
+        if (event.relatedTarget && !event.currentTarget.contains(event.relatedTarget)) {
+            focusWithinRef.current = false;
+        }
+    }, []);
+    // Default resolution (Invariant 3) + dynamic recovery (Invariant 7), both
+    // uncontrolled-only (controlled mode delegates recovery to the consumer).
+    useIsomorphicLayoutEffect(()=>{
+        if (value !== undefined) {
+            return;
+        }
+        const triggers = triggersRef.current;
+        const activeIsValid = activeValue !== undefined && triggers.some((trigger)=>trigger.value === activeValue && !trigger.disabled);
+        if (activeIsValid) {
+            return;
+        }
+        const recoveredIndex = findNearestEnabledIndex(triggers, lastActiveIndexRef.current);
+        if (recoveredIndex !== -1) {
+            const recovered = triggers[recoveredIndex];
+            setActiveValue(recovered.value);
+            // Restore keyboard position if focus was inside the tablist (e.g. the
+            // focused active trigger was just removed and focus fell to <body>).
+            if (focusWithinRef.current) {
+                recovered.element.focus();
+            }
+        }
+    });
+    const triggers = triggersRef.current;
+    const activeIndex = triggers.findIndex((trigger)=>trigger.value === activeValue);
+    if (activeIndex !== -1) {
+        lastActiveIndexRef.current = activeIndex;
+    }
+    // Exactly one trigger carries tabIndex=0 (Invariant 2): the active trigger if
+    // it matches one (even when disabled, Invariant 5), else the first enabled,
+    // else the first.
+    let tabbableValue;
+    if (activeIndex !== -1) {
+        tabbableValue = activeValue;
+    } else {
+        tabbableValue = (triggers.find((trigger)=>!trigger.disabled) ?? triggers[0])?.value;
+    }
+    // biome-ignore lint/correctness/useExhaustiveDependencies: registrationVersion is an intentional tripwire. The memo reads the mutable trigger/panel registries (refs the linter cannot see), so it MUST recompute on every (un)registration; removing this dep reintroduces stale/dangling aria-controls.
+    const contextValue = useMemo(()=>({
+            value: activeValue,
+            tabbableValue,
+            setValue,
+            orientation,
+            activationMode,
+            size,
+            mode,
+            baseId,
+            registerTrigger,
+            unregisterTrigger,
+            getTriggers,
+            registerPanel,
+            unregisterPanel,
+            hasPanel
+        }), [
+        activeValue,
+        tabbableValue,
+        // registrationVersion drives recompute of roving tabIndex / aria-controls
+        // from the registries when a trigger/panel (un)registers.
+        registrationVersion,
+        setValue,
+        orientation,
+        activationMode,
+        size,
+        mode,
+        baseId,
+        registerTrigger,
+        unregisterTrigger,
+        getTriggers,
+        registerPanel,
+        unregisterPanel,
+        hasPanel
+    ]);
+    return /*#__PURE__*/ jsx(TabsContext.Provider, {
+        value: contextValue,
+        children: /*#__PURE__*/ jsx("div", {
+            className: getTabsClasses({
+                className,
+                orientation
+            }),
+            onFocus: handleRootFocus,
+            onBlur: handleRootBlur,
+            children: children
+        })
+    });
+}
+Tabs.displayName = "Tabs";
+
+
+
+
+
+
+function TabsContent({ value, children, className, ...rest }) {
+    const { value: activeValue, mode, baseId, registerPanel, unregisterPanel, getTriggers } = useContext(TabsContext);
+    useIsomorphicLayoutEffect(()=>{
+        registerPanel(value);
+        return ()=>{
+            unregisterPanel(value);
+        };
+    }, [
+        value,
+        registerPanel,
+        unregisterPanel
+    ]);
+    // Only the active panel renders, and only when a matching trigger exists
+    // (an orphan TabsContent never renders). Check active first so inactive
+    // panels skip the trigger-registry scan.
+    if (activeValue !== value) {
+        return null;
+    }
+    const hasMatchingTrigger = getTriggers().some((trigger)=>trigger.value === value);
+    if (!hasMatchingTrigger) {
+        return null;
+    }
+    const tabId = getTabId(baseId, value);
+    const panelId = getPanelId(baseId, value);
+    return /*#__PURE__*/ jsx("div", {
+        ...rest,
+        role: "tabpanel",
+        id: panelId,
+        "aria-labelledby": tabId,
+        tabIndex: 0,
+        className: getTabsContentClasses({
+            className,
+            mode
+        }),
+        children: children
+    });
+}
+TabsContent.displayName = "TabsContent";
+
+
+const getNextEnabledIndex = (triggers, currentIndex, direction)=>{
+    const count = triggers.length;
+    // Seed the sentinel per direction so the first forward step lands on 0 and the
+    // first backward step lands on count-1 (correct wrap when nothing is current).
+    let index = currentIndex < 0 ? direction === 1 ? -1 : count : currentIndex;
+    for(let i = 0; i < count; i++){
+        index = (index + direction + count) % count;
+        if (!triggers[index].disabled) {
+            return index;
+        }
+    }
+    return -1;
+};
+const getFirstEnabledIndex = (triggers)=>{
+    for(let i = 0; i < triggers.length; i++){
+        if (!triggers[i].disabled) {
+            return i;
+        }
+    }
+    return -1;
+};
+const getLastEnabledIndex = (triggers)=>{
+    for(let i = triggers.length - 1; i >= 0; i--){
+        if (!triggers[i].disabled) {
+            return i;
+        }
+    }
+    return -1;
+};
+/**
+ * Returns an onKeyDown handler for the tablist implementing the WAI-ARIA tabs
+ * keyboard pattern: arrow keys (per orientation) with wrap + disabled-skip,
+ * Home/End, and Enter/Space activation in manual mode. Off-axis arrows are not
+ * intercepted so native behavior (page scroll) is preserved.
+ */ const useTabsKeyboard = ({ getTriggers, orientation, activationMode, value, setValue })=>{
+    return useCallback((event)=>{
+        const triggers = getTriggers();
+        if (triggers.length === 0) {
+            return;
+        }
+        const nextKey = orientation === "vertical" ? "ArrowDown" : "ArrowRight";
+        const prevKey = orientation === "vertical" ? "ArrowUp" : "ArrowLeft";
+        const focusedIndex = triggers.findIndex((trigger)=>trigger.element === document.activeElement);
+        const currentIndex = focusedIndex >= 0 ? focusedIndex : triggers.findIndex((trigger)=>trigger.value === value);
+        const moveTo = (index)=>{
+            if (index < 0) {
+                return;
+            }
+            const target = triggers[index];
+            target.element.focus();
+            if (activationMode === "automatic") {
+                setValue(target.value);
+            }
+        };
+        switch(event.key){
+            case nextKey:
+                {
+                    event.preventDefault();
+                    moveTo(getNextEnabledIndex(triggers, currentIndex, 1));
+                    break;
+                }
+            case prevKey:
+                {
+                    event.preventDefault();
+                    moveTo(getNextEnabledIndex(triggers, currentIndex, -1));
+                    break;
+                }
+            case "Home":
+                {
+                    event.preventDefault();
+                    moveTo(getFirstEnabledIndex(triggers));
+                    break;
+                }
+            case "End":
+                {
+                    event.preventDefault();
+                    moveTo(getLastEnabledIndex(triggers));
+                    break;
+                }
+            case "Enter":
+            case " ":
+                {
+                    // Prevent the native <button> click (and Space-scroll) so we own
+                    // activation. In manual mode, activate the focused trigger; in
+                    // automatic mode the tab is already active, so this is a no-op.
+                    event.preventDefault();
+                    if (activationMode === "manual" && currentIndex >= 0 && !triggers[currentIndex].disabled) {
+                        setValue(triggers[currentIndex].value);
+                    }
+                    break;
+                }
+            default:
+                break;
+        }
+    }, [
+        getTriggers,
+        orientation,
+        activationMode,
+        value,
+        setValue
+    ]);
+};
+
+
+
+
+
+
+
+const TabsList = ({ children, className, onKeyDown, ...rest })=>{
+    const { orientation, activationMode, value, setValue, getTriggers } = useContext(TabsContext);
+    const listRef = useRef(null);
+    const handleKeyDown = useTabsKeyboard({
+        getTriggers,
+        orientation,
+        activationMode,
+        value,
+        setValue
+    });
+    // Dev: warn once if the tablist has no accessible name (APG requirement).
+    useEffect(()=>{
+        const list = listRef.current;
+        /* v8 ignore start - ref is always set after mount */ if (!list) {
+            return;
+        }
+        /* v8 ignore stop */ const hasName = list.hasAttribute("aria-label") || list.hasAttribute("aria-labelledby");
+        if (!hasName) {
+            console.warn("[ui-tabs] TabsList should have an accessible name via `aria-label` or `aria-labelledby`.");
+        }
+    }, []);
+    return /*#__PURE__*/ jsx("div", {
+        ...rest,
+        ref: listRef,
+        role: "tablist",
+        "aria-orientation": orientation,
+        className: clsx(getTabsListClasses({
+            orientation
+        }), className),
+        onKeyDown: (event)=>{
+            onKeyDown?.(event);
+            handleKeyDown(event);
+        },
+        children: children
+    });
+};
+TabsList.displayName = "TabsList";
+
+
+
+
+
+
+
+function TabsTrigger({ value, children, disabled = false, className, onClick, ...rest }) {
+    const { value: activeValue, tabbableValue, setValue, orientation, size, mode, baseId, registerTrigger, unregisterTrigger, hasPanel } = useContext(TabsContext);
+    const buttonRef = useRef(null);
+    // Register in a layout effect (before paint) so the panel's first render sees
+    // a populated trigger registry — avoids a one-frame empty/flicker state.
+    useIsomorphicLayoutEffect(()=>{
+        const element = buttonRef.current;
+        /* v8 ignore start - ref is always set after mount */ if (!element) {
+            return;
+        }
+        /* v8 ignore stop */ registerTrigger({
+            element,
+            value,
+            disabled
+        });
+        return ()=>{
+            unregisterTrigger(element);
+        };
+    }, [
+        value,
+        disabled,
+        registerTrigger,
+        unregisterTrigger
+    ]);
+    const active = activeValue === value;
+    const tabId = getTabId(baseId, value);
+    const panelId = getPanelId(baseId, value);
+    // Emit aria-controls only on the active trigger and only when its panel is
+    // registered (avoids a dangling IDREF; supports trigger-only/navigation use).
+    const controlsPanel = active && hasPanel(value);
+    return /*#__PURE__*/ jsx("button", {
+        ...rest,
+        ref: buttonRef,
+        type: "button",
+        role: "tab",
+        id: tabId,
+        "aria-selected": active,
+        "aria-controls": controlsPanel ? panelId : undefined,
+        tabIndex: tabbableValue === value ? 0 : -1,
+        disabled: disabled,
+        className: clsx(getTabsTriggerClasses({
+            size,
+            orientation,
+            active,
+            mode
+        }), className),
+        onClick: (event)=>{
+            onClick?.(event);
+            setValue(value);
+        },
+        children: /*#__PURE__*/ jsxs("span", {
+            className: "grid",
+            children: [
+                /*#__PURE__*/ jsx("span", {
+                    "aria-hidden": "true",
+                    className: "invisible font-semibold [grid-area:1/1]",
+                    children: children
+                }),
+                /*#__PURE__*/ jsx("span", {
+                    "data-active": active,
+                    className: "[grid-area:1/1] data-[active=true]:font-semibold",
+                    children: children
+                })
+            ]
+        })
+    });
+}
+TabsTrigger.displayName = "TabsTrigger";
+
+
+
+
+
+
+
+export { TABS_CLASSNAME, TABS_CONTENT_CLASSNAME, TABS_LIST_CLASSNAME, TABS_TRIGGER_CLASSNAME, Tabs, TabsContent, TabsList, TabsTrigger };

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@versini/ui-tabs",
+	"version": "1.1.0",
+	"license": "MIT",
+	"author": "Arno Versini",
+	"publishConfig": {
+		"access": "public"
+	},
+	"homepage": "https://www.npmjs.com/package/@versini/ui-tabs",
+	"repository": {
+		"type": "git",
+		"url": "git@github.com:aversini/ui-components.git"
+	},
+	"type": "module",
+	"main": "dist/components/index.js",
+	"types": "dist/components/index.d.ts",
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"scripts": {
+		"build:check": "tsc",
+		"build:js": "rslib build",
+		"build:types": "echo 'Types now built with rslib'",
+		"build": "npm-run-all --serial clean build:check build:js",
+		"clean": "rimraf dist tmp coverage",
+		"dev:js": "rslib build --watch",
+		"dev:types": "echo 'Types now watched with rslib'",
+		"dev": "rslib build --watch",
+		"lint": "biome lint src",
+		"lint:fix": "biome check src --write --no-errors-on-unmatched",
+		"prettier": "biome check --write --no-errors-on-unmatched",
+		"start": "static-server dist --port 5173",
+		"test:coverage:ui": "vitest --coverage --ui",
+		"test:coverage": "vitest run --coverage",
+		"test:watch": "vitest",
+		"test": "vitest run",
+		"test:visual": "playwright test -c playwright-ct.config.ts",
+		"test:visual:report": "playwright show-report playwright-report",
+		"test:visual:update": "playwright test -c playwright-ct.config.ts --update-snapshots",
+		"test:visual:ui": "playwright test -c playwright-ct.config.ts --ui"
+	},
+	"dependencies": {
+		"@versini/ui-hooks": "workspace:*",
+		"clsx": "2.1.1",
+		"tailwindcss": "4.3.0"
+	},
+	"sideEffects": [
+		"**/*.css"
+	]
+}