@skdx/react 0.26.0 → 0.28.0

package/dist/tabs/Tabs.d.ts

@@ -16,17 +16,25 @@ export declare function makeContentId(baseId: string, value: string): string;
  * `<div>` — layout of the list vs. panels is entirely up to your CSS.
  *
  * Works controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).
+ * `onValueChange` receives a `TabsValueChangeDetail` — the new value, the
+ * one it replaced, and whether a pointer or the keyboard drove it — not a bare
+ * string.
+ *
+ * Given no `children` draws derived anatomy from `items`; root's
+ * `aria-label`/`aria-labelledby` and `loop` forward onto the derived
+ * `TabsList`, which carries `role="tablist"`. Given children, they render
+ * verbatim.
  *
  * @example
  * ```tsx
- * <Tabs defaultValue="account">
- *   <TabsList aria-label="Manage account">
- *     <TabsTrigger value="account">Account</TabsTrigger>
- *     <TabsTrigger value="password">Password</TabsTrigger>
- *   </TabsList>
- *   <TabsContent value="account">Account settings…</TabsContent>
- *   <TabsContent value="password">Password settings…</TabsContent>
- * </Tabs>
+ * <Tabs
+ *   defaultValue="account"
+ *   aria-label="Manage account"
+ *   items={[
+ *     { value: 'account', label: 'Account', content: 'Account settings…' },
+ *     { value: 'password', label: 'Password', content: 'Password settings…' },
+ *   ]}
+ * />
  * ```
  */
 export declare const Tabs: React.ForwardRefExoticComponent<Omit<TabsProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/tabs/Tabs.js

