@skdx/react 0.27.0 → 0.29.0

package/dist/tabs/types.d.ts

@@ -1,49 +1,110 @@
+import type * as React from 'react';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
-/** @internal Shared state distributed from {@link Tabs} to its parts via context. Not part of the public API. */
+/** Why the selected tab changed: keyboard, pointer, or programmatic value write. */
+export type TabsChangeReason = 'keyboard' | 'pointer' | 'programmatic';
+/** Payload passed to `onValueChange`: the old value, the new value, and what caused the change. */
+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 click/tap or keyboard activation/navigation. */
+    reason: TabsChangeReason;
+}
+/** @internal Shared state distributed from {@link Tabs} to its parts via context. */
 export interface TabsContextValue {
     baseId: string;
-    value?: string;
-    onValueChange: (value: string) => void;
+    value?: string | undefined;
+    /** 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 focus was moved by the tablist's own Arrow/Home/End handling, so
+     * automatic activation ignores focus events from anywhere else.
+     */
+    arrowNavigatingRef: React.RefObject<boolean>;
     /**
-     * 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.
-     * `null` only before that has been resolved, or when every tab is disabled.
+     * Values whose panels are mounted; a trigger publishes `aria-controls` only
+     * for a panel that is actually present, since `forceMount` is invisible to it.
+     */
+    mountedContentValues: ReadonlySet<string>;
+    setContentMounted: (value: string, mounted: boolean) => void;
+    /**
+     * The tablist's single tab stop: the selected tab if mounted and enabled,
+     * else the first enabled tab; `null` until resolved or all disabled.
      */
     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 | undefined;
+    /**
+     * Excludes this tab from selection, arrow-key navigation and the tab order.
+     * @default false
+     */
+    disabled?: boolean | undefined;
+}
 /** Props for the {@link Tabs} root. */
 export interface TabsProps extends PrimitivePropsWithRef<'div'> {
     /**
-     * Selected tab's value, for controlled usage. Pair with `onValueChange`.
+     * The tabs to render as derived triggers and panels; ignored when `children` is given.
+     * @default undefined — nothing is derived; compose the list and panels as `children`.
+     */
+    items?: TabsItem[] | undefined;
+    /**
+     * Renders a derived panel's body in place of the entry's `content`, for content the item data can't hold.
+     * @default undefined — the entry's `content` is rendered.
+     */
+    renderPanel?: ((item: TabsItem) => React.ReactNode) | undefined;
+    /**
+     * Whether arrow-key navigation wraps from the last trigger to the first and back.
+     * @default true
+     */
+    loop?: boolean | undefined;
+    /**
+     * Selected tab's value, for controlled usage; pair with `onValueChange`.
      * @default undefined — uncontrolled, tracks its own selected value internally.
      */
-    value?: string;
+    value?: string | undefined;
     /**
      * Initially selected tab's value, for uncontrolled usage.
      * @default undefined — falls back to the first enabled trigger.
      */
-    defaultValue?: string;
+    defaultValue?: string | undefined;
     /**
-     * Fires with the new value whenever the selected tab changes, controlled or not.
+     * Fires when the selected tab changes, controlled or not, with the new value, the previous value, and the reason.
      * @default undefined — no-op.
      */
-    onValueChange?: (value: string) => void;
+    onValueChange?: ((detail: TabsValueChangeDetail) => void) | undefined;
     /**
      * Layout axis, exposed as `data-orientation` and used to pick Arrow Left/Right
      * vs Arrow Up/Down for keyboard navigation between triggers.
      * @default 'horizontal'
      */
-    orientation?: 'horizontal' | 'vertical';
+    orientation?: 'horizontal' | 'vertical' | undefined;
     /**
-     * `'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.
+     * `'automatic'` selects a tab as soon as it receives focus; `'manual'` only selects on Enter/Space.
      * @default 'automatic'
      */
-    activationMode?: 'automatic' | 'manual';
+    activationMode?: 'automatic' | 'manual' | undefined;
+    /**
+     * Disables every trigger; OR-ed with each `TabsTrigger`'s own `disabled`, never overridden.
+     * @default false
+     */
+    disabled?: boolean | undefined;
 }
 /** Props for {@link TabsList}, the roving-focus container for `TabsTrigger`s. */
 export interface TabsListProps extends PrimitivePropsWithRef<'div'> {
@@ -52,22 +113,30 @@ export interface TabsListProps extends PrimitivePropsWithRef<'div'> {
      * (and vice versa).
      * @default true
      */
-    loop?: boolean;
+    loop?: boolean | undefined;
 }
 /** Props for a single {@link TabsTrigger} button. */
 export interface TabsTriggerProps extends PrimitivePropsWithRef<'button'> {
     /** Unique identifier matched against a sibling `TabsContent`'s `value`. */
     value: string;
+    /**
+     * Excludes this trigger from selection and the tab order; OR-ed with the root's `disabled` and reflected as `data-disabled`.
+     * @default false
+     */
+    disabled?: boolean | undefined;
 }
 /** Props for a single {@link TabsContent} panel. */
 export interface TabsContentProps extends PrimitivePropsWithRef<'div'> {
     /** Unique identifier matched against the `TabsTrigger` that reveals this panel. */
     value: string;
     /**
-     * Keep this panel mounted (hidden via the `hidden` attribute) even while
-     * inactive, instead of unmounting it. Useful for animation libraries that
-     * need the outgoing panel present in the DOM during an exit transition.
+     * Keeps this panel mounted and hidden via the `hidden` attribute instead of unmounting it while inactive.
      * @default false
      */
-    forceMount?: boolean;
+    forceMount?: boolean | undefined;
+    /**
+     * Whether the panel itself is a tab stop; pass `-1` when the panel's own content is already focusable.
+     * @default 0
+     */
+    tabIndex?: 0 | -1 | undefined;
 }

package/dist/tag-group/TagGroup.cjs

@@ -1 +1,2 @@
-"use strict";var S=Object.create;var u=Object.defineProperty;var C=Object.getOwnPropertyDescriptor;var P=Object.getOwnPropertyNames;var k=Object.getPrototypeOf,A=Object.prototype.hasOwnProperty;var L=(t,e)=>{for(var o in e)u(t,o,{get:e[o],enumerable:!0})},T=(t,e,o,a)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of P(e))!A.call(t,r)&&r!==o&&u(t,r,{get:()=>e[r],enumerable:!(a=C(e,r))||a.enumerable});return t};var O=(t,e,o)=>(o=t!=null?S(k(t)):{},T(e||!t||!t.__esModule?u(o,"default",{value:t,enumerable:!0}):o,t)),w=t=>T(u({},"__esModule",{value:!0}),t);var _={};L(_,{TAG_GROUP_SELECTOR:()=>l,TAG_SELECTOR:()=>p,TagGroup:()=>d,focusTagNeighbor:()=>b,useTagGroupContext:()=>R});module.exports=w(_);var n=O(require("react"),1),x=require("../utils/createContext.cjs"),G=require("../utils/part.cjs"),i=require("../utils/primitive.cjs"),h=require("../utils/useRovingFocus.cjs"),g=require("react/jsx-runtime"),l="[data-skdx-tag-group]",p="[data-skdx-tag]",[M,R]=(0,x.createSafeContext)("TagGroup");function b(t,e){let o=t?.closest(l)??null,a=o?Array.from(o.querySelectorAll(p)):[],r=t?a.indexOf(t):-1,s=r===-1?void 0:a[r+1];return(s??a[r-1]??o)?.focus(),s?e:Math.max(e-1,0)}var d=n.forwardRef(({orientation:t="horizontal",loop:e=!0,disabled:o=!1,...a},r)=>{let[s,y]=n.useState(0),[f,m]=n.useState(0),E=(0,h.useRovingFocus)({orientation:t,loop:e,itemSelector:p}),v=n.useCallback(()=>(m(c=>c+1),()=>m(c=>c-1)),[]);return(0,g.jsx)(M,{tabStopIndex:f===0?s:Math.min(s,f-1),setActiveIndex:y,register:v,disabled:o,children:(0,g.jsx)(i.Primitive.div,{role:"list","data-skdx-tag-group":"","data-orientation":t,"data-disabled":o?"":void 0,tabIndex:-1,...a,...(0,G.skdxPart)("tag-group","root",a.className),ref:r,onKeyDown:(0,i.composeEventHandlers)(a.onKeyDown,E)})})});d.displayName="TagGroup";0&&(module.exports={TAG_GROUP_SELECTOR,TAG_SELECTOR,TagGroup,focusTagNeighbor,useTagGroupContext});
+'use client';
+"use strict";var Le=Object.create;var T=Object.defineProperty;var Ee=Object.getOwnPropertyDescriptor;var Ce=Object.getOwnPropertyNames;var Pe=Object.getPrototypeOf,Ne=Object.prototype.hasOwnProperty;var Se=(e,t)=>{for(var o in t)T(e,o,{get:t[o],enumerable:!0})},B=(e,t,o,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of Ce(t))!Ne.call(e,n)&&n!==o&&T(e,n,{get:()=>t[n],enumerable:!(r=Ee(t,n))||r.enumerable});return e};var N=(e,t,o)=>(o=e!=null?Le(Pe(e)):{},B(t||!e||!e.__esModule?T(o,"default",{value:e,enumerable:!0}):o,e)),ke=e=>B(T({},"__esModule",{value:!0}),e);var De={};Se(De,{TAG_GROUP_SELECTOR:()=>x,TAG_SELECTOR:()=>g,TagGroup:()=>k,TagGroupEmpty:()=>ce,TagGroupLabel:()=>oe,TagGroupList:()=>ie,TagGroupProvider:()=>Y,focusTagNeighbor:()=>j,resolveTagNeighbor:()=>S,useOptionalTagGroupContext:()=>Z,useTagGroupContext:()=>p});module.exports=ke(De);var a=N(require("react"),1),V=require("../utils/appearance.cjs"),X=require("../utils/composeRefs.cjs"),$=require("../utils/createContext.cjs"),z=require("../utils/dev-mode.cjs"),Q=require("../utils/part.cjs"),R=require("../utils/primitive.cjs"),W=require("../utils/useRovingFocus.cjs");var F=require("../badge/Badge.cjs"),K=require("../badge/Badge.cjs"),q=require("../badge/Badge.cjs"),l=require("react/jsx-runtime"),J=({tags:e=[],removable:t})=>(0,l.jsx)(l.Fragment,{children:e.map((o,r)=>(0,l.jsxs)(F.Badge,{index:r,label:o.label,disabled:o.disabled,onDelete:t?()=>{}:void 0,children:[o.label,t?(0,l.jsx)(q.BadgeDelete,{children:(0,l.jsx)(K.BadgeDeleteIcon,{})}):null]},o.value))});var b=require("react/jsx-runtime");function U(e,t,o){let r=(e.get(t)??0)+o;r<=0?e.delete(t):e.set(t,r),o===1&&r>1&&(0,z.isDevMode)()&&console.warn(`[skdx] TagGroup: ${r} mounted Tags report index={${t}}. \`index\` must match render order \u2014 pass the array index from the map that produced the tags. Duplicates put more than one tag in the tab order; a gap leaves the group with none.`)}var x="[data-skdx-tag-group]",g="[data-skdx-tag]",[Y,p,Z]=(0,$.createSafeContext)("TagGroup");function S(e,t){let o=e?.closest(x)??null,r=o?Array.from(o.querySelectorAll(g)):[],n=e?r.indexOf(e):-1,c=n===-1?void 0:r[n+1];return{target:c??r[n-1]??o,index:c?t:Math.max(t-1,0)}}function j(e,t){let o=S(e,t);return o.target?.focus(),o.index}var k=({orientation:e="horizontal",loop:t=!0,disabled:o=!1,onRemove:r,tags:n,children:c,ref:de,density:ge,...u})=>{let[D,I]=a.useState(0),[m,M]=a.useState(0),[y,A]=a.useState(void 0),[fe,O]=a.useState(0),Te=(0,W.useRovingFocus)({orientation:e,loop:t,itemSelector:g,scopeSelector:x}),v=a.useRef(null),be=(0,X.useComposedRefs)(de,v),h=a.useRef(null),H=a.useRef(m),Re=a.useCallback(s=>{I(s);let i=v.current,d=i?.ownerDocument.activeElement;i&&d&&i.contains(d)&&(h.current=d)},[]),w=a.useRef(new Map),xe=a.useCallback(s=>(M(i=>i+1),U(w.current,s,1),()=>{M(i=>i-1),U(w.current,s,-1)}),[]),Ge=a.useCallback(s=>(A(s),()=>A(i=>i===s?void 0:i)),[]),ye=a.useCallback(()=>(O(s=>s+1),()=>O(s=>s-1)),[]),ve=a.useCallback(s=>r?.(s),[r]),f=fe>0,he={"aria-label":u["aria-label"],"aria-labelledby":y??u["aria-labelledby"]},L=m===0?D:Math.min(D,m-1);return a.useEffect(()=>{let s=H.current;if(H.current=m,m>=s)return;let i=v.current,d=h.current;if(!i||!d||d.isConnected)return;let _=i.ownerDocument,E=_.activeElement;if(E&&E!==_.body&&E.isConnected)return;h.current=null;let C=Array.from(i.querySelectorAll(g)),P=C[Math.min(L,C.length-1)];(P??i).focus(),P&&I(C.indexOf(P))},[m,L]),(0,b.jsx)(Y,{tabStopIndex:L,setActiveIndex:Re,register:xe,onTagRemoved:ve,count:m,labelId:y,registerLabel:Ge,hasList:f,registerList:ye,labelling:he,orientation:e,disabled:o,children:(0,b.jsx)(R.Primitive.div,{role:f?void 0:"list","data-skdx-tag-group":"","data-orientation":e,"data-disabled":o?"":void 0,tabIndex:-1,...u,"aria-labelledby":f?void 0:y??u["aria-labelledby"],"aria-label":f?void 0:u["aria-label"],...(0,V.appearanceAttrs)({density:ge},u),...(0,Q.skdxPart)("tag-group","root",u.className),ref:be,onKeyDown:(0,R.composeEventHandlers)(u.onKeyDown,Te),children:c??(0,b.jsx)(J,{tags:n,removable:r!==void 0})})})};k.displayName="TagGroup";var G=N(require("react"),1),ee=require("../utils/part.cjs"),te=require("../utils/primitive.cjs");var re=require("react/jsx-runtime"),oe=({ref:e,...t})=>{let o=p("TagGroupLabel"),r=G.useId(),n=t.id??r,{registerLabel:c}=o;return G.useEffect(()=>c(n),[c,n]),(0,re.jsx)(te.Primitive.span,{...t,id:n,...(0,ee.skdxPart)("tag-group","label",t.className),ref:e})};oe.displayName="TagGroupLabel";var ae=N(require("react"),1),ne=require("../utils/part.cjs"),se=require("../utils/primitive.cjs");var ue=require("react/jsx-runtime"),ie=({ref:e,...t})=>{let o=p("TagGroupList"),{registerList:r}=o;return ae.useEffect(()=>r(),[r]),(0,ue.jsx)(se.Primitive.ul,{role:"list","data-orientation":o.orientation,"data-disabled":o.disabled?"":void 0,tabIndex:-1,...o.labelling,...t,...(0,ne.skdxPart)("tag-group","list",t.className),ref:e})};ie.displayName="TagGroupList";var le=require("../utils/part.cjs"),pe=require("../utils/primitive.cjs");var me=require("react/jsx-runtime"),ce=({ref:e,...t})=>p("TagGroupEmpty").count>0?null:(0,me.jsx)(pe.Primitive.div,{...t,...(0,le.skdxPart)("tag-group","empty",t.className),ref:e});ce.displayName="TagGroupEmpty";0&&(module.exports={TAG_GROUP_SELECTOR,TAG_SELECTOR,TagGroup,TagGroupEmpty,TagGroupLabel,TagGroupList,TagGroupProvider,focusTagNeighbor,resolveTagNeighbor,useOptionalTagGroupContext,useTagGroupContext});

