@nanisoft/prism-ui 0.13.0 → 0.16.0

package/dist/components/ui/tabs.d.ts

@@ -56,9 +56,28 @@ export interface TabsContentProps extends Omit<ComponentProps<'div'>, 'value'> {
  * process.
  */
 declare function Tabs({ className, ...props }: TabsProps): import("react").JSX.Element;
-/** The row or column of tab triggers. */
+/**
+ * The row or column of tab triggers.
+ *
+ * `pointer-coarse:h-13` is half of the coarse-pointer floor and it is the half that is
+ * easy to forget: the list is `h-9 p-1`, so its content box is 28 tall and a trigger
+ * grown to 44 would not fit inside it. `h-13` is 52, which is the trigger's 44 plus
+ * the list's own `p-1` on each side. The vertical orientation is exempt, because there
+ * the list is `h-fit flex-col` and each trigger sizes the row it is in. A band was
+ * rejected on condition 1 for the sharpest possible reason: the triggers sit a `gap-1`
+ * apart inside one list, so a band on one is a press aimed at its neighbour. See
+ * DESIGN.md, The coarse-pointer floor.
+ */
 declare function TabsList({ className, ...props }: TabsListProps): import("react").JSX.Element;
-/** One trigger in the tab list. */
+/**
+ * One trigger in the tab list.
+ *
+ * `pointer-coarse:h-11` is the other half of the floor. The trigger states its height
+ * through `py-1` and its content, so this states it outright rather than growing the
+ * padding to an implied 44: twelve pixels of padding either side of a twenty pixel
+ * line box is the floor reached by arithmetic, and an arithmetic floor is a number a
+ * later edit can change without noticing. See The coarse-pointer floor.
+ */
 declare function TabsTrigger({ className, ...props }: TabsTriggerProps): import("react").JSX.Element;
 /** The panel a trigger reveals. */
 declare function TabsContent({ className, ...props }: TabsContentProps): import("react").JSX.Element;

package/dist/components/ui/tabs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["../../../src/components/ui/tabs.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IACxE,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,iEAAiE;IACjE,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;CACxC;AAED,8CAA8C;AAC9C,MAAM,WAAW,aAAc,SAAQ,cAAc,CAAC,KAAK,CAAC;IAC1D,0EAA0E;IAC1E,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC/E,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAC5E,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;;;;;;;GAQG;AACH,iBAAS,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,SAAS,+BAQ/C;AAED,yCAAyC;AACzC,iBAAS,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,aAAa,+BAYvD;AAED,mCAAmC;AACnC,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,gBAAgB,+BAgB7D;AAED,mCAAmC;AACnC,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,gBAAgB,+BAQ7D;AAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,CAAA"}
+{"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["../../../src/components/ui/tabs.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IACxE,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,iEAAiE;IACjE,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;CACxC;AAED,8CAA8C;AAC9C,MAAM,WAAW,aAAc,SAAQ,cAAc,CAAC,KAAK,CAAC;IAC1D,0EAA0E;IAC1E,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC/E,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAC5E,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;;;;;;;GAQG;AACH,iBAAS,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,SAAS,+BAQ/C;AAED;;;;;;;;;;;GAWG;AACH,iBAAS,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,aAAa,+BAavD;AAED;;;;;;;;GAQG;AACH,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,gBAAgB,+BAiB7D;AAED,mCAAmC;AACnC,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,gBAAgB,+BAQ7D;AAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,CAAA"}

package/dist/components/ui/tabs.js

@@ -14,13 +14,32 @@ import { cn } from '../../lib/utils.js';
 function Tabs({ className, ...props }) {
     return (_jsx(TabsPrimitive.Root, { "data-slot": "tabs", className: cn('flex flex-col gap-2', className), ...props }));
 }
-/** The row or column of tab triggers. */
+/**
+ * The row or column of tab triggers.
+ *
+ * `pointer-coarse:h-13` is half of the coarse-pointer floor and it is the half that is
+ * easy to forget: the list is `h-9 p-1`, so its content box is 28 tall and a trigger
+ * grown to 44 would not fit inside it. `h-13` is 52, which is the trigger's 44 plus
+ * the list's own `p-1` on each side. The vertical orientation is exempt, because there
+ * the list is `h-fit flex-col` and each trigger sizes the row it is in. A band was
+ * rejected on condition 1 for the sharpest possible reason: the triggers sit a `gap-1`
+ * apart inside one list, so a band on one is a press aimed at its neighbour. See
+ * DESIGN.md, The coarse-pointer floor.
+ */
 function TabsList({ className, ...props }) {
-    return (_jsx(TabsPrimitive.List, { "data-slot": "tabs-list", className: cn('bg-muted text-muted-foreground inline-flex h-9 w-fit items-center justify-center gap-1 rounded-lg p-1', 'data-[orientation=vertical]:h-fit data-[orientation=vertical]:flex-col', className), ...props }));
+    return (_jsx(TabsPrimitive.List, { "data-slot": "tabs-list", className: cn('bg-muted text-muted-foreground inline-flex h-9 w-fit items-center justify-center gap-1 rounded-lg p-1', 'data-[orientation=vertical]:h-fit data-[orientation=vertical]:flex-col', 'pointer-coarse:h-13', className), ...props }));
 }
-/** One trigger in the tab list. */
+/**
+ * One trigger in the tab list.
+ *
+ * `pointer-coarse:h-11` is the other half of the floor. The trigger states its height
+ * through `py-1` and its content, so this states it outright rather than growing the
+ * padding to an implied 44: twelve pixels of padding either side of a twenty pixel
+ * line box is the floor reached by arithmetic, and an arithmetic floor is a number a
+ * later edit can change without noticing. See The coarse-pointer floor.
+ */
 function TabsTrigger({ className, ...props }) {
-    return (_jsx(TabsPrimitive.Tab, { "data-slot": "tabs-trigger", className: cn('text-foreground inline-flex flex-1 items-center justify-center gap-1.5 rounded-md px-3 py-1 text-sm font-medium whitespace-nowrap outline-none', 'transition-[color,box-shadow,background-color] duration-fast ease-out', 'focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'data-[active]:bg-background data-[active]:shadow-xs', 'data-[disabled]:pointer-events-none data-[disabled]:opacity-50', "[&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0", className), ...props }));
+    return (_jsx(TabsPrimitive.Tab, { "data-slot": "tabs-trigger", className: cn('text-foreground inline-flex flex-1 items-center justify-center gap-1.5 rounded-md px-3 py-1 text-sm font-medium whitespace-nowrap outline-none', 'transition-[color,box-shadow,background-color] duration-fast ease-out', 'focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'data-[active]:bg-background data-[active]:shadow-xs', 'data-[disabled]:pointer-events-none data-[disabled]:opacity-50', "[&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0", 'pointer-coarse:h-11', className), ...props }));
 }
 /** The panel a trigger reveals. */
 function TabsContent({ className, ...props }) {

package/dist/components/ui/tag-group.d.ts

@@ -0,0 +1,154 @@
+import { type ReactNode } from 'react';
+/**
+ * One tag in a group, and the tone it is drawn in.
+ *
+ * The tone is the caller's because it is a claim about the tag rather than about
+ * the design system: a skill, a recipient, a filter, and a licence key are all
+ * tags, and which of them deserves the destructive fill is the caller's decision
+ * about their own product. `neutral` is the answer when there is nothing to say,
+ * and it is the default for that reason.
+ */
+export type TagGroupTag = {
+    /**
+     * The caller's own identity for the tag, and what the remove control reports.
+     *
+     * Required, and required as a string rather than as the label: two tags can
+     * carry the same label, and a remove control that named the label would
+     * announce two identical buttons and leave the reader to guess which one they
+     * are on.
+     */
+    id: string;
+    /** What the chip says. A node, because a tag is often an avatar and a word. */
+    label: ReactNode;
+    /** The fill the chip is drawn in. */
+    tone?: 'neutral' | 'info' | 'success' | 'warning' | 'destructive';
+};
+/** The props a single Tag accepts. */
+export interface TagProps {
+    /** What the chip says. */
+    label: ReactNode;
+    /** The fill the chip is drawn in. */
+    tone?: TagGroupTag['tone'];
+    /**
+     * Called when the reader presses the remove control.
+     *
+     * Omit it and the chip is read-only, which is a legitimate state rather than a
+     * missing prop. See the note on `TagGroup` for the difference between a tag
+     * and a badge.
+     */
+    onRemove?: () => void;
+    /**
+     * The accessible name of the remove control, naming the tag it removes.
+     *
+     * Required whenever `onRemove` is given, and the Component throws without it
+     * rather than drawing a button it cannot name.
+     */
+    removeLabel?: string;
+    /** Layout only. */
+    className?: string;
+}
+/** The props a TagGroup accepts. */
+export interface TagGroupProps {
+    /**
+     * The tags, in the order a reader should meet them.
+     *
+     * Required, and order is the caller's because it is a claim about importance.
+     * The group wraps onto the next line rather than truncating, so a set of
+     * thirty tags is thirty tags and not the first eight.
+     */
+    tags: TagGroupTag[];
+    /**
+     * Called with a tag's `id` when the reader removes it.
+     *
+     * Omit it and the group is read-only, which is a legitimate state rather than a
+     * missing prop: a set of tags that were applied for the reader rather than
+     * chosen by them is a set of tags nobody can take back, and drawing a remove
+     * control there would promise a freedom the field does not have.
+     */
+    onRemove?: (id: string) => void;
+    /**
+     * The accessible name of one tag's remove control, given that tag's label.
+     *
+     * Required whenever `onRemove` is given, and a function rather than a string
+     * for a reason Prism cannot design around: a tag's label is a node, so the
+     * name of the control that removes it cannot be composed from it. A tag that
+     * shows an avatar and a word has no string to interpolate, and one that shows
+     * a word and a count has a count the reader needs to hear in the name of the
+     * control that will take it away. The Component refuses rather than guessing,
+     * because the guess is a nameless button in every locale but one.
+     */
+    removeLabel?: (label: ReactNode) => string;
+    /**
+     * The group's own name, drawn above the tags and used as its accessible name.
+     *
+     * A node and not a string, so the same element that a sighted reader reads is
+     * the one a screen reader names the group by. Without it the group is
+     * announced as an unlabelled group, which tells a reader nothing about why
+     * these particular tags are collected together.
+     */
+    label?: ReactNode;
+    /**
+     * What to draw when there are no tags.
+     *
+     * An empty group with no `empty` renders nothing at all, which is the same
+     * choice `FactList` makes: a bordered box with a heading above it and nothing
+     * inside it reads as a rendering failure rather than as an absence. Never a
+     * placeholder chip: a chip that is not a tag, drawn where tags go, is a thing
+     * a reader tries to remove.
+     */
+    empty?: ReactNode;
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * A wrapping row of tags the reader chose, each of which can be taken back.
+ *
+ * **A Tag is what the reader chose; a Badge is what they are told.** That is the
+ * whole difference between this and `badge.tsx`, and the remove control is all
+ * of it. A badge carries a status the system decided: a count, a plan name, a
+ * licence tier. A tag carries something the reader picked and can un-pick, and
+ * the control that un-picks it is the reason the two are different Components.
+ * Folding them together would mean either a badge with a remove control on it,
+ * which offers the reader a freedom the status does not have, or a tag with no
+ * remove control on it, which is a badge that happens to be round.
+ *
+ * **A group with no `onRemove` is read-only, and that is a legitimate state.**
+ * A set of tags applied for the reader, by an import, by a colleague or by a
+ * saved filter, is a real thing, and the honest way to draw it is as tags with
+ * no way to take one back. What is not honest is drawing the remove control
+ * anyway and having it do nothing, so the control is drawn exactly when
+ * `onRemove` is given. `TagGroup` throws if it is given one without `removeLabel`
+ * rather than shipping a nameless button.
+ *
+ * **The remove control's name has to name the tag, so it cannot be composed.**
+ * A tag's label is a node because a tag is often an avatar and a word, and the
+ * accessible name of the control that removes it has to include that word. Prism
+ * cannot interpolate a `ReactNode` into a sentence, so it asks for a function of
+ * the label instead of a template it fills in. The cost is real: every caller
+ * writes the sentence, once, in their own language, and a caller who has four
+ * tag groups writes it four times or writes it once and reuses it.
+ *
+ * **The group wraps and the label sits on its own line.** Tags accumulate, and a
+ * row that clipped or scrolled would hide tags a reader had chosen and cannot
+ * see. A group that reaches the end of its container starts a new line, so the
+ * set stays whole and the layout above it is the caller's to decide.
+ *
+ * It carries no directive. It holds no state: which tags exist and which one is
+ * being removed are the caller's, so the group is the same code whether the
+ * caller is a server component rendering a saved filter or a client component
+ * holding a form.
+ */
+declare function TagGroup({ tags, onRemove, removeLabel, label, empty, className, }: TagGroupProps): import("react").JSX.Element | null;
+/**
+ * One tag on its own, for a caller placing a chip where no group is wanted.
+ *
+ * Everything said about a tag in `TagGroup` applies here, and the reason it is
+ * exported at all is that a chip has uses a group does not cover: the selected
+ * option in a combobox row, the one filter a panel is showing on its own, a
+ * token in a text field's own row. Each of those is one chip, and wrapping a
+ * single chip in a group would draw a label and a role the caller did not ask
+ * for.
+ */
+declare function Tag({ label, tone, onRemove, removeLabel, className, }: TagProps): import("react").JSX.Element;
+export { TagGroup, Tag };
+//# sourceMappingURL=tag-group.d.ts.map

package/dist/components/ui/tag-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-group.d.ts","sourceRoot":"","sources":["../../../src/components/ui/tag-group.tsx"],"names":[],"mappings":"AACA,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAI7C;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;;;;;;;OAOG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,+EAA+E;IAC/E,KAAK,EAAE,SAAS,CAAA;IAChB,qCAAqC;IACrC,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAA;CAClE,CAAA;AAED,sCAAsC;AACtC,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,KAAK,EAAE,SAAS,CAAA;IAChB,qCAAqC;IACrC,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,oCAAoC;AACpC,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,IAAI,EAAE,WAAW,EAAE,CAAA;IACnB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,MAAM,CAAA;IAC1C;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAmCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,iBAAS,QAAQ,CAAC,EAChB,IAAI,EACJ,QAAQ,EACR,WAAW,EACX,KAAK,EACL,KAAK,EACL,SAAS,GACV,EAAE,aAAa,sCAsDf;AAED;;;;;;;;;GASG;AACH,iBAAS,GAAG,CAAC,EACX,KAAK,EACL,IAAgB,EAChB,QAAQ,EACR,WAAW,EACX,SAAS,GACV,EAAE,QAAQ,+BAmCV;AAED,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAA"}

package/dist/components/ui/tag-group.js

@@ -0,0 +1,111 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { XIcon } from 'lucide-react';
+import { useId } from 'react';
+import { cn } from '../../lib/utils.js';
+/**
+ * The five fills a chip is drawn in, and nothing else.
+ *
+ * A tone names an intent and every one of them is a semantic utility, so a chip
+ * in a scoped pack boundary re-inks with everything around it. `info` is the
+ * brand hue at a tenth's strength with a border at four tenths, because the
+ * contract publishes no information role and inventing one here would be a
+ * second place a new colour gets decided.
+ */
+const TAG_TONE = {
+    neutral: 'bg-secondary text-secondary-foreground border-transparent',
+    info: 'bg-brand-ink/10 text-foreground border-brand-ink/40',
+    success: 'bg-success text-success-foreground border-transparent',
+    warning: 'bg-warning text-warning-foreground border-transparent',
+    destructive: 'bg-destructive text-destructive-foreground border-transparent',
+};
+/**
+ * The remove control, drawn once and shared by the group and the lone chip.
+ *
+ * The ink is left to the chip's tone: the control changes its opacity and its
+ * ring and never its colour, because a control that has to know which of five
+ * fills it is sitting on is a control whose contrast has to be checked five
+ * times and is right in none of them by default.
+ *
+ * On a coarse pointer the control takes the 44px floor and the chip grows to
+ * hold it, so a row of tags on a phone is a row of 44px pills. That is the price
+ * of the floor and it is paid visibly: the alternative is a 16px target sitting
+ * 4px from a label the reader also wants to press.
+ */
+const REMOVE_CONTROL = 'inline-flex size-4 shrink-0 items-center justify-center rounded-sm opacity-70 outline-none transition-opacity duration-fast ease-out pointer-coarse:size-11 hover:opacity-100 focus-visible:opacity-100 focus-visible:ring-ring focus-visible:ring-[3px]';
+/**
+ * A wrapping row of tags the reader chose, each of which can be taken back.
+ *
+ * **A Tag is what the reader chose; a Badge is what they are told.** That is the
+ * whole difference between this and `badge.tsx`, and the remove control is all
+ * of it. A badge carries a status the system decided: a count, a plan name, a
+ * licence tier. A tag carries something the reader picked and can un-pick, and
+ * the control that un-picks it is the reason the two are different Components.
+ * Folding them together would mean either a badge with a remove control on it,
+ * which offers the reader a freedom the status does not have, or a tag with no
+ * remove control on it, which is a badge that happens to be round.
+ *
+ * **A group with no `onRemove` is read-only, and that is a legitimate state.**
+ * A set of tags applied for the reader, by an import, by a colleague or by a
+ * saved filter, is a real thing, and the honest way to draw it is as tags with
+ * no way to take one back. What is not honest is drawing the remove control
+ * anyway and having it do nothing, so the control is drawn exactly when
+ * `onRemove` is given. `TagGroup` throws if it is given one without `removeLabel`
+ * rather than shipping a nameless button.
+ *
+ * **The remove control's name has to name the tag, so it cannot be composed.**
+ * A tag's label is a node because a tag is often an avatar and a word, and the
+ * accessible name of the control that removes it has to include that word. Prism
+ * cannot interpolate a `ReactNode` into a sentence, so it asks for a function of
+ * the label instead of a template it fills in. The cost is real: every caller
+ * writes the sentence, once, in their own language, and a caller who has four
+ * tag groups writes it four times or writes it once and reuses it.
+ *
+ * **The group wraps and the label sits on its own line.** Tags accumulate, and a
+ * row that clipped or scrolled would hide tags a reader had chosen and cannot
+ * see. A group that reaches the end of its container starts a new line, so the
+ * set stays whole and the layout above it is the caller's to decide.
+ *
+ * It carries no directive. It holds no state: which tags exist and which one is
+ * being removed are the caller's, so the group is the same code whether the
+ * caller is a server component rendering a saved filter or a client component
+ * holding a form.
+ */
+function TagGroup({ tags, onRemove, removeLabel, label, empty, className, }) {
+    const generated = useId();
+    const labelId = `${generated}-label`;
+    if (onRemove !== undefined && removeLabel === undefined) {
+        throw new Error('TagGroup: a removable group needs removeLabel, because the accessible name of a remove control has ' +
+            'to name the tag it removes and this Component cannot compose a name from a ReactNode. Pass a ' +
+            'function of the tag label, or drop onRemove for a group the reader cannot change.');
+    }
+    if (tags.length === 0 && empty === undefined)
+        return null;
+    return (_jsxs("div", { "data-slot": "tag-group", role: "group", "aria-labelledby": label === undefined ? undefined : labelId, className: cn('flex flex-wrap items-center gap-1.5', className), children: [label === undefined ? null : (_jsx("span", { id: labelId, "data-slot": "tag-group-label", className: "text-muted-foreground w-full text-xs font-medium tracking-wide uppercase", children: label })), tags.length === 0 ? (_jsx("p", { "data-slot": "tag-group-empty", className: "text-muted-foreground text-sm", children: empty })) : (tags.map((tag) => (_jsx(Tag, { label: tag.label, tone: tag.tone, ...(onRemove === undefined
+                    ? null
+                    : {
+                        onRemove: () => onRemove(tag.id),
+                        // The throw above is what makes this call total. The compiler
+                        // cannot see it, so the optional call is the shape that is
+                        // honest at the type level and unreachable at the run level.
+                        removeLabel: removeLabel?.(tag.label),
+                    }) }, tag.id))))] }));
+}
+/**
+ * One tag on its own, for a caller placing a chip where no group is wanted.
+ *
+ * Everything said about a tag in `TagGroup` applies here, and the reason it is
+ * exported at all is that a chip has uses a group does not cover: the selected
+ * option in a combobox row, the one filter a panel is showing on its own, a
+ * token in a text field's own row. Each of those is one chip, and wrapping a
+ * single chip in a group would draw a label and a role the caller did not ask
+ * for.
+ */
+function Tag({ label, tone = 'neutral', onRemove, removeLabel, className, }) {
+    if (onRemove !== undefined && removeLabel === undefined) {
+        throw new Error('Tag: a removable tag needs removeLabel, because a remove control with no accessible name is ' +
+            'announced as a button and nothing else. Pass the name for this tag, or drop onRemove for a ' +
+            'read-only chip.');
+    }
+    return (_jsxs("span", { "data-slot": "tag", "data-tone": tone, className: cn('inline-flex max-w-full items-center gap-1 rounded-md border px-2 py-0.5 text-xs font-medium', TAG_TONE[tone], className), children: [_jsx("span", { "data-slot": "tag-label", className: "min-w-0 truncate", children: label }), onRemove === undefined ? null : (_jsx("button", { type: "button", "data-slot": "tag-remove", "aria-label": removeLabel, onClick: onRemove, className: REMOVE_CONTROL, children: _jsx(XIcon, { className: "size-3", "aria-hidden": "true" }) }))] }));
+}
+export { TagGroup, Tag };

package/dist/components/ui/task-progress.d.ts

@@ -0,0 +1,149 @@
+import type { ReactNode } from 'react';
+/**
+ * Where a task is, as one value the caller holds.
+ *
+ * Four positions and a union, for the reason `LifecycleButtonState` states in
+ * full: a boolean has two answers, and the two this cannot express are the two
+ * that cost the most. A task that failed is not "running: false", and a task
+ * whose position is known is not a spinner. Encoding four positions across a
+ * boolean and a number puts them in two props that do not know about each other,
+ * and every consumer then draws all four combinations itself.
+ *
+ * `idle` exists so a caller can hold a resting position in the same state it
+ * holds the other three, rather than unmounting on the transitions it did not
+ * expect. See the JSDoc on the Component for what `idle` draws, which is nothing.
+ */
+export type TaskProgressPhase = 
+/** Nothing has been asked, or nothing is running. This Component draws no bar. */
+{
+    phase: 'idle';
+}
+/**
+ * The task is running.
+ *
+ * `progress` is a real measurement rather than a clock: a byte count, a row
+ * count or a completed-step count gives a ratio, and the reader is told the
+ * position. Omit it and the work is of unknown length, which is a different
+ * fact and is drawn and announced as such.
+ */
+ | {
+    phase: 'running';
+    progress?: number;
+    progressText?: string;
+}
+/** The task finished, with the caller's own sentence about what it did. */
+ | {
+    phase: 'succeeded';
+    outcome: ReactNode;
+}
+/** The task did not finish, with the caller's own sentence about why. */
+ | {
+    phase: 'failed';
+    reason: ReactNode;
+};
+/**
+ * The props the Task progress accepts.
+ *
+ * A declared interface rather than a forwarded native one. There is no single
+ * element to forward to, because the Component draws a line, a bar and an
+ * announcement, and it takes no callback at all, so there is nothing for a
+ * forwarded handler to add.
+ */
+export interface TaskProgressProps {
+    /**
+     * Where the task is.
+     *
+     * Required and controlled, and the whole of the Component: the caller owns the
+     * request, so the caller owns where the request is. Prism draws the line, the
+     * mark, the bar and the announcement that a position implies, and calls nothing.
+     * It never moves the position, holds no promise and runs no clock.
+     */
+    phase: TaskProgressPhase;
+    /**
+     * What the task is, read beside the bar and at the outcome.
+     *
+     * Required, and a `ReactNode` because a caller's task is often more than a
+     * word: "Exporting 12 invoices", "Rebuilding the estate index". It is drawn
+     * rather than derived, because a Component cannot describe work it has not been
+     * told about.
+     */
+    label: ReactNode;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+}
+/**
+ * One line that follows a pending task from start to resolution, and announces the
+ * outcome.
+ *
+ * **It is the running state and not the control that starts it.**
+ * `LifecycleButton` is the button a reader presses to begin a save, a publish or
+ * an export, and it carries the label, the mark, the meter, the failure and the
+ * retry because all of those belong to a control somebody is looking at. This is
+ * the other half: a task the caller started somewhere else, or started on a
+ * schedule, or started on another device, whose position the reader has to be able
+ * to find without hunting for the control that began it. The difference is not
+ * that one has a bar and the other does not; both draw a bar. The difference is
+ * that this Component has no `onActivate`, no retry and no idle label, because a
+ * line is not something a reader presses, and a control that pressed nothing is a
+ * control that lies. A caller who wants both in one place composes the two.
+ *
+ * **The bar exists only while the task is running, and that is the honest shape.**
+ * A bar at one hundred percent is a measurement of nothing, and it would sit on
+ * the page until the caller cleared it while the outcome line said what actually
+ * happened. So the bar is the running position's own, it leaves with it, and the
+ * settled positions draw the caller's sentence and a mark. The cost is that a
+ * reader watching a long task sees no completion bar to watch reach the end; the
+ * announcement is what tells them, and that is the same arrangement
+ * `LifecycleButton` settles at.
+ *
+ * **`idle` renders nothing, and the reason is the same one `LiveRegion` gives.**
+ * A Component holding a task that is not running has nothing to report, and a bar
+ * at zero is a claim that work is in progress. So the resting position draws no
+ * element, which also means a caller that wants the task's name visible before it
+ * starts draws the name themselves. **The cost is that this Component cannot be
+ * the only thing on the page**, because a line that vanishes is a line whose
+ * arrival shifts the layout around it, and a caller who needs the space held
+ * reserves it.
+ *
+ * **The determinate fill is legal motion, and the reason is that it is bound to a
+ * real state transition.** The bar is `Progress`, which eases its width on the
+ * base duration; there is no keyframe, no loop and no cycle anywhere in this
+ * Component, because a bar that is moving because a number changed is state
+ * feedback under the first of the two motion laws in this system and nothing
+ * else. A task with no number is drawn and announced as indeterminate, and the
+ * Component refuses to fill a bar it has no number for: the refusal is a thrown
+ * diagnostic rather than a silently invented position.
+ *
+ * **`Progress` and `LiveRegion` are composed, not redrawn, and the reason the
+ * outcome is announced at all is that the control is not on screen.** A reader who
+ * started a task, watched it run and looked away has had no answer, and the
+ * settled line is often the only evidence on the page that anything happened. So
+ * the outcome goes through a live region, polite for a success because a finished
+ * export waits its turn, and assertive for a failure because a refused one does
+ * not. The reason line beneath is deliberately not an alert, so a failure is
+ * announced once rather than twice in the same commit.
+ *
+ * **The region is mounted at the outcome rather than held empty, and the cost is
+ * real.** `LiveRegion` deliberately renders nothing when it has nothing to say,
+ * because a region sitting on the page permanently announces unrelated changes of
+ * its ancestors. The consequence is that this region is created at the moment of
+ * its content, and a live region created with its content is announced by most
+ * screen readers and not by all of them. A caller who needs the guarantee on every
+ * transition keeps a `LiveRegion` of their own beside this Component and passes
+ * the outcome into it, which is two lines and no override of anything here.
+ *
+ * **It is a server Component**, and that is a deliberate claim rather than an
+ * accident. It holds no state, runs no hook, reads no context and takes no
+ * handler: the only callback-shaped thing here is the caller's `phase`, which is
+ * data. The two Components it composes carry the client work between them, so
+ * `Progress` is a client island inside a server line and `LiveRegion` needs no
+ * JavaScript at all, because a live region is announced by the browser's own
+ * mutation observer. What that costs is that the caller owns the transition, so a
+ * caller who moves the phase from a response handler is already in the client
+ * graph and pays for it there; a caller who moves it on a server action gets the
+ * line redrawn with no announcement, which is the ordinary case for a page load
+ * and the wrong case for a task that finished while the reader was on the page.
+ */
+declare function TaskProgress({ phase, label, className }: TaskProgressProps): import("react").JSX.Element | null;
+export { TaskProgress };
+//# sourceMappingURL=task-progress.d.ts.map

package/dist/components/ui/task-progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-progress.d.ts","sourceRoot":"","sources":["../../../src/components/ui/task-progress.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAMtC;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB;AAC3B,kFAAkF;AAChF;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE;AACnB;;;;;;;GAOG;GACD;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE;AAChE,2EAA2E;GACzE;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,SAAS,CAAA;CAAE;AAC5C,yEAAyE;GACvE;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAA;AAE1C;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;OAOG;IACH,KAAK,EAAE,iBAAiB,CAAA;IACxB;;;;;;;OAOG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,iBAAS,YAAY,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,iBAAiB,sCAyDnE;AAED,OAAO,EAAE,YAAY,EAAE,CAAA"}

package/dist/components/ui/task-progress.js

@@ -0,0 +1,110 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CircleCheckIcon, TriangleAlertIcon } from 'lucide-react';
+import { LiveRegion } from './live-region.js';
+import { Progress } from './progress.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The mark each settled position carries, and the ink it is drawn in.
+ *
+ * Two entries and not four, because the running position carries a bar rather
+ * than a mark, and a ring beside a line that already says what is happening is a
+ * second copy of a sentence the reader can already see. The inks are the semantic
+ * state roles rather than a ramp step, and the shapes differ as well as the
+ * colours, so a reader who cannot separate them still reads which is which.
+ */
+const SETTLED_MARK = {
+    succeeded: { Mark: CircleCheckIcon, ink: 'text-success' },
+    failed: { Mark: TriangleAlertIcon, ink: 'text-destructive' },
+};
+/**
+ * One line that follows a pending task from start to resolution, and announces the
+ * outcome.
+ *
+ * **It is the running state and not the control that starts it.**
+ * `LifecycleButton` is the button a reader presses to begin a save, a publish or
+ * an export, and it carries the label, the mark, the meter, the failure and the
+ * retry because all of those belong to a control somebody is looking at. This is
+ * the other half: a task the caller started somewhere else, or started on a
+ * schedule, or started on another device, whose position the reader has to be able
+ * to find without hunting for the control that began it. The difference is not
+ * that one has a bar and the other does not; both draw a bar. The difference is
+ * that this Component has no `onActivate`, no retry and no idle label, because a
+ * line is not something a reader presses, and a control that pressed nothing is a
+ * control that lies. A caller who wants both in one place composes the two.
+ *
+ * **The bar exists only while the task is running, and that is the honest shape.**
+ * A bar at one hundred percent is a measurement of nothing, and it would sit on
+ * the page until the caller cleared it while the outcome line said what actually
+ * happened. So the bar is the running position's own, it leaves with it, and the
+ * settled positions draw the caller's sentence and a mark. The cost is that a
+ * reader watching a long task sees no completion bar to watch reach the end; the
+ * announcement is what tells them, and that is the same arrangement
+ * `LifecycleButton` settles at.
+ *
+ * **`idle` renders nothing, and the reason is the same one `LiveRegion` gives.**
+ * A Component holding a task that is not running has nothing to report, and a bar
+ * at zero is a claim that work is in progress. So the resting position draws no
+ * element, which also means a caller that wants the task's name visible before it
+ * starts draws the name themselves. **The cost is that this Component cannot be
+ * the only thing on the page**, because a line that vanishes is a line whose
+ * arrival shifts the layout around it, and a caller who needs the space held
+ * reserves it.
+ *
+ * **The determinate fill is legal motion, and the reason is that it is bound to a
+ * real state transition.** The bar is `Progress`, which eases its width on the
+ * base duration; there is no keyframe, no loop and no cycle anywhere in this
+ * Component, because a bar that is moving because a number changed is state
+ * feedback under the first of the two motion laws in this system and nothing
+ * else. A task with no number is drawn and announced as indeterminate, and the
+ * Component refuses to fill a bar it has no number for: the refusal is a thrown
+ * diagnostic rather than a silently invented position.
+ *
+ * **`Progress` and `LiveRegion` are composed, not redrawn, and the reason the
+ * outcome is announced at all is that the control is not on screen.** A reader who
+ * started a task, watched it run and looked away has had no answer, and the
+ * settled line is often the only evidence on the page that anything happened. So
+ * the outcome goes through a live region, polite for a success because a finished
+ * export waits its turn, and assertive for a failure because a refused one does
+ * not. The reason line beneath is deliberately not an alert, so a failure is
+ * announced once rather than twice in the same commit.
+ *
+ * **The region is mounted at the outcome rather than held empty, and the cost is
+ * real.** `LiveRegion` deliberately renders nothing when it has nothing to say,
+ * because a region sitting on the page permanently announces unrelated changes of
+ * its ancestors. The consequence is that this region is created at the moment of
+ * its content, and a live region created with its content is announced by most
+ * screen readers and not by all of them. A caller who needs the guarantee on every
+ * transition keeps a `LiveRegion` of their own beside this Component and passes
+ * the outcome into it, which is two lines and no override of anything here.
+ *
+ * **It is a server Component**, and that is a deliberate claim rather than an
+ * accident. It holds no state, runs no hook, reads no context and takes no
+ * handler: the only callback-shaped thing here is the caller's `phase`, which is
+ * data. The two Components it composes carry the client work between them, so
+ * `Progress` is a client island inside a server line and `LiveRegion` needs no
+ * JavaScript at all, because a live region is announced by the browser's own
+ * mutation observer. What that costs is that the caller owns the transition, so a
+ * caller who moves the phase from a response handler is already in the client
+ * graph and pays for it there; a caller who moves it on a server action gets the
+ * line redrawn with no announcement, which is the ordinary case for a page load
+ * and the wrong case for a task that finished while the reader was on the page.
+ */
+function TaskProgress({ phase, label, className }) {
+    if (phase.phase === 'idle')
+        return null;
+    if (phase.phase === 'running' && phase.progress !== undefined && phase.progressText === undefined) {
+        throw new Error('TaskProgress: the running phase carries a progress fraction and no progressText, so the bar would be ' +
+            'announced as a decimal between zero and one, which is a measurement of nothing a reader can act on. ' +
+            'Pass the position in the words the reader would say it, or drop progress and let the bar be indeterminate.');
+    }
+    const running = phase.phase === 'running';
+    const settled = phase.phase === 'succeeded' || phase.phase === 'failed';
+    const mark = settled ? SETTLED_MARK[phase.phase] : null;
+    const outcome = phase.phase === 'succeeded' ? phase.outcome : phase.phase === 'failed' ? phase.reason : undefined;
+    return (_jsxs("div", { "data-slot": "task-progress", className: cn('flex w-full flex-col gap-1.5', className), children: [_jsxs("div", { "data-slot": "task-progress-line", className: "flex items-center gap-2", children: [mark === null ? null : _jsx(mark.Mark, { className: mark.ink, "aria-hidden": "true" }), _jsx("span", { "data-slot": "task-progress-label", className: "text-sm font-medium", children: label })] }), running ? (_jsx(Progress, { "data-slot": "task-progress-bar", 
+                // The clamped fraction and the same Component with no value, so the two
+                // are one question asked with and without an answer rather than a bar
+                // and a ring on one line.
+                value: phase.progress === undefined ? null : Math.min(1, Math.max(0, phase.progress)), max: 1, valueText: phase.progressText })) : null, outcome === undefined ? null : (_jsx("p", { "data-slot": "task-progress-outcome", className: "text-muted-foreground text-sm", children: outcome })), settled ? (_jsx(LiveRegion, { className: "sr-only", politeness: phase.phase === 'failed' ? 'assertive' : 'polite', children: outcome })) : null] }));
+}
+export { TaskProgress };