@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/components/ui/prompt-composer.d.ts

@@ -0,0 +1,302 @@
+import { type ReactNode } from 'react';
+/**
+ * The five points a request can be at.
+ *
+ * A closed set of five, and the fifth is the one that makes it a lifecycle rather
+ * than a flag. A request that is being sent, a request whose answer is arriving
+ * one piece at a time, and a request that has ended are three different situations
+ * with three different affordances, and the difference between them is not a
+ * matter of degree: there is nothing to stop in the first and everything to stop in
+ * the second, and a surface that has only a busy flag has to pretend otherwise.
+ * `failed` and `done` are the two ends of the answer, and they are separate
+ * members rather than one `finished` flag because a request that ended and a
+ * request that ended badly call for different words and different next actions.
+ */
+export type PromptComposerPhase = 'idle' | 'sending' | 'streaming' | 'done' | 'failed';
+/**
+ * Where the request is, as a value the caller holds.
+ *
+ * A union rather than a `phase` prop beside four booleans, and the reason is that
+ * four booleans can say things this type cannot. `sending` and `streaming` are
+ * mutually exclusive, `failed` and `done` are mutually exclusive, and an optional
+ * prop set cannot say either. A boolean is a fact about one axis, and a lifecycle
+ * is a position on one line, so the line is what the value is. A caller that
+ * switched exhaustively over it is broken by a sixth state later rather than
+ * rendering a control that is two things at once.
+ */
+export type PromptComposerState = 
+/** Nothing has been asked, and the request field is the reader's to write in. */
+{
+    phase: 'idle';
+}
+/** The request is on its way and no part of the answer has arrived. */
+ | {
+    phase: 'sending';
+}
+/** Part of the answer has arrived and more is coming. */
+ | {
+    phase: 'streaming';
+}
+/** The answer is complete. */
+ | {
+    phase: 'done';
+}
+/** The request ended badly, with the caller's own sentence about why. */
+ | {
+    phase: 'failed';
+    reason?: ReactNode;
+};
+/**
+ * One thing attached to the request, and the two things the tray knows about it.
+ *
+ * A reference and not a file, for the reason `ImageListField` states at length:
+ * what a composer holds is whatever the caller's own store calls this thing, and a
+ * `File` object would make the tray meaningful only on the machine that produced
+ * it. There is no size and no transfer state, because an attachment in a prompt is
+ * usually already in the caller's storage and a byte count for it is a measurement
+ * of something the reader did not choose to see.
+ */
+export type PromptComposerAttachment = {
+    /**
+     * The caller's own identity for the attachment, and what the remove control
+     * reports.
+     *
+     * Required, and a string rather than the name: a reader can attach the same
+     * document twice, and two remove controls announcing the same name are two
+     * controls nobody can tell apart.
+     */
+    id: string;
+    /** The name a reader recognises the attachment by. */
+    name: string;
+};
+/**
+ * The props the Prompt composer accepts.
+ *
+ * A declared interface rather than a forwarded native one, and the reason is
+ * visible in the list: every one of these is either a state the caller holds or a
+ * sentence the caller owns, and there is no native attribute left over once the
+ * fourteen are spent.
+ */
+export interface PromptComposerProps {
+    /**
+     * The request field's name, drawn above it and used as the name of the whole
+     * region.
+     *
+     * A `ReactNode` and not a string, because the element a sighted reader reads is
+     * the element a screen reader names the region by, and the two cannot drift
+     * when they are one node. Write it as the question the reader is about to ask:
+     * "What should the agent do?", or "Message the pipeline".
+     */
+    label: ReactNode;
+    /**
+     * Where the request is.
+     *
+     * Required and controlled, and the whole of the Component's reason to be
+     * separate from a form field: the lifecycle is the caller's, because the request
+     * is the caller's, and a Component that held the state would hold the transport
+     * with it. Prism draws the affordances a position implies and calls the four
+     * callbacks; it never moves the position itself.
+     */
+    state: PromptComposerState;
+    /**
+     * The request text.
+     *
+     * Controlled, and not held here, for the same reason the position is not. A
+     * composer whose draft lives inside a design system is a draft a caller cannot
+     * seed from a conversation, cannot restore from a store, cannot count tokens
+     * against, and cannot clear when a send succeeds without the Component offering
+     * a prop for it. Every one of those is a decision about the caller's product.
+     */
+    text: string;
+    /**
+     * Called with the whole request text on every keystroke.
+     *
+     * The value rather than the change, because a controlled field whose callback
+     * reports a delta is a field whose caller has to reconstruct the value to know
+     * what it is now, and every one of them does.
+     */
+    onTextChange: (text: string) => void;
+    /**
+     * Called with the request text when the reader asks for the request to be made.
+     *
+     * Takes the text rather than reading it from a field, so the callback is the
+     * caller's whole input and the Component holds nothing. The caller decides what
+     * happens next, which in practice means moving the position to `sending`.
+     */
+    onSubmit: (text: string) => void;
+    /**
+     * Called when the reader stops a request that is still arriving.
+     *
+     * Required rather than optional, and the reason is the lifecycle. The union names
+     * `streaming`, so a caller who reaches that position owes a way out of it, and a
+     * Component that rendered a state it had no exit for would be a surface where a
+     * reader's request runs on with no way to end it. Prism has no opinion about
+     * what stopping means: an abort on the caller's transport, a socket closed, a
+     * value discarded. It draws the control and calls this.
+     */
+    onStop: () => void;
+    /**
+     * Called when the reader asks for the failed request to be made again.
+     *
+     * Required for the same argument as `onStop`, over `failed`. A failure with no
+     * way to try again is a dead end, and the affordance belongs here rather than
+     * beside the send control because the two actions are not the same: retrying is
+     * a claim that the same request is worth making again, and sending is a claim
+     * that a different one is.
+     */
+    onRetry: () => void;
+    /**
+     * The visible label of the send control, in the product's own words.
+     *
+     * Required and never defaulted: "Send", "Run the agent" and "Enviar" are three
+     * products' answers, and a reader who cannot tell what a control will do before
+     * pressing it will press it to find out.
+     */
+    sendLabel: ReactNode;
+    /**
+     * The visible label of the stop control, shown only while a request is streaming.
+     *
+     * Required even though the control exists in one position out of five, for the
+     * same reason `Spinner`'s label is: a shared library cannot know whether the
+     * reader is stopping a request, a job or a transfer, and "Stop" alone is a
+     * weaker name than "Stop generating".
+     */
+    stopLabel: ReactNode;
+    /**
+     * The visible label of the retry control, shown only after a failure.
+     *
+     * Required, and worth writing with the cost in it where there is one: "Try
+     * again" for a request that may succeed unchanged, and "Try again, shorter" when
+     * a length limit is the likely cause.
+     */
+    retryLabel: ReactNode;
+    /**
+     * The visible label of the attach control, in the product's own words.
+     *
+     * Required, and the same argument as `sendLabel`. It names what is being
+     * attached: "Attach", "Attach a file", "Add a document".
+     */
+    attachLabel: ReactNode;
+    /**
+     * Called when the reader asks to attach something.
+     *
+     * A callback, and the same seam `ImageListField` opens. A composer cannot know
+     * what an attachment is on the caller's side: a browser `File` on its way to an
+     * upload, a reference to a document already in the caller's store, a frame from
+     * a camera the browser has no input for. Prism draws the control that asks, and
+     * the caller opens whatever picker it owns. The alternative, Prism rendering a
+     * `Dropzone` and taking `File` objects, would make a composer for model requests
+     * into a file upload with a text box on it.
+     */
+    onAttach: () => void;
+    /**
+     * What is attached, in the order the reader attached it.
+     *
+     * Required, and an array that is usually empty. A composer is not a receipt: the
+     * things on it are still part of a request the reader is composing, so they are
+     * always removable and there is no read-only arrangement to express.
+     */
+    attachments: readonly PromptComposerAttachment[];
+    /**
+     * Called with an attachment's `id` when the reader takes it off the request.
+     *
+     * Required, and for the same reason `onRemove` is required on `ImageListField`:
+     * an attachment a reader cannot detach before sending is a mistake they have to
+     * live with.
+     */
+    onRemoveAttachment: (id: string) => void;
+    /**
+     * The accessible name of one tray row's remove control, given that row's
+     * attachment name.
+     *
+     * Required, and a function because the name has to name the attachment and the
+     * name is the caller's string. A nameless control in a tray of six is announced
+     * as "button" six times.
+     */
+    removeAttachmentLabel: (name: string) => string;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+}
+/**
+ * A field for writing a request, what is attached to it, and the controls that
+ * make it, stop it and try it again.
+ *
+ * **It owns a request lifecycle, and that is the reason it is not a form field
+ * with a button beside it.** A request that is being sent, one whose answer is
+ * arriving in pieces, and one that has ended are three situations with three
+ * different affordances, and the difference between the first two is not degree:
+ * there is nothing to stop in the first and everything to stop in the second. A
+ * field with a `busy` flag has to render one control for both, and every product
+ * that has tried ends up either offering a stop that stops nothing or hiding the
+ * stop for the whole of a transfer it was most needed during. The state here is
+ * five positions on a line, the union says so, and the affordances are a table
+ * rather than a judgement.
+ *
+ * **The stop control exists in exactly one position, and that is what makes it
+ * trustworthy.** A stop control that is present and disabled is a promise the
+ * reader will test; a stop control that is absent during the sending position is
+ * honest, because there is genuinely nothing to stop yet. So the row is: nothing
+ * to stop while `sending`, a stop while `streaming`, and nothing but a retry after
+ * a failure. The absence is drawn as absence, not as a greyed control, which is
+ * the one place this Component breaks from the unavailable-is-drawn rule the rest
+ * of the package follows, and the reason is that the rule protects a reader from
+ * a mystery, and there is no mystery here: a control that is not there is a
+ * control that is not needed.
+ *
+ * **Prism owns no model and no transport, and the position is the caller's for
+ * that reason.** The socket, the request, the persistence, the order the pieces
+ * arrive in and what happens when one arrives out of order are all the caller's,
+ * and the state prop is the whole of the contract between them. That is the same
+ * division `LiveRegion` makes with the events it announces, and it is why this is
+ * a control surface over a state machine rather than a client: a Component that
+ * opened a connection would be a Component every consumer inherits a connection
+ * from, and the no-override-path law decides that. Nothing here fetches, and
+ * nothing here knows what a model is.
+ *
+ * **The request field goes read-only while the answer is coming, rather than
+ * disappearing or going disabled.** A reader mid-stream usually wants to read what
+ * they sent, and often wants to select part of it to quote in the next turn.
+ * `readOnly` keeps the field focusable, selectable and in the tab order while
+ * making the edit impossible, and `disabled` would take all three away over a
+ * field the reader may still want to look at.
+ *
+ * **The tray is a nested list with its own remove behaviour, and the focus moves
+ * there too.** An attachment is not a chip: a chip is a selected value in a set
+ * the reader chose between, and an attachment is one item in a list the reader is
+ * still building, so it is drawn as a row with a name and a control, inside a list
+ * the whole region is named by. Removing one of six has the same focus problem as
+ * removing a row from any other list here, and it gets the same answer: the row
+ * that moved up, or the one above it, or the attach control when the last one goes,
+ * because that is the only operable thing left. A reader who detaches a document
+ * and is then returned to the top of the page has been dropped on a detached node
+ * and cannot tell it from a page that reloaded.
+ *
+ * **The one line of failure is `FieldError`, and the reuse is deliberate.** It is
+ * exactly one line of destructive text carrying `role="alert"`, which is what a
+ * one-line failure is, and an alert with its own border and padding inside a
+ * composer would be a card inside a card that changes the height of the box the
+ * reader is about to type into. The cost is named rather than hidden: the
+ * Component is called a field error and this is a request outcome, so the two are
+ * indistinguishable to a screen reader, and a composer that also holds a control
+ * with its own validation error will announce both as alerts. A caller who needs
+ * them told apart composes their own region beside the field.
+ *
+ * **There is no spinner while a request streams, and the omission is a decision.**
+ * The one thing this Component could honestly report is that pieces of the answer
+ * are arriving, and that is visible in the caller's own editor, where they land. A
+ * ring beside a stop control is a second animation saying what the arriving text
+ * already says, and DESIGN.md's first motion law is that feedback is a response
+ * to something the reader did. The reader pressed send; the text appearing is the
+ * answer.
+ *
+ * **It is a client Component**, because the request field is controlled, because
+ * five callbacks cross into it and because the tray moves focus after a change.
+ * What that costs is the ordinary one, and worth stating because the surface
+ * invites a server render: a server Component may render a composer with its
+ * state and text already in place and it will look right, and what it may not do
+ * is offer the stop control, the retry, or focus that behaves, because those are
+ * facts about what happens after the reader acts.
+ */
+declare function PromptComposer({ label, state, text, onTextChange, onSubmit, onStop, onRetry, sendLabel, stopLabel, retryLabel, attachLabel, onAttach, attachments, onRemoveAttachment, removeAttachmentLabel, className, }: PromptComposerProps): import("react").JSX.Element;
+export { PromptComposer };
+//# sourceMappingURL=prompt-composer.d.ts.map