package/dist/tag-group/TagGroup.d.cts

@@ -4,72 +4,34 @@ import type { TagGroupContextValue, TagGroupProps } from './types.cjs';
 export declare const TAG_GROUP_SELECTOR = "[data-skdx-tag-group]";
 /** @internal Marks a `Tag`, so the group can discover its items from the DOM without a registration round-trip. */
 export declare const TAG_SELECTOR = "[data-skdx-tag]";
-/**
- * Reads the roving-tabindex state a {@link TagGroup} publishes to the
- * tags inside it: `tabStopIndex`, the index of the tag that currently owns the
- * group's single Tab stop; `setActiveIndex` to claim it; `register` to count
- * mounted tags so that index stays clamped when one is removed; and the
- * group-wide `disabled`.
- *
- * {@link Tag} reads it on mount and whenever it takes focus, under its own name,
- * which is the name the hook puts in the error it throws when a tag is rendered
- * outside a `TagGroup` — a tag with no group has no roving order to join and
- * would silently become a second tab stop. Not part of the public API.
- *
- * @internal
- */
-export declare const TagGroupProvider: {
-    (props: TagGroupContextValue & {
-        children: React.ReactNode;
-    }): React.JSX.Element;
-    displayName: string;
-}, useTagGroupContext: (consumerName: string) => TagGroupContextValue;
-/**
- * Moves focus off the tag at `index` *before* it is removed, and returns the
- * index the newly focused tag will hold once the removal lands.
- *
- * Focus moves to the following tag, or to the preceding one when the removed
- * tag was last, or to the group itself when it was the only one — never to
- * `<body>`, which is what happens by default when the focused element is
- * unmounted and is exactly the thing that makes a list of removable tags
- * unusable from the keyboard.
- *
- * Focus is moved *first* and the removal is left to the caller, so this works
- * the same whether the consumer's state update is synchronous or not: the
- * neighbour element survives the re-render, so it keeps the focus it was
- * given. The returned index is one lower than the neighbour's current one
- * when the removed tag came before it, which is why it can't simply be read
- * back from the DOM afterwards.
- *
- * @internal
- */
+/** @internal Roving-tabindex state shared with `Tag` children: single Tab stop, registration, removal. */
+export declare const TagGroupProvider: React.FC<TagGroupContextValue & {
+    children: React.ReactNode;
+}>, useTagGroupContext: (consumerName: string) => TagGroupContextValue, useOptionalTagGroupContext: () => TagGroupContextValue | undefined;
+/** @internal Where focus goes when the tag at some index is removed, and the index the newly focused tag will then hold. */
+export interface TagNeighbor {
+    /** The element to focus: the following tag, the preceding one, or the group root when this was the only tag. */
+    target: HTMLElement | null;
+    /** The index that element will hold once the removal lands. */
+    index: number;
+}
+/** @internal Resolves the next-focus target when the tag at `index` is removed, without moving focus. */
+export declare function resolveTagNeighbor(tag: HTMLElement | null, index: number): TagNeighbor;
+/** @internal {@link resolveTagNeighbor} and the focus move in one call. */
 export declare function focusTagNeighbor(tag: HTMLElement | null, index: number): number;
 /**
- * A keyboard-navigable list of {@link Tag}s: renders `<div role="list">` and
- * gives the whole group a *single* Tab stop, with the arrow keys (plus
- * `Home`/`End`) moving between tags — the roving-tabindex pattern, so a
- * twenty-tag filter bar costs one Tab press to skip, not twenty.
- *
- * Its real job is the other half of that: when a tag is deleted, focus moves
- * to the neighbouring tag (or to the group when the last one goes) instead of
- * falling back to `<body>`. Deleting three tags in a row therefore takes three
- * `Delete` presses rather than three presses and three trips back through the
- * document.
- *
- * The group holds no tag data — each `Tag` owns its own `onDelete`, so the
- * list can come from anywhere. Name the group with `aria-label` or
- * `aria-labelledby`; `role="list"` has no implicit name.
+ * A roving-tabindex list of tags: single Tab stop, arrow keys navigate between tags.
  *
  * @example
  * ```tsx
- * <TagGroup aria-label="Filters">
- *   {tags.map((tag, index) => (
- *     <Tag key={tag} index={index} value={tag} onDelete={() => remove(tag)}>
- *       {tag}
- *       <TagDelete>×</TagDelete>
- *     </Tag>
- *   ))}
- * </TagGroup>
+ * <TagGroup
+ *   aria-label="Filters"
+ *   tags={filters.map((filter) => ({ value: filter, label: filter }))}
+ *   onRemove={(detail) => remove(detail.label)}
+ * />
  * ```
  */