@@ -1 +1 @@
-import*as s from"react";import{createSafeContext as V}from"../utils/createContext.js";import{skdxPart as I}from"../utils/part.js";import{Primitive as L}from"../utils/primitive.js";import{useControllableState as k}from"../utils/useControllableState.js";import{jsx as p}from"react/jsx-runtime";var[h,i]=V("Tabs");function d(e,o){return`${e}-trigger-${o}`}function b(e,o){return`${e}-content-${o}`}var w=s.forwardRef(({value:e,defaultValue:o,onValueChange:n,orientation:r="horizontal",activationMode:t="automatic",...a},l)=>{let[m,x]=k({prop:e,defaultProp:o,onChange:n}),y=s.useId(),[R,P]=s.useState(null);return p(h,{baseId:y,value:m,onValueChange:x,orientation:r,activationMode:t,firstEnabledValue:R,setFirstEnabledValue:P,children:p(L.div,{"data-orientation":r,...a,...I("tabs","root",a.className),ref:l})})});w.displayName="Tabs";import*as c from"react";import{useComposedRefs as D}from"../utils/composeRefs.js";import{skdxPart as S}from"../utils/part.js";import{composeEventHandlers as H,Primitive as M}from"../utils/primitive.js";import{useRovingFocus as N,useRovingTabStop as T}from"../utils/useRovingFocus.js";import{jsx as $}from"react/jsx-runtime";var F='[role="tab"]:not([disabled])',K='[role="tab"][data-state="active"]:not([disabled])',u=c.forwardRef(({loop:e=!0,...o},n)=>{let r=i("TabsList"),t=N({orientation:r.orientation,loop:e,itemSelector:'[role="tab"]'}),a=c.useRef(null),l=D(n,a);return T(a,K,"data-value",r.firstEnabledValue,r.setFirstEnabledValue),T(a,F,"data-value",r.firstEnabledValue,r.setFirstEnabledValue),$(M.div,{role:"tablist","aria-orientation":r.orientation,"data-orientation":r.orientation,...o,...S("tabs","list",o.className),ref:l,onKeyDown:H(o.onKeyDown,t)})});u.displayName="TabsList";import*as g from"react";import{skdxPart as A}from"../utils/part.js";import{composeEventHandlers as f,Primitive as B}from"../utils/primitive.js";import{rovingTabIndex as O}from"../utils/useRovingFocus.js";import{jsx as _}from"react/jsx-runtime";var v=g.forwardRef(({value:e,disabled:o,...n},r)=>{let t=i("TabsTrigger"),a=t.value===e,l=t.firstEnabledValue===null?a&&!o:t.firstEnabledValue===e;return _(B.button,{type:"button",role:"tab","aria-selected":a,"aria-controls":b(t.baseId,e),id:d(t.baseId,e),"data-state":a?"active":"inactive","data-disabled":o?"":void 0,"data-orientation":t.orientation,"data-value":e,disabled:o,tabIndex:O(t.firstEnabledValue!==null||t.value!==void 0,l,o),...n,...A("tabs","trigger",n.className),ref:r,onClick:f(n.onClick,()=>{o||t.onValueChange(e)}),onFocus:f(n.onFocus,()=>{t.activationMode==="automatic"&&!o&&!a&&t.onValueChange(e)}),onKeyDown:f(n.onKeyDown,m=>{[" ","Enter"].includes(m.key)&&!o&&(m.preventDefault(),t.onValueChange(e))})})});v.displayName="TabsTrigger";import*as C from"react";import{skdxPart as z}from"../utils/part.js";import{Primitive as q}from"../utils/primitive.js";import{jsx as G}from"react/jsx-runtime";var E=C.forwardRef(({value:e,forceMount:o,...n},r)=>{let t=i("TabsContent"),a=t.value===e;return o||a?G(q.div,{role:"tabpanel","aria-labelledby":d(t.baseId,e),id:b(t.baseId,e),"data-state":a?"active":"inactive","data-orientation":t.orientation,hidden:!a,tabIndex:0,...n,...z("tabs","content",n.className),ref:r}):null});E.displayName="TabsContent";export{w as Tabs,E as TabsContent,u as TabsList,h as TabsProvider,v as TabsTrigger,b as makeContentId,d as makeTriggerId,i as useTabsContext};
+import*as l from"react";import{createSafeContext as re}from"../utils/createContext.js";import{skdxPart as se}from"../utils/part.js";import{Primitive as ie}from"../utils/primitive.js";import{useControllableState as le}from"../utils/useControllableState.js";import*as g from"react";import{skdxPart as _}from"../utils/part.js";import{Primitive as z}from"../utils/primitive.js";import{jsx as U}from"react/jsx-runtime";var E=g.forwardRef(({value:t,forceMount:n,tabIndex:r=0,...o},a)=>{let e=m("TabsContent"),i=e.value===t,d=n||i,{setContentMounted:s}=e;return g.useEffect(()=>(s(t,d),()=>s(t,!1)),[s,t,d]),d?U(z.div,{role:"tabpanel","aria-labelledby":v(e.baseId,t),id:y(e.baseId,t),"data-state":i?"active":"inactive","data-orientation":e.orientation,hidden:!i,tabIndex:r,...o,..._("tabs","content",o.className),ref:a}):null});E.displayName="TabsContent";import*as f from"react";import{useComposedRefs as q}from"../utils/composeRefs.js";import{skdxPart as G}from"../utils/part.js";import{composeEventHandlers as J,Primitive as Q}from"../utils/primitive.js";import{useRovingFocus as W,useRovingTabStop as D}from"../utils/useRovingFocus.js";import{jsx as Z}from"react/jsx-runtime";var X='[role="tab"]:not([disabled])',Y='[role="tab"][data-state="active"]:not([disabled])',w=f.forwardRef(({loop:t=!0,...n},r)=>{let o=m("TabsList"),a=W({orientation:o.orientation,loop:t,itemSelector:'[role="tab"]'}),e=f.useRef(null),i=q(r,e);D(e,Y,"data-value",o.firstEnabledValue,o.setFirstEnabledValue),D(e,X,"data-value",o.firstEnabledValue,o.setFirstEnabledValue);let d=f.useCallback(s=>{let b=s.currentTarget.ownerDocument.activeElement;o.arrowNavigating.current=!0;try{a(s)}finally{o.arrowNavigating.current=!1}let c=s.currentTarget.ownerDocument.activeElement;c!==b&&c instanceof HTMLElement&&e.current?.contains(c)&&c.scrollIntoView?.({block:"nearest",inline:"nearest"})},[o,a]);return Z(Q.div,{role:"tablist","aria-orientation":o.orientation,"data-orientation":o.orientation,...n,...G("tabs","list",n.className),ref:i,onKeyDown:J(n.onKeyDown,d)})});w.displayName="TabsList";import*as C from"react";import{skdxPart as j}from"../utils/part.js";import{composeEventHandlers as p,Primitive as ee}from"../utils/primitive.js";import{rovingTabIndex as te}from"../utils/useRovingFocus.js";import{jsx as ae}from"react/jsx-runtime";var x=C.forwardRef(({value:t,disabled:n,...r},o)=>{let a=m("TabsTrigger"),e=a.disabled||n||!1,i=a.value===t,d=a.firstEnabledValue===null?i&&!e:a.firstEnabledValue===t,s=C.useRef(!1);return ae(ee.button,{type:"button",role:"tab","aria-selected":i,"aria-controls":i||a.mountedContentValues.has(t)?y(a.baseId,t):void 0,id:v(a.baseId,t),"data-state":i?"active":"inactive","data-disabled":e?"":void 0,"data-orientation":a.orientation,"data-value":t,disabled:e,tabIndex:te(a.firstEnabledValue!==null||a.value!==void 0,d,e),...r,...j("tabs","trigger",r.className),ref:o,onPointerDown:p(r.onPointerDown,()=>{s.current=!0}),onBlur:p(r.onBlur,()=>{s.current=!1}),onClick:p(r.onClick,()=>{e||a.onValueChange(t,"pointer")}),onFocus:p(r.onFocus,()=>{let b=s.current||a.arrowNavigating.current;a.activationMode==="automatic"&&b&&!e&&!i&&a.onValueChange(t,s.current?"pointer":"keyboard")}),onKeyDown:p(r.onKeyDown,b=>{[" ","Enter"].includes(b.key)&&!e&&(b.preventDefault(),a.onValueChange(t,"keyboard"))})})});x.displayName="TabsTrigger";import{Fragment as oe,jsx as V,jsxs as ne}from"react/jsx-runtime";var L=({items:t=[],renderPanel:n,loop:r,"aria-label":o,"aria-labelledby":a})=>ne(oe,{children:[V(w,{loop:r,"aria-label":o,"aria-labelledby":a,children:t.map(e=>V(x,{value:e.value,disabled:e.disabled,children:e.label},e.value))}),t.map(e=>V(E,{value:e.value,children:n?n(e):e.content},e.value))]});import{jsx as P}from"react/jsx-runtime";var[de,m]=re("Tabs");function v(t,n){return`${t}-trigger-${n}`}function y(t,n){return`${t}-content-${n}`}var N=l.forwardRef(({value:t,defaultValue:n,onValueChange:r,orientation:o="horizontal",activationMode:a="automatic",disabled:e=!1,items:i,renderPanel:d,loop:s,children:b,...c},M)=>{let k=l.useRef({previousValue:null,reason:"programmatic"}),[I,S]=le({prop:t,defaultProp:n,onChange:u=>{r?.({value:u,...k.current})}}),H=l.useId(),[F,K]=l.useState(null),B=l.useRef(!1),[A,O]=l.useState(()=>new Set),$=l.useCallback((u,T)=>{O(R=>{if(R.has(u)===T)return R;let h=new Set(R);return T?h.add(u):h.delete(u),h})},[]);return P(de,{baseId:H,value:I,onValueChange:(u,T)=>{k.current={previousValue:I??null,reason:T},S(u)},orientation:o,activationMode:a,disabled:e,arrowNavigating:B,mountedContentValues:A,setContentMounted:$,firstEnabledValue:F,setFirstEnabledValue:K,children:P(ie.div,{"data-orientation":o,"data-disabled":e?"":void 0,...c,...se("tabs","root",c.className),ref:M,children:b??P(L,{items:i,renderPanel:d,loop:s,"aria-label":c["aria-label"],"aria-labelledby":c["aria-labelledby"]})})})});N.displayName="Tabs";export{N as Tabs,E as TabsContent,w as TabsList,de as TabsProvider,x as TabsTrigger,y as makeContentId,v as makeTriggerId,m as useTabsContext};

