@skdx/react 0.26.0 → 0.28.0

package/dist/tag/Tag.d.cts

@@ -1,18 +1,8 @@
 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
+ * Context for Tag subtree: label, disabled state, remove function (dispatches
+ * cancelable `delete`, moves focus to neighbor). @internal
  */
 export declare const TagProvider: {
     (props: TagContextValue & {
@@ -22,21 +12,30 @@ export declare const TagProvider: {
 }, 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
+ * takes part in the group's roving tabindex, and removes itself on `TagDelete` 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
+ * affordance; the button borrows `label` 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`.
+ * A `TagGroup` is optional. Inside one the tag is a `role="listitem"` in the
+ * group's roving tabindex and `index` is required. Standalone it is a plain
+ * styled element — no `listitem` role, which is invalid outside a list, no tab
+ * stop, and no delete wiring; `TagDelete` inside one throws, because there is
+ * no group to remove the tag from. Pair it with `as` for the shapes templates
+ * hand-write: `<Tag as="li">` inside their own list, `<Tag as="a" href>` as a
+ * filter link.
+ *
+ * Given no `children` it draws the derived anatomy: an optional `TagLeading`,
+ * the `TagLabel`, and a `TagDelete` when `deletable`. Given children, they
+ * are rendered verbatim for full manual composition; reach for
+ * `@skdx/react/primitives/tag` for the parts.
  *
  * @example
  * ```tsx
- * <Tag index={0} value="react" onDelete={() => remove('react')}>
+ * <Tag index={0} label="react" onDelete={() => remove('react')}>
  *   react
  *   <TagDelete>×</TagDelete>
  * </Tag>

package/dist/tag/Tag.d.ts

@@ -1,18 +1,8 @@
 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
+ * Context for Tag subtree: label, disabled state, remove function (dispatches
+ * cancelable `delete`, moves focus to neighbor). @internal
  */
 export declare const TagProvider: {
     (props: TagContextValue & {
@@ -22,21 +12,30 @@ export declare const TagProvider: {
 }, 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
+ * takes part in the group's roving tabindex, and removes itself on `TagDelete` 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
+ * affordance; the button borrows `label` 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`.
+ * A `TagGroup` is optional. Inside one the tag is a `role="listitem"` in the
+ * group's roving tabindex and `index` is required. Standalone it is a plain
+ * styled element — no `listitem` role, which is invalid outside a list, no tab
+ * stop, and no delete wiring; `TagDelete` inside one throws, because there is
+ * no group to remove the tag from. Pair it with `as` for the shapes templates
+ * hand-write: `<Tag as="li">` inside their own list, `<Tag as="a" href>` as a
+ * filter link.
+ *
+ * Given no `children` it draws the derived anatomy: an optional `TagLeading`,
+ * the `TagLabel`, and a `TagDelete` when `deletable`. Given children, they
+ * are rendered verbatim for full manual composition; reach for
+ * `@skdx/react/primitives/tag` for the parts.
  *
  * @example
  * ```tsx
- * <Tag index={0} value="react" onDelete={() => remove('react')}>
+ * <Tag index={0} label="react" onDelete={() => remove('react')}>
  *   react
  *   <TagDelete>×</TagDelete>
  * </Tag>

package/dist/tag/Tag.js

@@ -1 +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};
+import*as n from"react";import{resolveTagNeighbor as X,useOptionalTagGroupContext as Z}from"../tag-group/TagGroup.js";import{useComposedRefs as j}from"../utils/composeRefs.js";import{createSafeContext as ee}from"../utils/createContext.js";import{announce as te}from"../utils/liveAnnouncer.js";import{skdxPart as ae}from"../utils/part.js";import{composeEventHandlers as b,Primitive as oe}from"../utils/primitive.js";import*as R from"react";import{skdxPart as K}from"../utils/part.js";import{composeEventHandlers as W,Primitive as U}from"../utils/primitive.js";import{jsx as V}from"react/jsx-runtime";var c=R.forwardRef((t,e)=>{let a=i("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 V(U.button,{type:"button","aria-label":`${a.deleteLabel} ${a.label}`.trim(),disabled:a.disabled,"data-disabled":a.disabled?"":void 0,tabIndex:-1,...t,...K("tag","delete",t.className),ref:e,onClick:W(t.onClick,()=>{a.remove()})})});c.displayName="TagDelete";import*as L from"react";import{skdxPart as $}from"../utils/part.js";import{Primitive as q}from"../utils/primitive.js";import{jsx as F}from"react/jsx-runtime";var f=L.forwardRef((t,e)=>(i("TagLabel"),F(q.span,{...t,...$("tag","label",t.className),ref:e})));f.displayName="TagLabel";import*as P from"react";import{skdxPart as O}from"../utils/part.js";import{Primitive as z}from"../utils/primitive.js";import{jsx as Y}from"react/jsx-runtime";var h=P.forwardRef((t,e)=>(i("TagLeading"),Y(z.span,{...t,...O("tag","leading",t.className),ref:e})));h.displayName="TagLeading";import{Fragment as J,jsx as l,jsxs as Q}from"react/jsx-runtime";function _(){return l("svg",{viewBox:"0 0 16 16",width:"1em",height:"1em",fill:"none","aria-hidden":"true",focusable:"false",children:l("path",{d:"M4 4l8 8M12 4l-8 8",stroke:"currentColor",strokeWidth:"1.5",strokeLinecap:"round"})})}function E({label:t,leading:e,deletable:a}){return Q(J,{children:[e?l(h,{children:e}):null,l(f,{children:t}),a?l(c,{children:l(_,{})}):null]})}import{jsx as T}from"react/jsx-runtime";var D=["Delete","Backspace"],[re,i]=ee("Tag"),C=n.forwardRef(({as:t="span",index:e,label:a,selected:v=!1,disabled:N=!1,onDelete:m,leading:I,deletable:S=!1,deleteLabel:M="Remove",children:H,...d},G)=>{let o=Z(),s=a??"",p=N||(o?.disabled??!1),y=n.useRef(null),A=j(G,y),u=o?.register,g=o?.setActiveIndex,x=o?.onTagRemoved;n.useEffect(()=>{if(!(!u||e===void 0))return u(e)},[u,e]);let w=n.useCallback(()=>{if(p||!m||!o||e===void 0)return;let r=X(y.current,e),k=new CustomEvent("delete",{cancelable:!0,detail:null});m(k),!k.defaultPrevented&&(r.target?.focus(),g?.(r.index),x?.({label:s,index:e}),s&&te(`${s} removed`))},[p,m,o,g,x,e,s]),B=oe[t];return T(re,{label:s,deleteLabel:M,disabled:p,selected:v,grouped:o!==void 0,remove:w,children:T(B,{role:o?"listitem":void 0,"data-skdx-tag":"","aria-disabled":p?!0:void 0,"data-disabled":p?"":void 0,"data-selected":v?"":void 0,tabIndex:o?o.tabStopIndex===e?0:-1:void 0,...d,...ae("tag","root",d.className),ref:A,onFocus:b(d.onFocus,()=>{e!==void 0&&g?.(e)}),onKeyDown:b(d.onKeyDown,r=>{D.includes(r.key)&&r.preventDefault()}),onKeyUp:b(d.onKeyUp,r=>{D.includes(r.key)&&(r.preventDefault(),w())}),children:H??T(E,{label:s,leading:I,deletable:S})})})});C.displayName="Tag";export{C as Tag,E as TagAnatomy,c as TagDelete,_ as TagDeleteIcon,f as TagLabel,h as TagLeading,re as TagProvider,i as useTagContext};

package/dist/tag/TagAnatomy.d.cts

@@ -0,0 +1,17 @@
+import type * as React from 'react';
+/**
+ * The × glyph a derived `TagDelete` draws.
+ * @internal
+ */
+export declare function TagDeleteIcon(): React.JSX.Element;
+/**
+ * The anatomy a {@link Tag} draws when given no children: an optional
+ * leading icon, the label, and a delete button when `deletable`.
+ *
+ * @internal
+ */
+export declare function TagAnatomy({ label, leading, deletable, }: {
+    label: string;
+    leading?: React.ReactNode;
+    deletable?: boolean;
+}): React.JSX.Element;

package/dist/tag/TagAnatomy.d.ts

@@ -0,0 +1,17 @@
+import type * as React from 'react';
+/**
+ * The × glyph a derived `TagDelete` draws.
+ * @internal
+ */
+export declare function TagDeleteIcon(): React.JSX.Element;
+/**
+ * The anatomy a {@link Tag} draws when given no children: an optional
+ * leading icon, the label, and a delete button when `deletable`.
+ *
+ * @internal
+ */
+export declare function TagAnatomy({ label, leading, deletable, }: {
+    label: string;
+    leading?: React.ReactNode;
+    deletable?: boolean;
+}): React.JSX.Element;

package/dist/tag/TagDelete.d.cts

@@ -1,19 +1,13 @@
 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.
+ * Removes its parent {@link Tag} on click. Requires `TagGroup` and throws
+ * without it. Not a Tab stop (group has one; keyboard removal is via the tag).
+ * Children are decorative; accessible name comes from generated `aria-label`.
  *
  * @example
  * ```tsx
- * <Tag index={0} value="react" onDelete={() => remove('react')}>
+ * <Tag index={0} label="react" onDelete={() => remove('react')}>
  *   react
  *   <TagDelete>×</TagDelete>
  * </Tag>

package/dist/tag/TagDelete.d.ts

@@ -1,19 +1,13 @@
 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.
+ * Removes its parent {@link Tag} on click. Requires `TagGroup` and throws
+ * without it. Not a Tab stop (group has one; keyboard removal is via the tag).
+ * Children are decorative; accessible name comes from generated `aria-label`.
  *
  * @example
  * ```tsx
- * <Tag index={0} value="react" onDelete={() => remove('react')}>
+ * <Tag index={0} label="react" onDelete={() => remove('react')}>
  *   react
  *   <TagDelete>×</TagDelete>
  * </Tag>

package/dist/tag/TagLabel.d.cts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { TagLabelProps } from './types.cjs';
+/**
+ * An optional wrapper around a {@link Tag}'s visible text, so a skin can
+ * truncate the label without also truncating a {@link TagLeading} icon or the
+ * {@link TagDelete} button. Match the root's `label` prop: the announcement
+ * is named from it.
+ *
+ * @example
+ * ```tsx
+ * <Tag index={0} label="react" onDelete={() => remove('react')}>
+ *   <TagLabel>react</TagLabel>
+ *   <TagDelete>×</TagDelete>
+ * </Tag>
+ * ```
+ */
+export declare const TagLabel: React.ForwardRefExoticComponent<Omit<TagLabelProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/tag/TagLabel.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { TagLabelProps } from './types.js';
+/**
+ * An optional wrapper around a {@link Tag}'s visible text, so a skin can
+ * truncate the label without also truncating a {@link TagLeading} icon or the
+ * {@link TagDelete} button. Match the root's `label` prop: the announcement
+ * is named from it.
+ *
+ * @example
+ * ```tsx
+ * <Tag index={0} label="react" onDelete={() => remove('react')}>
+ *   <TagLabel>react</TagLabel>
+ *   <TagDelete>×</TagDelete>
+ * </Tag>
+ * ```
+ */
+export declare const TagLabel: React.ForwardRefExoticComponent<Omit<TagLabelProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/tag/TagLeading.d.cts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { TagLeadingProps } from './types.cjs';
+/**
+ * Icon or avatar slot before {@link Tag}'s text — lets skin size leading object and truncate label independently.
+ *
+ * Decorative by default (accessible name comes from root's `label`). Mark the icon `aria-hidden` unless it carries meaning the label doesn't.
+ *
+ * @example
+ * ```tsx
+ * <Tag index={0} label="react" onDelete={() => remove('react')}>
+ *   <TagLeading><ReactIcon aria-hidden /></TagLeading>
+ *   <TagLabel>react</TagLabel>
+ *   <TagDelete>×</TagDelete>
+ * </Tag>
+ * ```
+ */
+export declare const TagLeading: React.ForwardRefExoticComponent<Omit<TagLeadingProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/tag/TagLeading.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { TagLeadingProps } from './types.js';
+/**
+ * Icon or avatar slot before {@link Tag}'s text — lets skin size leading object and truncate label independently.
+ *
+ * Decorative by default (accessible name comes from root's `label`). Mark the icon `aria-hidden` unless it carries meaning the label doesn't.
+ *
+ * @example
+ * ```tsx
+ * <Tag index={0} label="react" onDelete={() => remove('react')}>
+ *   <TagLeading><ReactIcon aria-hidden /></TagLeading>
+ *   <TagLabel>react</TagLabel>
+ *   <TagDelete>×</TagDelete>
+ * </Tag>
+ * ```
+ */
+export declare const TagLeading: React.ForwardRefExoticComponent<Omit<TagLeadingProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/tag/index.d.cts

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

package/dist/tag/index.d.ts

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

package/dist/tag/primitives.d.cts

@@ -0,0 +1,19 @@
+/**
+ * Primitive components for building custom `Tag` layouts.
+ *
+ * @example
+ * ```tsx
+ * import { Tag, TagDelete, TagLabel, TagLeading } from '@skdx/react/primitives/tag';
+ *
+ * <Tag index={0} label="react" onDelete={() => remove('react')}>
+ *   <TagLeading><ReactIcon aria-hidden /></TagLeading>
+ *   <TagLabel>react</TagLabel>
+ *   <TagDelete>×</TagDelete>
+ * </Tag>
+ * ```
+ */
+export { Tag } from './Tag.cjs';
+export { TagDelete } from './TagDelete.cjs';
+export { TagLabel } from './TagLabel.cjs';
+export { TagLeading } from './TagLeading.cjs';
+export type { TagProps, TagDeleteEvent, TagDeleteProps, TagLabelProps, TagLeadingProps, } from './types.cjs';

package/dist/tag/primitives.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Primitive components for building custom `Tag` layouts.
+ *
+ * @example
+ * ```tsx
+ * import { Tag, TagDelete, TagLabel, TagLeading } from '@skdx/react/primitives/tag';
+ *
+ * <Tag index={0} label="react" onDelete={() => remove('react')}>
+ *   <TagLeading><ReactIcon aria-hidden /></TagLeading>
+ *   <TagLabel>react</TagLabel>
+ *   <TagDelete>×</TagDelete>
+ * </Tag>
+ * ```
+ */
+export { Tag } from './Tag.js';
+export { TagDelete } from './TagDelete.js';
+export { TagLabel } from './TagLabel.js';
+export { TagLeading } from './TagLeading.js';
+export type { TagProps, TagDeleteEvent, TagDeleteProps, TagLabelProps, TagLeadingProps, } from './types.js';

package/dist/tag/types.d.cts

@@ -1,28 +1,72 @@
-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. */
+import type * as React from 'react';
+import type { PolymorphicTag, PrimitivePropsWithRef } from '../utils/primitive.cjs';
+/**
+ * The cancelable `CustomEvent` a {@link TagProps.onDelete} handler receives, since
+ * no native event means "this tag asked to be removed".
+ *
+ * `preventDefault()` vetoes the consequences of removal, not the consumer's own
+ * state update: focus stays on this tag and nothing is announced — the veto a
+ * confirmation step needs.
+ */
+export type TagDeleteEvent = CustomEvent<null>;
+/** @internal Shared state distributed from Tag to its parts via context. */
 export interface TagContextValue {
-    /** The tag's own text, used to name the delete button. */
-    value: string;
+    /** The tag's own text, used to name the delete button and the removal announcement. */
+    label: string;
+    /** The word the delete button's generated name is built from — "Remove <label>". */
+    deleteLabel: 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. */
+    /** Whether this tag reads as chosen. */
+    selected: boolean;
+    /** Dispatches the cancelable `delete`; if it survives, moves focus to a neighbour and announces the removal. No-op when disabled or without `onDelete`. */
     remove: () => void;
+    /** Whether this tag sits inside a `TagGroup`. False when standalone, where removal has no group to resolve focus against. */
+    grouped: boolean;
 }
 /** 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.
+     * Element name to render instead of the default `<span>`, from the library's tag
+     * allowlist. Takes a tag name only, never a component. An element needing its own
+     * attributes (an `<a>` and its `href`) goes through `asChild`, which is fully
+     * typed and outranks `as` when both are set.
+     * @default 'span'
      */
-    index: number;
+    as?: PolymorphicTag;
     /**
-     * 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".
+     * This tag's position in the rendered list, deciding which tag owns the single
+     * Tab stop. Must match render order — the array index from the `map` that
+     * produced them. Not discovered from DOM order, which breaks under a virtualised
+     * list; the group warns when two mounted tags report the same `index`, which
+     * otherwise silently yields two Tab stops.
+     *
+     * Required inside a `TagGroup`, meaningless without one.
+     * @default undefined — standalone, with no roving order to take part in.
      */
-    value?: string;
+    index?: number;
+    /**
+     * This tag's text. Names the delete button (`Remove react`) and the removal
+     * announcement (`react removed`). Without it every delete button is announced
+     * as a bare "Remove", telling a screen-reader user nothing about what they are
+     * removing, and the removal is not announced at all.
+     *
+     * It is *not* rendered — pass the text as children too, or wrap it in a
+     * {@link TagLabel}.
+     * @default '' — the delete button is named just "Remove" and removal is silent.
+     */
+    label?: string;
+    /**
+     * Whether this tag reads as chosen, mirrored as `data-selected` for the
+     * skin's selected treatment.
+     *
+     * Presentation only: no ARIA selection state accompanies it. `aria-pressed`
+     * requires `role="button"` and `aria-selected` requires `role="option"`, and
+     * neither is permitted on the `listitem` a tag is. A tag whose selection must
+     * be *announced* has to say so in its own text.
+     * @default false
+     */
+    selected?: boolean;
     /**
      * 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`
@@ -31,13 +75,40 @@ export interface TagProps extends PrimitivePropsWithRef<'span'> {
      */
     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>`.
+     * Renders a leading `TagLeading` holding this content, before the label.
+     * Ignored when `children` is given.
+     * @default undefined — no leading slot rendered.
+     */
+    leading?: React.ReactNode;
+    /**
+     * Renders a derived `TagDelete`. Ignored when `children` is given.
+     * @default false
+     */
+    deletable?: boolean;
+    /**
+     * The word the derived `TagDelete`'s accessible name is built from —
+     * `"<deleteLabel> <label>"`.
+     * @default 'Remove'
+     */
+    deleteLabel?: string;
+    /**
+     * Removes this tag from whatever list the consumer renders it from.
+     *
+     * Receives a cancelable {@link TagDeleteEvent}. Call `preventDefault()` to hold
+     * the removal for a confirmation step: focus stays on this tag with nothing
+     * announced. Otherwise focus moves to a neighbouring tag and `"<label> removed"`
+     * is announced, both *after* this handler returns, 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;
+    onDelete?: (event: TagDeleteEvent) => void;
 }
 /** Props for {@link TagDelete}, the button that removes its parent {@link Tag}. */
 export interface TagDeleteProps extends PrimitivePropsWithRef<'button'> {
 }
+/** Props for {@link TagLeading}, the slot before a {@link Tag}'s label. */
+export interface TagLeadingProps extends PrimitivePropsWithRef<'span'> {
+}
+/** Props for {@link TagLabel}, the wrapper around a {@link Tag}'s visible text. */
+export interface TagLabelProps extends PrimitivePropsWithRef<'span'> {
+}

package/dist/tag/types.d.ts

@@ -1,28 +1,72 @@
-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. */
+import type * as React from 'react';
+import type { PolymorphicTag, PrimitivePropsWithRef } from '../utils/primitive.js';
+/**
+ * The cancelable `CustomEvent` a {@link TagProps.onDelete} handler receives, since
+ * no native event means "this tag asked to be removed".
+ *
+ * `preventDefault()` vetoes the consequences of removal, not the consumer's own
+ * state update: focus stays on this tag and nothing is announced — the veto a
+ * confirmation step needs.
+ */
+export type TagDeleteEvent = CustomEvent<null>;
+/** @internal Shared state distributed from Tag to its parts via context. */
 export interface TagContextValue {
-    /** The tag's own text, used to name the delete button. */
-    value: string;
+    /** The tag's own text, used to name the delete button and the removal announcement. */
+    label: string;
+    /** The word the delete button's generated name is built from — "Remove <label>". */
+    deleteLabel: 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. */
+    /** Whether this tag reads as chosen. */
+    selected: boolean;
+    /** Dispatches the cancelable `delete`; if it survives, moves focus to a neighbour and announces the removal. No-op when disabled or without `onDelete`. */
     remove: () => void;
+    /** Whether this tag sits inside a `TagGroup`. False when standalone, where removal has no group to resolve focus against. */
+    grouped: boolean;
 }
 /** 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.
+     * Element name to render instead of the default `<span>`, from the library's tag
+     * allowlist. Takes a tag name only, never a component. An element needing its own
+     * attributes (an `<a>` and its `href`) goes through `asChild`, which is fully
+     * typed and outranks `as` when both are set.
+     * @default 'span'
      */
-    index: number;
+    as?: PolymorphicTag;
     /**
-     * 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".
+     * This tag's position in the rendered list, deciding which tag owns the single
+     * Tab stop. Must match render order — the array index from the `map` that
+     * produced them. Not discovered from DOM order, which breaks under a virtualised
+     * list; the group warns when two mounted tags report the same `index`, which
+     * otherwise silently yields two Tab stops.
+     *
+     * Required inside a `TagGroup`, meaningless without one.
+     * @default undefined — standalone, with no roving order to take part in.
      */
-    value?: string;
+    index?: number;
+    /**
+     * This tag's text. Names the delete button (`Remove react`) and the removal
+     * announcement (`react removed`). Without it every delete button is announced
+     * as a bare "Remove", telling a screen-reader user nothing about what they are
+     * removing, and the removal is not announced at all.
+     *
+     * It is *not* rendered — pass the text as children too, or wrap it in a
+     * {@link TagLabel}.
+     * @default '' — the delete button is named just "Remove" and removal is silent.
+     */
+    label?: string;
+    /**
+     * Whether this tag reads as chosen, mirrored as `data-selected` for the
+     * skin's selected treatment.
+     *
+     * Presentation only: no ARIA selection state accompanies it. `aria-pressed`
+     * requires `role="button"` and `aria-selected` requires `role="option"`, and
+     * neither is permitted on the `listitem` a tag is. A tag whose selection must
+     * be *announced* has to say so in its own text.
+     * @default false
+     */
+    selected?: boolean;
     /**
      * 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`
@@ -31,13 +75,40 @@ export interface TagProps extends PrimitivePropsWithRef<'span'> {
      */
     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>`.
+     * Renders a leading `TagLeading` holding this content, before the label.
+     * Ignored when `children` is given.
+     * @default undefined — no leading slot rendered.
+     */
+    leading?: React.ReactNode;
+    /**
+     * Renders a derived `TagDelete`. Ignored when `children` is given.
+     * @default false
+     */
+    deletable?: boolean;
+    /**
+     * The word the derived `TagDelete`'s accessible name is built from —
+     * `"<deleteLabel> <label>"`.
+     * @default 'Remove'
+     */
+    deleteLabel?: string;
+    /**
+     * Removes this tag from whatever list the consumer renders it from.
+     *
+     * Receives a cancelable {@link TagDeleteEvent}. Call `preventDefault()` to hold
+     * the removal for a confirmation step: focus stays on this tag with nothing
+     * announced. Otherwise focus moves to a neighbouring tag and `"<label> removed"`
+     * is announced, both *after* this handler returns, 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;
+    onDelete?: (event: TagDeleteEvent) => void;
 }
 /** Props for {@link TagDelete}, the button that removes its parent {@link Tag}. */
 export interface TagDeleteProps extends PrimitivePropsWithRef<'button'> {
 }
+/** Props for {@link TagLeading}, the slot before a {@link Tag}'s label. */
+export interface TagLeadingProps extends PrimitivePropsWithRef<'span'> {
+}
+/** Props for {@link TagLabel}, the wrapper around a {@link Tag}'s visible text. */
+export interface TagLabelProps extends PrimitivePropsWithRef<'span'> {
+}