-export declare const TagGroup: React.ForwardRefExoticComponent<Omit<TagGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const TagGroup: {
+    ({ orientation, loop, disabled, onRemove, tags, children, ref: forwardedRef, density, ...props }: TagGroupProps): React.ReactNode;
+    displayName: string;
+};

package/dist/tag-group/TagGroup.d.ts

@@ -4,72 +4,34 @@ import type { TagGroupContextValue, TagGroupProps } from './types.js';
 export declare const TAG_GROUP_SELECTOR = "[data-skdx-tag-group]";
 /** @internal Marks a `Tag`, so the group can discover its items from the DOM without a registration round-trip. */
 export declare const TAG_SELECTOR = "[data-skdx-tag]";
-/**
- * Reads the roving-tabindex state a {@link TagGroup} publishes to the
- * tags inside it: `tabStopIndex`, the index of the tag that currently owns the
- * group's single Tab stop; `setActiveIndex` to claim it; `register` to count
- * mounted tags so that index stays clamped when one is removed; and the
- * group-wide `disabled`.
- *
- * {@link Tag} reads it on mount and whenever it takes focus, under its own name,
- * which is the name the hook puts in the error it throws when a tag is rendered
- * outside a `TagGroup` — a tag with no group has no roving order to join and
- * would silently become a second tab stop. Not part of the public API.
- *
- * @internal
- */
-export declare const TagGroupProvider: {
-    (props: TagGroupContextValue & {
-        children: React.ReactNode;
-    }): React.JSX.Element;
-    displayName: string;
-}, useTagGroupContext: (consumerName: string) => TagGroupContextValue;
-/**
- * Moves focus off the tag at `index` *before* it is removed, and returns the
- * index the newly focused tag will hold once the removal lands.
- *
- * Focus moves to the following tag, or to the preceding one when the removed
- * tag was last, or to the group itself when it was the only one — never to
- * `<body>`, which is what happens by default when the focused element is
- * unmounted and is exactly the thing that makes a list of removable tags
- * unusable from the keyboard.
- *
- * Focus is moved *first* and the removal is left to the caller, so this works
- * the same whether the consumer's state update is synchronous or not: the
- * neighbour element survives the re-render, so it keeps the focus it was
- * given. The returned index is one lower than the neighbour's current one
- * when the removed tag came before it, which is why it can't simply be read
- * back from the DOM afterwards.
- *
- * @internal
- */
+/** @internal Roving-tabindex state shared with `Tag` children: single Tab stop, registration, removal. */
+export declare const TagGroupProvider: React.FC<TagGroupContextValue & {
+    children: React.ReactNode;
+}>, useTagGroupContext: (consumerName: string) => TagGroupContextValue, useOptionalTagGroupContext: () => TagGroupContextValue | undefined;
+/** @internal Where focus goes when the tag at some index is removed, and the index the newly focused tag will then hold. */
+export interface TagNeighbor {
+    /** The element to focus: the following tag, the preceding one, or the group root when this was the only tag. */
+    target: HTMLElement | null;
+    /** The index that element will hold once the removal lands. */
+    index: number;
+}
+/** @internal Resolves the next-focus target when the tag at `index` is removed, without moving focus. */
+export declare function resolveTagNeighbor(tag: HTMLElement | null, index: number): TagNeighbor;
+/** @internal {@link resolveTagNeighbor} and the focus move in one call. */
 export declare function focusTagNeighbor(tag: HTMLElement | null, index: number): number;
 /**
- * A keyboard-navigable list of {@link Tag}s: renders `<div role="list">` and
- * gives the whole group a *single* Tab stop, with the arrow keys (plus
- * `Home`/`End`) moving between tags — the roving-tabindex pattern, so a
- * twenty-tag filter bar costs one Tab press to skip, not twenty.
- *
- * Its real job is the other half of that: when a tag is deleted, focus moves
- * to the neighbouring tag (or to the group when the last one goes) instead of
- * falling back to `<body>`. Deleting three tags in a row therefore takes three
- * `Delete` presses rather than three presses and three trips back through the
- * document.
- *
- * The group holds no tag data — each `Tag` owns its own `onDelete`, so the
- * list can come from anywhere. Name the group with `aria-label` or
- * `aria-labelledby`; `role="list"` has no implicit name.
+ * A roving-tabindex list of tags: single Tab stop, arrow keys navigate between tags.
  *
  * @example
  * ```tsx
- * <TagGroup aria-label="Filters">
- *   {tags.map((tag, index) => (
- *     <Tag key={tag} index={index} value={tag} onDelete={() => remove(tag)}>
- *       {tag}
- *       <TagDelete>×</TagDelete>
- *     </Tag>
- *   ))}
- * </TagGroup>
+ * <TagGroup
+ *   aria-label="Filters"
+ *   tags={filters.map((filter) => ({ value: filter, label: filter }))}
+ *   onRemove={(detail) => remove(detail.label)}
+ * />
  * ```
  */