package/dist/tabs/TabsAnatomy.d.cts

@@ -0,0 +1,15 @@
+import type * as React from 'react';
+import type { TabsItem } from './types.cjs';
+/**
+ * The anatomy a {@link Tabs} draws from `items`: a `TabsList` of one `TabsTrigger` per
+ * entry, then one `TabsContent` panel each.
+ *
+ * @internal
+ */
+export declare const TabsAnatomy: ({ items, renderPanel, loop, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, }: {
+    items?: TabsItem[];
+    renderPanel?: (item: TabsItem) => React.ReactNode;
+    loop?: boolean;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+}) => React.JSX.Element;

package/dist/tabs/TabsAnatomy.d.ts

@@ -0,0 +1,15 @@
+import type * as React from 'react';
+import type { TabsItem } from './types.js';
+/**
+ * The anatomy a {@link Tabs} draws from `items`: a `TabsList` of one `TabsTrigger` per
+ * entry, then one `TabsContent` panel each.
+ *
+ * @internal
+ */
+export declare const TabsAnatomy: ({ items, renderPanel, loop, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, }: {
+    items?: TabsItem[];
+    renderPanel?: (item: TabsItem) => React.ReactNode;
+    loop?: boolean;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+}) => React.JSX.Element;

package/dist/tabs/TabsContent.d.cts

@@ -4,7 +4,8 @@ import type { TabsContentProps } from './types.cjs';
  * Panel shown when its `value` matches the parent `Tabs`' selected value.
  * Renders `role="tabpanel"`, is unmounted while inactive unless `forceMount`
  * is set, and is a focusable landmark (`tabIndex={0}`) so keyboard users can
- * tab from the trigger straight into the panel's content.
+ * tab from the trigger straight into the panel's content — pass
+ * `tabIndex={-1}` for a panel whose own content is already focusable.
  *
  * @example
  * ```tsx

package/dist/tabs/TabsContent.d.ts

@@ -4,7 +4,8 @@ import type { TabsContentProps } from './types.js';
  * Panel shown when its `value` matches the parent `Tabs`' selected value.
  * Renders `role="tabpanel"`, is unmounted while inactive unless `forceMount`
  * is set, and is a focusable landmark (`tabIndex={0}`) so keyboard users can
- * tab from the trigger straight into the panel's content.
+ * tab from the trigger straight into the panel's content — pass
+ * `tabIndex={-1}` for a panel whose own content is already focusable.
  *
  * @example
  * ```tsx

package/dist/tabs/TabsTrigger.d.cts

@@ -2,8 +2,8 @@ import * as React from 'react';
 import type { TabsTriggerProps } from './types.cjs';
 /**
  * A single tab button. Renders `role="tab"` with `aria-selected` and
- * `data-state="active" | "inactive"` for styling; selecting it (click, or
- * focus under `activationMode="automatic"`) updates the parent `Tabs`' value.
+ * `data-state="active" | "inactive"`. Selecting it (click or focus under `activationMode="automatic"`)
+ * updates the parent `Tabs`' value.
  *
  * @example
  * ```tsx

package/dist/tabs/TabsTrigger.d.ts

@@ -2,8 +2,8 @@ import * as React from 'react';
 import type { TabsTriggerProps } from './types.js';
 /**
  * A single tab button. Renders `role="tab"` with `aria-selected` and
- * `data-state="active" | "inactive"` for styling; selecting it (click, or
- * focus under `activationMode="automatic"`) updates the parent `Tabs`' value.
+ * `data-state="active" | "inactive"`. Selecting it (click or focus under `activationMode="automatic"`)
+ * updates the parent `Tabs`' value.
  *
  * @example
  * ```tsx

package/dist/tabs/index.d.cts

@@ -1,5 +1,2 @@
-export * from './Tabs.cjs';
-export { TabsList } from './TabsList.cjs';
-export { TabsTrigger } from './TabsTrigger.cjs';
-export { TabsContent } from './TabsContent.cjs';
-export type { TabsProps, TabsListProps, TabsTriggerProps, TabsContentProps } from './types.cjs';
+export { Tabs } from './Tabs.cjs';
+export type { TabsProps, TabsItem, TabsChangeReason, TabsValueChangeDetail } from './types.cjs';

package/dist/tabs/index.d.ts

@@ -1,5 +1,2 @@
-export * from './Tabs.js';
-export { TabsList } from './TabsList.js';
-export { TabsTrigger } from './TabsTrigger.js';
-export { TabsContent } from './TabsContent.js';
-export type { TabsProps, TabsListProps, TabsTriggerProps, TabsContentProps } from './types.js';
+export { Tabs } from './Tabs.js';
+export type { TabsProps, TabsItem, TabsChangeReason, TabsValueChangeDetail } from './types.js';

package/dist/tabs/primitives.d.cts

@@ -0,0 +1,22 @@
+/**
+ * Primitives for `Tabs` — manual composition escape hatch.
+ *
+ * @example
+ * ```tsx
+ * import { Tabs, TabsList, TabsTrigger, TabsContent } from '@skdx/react/primitives/tabs';
+ *
+ * <Tabs defaultValue="account">
+ *   <TabsList aria-label="Manage account">
+ *     <TabsTrigger value="account">Account</TabsTrigger>
+ *     <TabsTrigger value="password">Password</TabsTrigger>
+ *   </TabsList>
+ *   <TabsContent value="account" forceMount>Account settings…</TabsContent>
+ *   <TabsContent value="password" forceMount>Password settings…</TabsContent>
+ * </Tabs>
+ * ```
+ */
+export { Tabs, makeTriggerId, makeContentId } from './Tabs.cjs';
+export { TabsList } from './TabsList.cjs';
+export { TabsTrigger } from './TabsTrigger.cjs';
+export { TabsContent } from './TabsContent.cjs';
+export type { TabsProps, TabsListProps, TabsTriggerProps, TabsContentProps } from './types.cjs';

