@skdx/react 0.26.0

package/dist/tabs/types.d.ts

@@ -0,0 +1,73 @@
+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. */
+export interface TabsContextValue {
+    baseId: string;
+    value?: string;
+    onValueChange: (value: string) => void;
+    orientation: 'horizontal' | 'vertical';
+    activationMode: 'automatic' | 'manual';
+    /**
+     * 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.
+     */
+    firstEnabledValue: string | null;
+    setFirstEnabledValue: (value: string | null) => void;
+}
+/** Props for the {@link Tabs} root. */
+export interface TabsProps extends PrimitivePropsWithRef<'div'> {
+    /**
+     * Selected tab's value, for controlled usage. Pair with `onValueChange`.
+     * @default undefined — uncontrolled, tracks its own selected value internally.
+     */
+    value?: string;
+    /**
+     * Initially selected tab's value, for uncontrolled usage.
+     * @default undefined — falls back to the first enabled trigger.
+     */
+    defaultValue?: string;
+    /**
+     * Fires with the new value whenever the selected tab changes, controlled or not.
+     * @default undefined — no-op.
+     */
+    onValueChange?: (value: string) => void;
+    /**
+     * 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';
+    /**
+     * `'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.
+     * @default 'automatic'
+     */
+    activationMode?: 'automatic' | 'manual';
+}
+/** Props for {@link TabsList}, the roving-focus container for `TabsTrigger`s. */
+export interface TabsListProps extends PrimitivePropsWithRef<'div'> {
+    /**
+     * Whether arrow-key navigation wraps from the last trigger back to the first
+     * (and vice versa).
+     * @default true
+     */
+    loop?: boolean;
+}
+/** Props for a single {@link TabsTrigger} button. */
+export interface TabsTriggerProps extends PrimitivePropsWithRef<'button'> {
+    /** Unique identifier matched against a sibling `TabsContent`'s `value`. */
+    value: string;
+}
+/** 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.
+     * @default false
+     */
+    forceMount?: boolean;
+}

package/dist/tag/Tag.cjs

@@ -0,0 +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});

package/dist/tag/Tag.d.cts