-export declare const TagGroup: React.ForwardRefExoticComponent<Omit<TagGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const TagGroup: {
+    ({ orientation, loop, disabled, onRemove, tags, children, ref: forwardedRef, density, ...props }: TagGroupProps): React.ReactNode;
+    displayName: string;
+};

package/dist/tag-group/TagGroup.js

@@ -1 +1,2 @@
-import*as e from"react";import{createSafeContext as x}from"../utils/createContext.js";import{skdxPart as G}from"../utils/part.js";import{composeEventHandlers as h,Primitive as R}from"../utils/primitive.js";import{useRovingFocus as b}from"../utils/useRovingFocus.js";import{jsx as g}from"react/jsx-runtime";var l="[data-skdx-tag-group]",i="[data-skdx-tag]",[y,E]=x("TagGroup");function v(o,s){let r=o?.closest(l)??null,t=r?Array.from(r.querySelectorAll(i)):[],a=o?t.indexOf(o):-1,n=a===-1?void 0:t[a+1];return(n??t[a-1]??r)?.focus(),n?s:Math.max(s-1,0)}var d=e.forwardRef(({orientation:o="horizontal",loop:s=!0,disabled:r=!1,...t},a)=>{let[n,f]=e.useState(0),[p,c]=e.useState(0),m=b({orientation:o,loop:s,itemSelector:i}),T=e.useCallback(()=>(c(u=>u+1),()=>c(u=>u-1)),[]);return g(y,{tabStopIndex:p===0?n:Math.min(n,p-1),setActiveIndex:f,register:T,disabled:r,children:g(R.div,{role:"list","data-skdx-tag-group":"","data-orientation":o,"data-disabled":r?"":void 0,tabIndex:-1,...t,...G("tag-group","root",t.className),ref:a,onKeyDown:h(t.onKeyDown,m)})})});d.displayName="TagGroup";export{l as TAG_GROUP_SELECTOR,i as TAG_SELECTOR,d as TagGroup,v as focusTagNeighbor,E as useTagGroupContext};
+'use client';
+import*as a from"react";import{appearanceAttrs as te}from"../utils/appearance.js";import{useComposedRefs as oe}from"../utils/composeRefs.js";import{createSafeContext as re}from"../utils/createContext.js";import{isDevMode as ae}from"../utils/dev-mode.js";import{skdxPart as ne}from"../utils/part.js";import{composeEventHandlers as se,Primitive as ie}from"../utils/primitive.js";import{useRovingFocus as ue}from"../utils/useRovingFocus.js";import{Badge as W}from"../badge/Badge.js";import{BadgeDeleteIcon as Y}from"../badge/Badge.js";import{BadgeDelete as Z}from"../badge/Badge.js";import{Fragment as ee,jsx as h,jsxs as j}from"react/jsx-runtime";var A=({tags:o=[],removable:t})=>h(ee,{children:o.map((e,r)=>j(W,{index:r,label:e.label,disabled:e.disabled,onDelete:t?()=>{}:void 0,children:[e.label,t?h(Z,{children:h(Y,{})}):null]},e.value))});import{jsx as L}from"react/jsx-runtime";function O(o,t,e){let r=(o.get(t)??0)+e;r<=0?o.delete(t):o.set(t,r),e===1&&r>1&&ae()&&console.warn(`[skdx] TagGroup: ${r} mounted Tags report index={${t}}. \`index\` must match render order \u2014 pass the array index from the map that produced the tags. Duplicates put more than one tag in the tab order; a gap leaves the group with none.`)}var E="[data-skdx-tag-group]",g="[data-skdx-tag]",[le,c,pe]=re("TagGroup");function H(o,t){let e=o?.closest(E)??null,r=e?Array.from(e.querySelectorAll(g)):[],i=o?r.indexOf(o):-1,l=i===-1?void 0:r[i+1];return{target:l??r[i-1]??e,index:l?t:Math.max(t-1,0)}}function ce(o,t){let e=H(o,t);return e.target?.focus(),e.index}var w=({orientation:o="horizontal",loop:t=!0,disabled:e=!1,onRemove:r,tags:i,children:l,ref:B,density:F,...u})=>{let[C,P]=a.useState(0),[p,N]=a.useState(0),[T,S]=a.useState(void 0),[K,k]=a.useState(0),q=ue({orientation:o,loop:t,itemSelector:g,scopeSelector:E}),b=a.useRef(null),J=oe(B,b),R=a.useRef(null),D=a.useRef(p),U=a.useCallback(n=>{P(n);let s=b.current,m=s?.ownerDocument.activeElement;s&&m&&s.contains(m)&&(R.current=m)},[]),I=a.useRef(new Map),V=a.useCallback(n=>(N(s=>s+1),O(I.current,n,1),()=>{N(s=>s-1),O(I.current,n,-1)}),[]),X=a.useCallback(n=>(S(n),()=>S(s=>s===n?void 0:s)),[]),$=a.useCallback(()=>(k(n=>n+1),()=>k(n=>n-1)),[]),z=a.useCallback(n=>r?.(n),[r]),d=K>0,Q={"aria-label":u["aria-label"],"aria-labelledby":T??u["aria-labelledby"]},x=p===0?C:Math.min(C,p-1);return a.useEffect(()=>{let n=D.current;if(D.current=p,p>=n)return;let s=b.current,m=R.current;if(!s||!m||m.isConnected)return;let M=s.ownerDocument,G=M.activeElement;if(G&&G!==M.body&&G.isConnected)return;R.current=null;let y=Array.from(s.querySelectorAll(g)),v=y[Math.min(x,y.length-1)];(v??s).focus(),v&&P(y.indexOf(v))},[p,x]),L(le,{tabStopIndex:x,setActiveIndex:U,register:V,onTagRemoved:z,count:p,labelId:T,registerLabel:X,hasList:d,registerList:$,labelling:Q,orientation:o,disabled:e,children:L(ie.div,{role:d?void 0:"list","data-skdx-tag-group":"","data-orientation":o,"data-disabled":e?"":void 0,tabIndex:-1,...u,"aria-labelledby":d?void 0:T??u["aria-labelledby"],"aria-label":d?void 0:u["aria-label"],...te({density:F},u),...ne("tag-group","root",u.className),ref:J,onKeyDown:se(u.onKeyDown,q),children:l??L(A,{tags:i,removable:r!==void 0})})})};w.displayName="TagGroup";import*as f from"react";import{skdxPart as me}from"../utils/part.js";import{Primitive as de}from"../utils/primitive.js";import{jsx as fe}from"react/jsx-runtime";var ge=({ref:o,...t})=>{let e=c("TagGroupLabel"),r=f.useId(),i=t.id??r,{registerLabel:l}=e;return f.useEffect(()=>l(i),[l,i]),fe(de.span,{...t,id:i,...me("tag-group","label",t.className),ref:o})};ge.displayName="TagGroupLabel";import*as _ from"react";import{skdxPart as Te}from"../utils/part.js";import{Primitive as be}from"../utils/primitive.js";import{jsx as xe}from"react/jsx-runtime";var Re=({ref:o,...t})=>{let e=c("TagGroupList"),{registerList:r}=e;return _.useEffect(()=>r(),[r]),xe(be.ul,{role:"list","data-orientation":e.orientation,"data-disabled":e.disabled?"":void 0,tabIndex:-1,...e.labelling,...t,...Te("tag-group","list",t.className),ref:o})};Re.displayName="TagGroupList";import{skdxPart as Ge}from"../utils/part.js";import{Primitive as ye}from"../utils/primitive.js";import{jsx as he}from"react/jsx-runtime";var ve=({ref:o,...t})=>c("TagGroupEmpty").count>0?null:he(ye.div,{...t,...Ge("tag-group","empty",t.className),ref:o});ve.displayName="TagGroupEmpty";export{E as TAG_GROUP_SELECTOR,g as TAG_SELECTOR,w as TagGroup,ve as TagGroupEmpty,ge as TagGroupLabel,Re as TagGroupList,le as TagGroupProvider,ce as focusTagNeighbor,H as resolveTagNeighbor,pe as useOptionalTagGroupContext,c as useTagGroupContext};