package/dist/tabs/primitives.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Primitives for `Tabs` — manual composition escape hatch.
+ *
+ * @example
+ * ```tsx
+ * import { Tabs, TabsList, TabsTrigger, TabsContent } from '@skdx/react/primitives/tabs';
+ *
+ * <Tabs defaultValue="account">
+ *   <TabsList aria-label="Manage account">
+ *     <TabsTrigger value="account">Account</TabsTrigger>
+ *     <TabsTrigger value="password">Password</TabsTrigger>
+ *   </TabsList>
+ *   <TabsContent value="account" forceMount>Account settings…</TabsContent>
+ *   <TabsContent value="password" forceMount>Password settings…</TabsContent>
+ * </Tabs>
+ * ```
+ */
+export { Tabs, makeTriggerId, makeContentId } from './Tabs.js';
+export { TabsList } from './TabsList.js';
+export { TabsTrigger } from './TabsTrigger.js';
+export { TabsContent } from './TabsContent.js';
+export type { TabsProps, TabsListProps, TabsTriggerProps, TabsContentProps } from './types.js';

package/dist/tabs/types.d.cts

@@ -1,11 +1,60 @@
+import type * as React from 'react';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+/**
+ * Why the selected tab changed: keyboard arrow/Home/End, pointer click/tap,
+ * or programmatic value write.
+ */
+export type TabsChangeReason = 'keyboard' | 'pointer' | 'programmatic';
+/**
+ * The payload `onValueChange` receives.
+ *
+ * Both ends of the change, plus what drove it. `previousValue` is here because
+ * a consumer reacting to a tab switch almost always needs the tab it came
+ * *from* — and in a controlled `Tabs` the old value is already gone by the time
+ * the handler runs. `reason` is here because `value-change` fires identically
+ * whether the user arrowed onto a tab or clicked it, and a consumer that wants
+ * to scroll the new panel into view only for keyboard navigation has no other
+ * way to tell.
+ */
+export interface TabsValueChangeDetail {
+    /** The tab that is now selected. */
+    value: string;
+    /** The tab selected before this change, or `null` when nothing was. */
+    previousValue: string | null;
+    /**
+     * What drove the change: `'pointer'` for a click or tap, `'keyboard'` for
+     * Enter/Space and for the focus an arrow key, Home or End moved. React never
+     * reports `'programmatic'` — a controlled `value` write is the consumer's own
+     * state moving, and echoing it back as an event would loop.
+     */
+    reason: TabsChangeReason;
+}
 /** @internal Shared state distributed from {@link Tabs} to its parts via context. Not part of the public API. */
 export interface TabsContextValue {
     baseId: string;
     value?: string;
-    onValueChange: (value: string) => void;
+    /** Selects `value` and reports it, tagged with what drove the selection. */
+    onValueChange: (value: string, reason: TabsChangeReason) => void;
     orientation: 'horizontal' | 'vertical';
     activationMode: 'automatic' | 'manual';
+    /** The root's `disabled`, OR-ed into every trigger's own. */
+    disabled: boolean;
+    /**
+     * Whether the focus currently being dispatched was moved by the tablist's own
+     * Arrow/Home/End handling. Read by a trigger's focus handler so automatic
+     * activation fires for a keyboard *browse* and not for every focus event —
+     * see `TabsList`'s keydown handler, which raises and lowers it around the
+     * synchronous `focus()` call.
+     */
+    arrowNavigating: React.MutableRefObject<boolean>;
+    /**
+     * The values whose panels are currently in the DOM. A trigger publishes
+     * `aria-controls` only for a panel that is actually there, and a panel is
+     * unmounted while inactive unless it sets `forceMount` — which the trigger
+     * cannot see, so the panels report themselves.
+     */
+    mountedContentValues: ReadonlySet<string>;
+    setContentMounted: (value: string, mounted: boolean) => void;
     /**
      * The tablist's single tab stop, resolved against the DOM by `TabsList`: the
      * selected tab while it is mounted and enabled, else the first enabled tab.
@@ -14,8 +63,48 @@ export interface TabsContextValue {
     firstEnabledValue: string | null;
     setFirstEnabledValue: (value: string | null) => void;
 }
+/** One entry of {@link TabsProps.items} — a tab and the panel it reveals. */
+export interface TabsItem {
+    /** Unique identifier, matched against the selected value and shared by the derived trigger and panel. */
+    value: string;
+    /** Text rendered inside the derived `TabsTrigger`. */
+    label: React.ReactNode;
+    /**
+     * The panel body revealed when this tab is selected. Ignored when
+     * `renderPanel` is given.
+     * @default undefined — the panel renders empty.
+     */
+    content?: React.ReactNode;
+    /**
+     * Excludes this tab from selection, arrow-key navigation and the tab order.
+     * @default false
+     */
+    disabled?: boolean;
+}
 /** Props for the {@link Tabs} root. */
 export interface TabsProps extends PrimitivePropsWithRef<'div'> {
+    /**
+     * The tabs the interface renders — one derived `TabsTrigger` inside a derived
+     * `TabsList`, and one derived `TabsContent` panel each. Ignored when `children` is
+     * given, which switches to full manual composition.
+     * @default undefined — nothing is derived; compose the list and panels as `children`.
+     */
+    items?: TabsItem[];
+    /**
+     * Renders a derived panel's body in place of the entry's `content` — a form,
+     * a lazily-loaded subtree, anything the datum cannot hold. The panel element
+     * itself, with its `role`, ids and `hidden` handling, stays the library's.
+     * @default undefined — the entry's `content` is rendered.
+     */
+    renderPanel?: (item: TabsItem) => React.ReactNode;
+    /**
+     * Whether arrow-key navigation wraps from the last trigger back to the first
+     * (and vice versa). Forwarded to the derived `TabsList`, which is the element
+     * that owns roving focus; ignored when `children` is given, where the prop
+     * belongs on your own `TabsList`.
+     * @default true
+     */
+    loop?: boolean;
     /**
      * Selected tab's value, for controlled usage. Pair with `onValueChange`.
      * @default undefined — uncontrolled, tracks its own selected value internally.
@@ -27,10 +116,12 @@ export interface TabsProps extends PrimitivePropsWithRef<'div'> {
      */
     defaultValue?: string;
     /**
-     * Fires with the new value whenever the selected tab changes, controlled or not.
+     * Fires whenever the selected tab changes, controlled or not, with the new
+     * value, the one it replaced and the reason it changed. Selecting the tab
+     * already selected emits nothing.
      * @default undefined — no-op.
      */
-    onValueChange?: (value: string) => void;
+    onValueChange?: (detail: TabsValueChangeDetail) => void;
     /**
      * Layout axis, exposed as `data-orientation` and used to pick Arrow Left/Right
      * vs Arrow Up/Down for keyboard navigation between triggers.
@@ -41,9 +132,27 @@ export interface TabsProps extends PrimitivePropsWithRef<'div'> {
      * `'automatic'` selects a tab as soon as it receives focus (arrow-key browsing).
      * `'manual'` only selects on Enter/Space, letting users tab through triggers
      * without changing panels — useful when panel content is expensive to render.
+     *
+     * Pairing rule: `'automatic'` is only appropriate when a panel renders
+     * without noticeable latency, and `TabsContent` unmounts every inactive panel
+     * by default. If your panels are expensive, either set
+     * `activationMode="manual"` or set `forceMount` on every `TabsContent` — an
+     * arrow-key browse from the first tab to the sixth otherwise mounts and
+     * unmounts four subtrees on the way past.
+     *
+     * Selection follows focus only for focus that the tablist's own
+     * Arrow/Home/End handling moved, or a pointer press on the trigger. Restoring
+     * focus to a trigger — a dialog closing back onto the tab that opened it —
+     * never changes the selection.
      * @default 'automatic'
      */
     activationMode?: 'automatic' | 'manual';
+    /**
+     * Disables every trigger in the tabbed interface. OR-ed with each
+     * `TabsTrigger`'s own `disabled`, never overridden.
+     * @default false
+     */
+    disabled?: boolean;
 }
 /** Props for {@link TabsList}, the roving-focus container for `TabsTrigger`s. */
 export interface TabsListProps extends PrimitivePropsWithRef<'div'> {
@@ -58,6 +167,14 @@ export interface TabsListProps extends PrimitivePropsWithRef<'div'> {
 export interface TabsTriggerProps extends PrimitivePropsWithRef<'button'> {
     /** Unique identifier matched against a sibling `TabsContent`'s `value`. */
     value: string;
+    /**
+     * Excludes this trigger from selection and arrow-key navigation, and keeps it
+     * out of the tab order — it can never hold the tablist's single tab stop.
+     * OR-ed with the root's `disabled`, never overridden. Reflected as `data-disabled`
+     * and `tabIndex` in addition to `disabled`.
+     * @default false
+     */
+    disabled?: boolean;
 }
 /** Props for a single {@link TabsContent} panel. */
 export interface TabsContentProps extends PrimitivePropsWithRef<'div'> {
@@ -70,4 +187,16 @@ export interface TabsContentProps extends PrimitivePropsWithRef<'div'> {
      * @default false
      */
     forceMount?: boolean;
+    /**
+     * Whether the panel itself is a tab stop.
+     *
+     * APG asks for `tabindex="0"` on a tabpanel *only when the panel contains no
+     * focusable elements*, so that a keyboard user can still reach the revealed
+     * content. Pass `-1` for a panel whose own content is focusable — a form, a
+     * link list — or you put an extra, contentless stop in front of it. Detecting
+     * focusable descendants is a DOM scan a headless component must not run on
+     * every render, so the condition is yours to state.
+     * @default 0
+     */
+    tabIndex?: 0 | -1;
 }

package/dist/tabs/types.d.ts

@@ -1,11 +1,60 @@
+import type * as React from 'react';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+/**
+ * Why the selected tab changed: keyboard arrow/Home/End, pointer click/tap,
+ * or programmatic value write.
+ */
+export type TabsChangeReason = 'keyboard' | 'pointer' | 'programmatic';
+/**
+ * The payload `onValueChange` receives.
+ *
+ * Both ends of the change, plus what drove it. `previousValue` is here because
+ * a consumer reacting to a tab switch almost always needs the tab it came
+ * *from* — and in a controlled `Tabs` the old value is already gone by the time
+ * the handler runs. `reason` is here because `value-change` fires identically
+ * whether the user arrowed onto a tab or clicked it, and a consumer that wants
+ * to scroll the new panel into view only for keyboard navigation has no other
+ * way to tell.
+ */
+export interface TabsValueChangeDetail {
+    /** The tab that is now selected. */
+    value: string;
+    /** The tab selected before this change, or `null` when nothing was. */
+    previousValue: string | null;
+    /**
+     * What drove the change: `'pointer'` for a click or tap, `'keyboard'` for
+     * Enter/Space and for the focus an arrow key, Home or End moved. React never
+     * reports `'programmatic'` — a controlled `value` write is the consumer's own
+     * state moving, and echoing it back as an event would loop.
+     */
+    reason: TabsChangeReason;
+}
 /** @internal Shared state distributed from {@link Tabs} to its parts via context. Not part of the public API. */
 export interface TabsContextValue {
     baseId: string;
     value?: string;
-    onValueChange: (value: string) => void;
+    /** Selects `value` and reports it, tagged with what drove the selection. */
+    onValueChange: (value: string, reason: TabsChangeReason) => void;
     orientation: 'horizontal' | 'vertical';
     activationMode: 'automatic' | 'manual';
+    /** The root's `disabled`, OR-ed into every trigger's own. */
+    disabled: boolean;
+    /**
+     * Whether the focus currently being dispatched was moved by the tablist's own
+     * Arrow/Home/End handling. Read by a trigger's focus handler so automatic
+     * activation fires for a keyboard *browse* and not for every focus event —
+     * see `TabsList`'s keydown handler, which raises and lowers it around the
+     * synchronous `focus()` call.
+     */
+    arrowNavigating: React.MutableRefObject<boolean>;
+    /**
+     * The values whose panels are currently in the DOM. A trigger publishes
+     * `aria-controls` only for a panel that is actually there, and a panel is
+     * unmounted while inactive unless it sets `forceMount` — which the trigger
+     * cannot see, so the panels report themselves.
+     */
+    mountedContentValues: ReadonlySet<string>;
+    setContentMounted: (value: string, mounted: boolean) => void;
     /**
      * The tablist's single tab stop, resolved against the DOM by `TabsList`: the
      * selected tab while it is mounted and enabled, else the first enabled tab.
@@ -14,8 +63,48 @@ export interface TabsContextValue {
     firstEnabledValue: string | null;
     setFirstEnabledValue: (value: string | null) => void;
 }
+/** One entry of {@link TabsProps.items} — a tab and the panel it reveals. */
+export interface TabsItem {
+    /** Unique identifier, matched against the selected value and shared by the derived trigger and panel. */
+    value: string;
+    /** Text rendered inside the derived `TabsTrigger`. */
+    label: React.ReactNode;
+    /**
+     * The panel body revealed when this tab is selected. Ignored when
+     * `renderPanel` is given.
+     * @default undefined — the panel renders empty.
+     */
+    content?: React.ReactNode;
+    /**
+     * Excludes this tab from selection, arrow-key navigation and the tab order.
+     * @default false
+     */
+    disabled?: boolean;
+}
 /** Props for the {@link Tabs} root. */
 export interface TabsProps extends PrimitivePropsWithRef<'div'> {
+    /**
+     * The tabs the interface renders — one derived `TabsTrigger` inside a derived
+     * `TabsList`, and one derived `TabsContent` panel each. Ignored when `children` is
+     * given, which switches to full manual composition.
+     * @default undefined — nothing is derived; compose the list and panels as `children`.
+     */
+    items?: TabsItem[];
+    /**
+     * Renders a derived panel's body in place of the entry's `content` — a form,
+     * a lazily-loaded subtree, anything the datum cannot hold. The panel element
+     * itself, with its `role`, ids and `hidden` handling, stays the library's.
+     * @default undefined — the entry's `content` is rendered.
+     */
+    renderPanel?: (item: TabsItem) => React.ReactNode;
+    /**
+     * Whether arrow-key navigation wraps from the last trigger back to the first
+     * (and vice versa). Forwarded to the derived `TabsList`, which is the element
+     * that owns roving focus; ignored when `children` is given, where the prop
+     * belongs on your own `TabsList`.
+     * @default true
+     */
+    loop?: boolean;
     /**
      * Selected tab's value, for controlled usage. Pair with `onValueChange`.
      * @default undefined — uncontrolled, tracks its own selected value internally.
@@ -27,10 +116,12 @@ export interface TabsProps extends PrimitivePropsWithRef<'div'> {
      */
     defaultValue?: string;
     /**
-     * Fires with the new value whenever the selected tab changes, controlled or not.
+     * Fires whenever the selected tab changes, controlled or not, with the new
+     * value, the one it replaced and the reason it changed. Selecting the tab
+     * already selected emits nothing.
      * @default undefined — no-op.
      */
-    onValueChange?: (value: string) => void;
+    onValueChange?: (detail: TabsValueChangeDetail) => void;
     /**
      * Layout axis, exposed as `data-orientation` and used to pick Arrow Left/Right
      * vs Arrow Up/Down for keyboard navigation between triggers.
@@ -41,9 +132,27 @@ export interface TabsProps extends PrimitivePropsWithRef<'div'> {
      * `'automatic'` selects a tab as soon as it receives focus (arrow-key browsing).
      * `'manual'` only selects on Enter/Space, letting users tab through triggers
      * without changing panels — useful when panel content is expensive to render.
+     *
+     * Pairing rule: `'automatic'` is only appropriate when a panel renders
+     * without noticeable latency, and `TabsContent` unmounts every inactive panel
+     * by default. If your panels are expensive, either set
+     * `activationMode="manual"` or set `forceMount` on every `TabsContent` — an
+     * arrow-key browse from the first tab to the sixth otherwise mounts and
+     * unmounts four subtrees on the way past.
+     *
+     * Selection follows focus only for focus that the tablist's own
+     * Arrow/Home/End handling moved, or a pointer press on the trigger. Restoring
+     * focus to a trigger — a dialog closing back onto the tab that opened it —
+     * never changes the selection.
      * @default 'automatic'
      */
     activationMode?: 'automatic' | 'manual';
+    /**
+     * Disables every trigger in the tabbed interface. OR-ed with each
+     * `TabsTrigger`'s own `disabled`, never overridden.
+     * @default false
+     */
+    disabled?: boolean;
 }
 /** Props for {@link TabsList}, the roving-focus container for `TabsTrigger`s. */
 export interface TabsListProps extends PrimitivePropsWithRef<'div'> {
@@ -58,6 +167,14 @@ export interface TabsListProps extends PrimitivePropsWithRef<'div'> {
 export interface TabsTriggerProps extends PrimitivePropsWithRef<'button'> {
     /** Unique identifier matched against a sibling `TabsContent`'s `value`. */
     value: string;
+    /**
+     * Excludes this trigger from selection and arrow-key navigation, and keeps it
+     * out of the tab order — it can never hold the tablist's single tab stop.
+     * OR-ed with the root's `disabled`, never overridden. Reflected as `data-disabled`
+     * and `tabIndex` in addition to `disabled`.
+     * @default false
+     */
+    disabled?: boolean;
 }
 /** Props for a single {@link TabsContent} panel. */
 export interface TabsContentProps extends PrimitivePropsWithRef<'div'> {
@@ -70,4 +187,16 @@ export interface TabsContentProps extends PrimitivePropsWithRef<'div'> {
      * @default false
      */
     forceMount?: boolean;
+    /**
+     * Whether the panel itself is a tab stop.
+     *
+     * APG asks for `tabindex="0"` on a tabpanel *only when the panel contains no
+     * focusable elements*, so that a keyboard user can still reach the revealed
+     * content. Pass `-1` for a panel whose own content is focusable — a form, a
+     * link list — or you put an extra, contentless stop in front of it. Detecting
+     * focusable descendants is a DOM scan a headless component must not run on
+     * every render, so the condition is yours to state.
+     * @default 0
+     */
+    tabIndex?: 0 | -1;
 }

package/dist/tag/Tag.cjs

@@ -1 +1 @@
-"use strict";var S=Object.create;var l=Object.defineProperty;var G=Object.getOwnPropertyDescriptor;var H=Object.getOwnPropertyNames;var L=Object.getPrototypeOf,M=Object.prototype.hasOwnProperty;var B=(e,t)=>{for(var a in t)l(e,a,{get:t[a],enumerable:!0})},y=(e,t,a,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of H(t))!M.call(e,o)&&o!==a&&l(e,o,{get:()=>t[o],enumerable:!(s=G(t,o))||s.enumerable});return e};var x=(e,t,a)=>(a=e!=null?S(L(e)):{},y(t||!e||!e.__esModule?l(a,"default",{value:e,enumerable:!0}):a,e)),F=e=>y(l({},"__esModule",{value:!0}),e);var V={};B(V,{Tag:()=>c,TagDelete:()=>T});module.exports=F(V);var r=x(require("react"),1),d=require("../tag-group/TagGroup.cjs"),k=require("../utils/composeRefs.cjs"),w=require("../utils/createContext.cjs"),R=require("../utils/part.cjs"),n=require("../utils/primitive.cjs"),f=require("react/jsx-runtime"),[K,P]=(0,w.createSafeContext)("Tag"),c=r.forwardRef(({index:e,value:t="",disabled:a=!1,onDelete:s,...o},E)=>{let m=(0,d.useTagGroupContext)("Tag"),i=a||m.disabled,h=r.useRef(null),N=(0,k.useComposedRefs)(E,h),{register:b,setActiveIndex:u}=m;r.useEffect(()=>b(),[b]);let v=r.useCallback(()=>{i||!s||(u((0,d.focusTagNeighbor)(h.current,e)),s())},[i,s,u,e]);return(0,f.jsx)(K,{value:t,disabled:i,remove:v,children:(0,f.jsx)(n.Primitive.span,{role:"listitem","data-skdx-tag":"","data-disabled":i?"":void 0,tabIndex:m.tabStopIndex===e?0:-1,...o,...(0,R.skdxPart)("tag","root",o.className),ref:N,onFocus:(0,n.composeEventHandlers)(o.onFocus,()=>u(e)),onKeyDown:(0,n.composeEventHandlers)(o.onKeyDown,g=>{g.key!=="Delete"&&g.key!=="Backspace"||(g.preventDefault(),v())})})})});c.displayName="Tag";var C=x(require("react"),1),D=require("../utils/part.cjs"),p=require("../utils/primitive.cjs");var I=require("react/jsx-runtime"),T=C.forwardRef((e,t)=>{let a=P("TagDelete");return(0,I.jsx)(p.Primitive.button,{type:"button","aria-label":`Remove ${a.value}`.trim(),disabled:a.disabled,"data-disabled":a.disabled?"":void 0,tabIndex:-1,...e,...(0,D.skdxPart)("tag","delete",e.className),ref:t,onClick:(0,p.composeEventHandlers)(e.onClick,()=>{a.remove()})})});T.displayName="TagDelete";0&&(module.exports={Tag,TagDelete});
+"use strict";var oe=Object.create;var c=Object.defineProperty;var re=Object.getOwnPropertyDescriptor;var ne=Object.getOwnPropertyNames;var se=Object.getPrototypeOf,ie=Object.prototype.hasOwnProperty;var le=(t,e)=>{for(var a in e)c(t,a,{get:e[a],enumerable:!0})},I=(t,e,a,m)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of ne(e))!ie.call(t,i)&&i!==a&&c(t,i,{get:()=>e[i],enumerable:!(m=re(e,i))||m.enumerable});return t};var f=(t,e,a)=>(a=t!=null?oe(se(t)):{},I(e||!t||!t.__esModule?c(a,"default",{value:t,enumerable:!0}):a,t)),de=t=>I(c({},"__esModule",{value:!0}),t);var pe={};le(pe,{Tag:()=>P,TagAnatomy:()=>L,TagDelete:()=>b,TagDeleteIcon:()=>q,TagLabel:()=>T,TagLeading:()=>v,TagProvider:()=>J,useTagContext:()=>l});module.exports=de(pe);var s=f(require("react"),1),x=require("../tag-group/TagGroup.cjs"),O=require("../utils/composeRefs.cjs"),z=require("../utils/createContext.cjs"),Y=require("../utils/liveAnnouncer.cjs"),_=require("../utils/part.cjs"),p=require("../utils/primitive.cjs");var S=f(require("react"),1),M=require("../utils/part.cjs"),h=require("../utils/primitive.cjs");var H=require("react/jsx-runtime"),b=S.forwardRef((t,e)=>{let a=l("TagDelete");if(!a.grouped)throw new Error("[skandadx] `TagDelete` requires its `Tag` to be inside a `TagGroup` \u2014 a standalone `Tag` has no group to remove it from.");return(0,H.jsx)(h.Primitive.button,{type:"button","aria-label":`${a.deleteLabel} ${a.label}`.trim(),disabled:a.disabled,"data-disabled":a.disabled?"":void 0,tabIndex:-1,...t,...(0,M.skdxPart)("tag","delete",t.className),ref:e,onClick:(0,h.composeEventHandlers)(t.onClick,()=>{a.remove()})})});b.displayName="TagDelete";var G=f(require("react"),1),A=require("../utils/part.cjs"),B=require("../utils/primitive.cjs");var K=require("react/jsx-runtime"),T=G.forwardRef((t,e)=>(l("TagLabel"),(0,K.jsx)(B.Primitive.span,{...t,...(0,A.skdxPart)("tag","label",t.className),ref:e})));T.displayName="TagLabel";var W=f(require("react"),1),U=require("../utils/part.cjs"),V=require("../utils/primitive.cjs");var $=require("react/jsx-runtime"),v=W.forwardRef((t,e)=>(l("TagLeading"),(0,$.jsx)(V.Primitive.span,{...t,...(0,U.skdxPart)("tag","leading",t.className),ref:e})));v.displayName="TagLeading";var o=require("react/jsx-runtime");function q(){return(0,o.jsx)("svg",{viewBox:"0 0 16 16",width:"1em",height:"1em",fill:"none","aria-hidden":"true",focusable:"false",children:(0,o.jsx)("path",{d:"M4 4l8 8M12 4l-8 8",stroke:"currentColor",strokeWidth:"1.5",strokeLinecap:"round"})})}function L({label:t,leading:e,deletable:a}){return(0,o.jsxs)(o.Fragment,{children:[e?(0,o.jsx)(v,{children:e}):null,(0,o.jsx)(T,{children:t}),a?(0,o.jsx)(b,{children:(0,o.jsx)(q,{})}):null]})}var y=require("react/jsx-runtime"),F=["Delete","Backspace"],[J,l]=(0,z.createSafeContext)("Tag"),P=s.forwardRef(({as:t="span",index:e,label:a,selected:m=!1,disabled:i=!1,onDelete:w,leading:Q,deletable:X=!1,deleteLabel:Z="Remove",children:j,...u},ee)=>{let r=(0,x.useOptionalTagGroupContext)(),d=a??"",g=i||(r?.disabled??!1),E=s.useRef(null),te=(0,O.useComposedRefs)(ee,E),k=r?.register,R=r?.setActiveIndex,D=r?.onTagRemoved;s.useEffect(()=>{if(!(!k||e===void 0))return k(e)},[k,e]);let C=s.useCallback(()=>{if(g||!w||!r||e===void 0)return;let n=(0,x.resolveTagNeighbor)(E.current,e),N=new CustomEvent("delete",{cancelable:!0,detail:null});w(N),!N.defaultPrevented&&(n.target?.focus(),R?.(n.index),D?.({label:d,index:e}),d&&(0,Y.announce)(`${d} removed`))},[g,w,r,R,D,e,d]),ae=p.Primitive[t];return(0,y.jsx)(J,{label:d,deleteLabel:Z,disabled:g,selected:m,grouped:r!==void 0,remove:C,children:(0,y.jsx)(ae,{role:r?"listitem":void 0,"data-skdx-tag":"","aria-disabled":g?!0:void 0,"data-disabled":g?"":void 0,"data-selected":m?"":void 0,tabIndex:r?r.tabStopIndex===e?0:-1:void 0,...u,...(0,_.skdxPart)("tag","root",u.className),ref:te,onFocus:(0,p.composeEventHandlers)(u.onFocus,()=>{e!==void 0&&R?.(e)}),onKeyDown:(0,p.composeEventHandlers)(u.onKeyDown,n=>{F.includes(n.key)&&n.preventDefault()}),onKeyUp:(0,p.composeEventHandlers)(u.onKeyUp,n=>{F.includes(n.key)&&(n.preventDefault(),C())}),children:j??(0,y.jsx)(L,{label:d,leading:Q,deletable:X})})})});P.displayName="Tag";0&&(module.exports={Tag,TagAnatomy,TagDelete,TagDeleteIcon,TagLabel,TagLeading,TagProvider,useTagContext});