@@ -0,0 +1,45 @@
+import * as React from 'react';
+import type { TagContextValue, TagProps } from './types.cjs';
+/**
+ * Reads what a single {@link Tag} publishes to its own subtree: the
+ * tag's `value` (which names its delete button — "Remove react", not a bare
+ * "Remove"), whether it is disabled by itself or by the enclosing group, and
+ * `remove`, which moves focus to a neighbouring tag *before* firing `onDelete`
+ * so deleting the focused tag does not drop focus to the body.
+ *
+ * Only {@link TagDelete} reads it, under its own name, which is the name the
+ * hook puts in the error it throws when a delete button is rendered outside a
+ * `Tag` — with no `Tag` it has nothing to remove and no text to be named after.
+ * Not part of the public API.
+ *
+ * @internal
+ */
+export declare const TagProvider: {
+    (props: TagContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useTagContext: (consumerName: string) => TagContextValue;
+/**
+ * One tag inside a {@link TagGroup}: renders a `<span role="listitem">` that
+ * takes part in the group's roving tabindex, and removes itself on `Delete` or
+ * `Backspace` when given an `onDelete`.
+ *
+ * A tag with no `onDelete` is static — it is still reachable with the arrow
+ * keys, but nothing removes it. Give it a {@link TagDelete} child for a mouse
+ * affordance; the button borrows `value` for its accessible name, so it
+ * announces "Remove react" rather than a row of identical "Remove" buttons.
+ *
+ * Must be rendered inside a `TagGroup` — the group owns the focus behaviour
+ * that makes a tag worth being a component at all. For a purely decorative
+ * label with no keyboard behaviour, use `Badge`.
+ *
+ * @example
+ * ```tsx
+ * <Tag index={0} value="react" onDelete={() => remove('react')}>
+ *   react
+ *   <TagDelete>×</TagDelete>
+ * </Tag>
+ * ```
+ */
+export declare const Tag: React.ForwardRefExoticComponent<Omit<TagProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/tag/Tag.d.ts

@@ -0,0 +1,45 @@
+import * as React from 'react';
+import type { TagContextValue, TagProps } from './types.js';
+/**
+ * Reads what a single {@link Tag} publishes to its own subtree: the
+ * tag's `value` (which names its delete button — "Remove react", not a bare
+ * "Remove"), whether it is disabled by itself or by the enclosing group, and
+ * `remove`, which moves focus to a neighbouring tag *before* firing `onDelete`
+ * so deleting the focused tag does not drop focus to the body.
+ *
+ * Only {@link TagDelete} reads it, under its own name, which is the name the
+ * hook puts in the error it throws when a delete button is rendered outside a
+ * `Tag` — with no `Tag` it has nothing to remove and no text to be named after.
+ * Not part of the public API.
+ *
+ * @internal
+ */
+export declare const TagProvider: {
+    (props: TagContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useTagContext: (consumerName: string) => TagContextValue;
+/**
+ * One tag inside a {@link TagGroup}: renders a `<span role="listitem">` that
+ * takes part in the group's roving tabindex, and removes itself on `Delete` or
+ * `Backspace` when given an `onDelete`.
+ *
+ * A tag with no `onDelete` is static — it is still reachable with the arrow
+ * keys, but nothing removes it. Give it a {@link TagDelete} child for a mouse
+ * affordance; the button borrows `value` for its accessible name, so it
+ * announces "Remove react" rather than a row of identical "Remove" buttons.
+ *
+ * Must be rendered inside a `TagGroup` — the group owns the focus behaviour
+ * that makes a tag worth being a component at all. For a purely decorative
+ * label with no keyboard behaviour, use `Badge`.
+ *
+ * @example
+ * ```tsx
+ * <Tag index={0} value="react" onDelete={() => remove('react')}>
+ *   react
+ *   <TagDelete>×</TagDelete>
+ * </Tag>
+ * ```
+ */
+export declare const Tag: React.ForwardRefExoticComponent<Omit<TagProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/tag/Tag.js

@@ -0,0 +1 @@
+import*as t from"react";import{focusTagNeighbor as x,useTagGroupContext as k}from"../tag-group/TagGroup.js";import{useComposedRefs as w}from"../utils/composeRefs.js";import{createSafeContext as R}from"../utils/createContext.js";import{skdxPart as P}from"../utils/part.js";import{composeEventHandlers as g,Primitive as C}from"../utils/primitive.js";import{jsx as f}from"react/jsx-runtime";var[D,c]=R("Tag"),T=t.forwardRef(({index:e,value:s="",disabled:a=!1,onDelete:n,...o},v)=>{let i=k("Tag"),r=a||i.disabled,p=t.useRef(null),y=w(v,p),{register:m,setActiveIndex:l}=i;t.useEffect(()=>m(),[m]);let u=t.useCallback(()=>{r||!n||(l(x(p.current,e)),n())},[r,n,l,e]);return f(D,{value:s,disabled:r,remove:u,children:f(C.span,{role:"listitem","data-skdx-tag":"","data-disabled":r?"":void 0,tabIndex:i.tabStopIndex===e?0:-1,...o,...P("tag","root",o.className),ref:y,onFocus:g(o.onFocus,()=>l(e)),onKeyDown:g(o.onKeyDown,d=>{d.key!=="Delete"&&d.key!=="Backspace"||(d.preventDefault(),u())})})})});T.displayName="Tag";import*as h from"react";import{skdxPart as I}from"../utils/part.js";import{composeEventHandlers as E,Primitive as N}from"../utils/primitive.js";import{jsx as S}from"react/jsx-runtime";var b=h.forwardRef((e,s)=>{let a=c("TagDelete");return S(N.button,{type:"button","aria-label":`Remove ${a.value}`.trim(),disabled:a.disabled,"data-disabled":a.disabled?"":void 0,tabIndex:-1,...e,...I("tag","delete",e.className),ref:s,onClick:E(e.onClick,()=>{a.remove()})})});b.displayName="TagDelete";export{T as Tag,b as TagDelete};

package/dist/tag/TagDelete.d.cts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import type { TagDeleteProps } from './types.cjs';
+/**
+ * Removes its parent {@link Tag} on click. Renders a
+ * `<button type="button">` named `Remove <value>` from the tag's `value`, so a
+ * group of them reads as "Remove react", "Remove typescript" rather than a row
+ * of identical "Remove" buttons.
+ *
+ * It is deliberately **not** a Tab stop: the group has one, and the keyboard
+ * path to removal is `Delete`/`Backspace` on the tag itself. Tabbing through
+ * every tag *and* every delete button is the thing the roving tabindex exists
+ * to avoid.
+ *
+ * @example
+ * ```tsx
+ * <Tag index={0} value="react" onDelete={() => remove('react')}>
+ *   react
+ *   <TagDelete>×</TagDelete>
+ * </Tag>
+ * ```
+ */
+export declare const TagDelete: React.ForwardRefExoticComponent<Omit<TagDeleteProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/tag/TagDelete.d.ts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import type { TagDeleteProps } from './types.js';
+/**
+ * Removes its parent {@link Tag} on click. Renders a
+ * `<button type="button">` named `Remove <value>` from the tag's `value`, so a
+ * group of them reads as "Remove react", "Remove typescript" rather than a row
+ * of identical "Remove" buttons.
+ *
+ * It is deliberately **not** a Tab stop: the group has one, and the keyboard
+ * path to removal is `Delete`/`Backspace` on the tag itself. Tabbing through
+ * every tag *and* every delete button is the thing the roving tabindex exists
+ * to avoid.
+ *
+ * @example
+ * ```tsx
+ * <Tag index={0} value="react" onDelete={() => remove('react')}>
+ *   react
+ *   <TagDelete>×</TagDelete>
+ * </Tag>
+ * ```
+ */
+export declare const TagDelete: React.ForwardRefExoticComponent<Omit<TagDeleteProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/tag/index.d.cts

@@ -0,0 +1,3 @@
+export { Tag } from './Tag.cjs';
+export { TagDelete } from './TagDelete.cjs';
+export { type TagDeleteProps, type TagProps } from './types.cjs';

package/dist/tag/index.d.ts

@@ -0,0 +1,3 @@
+export { Tag } from './Tag.js';
+export { TagDelete } from './TagDelete.js';
+export { type TagDeleteProps, type TagProps } from './types.js';

package/dist/tag/types.d.cts

@@ -0,0 +1,43 @@
+import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+/** @internal Shared state distributed from {@link Tag} to {@link TagDelete} via context. Not part of the public API. */
+export interface TagContextValue {
+    /** The tag's own text, used to name the delete button. */
+    value: string;
+    /** Whether this tag (or the whole group) is disabled. */
+    disabled: boolean;
+    /** Moves focus to a neighbouring tag and then fires `onDelete`; a no-op when disabled or when no `onDelete` was given. */
+    remove: () => void;
+}
+/** Props for a {@link Tag} — one removable tag inside a {@link TagGroup}. */
+export interface TagProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * This tag's position in the rendered list. The group uses it to decide
+     * which tag owns the single Tab stop, so it must match the order the tags
+     * are rendered in — the array index from the `map` that produced them.
+     */
+    index: number;
+    /**
+     * This tag's text, used to name the delete button (`Remove react`). Without
+     * it every delete button in the group is announced as a bare "Remove", which
+     * tells a screen-reader user nothing about *what* they are about to remove.
+     * @default '' — the delete button is named just "Remove".
+     */
+    value?: string;
+    /**
+     * Disables this tag alone: it can't be deleted, its delete button is
+     * `disabled`, and arrow-key navigation skips it. The group's own `disabled`
+     * also disables it.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Removes this tag from whatever list the consumer renders it from. Runs
+     * *after* focus has been moved to a neighbouring tag, so the state update
+     * that unmounts this element never drops focus to `<body>`.
+     * @default undefined — the tag is static: `Delete`/`Backspace` do nothing and `TagDelete` is inert.
+     */
+    onDelete?: () => void;
+}
+/** Props for {@link TagDelete}, the button that removes its parent {@link Tag}. */
+export interface TagDeleteProps extends PrimitivePropsWithRef<'button'> {
+}

package/dist/tag/types.d.ts

@@ -0,0 +1,43 @@
+import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+/** @internal Shared state distributed from {@link Tag} to {@link TagDelete} via context. Not part of the public API. */
+export interface TagContextValue {
+    /** The tag's own text, used to name the delete button. */
+    value: string;
+    /** Whether this tag (or the whole group) is disabled. */
+    disabled: boolean;
+    /** Moves focus to a neighbouring tag and then fires `onDelete`; a no-op when disabled or when no `onDelete` was given. */
+    remove: () => void;
+}
+/** Props for a {@link Tag} — one removable tag inside a {@link TagGroup}. */
+export interface TagProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * This tag's position in the rendered list. The group uses it to decide
+     * which tag owns the single Tab stop, so it must match the order the tags
+     * are rendered in — the array index from the `map` that produced them.
+     */
+    index: number;
+    /**
+     * This tag's text, used to name the delete button (`Remove react`). Without
+     * it every delete button in the group is announced as a bare "Remove", which
+     * tells a screen-reader user nothing about *what* they are about to remove.
+     * @default '' — the delete button is named just "Remove".
+     */
+    value?: string;
+    /**
+     * Disables this tag alone: it can't be deleted, its delete button is
+     * `disabled`, and arrow-key navigation skips it. The group's own `disabled`
+     * also disables it.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Removes this tag from whatever list the consumer renders it from. Runs
+     * *after* focus has been moved to a neighbouring tag, so the state update
+     * that unmounts this element never drops focus to `<body>`.
+     * @default undefined — the tag is static: `Delete`/`Backspace` do nothing and `TagDelete` is inert.
+     */
+    onDelete?: () => void;
+}
+/** Props for {@link TagDelete}, the button that removes its parent {@link Tag}. */
+export interface TagDeleteProps extends PrimitivePropsWithRef<'button'> {
+}

package/dist/tag-group/TagGroup.cjs

@@ -0,0 +1 @@
+"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});

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

@@ -0,0 +1,75 @@
+import * as React from 'react';
+import type { TagGroupContextValue, TagGroupProps } from './types.cjs';
+/** @internal Marks the {@link TagGroup} root, so a tag being removed can find the group to fall back to. */
+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
+ */
+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.
+ *
+ * @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>
+ * ```
+ */
+export declare const TagGroup: React.ForwardRefExoticComponent<Omit<TagGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,75 @@
+import * as React from 'react';
+import type { TagGroupContextValue, TagGroupProps } from './types.js';
+/** @internal Marks the {@link TagGroup} root, so a tag being removed can find the group to fall back to. */
+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
+ */
+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.
+ *
+ * @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>
+ * ```
+ */
+export declare const TagGroup: React.ForwardRefExoticComponent<Omit<TagGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/tag-group/TagGroup.js

@@ -0,0 +1 @@
+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};

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

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

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

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

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

@@ -0,0 +1,39 @@
+import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+/** Layout axis of a {@link TagGroup}, deciding which pair of arrow keys moves the roving tab stop. */
+export type TagGroupOrientation = 'horizontal' | 'vertical';
+/** @internal Shared state distributed from {@link TagGroup} to its `Tag` children via context. Not part of the public API. */
+export interface TagGroupContextValue {
+    /**
+     * Index of the tag that currently owns the group's single tab stop. Clamped
+     * to the number of mounted tags, so removing the last tag hands the stop to
+     * the new last one instead of leaving the group unreachable by Tab.
+     */
+    tabStopIndex: number;
+    /** Claims the tab stop for the tag at `index` — called when a tag takes focus, and again after a removal shifts the indices. */
+    setActiveIndex: (index: number) => void;
+    /** Registers a mounted tag so the group knows how many exist; returns its unregister. */
+    register: () => () => void;
+    /** Whether the whole group is disabled. */
+    disabled: boolean;
+}
+/** Props for the {@link TagGroup} root. */
+export interface TagGroupProps extends PrimitivePropsWithRef<'div'> {
+    /**
+     * Layout axis, exposed as `data-orientation` and used to pick Arrow
+     * Left/Right vs. Arrow Up/Down for roving-tabindex navigation.
+     * @default 'horizontal'
+     */
+    orientation?: TagGroupOrientation;
+    /**
+     * Whether arrow-key navigation wraps from the last tag back to the first
+     * (and vice versa).
+     * @default true
+     */
+    loop?: boolean;
+    /**
+     * Disables every {@link Tag} in the group — no tag can be deleted, and each
+     * one mirrors `data-disabled`.
+     * @default false
+     */
+    disabled?: boolean;
+}

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

@@ -0,0 +1,39 @@
+import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+/** Layout axis of a {@link TagGroup}, deciding which pair of arrow keys moves the roving tab stop. */
+export type TagGroupOrientation = 'horizontal' | 'vertical';
+/** @internal Shared state distributed from {@link TagGroup} to its `Tag` children via context. Not part of the public API. */
+export interface TagGroupContextValue {
+    /**
+     * Index of the tag that currently owns the group's single tab stop. Clamped
+     * to the number of mounted tags, so removing the last tag hands the stop to
+     * the new last one instead of leaving the group unreachable by Tab.
+     */
+    tabStopIndex: number;
+    /** Claims the tab stop for the tag at `index` — called when a tag takes focus, and again after a removal shifts the indices. */
+    setActiveIndex: (index: number) => void;
+    /** Registers a mounted tag so the group knows how many exist; returns its unregister. */
+    register: () => () => void;
+    /** Whether the whole group is disabled. */
+    disabled: boolean;
+}
+/** Props for the {@link TagGroup} root. */
+export interface TagGroupProps extends PrimitivePropsWithRef<'div'> {
+    /**
+     * Layout axis, exposed as `data-orientation` and used to pick Arrow
+     * Left/Right vs. Arrow Up/Down for roving-tabindex navigation.
+     * @default 'horizontal'
+     */
+    orientation?: TagGroupOrientation;
+    /**
+     * Whether arrow-key navigation wraps from the last tag back to the first
+     * (and vice versa).
+     * @default true
+     */
+    loop?: boolean;
+    /**
+     * Disables every {@link Tag} in the group — no tag can be deleted, and each
+     * one mirrors `data-disabled`.
+     * @default false
+     */
+    disabled?: boolean;
+}

package/dist/tags-input/TagsInput.cjs

@@ -0,0 +1 @@
+"use strict";var se=Object.create;var g=Object.defineProperty;var oe=Object.getOwnPropertyDescriptor;var re=Object.getOwnPropertyNames;var de=Object.getPrototypeOf,ie=Object.prototype.hasOwnProperty;var ue=(t,a)=>{for(var e in a)g(t,e,{get:a[e],enumerable:!0})},h=(t,a,e,n)=>{if(a&&typeof a=="object"||typeof a=="function")for(let s of re(a))!ie.call(t,s)&&s!==e&&g(t,s,{get:()=>a[s],enumerable:!(n=oe(a,s))||n.enumerable});return t};var T=(t,a,e)=>(e=t!=null?se(de(t)):{},h(a||!t||!t.__esModule?g(e,"default",{value:t,enumerable:!0}):e,t)),pe=t=>h(g({},"__esModule",{value:!0}),t);var me={};ue(me,{TAGS_INPUT_DELETE_SELECTOR:()=>v,TAGS_INPUT_FIELD_SELECTOR:()=>R,TAGS_INPUT_SELECTOR:()=>b,TagsInput:()=>C,TagsInputInput:()=>D,TagsInputItem:()=>k,TagsInputItemDelete:()=>L,focusDeleteNeighbor:()=>I});module.exports=pe(me);var o=T(require("react"),1),V=require("../utils/createContext.cjs"),H=require("../utils/part.cjs"),A=require("../utils/primitive.cjs"),P=require("../utils/useControllableState.cjs"),E=require("react/jsx-runtime"),[le,d]=(0,V.createSafeContext)("TagsInput"),b="[data-skdx-tags-input]",v="[data-skdx-tags-input-delete]",R="[data-skdx-tags-input-field]";function I(t){let a=t.closest(b),e=a?Array.from(a.querySelectorAll(v)):[],n=e.indexOf(t);((n===-1?void 0:e[n+1])??e[n-1]??a?.querySelector(R))?.focus()}var C=o.forwardRef(({value:t,defaultValue:a=[],onValueChange:e,disabled:n=!1,invalid:s=!1,readOnly:_=!1,max:l,delimiter:J=",",addOnPaste:Q=!0,validate:N,inputValue:W,defaultInputValue:X="",onInputValueChange:Y,...S},Z)=>{let[j=[],m]=(0,P.useControllableState)({prop:t,defaultProp:a,onChange:e}),[ee="",te]=(0,P.useControllableState)({prop:W,defaultProp:X,onChange:Y}),O=o.useRef(N);O.current=N;let x=o.useCallback(u=>{m((p=[])=>{let r=[...p];for(let y of u){let f=y.trim();if(!(!f||r.includes(f))){if(l!==void 0&&r.length>=l)break;O.current?.(f,r)!==!1&&r.push(f)}}return r.length===p.length?p:r})},[m,l]),ae=o.useCallback(u=>x([u]),[x]),ne=o.useCallback(u=>{m((p=[])=>p.filter((r,y)=>y!==u))},[m]);return(0,E.jsx)(le,{value:j,inputValue:ee,setInputValue:te,disabled:n,invalid:s,readOnly:_,max:l,delimiter:J,addOnPaste:Q,addTag:ae,addTags:x,removeTag:ne,children:(0,E.jsx)(A.Primitive.div,{"data-skdx-tags-input":"","data-disabled":n?"":void 0,"data-invalid":s?"":void 0,"data-readonly":_?"":void 0,...S,...(0,H.skdxPart)("tags-input","root",S.className),ref:Z})})});C.displayName="TagsInput";var M=T(require("react"),1),w=require("../utils/part.cjs"),i=require("../utils/primitive.cjs");var G=require("react/jsx-runtime"),D=M.forwardRef((t,a)=>{let e=d("TagsInputInput"),n=e.inputValue;return(0,G.jsx)(i.Primitive.input,{type:"text","data-skdx-tags-input-field":"",disabled:e.disabled,readOnly:e.readOnly,"aria-invalid":e.invalid?!0:void 0,"aria-readonly":e.readOnly?!0:void 0,"data-disabled":e.disabled?"":void 0,"data-invalid":e.invalid?"":void 0,"data-readonly":e.readOnly?"":void 0,...t,...(0,w.skdxPart)("tags-input","input",t.className),ref:a,value:n,onChange:(0,i.composeEventHandlers)(t.onChange,s=>e.setInputValue(s.target.value)),onKeyDown:(0,i.composeEventHandlers)(t.onKeyDown,s=>{e.disabled||e.readOnly||(s.key==="Enter"||s.key===e.delimiter?(s.preventDefault(),e.addTag(n),e.setInputValue("")):s.key==="Backspace"&&n===""&&e.value.length>0&&e.removeTag(e.value.length-1))}),onPaste:(0,i.composeEventHandlers)(t.onPaste,s=>{e.disabled||e.readOnly||!e.addOnPaste||(s.preventDefault(),e.addTags(s.clipboardData.getData("text").split(e.delimiter)),e.setInputValue(""))})})});D.displayName="TagsInputInput";var U=T(require("react"),1),q=require("../utils/part.cjs"),B=require("../utils/primitive.cjs");var F=require("react/jsx-runtime"),k=U.forwardRef(({index:t,...a},e)=>{let n=d("TagsInputItem");return(0,F.jsx)(B.Primitive.span,{"data-disabled":n.disabled?"":void 0,...a,...(0,q.skdxPart)("tags-input","item",a.className),ref:e})});k.displayName="TagsInputItem";var K=T(require("react"),1),$=require("../utils/part.cjs"),c=require("../utils/primitive.cjs");var z=require("react/jsx-runtime"),L=K.forwardRef(({index:t,...a},e)=>{let n=d("TagsInputItemDelete");return(0,z.jsx)(c.Primitive.button,{type:"button","aria-label":`Remove ${n.value[t]??""}`.trim(),disabled:n.disabled,"data-skdx-tags-input-delete":"","data-disabled":n.disabled?"":void 0,...a,...(0,$.skdxPart)("tags-input","item-delete",a.className),ref:e,onClick:(0,c.composeEventHandlers)(a.onClick,s=>{n.disabled||(I(s.currentTarget),n.removeTag(t))})})});L.displayName="TagsInputItemDelete";0&&(module.exports={TAGS_INPUT_DELETE_SELECTOR,TAGS_INPUT_FIELD_SELECTOR,TAGS_INPUT_SELECTOR,TagsInput,TagsInputInput,TagsInputItem,TagsInputItemDelete,focusDeleteNeighbor});