package/dist/components/ui/prompt-composer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-composer.d.ts","sourceRoot":"","sources":["../../../src/components/ui/prompt-composer.tsx"],"names":[],"mappings":"AAGA,OAAO,EAA8C,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAOlF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAA;AAEtF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB;AAC7B,iFAAiF;AAC/E;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE;AACnB,uEAAuE;GACrE;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE;AACtB,yDAAyD;GACvD;IAAE,KAAK,EAAE,WAAW,CAAA;CAAE;AACxB,8BAA8B;GAC5B;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE;AACnB,yEAAyE;GACvE;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,CAAA;AAE3C;;;;;;;;;GASG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;;;;;OAOG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;OAQG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;;;OAQG;IACH,KAAK,EAAE,mBAAmB,CAAA;IAC1B;;;;;;;;OAQG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;OAMG;IACH,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACpC;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC;;;;;;;;;OASG;IACH,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB;;;;;;OAMG;IACH,SAAS,EAAE,SAAS,CAAA;IACpB;;;;;;;OAOG;IACH,SAAS,EAAE,SAAS,CAAA;IACpB;;;;;;OAMG;IACH,UAAU,EAAE,SAAS,CAAA;IACrB;;;;;OAKG;IACH,WAAW,EAAE,SAAS,CAAA;IACtB;;;;;;;;;;OAUG;IACH,QAAQ,EAAE,MAAM,IAAI,CAAA;IACpB;;;;;;OAMG;IACH,WAAW,EAAE,SAAS,wBAAwB,EAAE,CAAA;IAChD;;;;;;OAMG;IACH,kBAAkB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IACxC;;;;;;;OAOG;IACH,qBAAqB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IAC/C,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,iBAAS,cAAc,CAAC,EACtB,KAAK,EACL,KAAK,EACL,IAAI,EACJ,YAAY,EACZ,QAAQ,EACR,MAAM,EACN,OAAO,EACP,SAAS,EACT,SAAS,EACT,UAAU,EACV,WAAW,EACX,QAAQ,EACR,WAAW,EACX,kBAAkB,EAClB,qBAAqB,EACrB,SAAS,GACV,EAAE,mBAAmB,+BA0KrB;AAED,OAAO,EAAE,cAAc,EAAE,CAAA"}