package/dist/tag-group/TagGroupAnatomy.d.cts

@@ -0,0 +1,7 @@
+import type { JSX } from 'react';
+import type { TagGroupTag } from './types.cjs';
+/** @internal The anatomy a {@link TagGroup} draws from `tags`. */
+export declare const TagGroupAnatomy: ({ tags, removable, }: {
+    tags?: TagGroupTag[] | undefined;
+    removable: boolean;
+}) => JSX.Element;

package/dist/tag-group/TagGroupAnatomy.d.ts

@@ -0,0 +1,7 @@
+import type { JSX } from 'react';
+import type { TagGroupTag } from './types.js';
+/** @internal The anatomy a {@link TagGroup} draws from `tags`. */
+export declare const TagGroupAnatomy: ({ tags, removable, }: {
+    tags?: TagGroupTag[] | undefined;
+    removable: boolean;
+}) => JSX.Element;

package/dist/tag-group/TagGroupEmpty.d.cts

@@ -0,0 +1,17 @@
+import type * as React from 'react';
+import type { TagGroupEmptyProps } from './types.cjs';
+/**
+ * Content shown while {@link TagGroup} holds no tags, rendered as a sibling of the tags rather than a listitem.
+ *
+ * @example
+ * ```tsx
+ * <TagGroup aria-label="Filters">
+ *   {tags.map((tag, index) => <Tag key={tag} index={index} label={tag}>{tag}</Tag>)}
+ *   <TagGroupEmpty>No filters applied</TagGroupEmpty>
+ * </TagGroup>
+ * ```
+ */
+export declare const TagGroupEmpty: {
+    ({ ref: forwardedRef, ...props }: TagGroupEmptyProps): React.ReactNode;
+    displayName: string;
+};