package/dist/components/ui/prompt-composer.js

@@ -0,0 +1,145 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PaperclipIcon, RefreshCwIcon, SendIcon, XIcon } from 'lucide-react';
+import { useEffect, useId, useRef } from 'react';
+import { Button } from './button.js';
+import { FieldError } from './field.js';
+import { Textarea } from './textarea.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The tray's remove control, drawn once and used by every row.
+ *
+ * The muted ink because every row is the same surface, and the 44px coarse-pointer
+ * floor because a tray on a phone is reached with a thumb. Duplicated as a
+ * constant for the reason `ImageListField` gives: there is no shared recipe on this
+ * package's surface, and exporting one class string would be publishing a styling
+ * hook.
+ */
+const REMOVE_CONTROL = 'text-muted-foreground hover:text-foreground inline-flex size-5 shrink-0 cursor-pointer items-center justify-center rounded-sm outline-none transition-colors duration-fast ease-out pointer-coarse:size-11 focus-visible:ring-ring focus-visible:ring-[3px]';
+/** The Component's own slots, read back through one root ref after a change. */
+const TRAY_REMOVE_SLOT = '[data-slot="prompt-composer-attachment-remove"]';
+const ATTACH_SLOT = '[data-slot="prompt-composer-attach"]';
+/**
+ * A field for writing a request, what is attached to it, and the controls that
+ * make it, stop it and try it again.
+ *
+ * **It owns a request lifecycle, and that is the reason it is not a form field
+ * with a button beside it.** A request that is being sent, one whose answer is
+ * arriving in pieces, and one that has ended are three situations with three
+ * different affordances, and the difference between the first two is not degree:
+ * there is nothing to stop in the first and everything to stop in the second. A
+ * field with a `busy` flag has to render one control for both, and every product
+ * that has tried ends up either offering a stop that stops nothing or hiding the
+ * stop for the whole of a transfer it was most needed during. The state here is
+ * five positions on a line, the union says so, and the affordances are a table
+ * rather than a judgement.
+ *
+ * **The stop control exists in exactly one position, and that is what makes it
+ * trustworthy.** A stop control that is present and disabled is a promise the
+ * reader will test; a stop control that is absent during the sending position is
+ * honest, because there is genuinely nothing to stop yet. So the row is: nothing
+ * to stop while `sending`, a stop while `streaming`, and nothing but a retry after
+ * a failure. The absence is drawn as absence, not as a greyed control, which is
+ * the one place this Component breaks from the unavailable-is-drawn rule the rest
+ * of the package follows, and the reason is that the rule protects a reader from
+ * a mystery, and there is no mystery here: a control that is not there is a
+ * control that is not needed.
+ *
+ * **Prism owns no model and no transport, and the position is the caller's for
+ * that reason.** The socket, the request, the persistence, the order the pieces
+ * arrive in and what happens when one arrives out of order are all the caller's,
+ * and the state prop is the whole of the contract between them. That is the same
+ * division `LiveRegion` makes with the events it announces, and it is why this is
+ * a control surface over a state machine rather than a client: a Component that
+ * opened a connection would be a Component every consumer inherits a connection
+ * from, and the no-override-path law decides that. Nothing here fetches, and
+ * nothing here knows what a model is.
+ *
+ * **The request field goes read-only while the answer is coming, rather than
+ * disappearing or going disabled.** A reader mid-stream usually wants to read what
+ * they sent, and often wants to select part of it to quote in the next turn.
+ * `readOnly` keeps the field focusable, selectable and in the tab order while
+ * making the edit impossible, and `disabled` would take all three away over a
+ * field the reader may still want to look at.
+ *
+ * **The tray is a nested list with its own remove behaviour, and the focus moves
+ * there too.** An attachment is not a chip: a chip is a selected value in a set
+ * the reader chose between, and an attachment is one item in a list the reader is
+ * still building, so it is drawn as a row with a name and a control, inside a list
+ * the whole region is named by. Removing one of six has the same focus problem as
+ * removing a row from any other list here, and it gets the same answer: the row
+ * that moved up, or the one above it, or the attach control when the last one goes,
+ * because that is the only operable thing left. A reader who detaches a document
+ * and is then returned to the top of the page has been dropped on a detached node
+ * and cannot tell it from a page that reloaded.
+ *
+ * **The one line of failure is `FieldError`, and the reuse is deliberate.** It is
+ * exactly one line of destructive text carrying `role="alert"`, which is what a
+ * one-line failure is, and an alert with its own border and padding inside a
+ * composer would be a card inside a card that changes the height of the box the
+ * reader is about to type into. The cost is named rather than hidden: the
+ * Component is called a field error and this is a request outcome, so the two are
+ * indistinguishable to a screen reader, and a composer that also holds a control
+ * with its own validation error will announce both as alerts. A caller who needs
+ * them told apart composes their own region beside the field.
+ *
+ * **There is no spinner while a request streams, and the omission is a decision.**
+ * The one thing this Component could honestly report is that pieces of the answer
+ * are arriving, and that is visible in the caller's own editor, where they land. A
+ * ring beside a stop control is a second animation saying what the arriving text
+ * already says, and DESIGN.md's first motion law is that feedback is a response
+ * to something the reader did. The reader pressed send; the text appearing is the
+ * answer.
+ *
+ * **It is a client Component**, because the request field is controlled, because
+ * five callbacks cross into it and because the tray moves focus after a change.
+ * What that costs is the ordinary one, and worth stating because the surface
+ * invites a server render: a server Component may render a composer with its
+ * state and text already in place and it will look right, and what it may not do
+ * is offer the stop control, the retry, or focus that behaves, because those are
+ * facts about what happens after the reader acts.
+ */
+function PromptComposer({ label, state, text, onTextChange, onSubmit, onStop, onRetry, sendLabel, stopLabel, retryLabel, attachLabel, onAttach, attachments, onRemoveAttachment, removeAttachmentLabel, className, }) {
+    const generated = useId();
+    const labelId = `${generated}-label`;
+    const fieldId = `${generated}-field`;
+    const rootRef = useRef(null);
+    // The tray row whose remove control should take focus after the caller's value
+    // settles. Armed before the callback runs, because the row that is going away
+    // cannot be focused and the row that replaces it does not exist yet.
+    const pending = useRef(null);
+    const streaming = state.phase === 'streaming';
+    const inFlight = state.phase === 'sending' || streaming;
+    const failed = state.phase === 'failed';
+    // A send control in two of the five positions, and its absence in the other three
+    // is the point: while a request is in the air there is nothing to send, and after
+    // a failure the action is to try that one again rather than to send a second one.
+    const showSend = state.phase === 'idle' || state.phase === 'done';
+    useEffect(() => {
+        const index = pending.current;
+        if (index === null)
+            return;
+        pending.current = null;
+        const root = rootRef.current;
+        if (root === null)
+            return;
+        const buttons = root.querySelectorAll(TRAY_REMOVE_SLOT);
+        const button = buttons.item(Math.min(index, buttons.length - 1));
+        if (button === null)
+            root.querySelector(ATTACH_SLOT)?.focus();
+        else
+            button.focus();
+    });
+    const removeAt = (index) => {
+        const attachment = attachments[index];
+        if (attachment === undefined)
+            return;
+        pending.current = index;
+        onRemoveAttachment(attachment.id);
+    };
+    const onFieldChange = (event) => {
+        onTextChange(event.target.value);
+    };
+    return (_jsxs("div", { ref: rootRef, "data-slot": "prompt-composer", "data-phase": state.phase, role: "group", "aria-labelledby": labelId, "aria-busy": inFlight || undefined, className: cn('flex w-full flex-col gap-2', className), children: [_jsx("span", { id: labelId, "data-slot": "prompt-composer-label", className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: label }), attachments.length === 0 ? null : (_jsx("ul", { "data-slot": "prompt-composer-attachments", "aria-labelledby": labelId, className: "flex w-full flex-col gap-1", children: attachments.map((attachment, index) => (_jsxs("li", { "data-slot": "prompt-composer-attachment", className: "border-border flex items-center gap-2 rounded-md border px-2 py-1.5", children: [_jsx("span", { "data-slot": "prompt-composer-attachment-name", className: "min-w-0 flex-1 truncate text-sm", children: attachment.name }), _jsx("button", { type: "button", "data-slot": "prompt-composer-attachment-remove", "aria-label": removeAttachmentLabel(attachment.name), onClick: () => removeAt(index), className: REMOVE_CONTROL, children: _jsx(XIcon, { className: "size-4", "aria-hidden": "true" }) })] }, attachment.id))) })), _jsx(Textarea, { id: fieldId, "data-slot": "prompt-composer-field", value: text, onChange: onFieldChange, readOnly: inFlight, className: "min-h-24" }), failed && state.reason !== undefined && state.reason !== null && state.reason !== false ? (_jsx(FieldError, { "data-slot": "prompt-composer-reason", children: state.reason })) : null, _jsxs("div", { "data-slot": "prompt-composer-actions", className: "flex flex-wrap items-center gap-2", children: [_jsx("span", { "data-slot": "prompt-composer-attach-control", className: cn('inline-flex', inFlight && 'opacity-50'), children: _jsxs(Button, { "data-slot": "prompt-composer-attach", type: "button", variant: "ghost", size: "sm", "aria-disabled": inFlight || undefined, onClick: inFlight ? () => undefined : onAttach, children: [_jsx(PaperclipIcon, { "aria-hidden": "true" }), attachLabel] }) }), _jsxs("div", { className: "ms-auto flex items-center gap-2", children: [failed ? (_jsxs(Button, { "data-slot": "prompt-composer-retry", type: "button", variant: "outline", size: "sm", onClick: onRetry, children: [_jsx(RefreshCwIcon, { "aria-hidden": "true" }), retryLabel] })) : null, streaming ? (_jsxs(Button, { "data-slot": "prompt-composer-stop", type: "button", variant: "destructive", size: "sm", onClick: onStop, children: [_jsx(XIcon, { "aria-hidden": "true" }), stopLabel] })) : null, showSend ? (_jsxs(Button, { "data-slot": "prompt-composer-send", type: "button", size: "sm", onClick: () => onSubmit(text), children: [_jsx(SendIcon, { "aria-hidden": "true" }), sendLabel] })) : null] })] })] }));
+}
+export { PromptComposer };