package/dist/tag-group/TagGroupEmpty.d.ts

@@ -0,0 +1,17 @@
+import type * as React from 'react';
+import type { TagGroupEmptyProps } from './types.js';
+/**
+ * Content shown while {@link TagGroup} holds no tags, rendered as a sibling of the tags rather than a listitem.
+ *
+ * @example
+ * ```tsx
+ * <TagGroup aria-label="Filters">
+ *   {tags.map((tag, index) => <Tag key={tag} index={index} label={tag}>{tag}</Tag>)}
+ *   <TagGroupEmpty>No filters applied</TagGroupEmpty>
+ * </TagGroup>
+ * ```
+ */
+export declare const TagGroupEmpty: {
+    ({ ref: forwardedRef, ...props }: TagGroupEmptyProps): React.ReactNode;
+    displayName: string;
+};

package/dist/tag-group/TagGroupLabel.d.cts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import type { TagGroupLabelProps } from './types.cjs';
+/**
+ * Heading that *names* a {@link TagGroup} via `aria-labelledby` — otherwise `role="list"` would need a repeating `aria-label`.
+ *
+ * @example
+ * ```tsx
+ * <TagGroup>
+ *   <TagGroupLabel>Filters</TagGroupLabel>
+ *   <TagGroupList>
+ *     <Tag index={0} label="react" onDelete={…}>react</Tag>
+ *   </TagGroupList>
+ * </TagGroup>
+ * ```
+ */
+export declare const TagGroupLabel: {
+    ({ ref: forwardedRef, ...props }: TagGroupLabelProps): React.ReactNode;
+    displayName: string;
+};

package/dist/tag-group/TagGroupLabel.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import type { TagGroupLabelProps } from './types.js';
+/**
+ * Heading that *names* a {@link TagGroup} via `aria-labelledby` — otherwise `role="list"` would need a repeating `aria-label`.
+ *
+ * @example
+ * ```tsx
+ * <TagGroup>
+ *   <TagGroupLabel>Filters</TagGroupLabel>
+ *   <TagGroupList>
+ *     <Tag index={0} label="react" onDelete={…}>react</Tag>
+ *   </TagGroupList>
+ * </TagGroup>
+ * ```
+ */
+export declare const TagGroupLabel: {
+    ({ ref: forwardedRef, ...props }: TagGroupLabelProps): React.ReactNode;
+    displayName: string;
+};

package/dist/tag-group/TagGroupList.d.cts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { TagGroupListProps } from './types.cjs';
+/**
+ * List container, needed when `TagGroup` has a heading so it isn't announced as an item.
+ *
+ * @example
+ * ```tsx
+ * <TagGroup>
+ *   <TagGroupLabel>Filters</TagGroupLabel>
+ *   <TagGroupList>
+ *     {tags.map((tag, index) => (
+ *       <Tag key={tag} index={index} label={tag} onDelete={() => remove(tag)}>
+ *         {tag}
+ *       </Tag>
+ *     ))}
+ *     <TagGroupEmpty>No filters applied</TagGroupEmpty>
+ *   </TagGroupList>
+ * </TagGroup>
+ * ```
+ */
+export declare const TagGroupList: {
+    ({ ref: forwardedRef, ...props }: TagGroupListProps): React.ReactNode;
+    displayName: string;
+};