package/dist/components/ui/proportion-list.d.ts

@@ -0,0 +1,188 @@
+import type { ComponentProps, ReactNode } from 'react';
+import { type StatusTone } from './status.js';
+/**
+ * One category in a list of shares of one whole.
+ *
+ * The shape is closed and short because the unit is a share: a category has a name,
+ * a measured quantity, an optional state, and an optional printed form. Nothing
+ * else a caller might reach for here is in the type, and the reason each absent
+ * member is absent is on the member.
+ */
+export type ProportionListItem = {
+    /**
+     * The category's own name.
+     *
+     * A string rather than a node, and that is the one narrowing in this file with a
+     * reason behind it: the name is also the accessible name `Meter` requires for
+     * its track, so a node here would force this Component to invent a word for the
+     * bar or to give it the label of the figure. A category's name is a name, and it
+     * is the one thing on the row that is never a composed figure.
+     */
+    label: string;
+    /**
+     * The measured quantity, in the caller's own units.
+     *
+     * A magnitude and not a percentage, because a caller holding counts of two
+     * hundred and forty has counts and not a share, and computing the share is one
+     * division this Component can do without claiming anything about the data.
+     */
+    value: number;
+    /**
+     * The words for the value, printed in place of the computed share.
+     *
+     * A node, because the printed form is often more than a percentage: "1,204
+     * captures", "42% of £2.9M", "4 of 9 sites". Omitted, the share is printed as a
+     * percentage to `precision` places, which is honest when the whole is the
+     * denominator and is a claim about the caller's domain when it is not, which is
+     * why the prop exists.
+     */
+    text?: ReactNode;
+    /**
+     * The state of this category, in the contract's tones and with the caller's words.
+     *
+     * Required as a pair rather than two members because `Status` refuses to render
+     * a tone without words: a dot with no label is a colour a screen reader cannot
+     * read and a sighted reader who cannot separate the tones cannot either. Passing
+     * `tone` alone would be a state with no name, so the pair is the whole of it.
+     *
+     * The tone also fills the bar, through the map below. See that map for what a
+     * tone means to a bar and what it does not.
+     */
+    status?: {
+        /** Which of the five tones the dot takes. */
+        tone: StatusTone;
+        /** The words naming the state, in the product's own vocabulary. */
+        label: ReactNode;
+    };
+};
+/** The props the ProportionList accepts. */
+export interface ProportionListProps extends Omit<ComponentProps<'figure'>, 'children'> {
+    /**
+     * The categories, in the order they are drawn and read.
+     *
+     * The order is the ranking, and nothing here sorts: a share list is nearly always
+     * a caller's own ordering, and a Component that sorted by value would put a list
+     * of three deliberately ordered categories into a different order with nothing
+     * said.
+     */
+    items: readonly ProportionListItem[];
+    /**
+     * What the shares are a share of, in the caller's own units.
+     *
+     * Omitted, the whole is the sum of the items, which is the ordinary case: a list
+     * of every category of one thing adds up to the thing. Pass it when the list does
+     * not exhaust the whole, a list of the top six of eleven categories, or one that
+     * deliberately leaves out a remainder, because a bar measured against a sum that
+     * is not the whole is a bar that overstates every category on the page.
+     *
+     * The cost of omitting it is a silent wrong denominator, and the only defence
+     * would be a prop Prism has no way to fill: a Component cannot tell an exhaustive
+     * list from a truncated one.
+     */
+    total?: number;
+    /**
+     * How many decimal places the computed share is printed to. @defaultValue 1
+     *
+     * One place because a share is a rounded quantity and a reader comparing two
+     * categories is comparing tenths of a percent. Pass `0` for a whole-number share,
+     * which is the right answer whenever the underlying counts are small enough that
+     * a tenth of a percent is noise.
+     */
+    precision?: number;
+    /**
+     * The name of the figure, read before the categories.
+     *
+     * Required rather than defaulted, for the two reasons `ChartFrame` states and the
+     * rest of the package repeats: two lists on a dashboard are two lists a reader
+     * cannot tell apart, and a list with no name is neither announced nor linkable. A
+     * figure named "Breakdown" is a Component shipping a sentence about a product it
+     * knows nothing about.
+     */
+    label: string;
+    /**
+     * The sentence under the list, which is where the whole belongs.
+     *
+     * The caller's words, because naming the whole is a claim about the data: "of
+     * £2.9M committed", "of 9 sites", "of readings this week". This Component knows
+     * the sum and not the thing summed, so it prints no total and puts no unit beside
+     * the shares. That is also the cost of the arrangement, and it is a real one: a
+     * reader who wants the whole has to be given the sentence, and a list with no
+     * `caption` says only what the shares say.
+     */
+    caption?: ReactNode;
+    /** What a reader is told when there is nothing to show. */
+    empty?: ReactNode;
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+}
+/**
+ * Each labelled category's share of one whole, as a proportional bar and a number.
+ *
+ * **The unit is a share, and that is what the whole Component is built around.** A
+ * part-to-whole with two or three parts is a `Chart` `donut`, and a series of
+ * unrelated values against a shared baseline is a `Chart` `bar`; neither is this,
+ * because a list of shares is neither of those things. Its bars cannot be modelled
+ * as independent series, since they are constrained to sum to the whole and a
+ * reader comparing two of them is comparing two slices of one pie rather than two
+ * measurements against a scale. So there is no `series` prop, no `mark`, and no
+ * axis: the bar is drawn from `value` against `total`, and the number printed
+ * beside it is that same division, so the two cannot disagree with each other or
+ * with the data.
+ *
+ * **The bar is decorative and the number is the reading, said plainly.** `Meter`
+ * draws the track and the fill, and the row wraps it in an `aria-hidden` box on
+ * purpose: a meter announces its name and its value, and the row already prints
+ * both, so an announced bar beside a printed one is the same sentence twice for
+ * every row on the page. `Meter` requires a name and the only name in the row is
+ * the category's own, so `label` is forwarded to it rather than invented, and the
+ * forwarding is invisible because the wrapper is hidden. A reader who cannot rank
+ * the fills still has every number, which is the whole reason the number is printed
+ * rather than left to the bar.
+ *
+ * **A share is drawn on one scale, so the bars are comparable down the page.** Every
+ * row's fill is `value / total` of the same track, and the tracks are the same
+ * width, which is what makes two categories comparable at a glance. That is the
+ * reason this is a list of bars rather than a stacked bar: a stack puts the shares
+ * in one figure, where the reader has to find the boundary between two categories
+ * to compare them, and a list puts each one on its own common baseline.
+ *
+ * **`Meter` is used rather than a second bar drawn here, and the honest cost is a
+ * palette of three state tones against five.** Composing it means the bar, its
+ * tone vocabulary and its accessibility are one Component's rather than two, and it
+ * means a share list looks like every other measurement in the product, which is
+ * what a reader wants from a bar. The cost is that `StatusTone` and `MeterTone` are
+ * different widths: there is no informational fill, so a category whose state is
+ * `info` draws a neutral bar and its colour meaning is carried by the dot beside the
+ * label. The alternative was a second set of fills authored here, and that is a
+ * second source of truth for a scale the tokens already own.
+ *
+ * **Two inputs throw, because a share that cannot be drawn is not a quiet share.**
+ * A negative quantity and a whole that is zero or less are both impossible rather
+ * than unusual, and both have exactly one honest rendering, which is to stop: a
+ * negative share drawn as an empty bar claims the category is zero when it is
+ * below zero, and a list drawn against a total of zero divides by nothing. The
+ * alternative was to clamp, which is what `Chart` does for a value past the end of
+ * its axis, and the reason it does not apply here is that there is no axis to be
+ * past: the whole is the denominator and it is either there or it is not.
+ *
+ * **The rows are a list, so a reader is told how many categories there are.**
+ * `<ul>` and `<li>` rather than a table of divs, because a reader moving by list
+ * item is told the count and each row is one stop, and because nothing in a
+ * category list is tabular data: there is one measure and it is beside its name.
+ * The rows are also not interactive, and no motion is attached to them for the same
+ * reason: a hover state on a row that cannot be pressed is an affordance for
+ * something the page does not do.
+ *
+ * **An empty list renders the caller's sentence rather than nothing.** A heading
+ * with no rows says the whole is nothing, and hiding the figure leaves a reader
+ * wondering whether it had been missed, which is the argument `Retention01` makes
+ * for leaving a withdrawn schedule on the page.
+ *
+ * **It is a server Component.** There is no state, no effect and no handler, the
+ * whole figure is arithmetic over props, and a dashboard of proportions costs no
+ * client code at all. `Status` and `Meter` are server Components too, so composing
+ * them costs nothing at this boundary either.
+ */
+declare function ProportionList({ className, items, total, precision, label, caption, empty, ...props }: ProportionListProps): import("react").JSX.Element;
+export { ProportionList };
+//# sourceMappingURL=proportion-list.d.ts.map

package/dist/components/ui/proportion-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proportion-list.d.ts","sourceRoot":"","sources":["../../../src/components/ui/proportion-list.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtD,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAGlD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE;QACP,6CAA6C;QAC7C,IAAI,EAAE,UAAU,CAAA;QAChB,mEAAmE;QACnE,KAAK,EAAE,SAAS,CAAA;KACjB,CAAA;CACF,CAAA;AAyBD,4CAA4C;AAC5C,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC;IACrF;;;;;;;OAOG;IACH,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACpC;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,iBAAS,cAAc,CAAC,EACtB,SAAS,EACT,KAAK,EACL,KAAK,EACL,SAAa,EACb,KAAK,EACL,OAAO,EACP,KAAK,EACL,GAAG,KAAK,EACT,EAAE,mBAAmB,+BAgHrB;AAED,OAAO,EAAE,cAAc,EAAE,CAAA"}