package/dist/tag-group/TagGroupList.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { TagGroupListProps } from './types.js';
+/**
+ * List container, needed when `TagGroup` has a heading so it isn't announced as an item.
+ *
+ * @example
+ * ```tsx
+ * <TagGroup>
+ *   <TagGroupLabel>Filters</TagGroupLabel>
+ *   <TagGroupList>
+ *     {tags.map((tag, index) => (
+ *       <Tag key={tag} index={index} label={tag} onDelete={() => remove(tag)}>
+ *         {tag}
+ *       </Tag>
+ *     ))}
+ *     <TagGroupEmpty>No filters applied</TagGroupEmpty>
+ *   </TagGroupList>
+ * </TagGroup>
+ * ```
+ */
+export declare const TagGroupList: {
+    ({ ref: forwardedRef, ...props }: TagGroupListProps): React.ReactNode;
+    displayName: string;
+};

package/dist/tag-group/index.d.cts

@@ -1,2 +1,2 @@
-export { TAG_GROUP_SELECTOR, TAG_SELECTOR, TagGroup, focusTagNeighbor, useTagGroupContext, } from './TagGroup.cjs';
-export { type TagGroupOrientation, type TagGroupProps } from './types.cjs';
+export { TAG_GROUP_SELECTOR, TAG_SELECTOR, TagGroup, focusTagNeighbor, resolveTagNeighbor, useOptionalTagGroupContext, useTagGroupContext, } from './TagGroup.cjs';
+export { type TagGroupOrientation, type TagGroupProps, type TagGroupTag, type TagRemovedDetail, } from './types.cjs';

package/dist/tag-group/index.d.ts

@@ -1,2 +1,2 @@
-export { TAG_GROUP_SELECTOR, TAG_SELECTOR, TagGroup, focusTagNeighbor, useTagGroupContext, } from './TagGroup.js';
-export { type TagGroupOrientation, type TagGroupProps } from './types.js';
+export { TAG_GROUP_SELECTOR, TAG_SELECTOR, TagGroup, focusTagNeighbor, resolveTagNeighbor, useOptionalTagGroupContext, useTagGroupContext, } from './TagGroup.js';
+export { type TagGroupOrientation, type TagGroupProps, type TagGroupTag, type TagRemovedDetail, } from './types.js';

package/dist/tag-group/primitives.d.cts

@@ -0,0 +1,27 @@
+/**
+ * Primitives for `TagGroup` — manual composition escape hatch.
+ *
+ * @example
+ * ```tsx
+ * import { TagGroup, TagGroupLabel, TagGroupList, TagGroupEmpty } from '@skdx/react/primitives/tag-group';
+ * import { Badge, BadgeDelete } from '@skdx/react/primitives/badge';
+ *
+ * <TagGroup>
+ *   <TagGroupLabel>Filters</TagGroupLabel>
+ *   <TagGroupList>
+ *     {filters.map((filter, index) => (
+ *       <Badge key={filter} index={index} label={filter} onDelete={() => remove(filter)}>
+ *         {filter}
+ *         <BadgeDelete>×</BadgeDelete>
+ *       </Badge>
+ *     ))}
+ *     <TagGroupEmpty>No filters applied</TagGroupEmpty>
+ *   </TagGroupList>
+ * </TagGroup>
+ * ```
+ */
+export { TagGroup } from './TagGroup.cjs';
+export { TagGroupLabel } from './TagGroupLabel.cjs';
+export { TagGroupList } from './TagGroupList.cjs';
+export { TagGroupEmpty } from './TagGroupEmpty.cjs';
+export type { TagGroupProps, TagGroupLabelProps, TagGroupListProps, TagGroupEmptyProps, } from './types.cjs';

package/dist/tag-group/primitives.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Primitives for `TagGroup` — manual composition escape hatch.
+ *
+ * @example
+ * ```tsx
+ * import { TagGroup, TagGroupLabel, TagGroupList, TagGroupEmpty } from '@skdx/react/primitives/tag-group';
+ * import { Badge, BadgeDelete } from '@skdx/react/primitives/badge';
+ *
+ * <TagGroup>
+ *   <TagGroupLabel>Filters</TagGroupLabel>
+ *   <TagGroupList>
+ *     {filters.map((filter, index) => (
+ *       <Badge key={filter} index={index} label={filter} onDelete={() => remove(filter)}>
+ *         {filter}
+ *         <BadgeDelete>×</BadgeDelete>
+ *       </Badge>
+ *     ))}
+ *     <TagGroupEmpty>No filters applied</TagGroupEmpty>
+ *   </TagGroupList>
+ * </TagGroup>
+ * ```
+ */
+export { TagGroup } from './TagGroup.js';
+export { TagGroupLabel } from './TagGroupLabel.js';
+export { TagGroupList } from './TagGroupList.js';
+export { TagGroupEmpty } from './TagGroupEmpty.js';
+export type { TagGroupProps, TagGroupLabelProps, TagGroupListProps, TagGroupEmptyProps, } from './types.js';