@nanisoft/prism-ui 0.13.0 → 0.16.0

package/dist/components/ui/emoji-picker.js

@@ -0,0 +1,278 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useRef, useState } from 'react';
+import { ScrollArea } from './scroll-area.js';
+import { SearchField } from './search-field.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The three cell steps, and the column count that goes with each one.
+ *
+ * The columns and the cell are one fact in one table rather than two, because
+ * the keyboard model reads the column count and the layout reads the class, and
+ * two tables would be two numbers that could disagree. A reader who presses the
+ * down arrow and lands two rows further down has been told the grid is wider
+ * than it is, and nothing about a Component can make that recoverable except
+ * keeping one number.
+ *
+ * `min-h` and not `size` on the cell: the columns are fractions of the caller's
+ * container, so a fixed square would overflow a narrow picker and leave a gap in
+ * a wide one. The floor is what carries the step, and it is raised to 44 pixels
+ * on a coarse pointer because an emoji cell is a target a finger has to hit.
+ */
+const EMOJI_SIZE = {
+    sm: { columns: 10, grid: 'grid-cols-10', cell: 'min-h-8', glyph: 'text-base' },
+    md: { columns: 8, grid: 'grid-cols-8', cell: 'min-h-10', glyph: 'text-xl' },
+    lg: { columns: 7, grid: 'grid-cols-7', cell: 'min-h-12', glyph: 'text-2xl' },
+};
+/**
+ * The words a query is matched against, folded to lower case once per change.
+ *
+ * The name and the keywords are one haystack rather than two fields, so a query
+ * word matches a keyword and a keyword matches a name with no rule to learn: the
+ * reader types words and the words are found. Folding happens here rather than
+ * at each comparison so a filter over a bounded set is one pass, not one fold
+ * per term per entry.
+ */
+function haystack(item) {
+    return `${item.name} ${item.keywords?.join(' ') ?? ''}`.toLowerCase();
+}
+/**
+ * A grid of emoji the reader chooses one of, with a search field and a rail of
+ * categories.
+ *
+ * **The emoji set is a prop and this module ships no table, and the cost of that
+ * is a real one.** A data set is a licensed asset or a derived one, it changes
+ * every Unicode release, and what a product's rail contains is that product's
+ * claim about itself. Shipping a table here would be a second source of truth
+ * for the picker, and it would be wrong in a way no gate could see: a consumer
+ * who wanted 40 workflow glyphs would have to delete three thousand rows, and a
+ * consumer who wanted the full set would have to wait for this package to
+ * refresh. So the picker takes the rows, and what the consumer gets back is a
+ * control rather than a data set. The honest cost: a consumer who wants a picker
+ * in an afternoon has to source the set first.
+ *
+ * **The caller's duty is to pass a bounded set, and this Component will not
+ * virtualise for them.** Every entry is a real button in the document, which is
+ * what makes the roving tab stop a button, what makes the browser's own
+ * find-in-page reach a glyph, and what makes the accessibility tree tell the
+ * truth about how many entries there are. Virtualising would take all three away
+ * and would make this a different control wearing this name: the tab stop would
+ * be a placeholder, find-in-page would stop finding glyphs, and the entry count a
+ * screen reader reports would be a number the Component asserted rather than one
+ * it could see. It would also need the row height and the scroll offset, which
+ * are layout measurements, which is a measurement a server render cannot make
+ * and a caller who has already said how wide the picker is would have to
+ * override. So a set of three thousand emoji in an eight column grid is a slow
+ * grid, and the honest answer to that is a different surface, a search first
+ * field with a result list, rather than a virtualised one under this name. Pass
+ * what a reader would actually scroll through: a few hundred entries at most,
+ * which is several screens and not several minutes.
+ *
+ * **The grid is a radio group of buttons with a roving tab stop, and the two
+ * halves of that sentence are both deliberate.** The single selection is a real
+ * fact, and `role="radiogroup"` with `role="radio"` and `aria-checked` on each
+ * cell is the only description of it that is true, for the reason
+ * `ToggleGroup` argues in full: pressed buttons say each cell is independent,
+ * which is the claim one selection is denying. The roving tab stop is ours
+ * because the platform's version of it belongs to a native radio group, and
+ * these are buttons in a grid whose column count the caller chose. The cost of
+ * owning it is that it has to be maintained: a grid where every cell is a tab
+ * stop is a grid a keyboard reader has to Tab through three hundred times, and a
+ * grid where no cell is one cannot be entered at all.
+ *
+ * **The keyboard model, in full, because a reader cannot discover it.** The
+ * whole grid is one Tab stop and the stop sits on the chosen entry, or on the
+ * first cell when nothing is chosen. The arrow keys move focus and do not
+ * choose: left and right by one cell, up and down by one column, each clamped at
+ * the edge rather than wrapped, because a grid that wraps surprises a reader
+ * who is reading a row as a row. Home and End go to the first and the last
+ * visible cell. Arrow Down from the search field moves into the grid on the
+ * current stop, which is what makes the field and the grid one control to a
+ * reader rather than two stops to learn. Enter and Space choose, because the
+ * cells are buttons. Escape empties the query and calls `onDismiss` when one was
+ * passed.
+ *
+ * **The rail is a row of ordinary tab stops and is not a composite widget.**
+ * `role="tablist"` is the role that describes it, and a tablist is a
+ * required-name role, so using it would need a seventh string prop for a control
+ * whose members are already named by the category names. The rail instead draws
+ * plain buttons with `aria-current` on the one showing, which says "this is the
+ * current item in this set" without claiming the grid is a tab panel. The cost is
+ * that a reader Tabs through each category rather than arrowing them, and with a
+ * handful of categories that is the better trade; a picker with forty categories
+ * is a picker with the wrong rail.
+ *
+ * **The rail is drawn only while the query is empty, and that is a decision
+ * rather than an omission.** A search that filtered only the showing category
+ * would mean a reader who has landed on Reactions and typed "cat" is told there
+ * is no cat, which is a false statement about the product's own set. So a query
+ * searches every category at once, the grid flattens them in the order the
+ * categories were passed, and the rail is not drawn while it does, because a
+ * category button that does nothing is a control that lies. The cost is a layout
+ * change when the reader types the first character, and the alternative, keeping
+ * the rail, is a worse failure than a shift.
+ *
+ * **The arrow step follows the declared column count and not the measured one,
+ * and the gap is named rather than hidden.** A grid that renders fewer columns
+ * than `size` says, because the caller put it in a narrow container, moves down
+ * by a row the reader cannot see. Prism could measure the rendered column count
+ * and it does not, for the reason it does not virtualise: a measurement is a
+ * layout read, it is not available in a server render, and it would put the
+ * keyboard model at the mercy of whatever the caller did to the width. Passing a
+ * smaller `size` is the fix and it is one prop.
+ *
+ * **Motion is state feedback on two tokens and there is no keyframe.** The cell
+ * and the rail change ink with `duration-fast ease-out`, which is the same
+ * feedback the rest of the package gives, and the press scales by a token-free
+ * factor on `transition-[color,background-color,scale]`. Neither carries a
+ * `motion-safe:`: `packages/ui/src/styles.css` ends with one unlayered
+ * `prefers-reduced-motion` rule that stops every transition in the package, so a
+ * reader who has asked for less motion gets the colour change at full strength
+ * and the press with no movement at all, and the two decisions live in one place
+ * rather than one per cell. Nothing here waits for a script, a scroll position or
+ * a timer, so the picker is complete and legible at first paint whatever the
+ * reader's settings are.
+ *
+ * **It is a client Component, and the directive is unconditional.** The picker
+ * holds the query, the showing category, the roving stop and the announcement,
+ * and all four are the control rather than a decoration of it. The cost is named
+ * rather than hidden: a consumer who renders a read-only list of the set they
+ * already hold ships a client runtime for it, and the honest answer for that case
+ * is their own list, because a picker with no search and no selection is a grid
+ * of glyphs and the grid is three lines of their own markup.
+ */
+function EmojiPicker({ groups, value, onValueChange, searchLabel, searchPlaceholder, clearLabel, emptyLabel, selectLabel, onDismiss, size = 'md', className, }) {
+    const gridRef = useRef(null);
+    const [query, setQuery] = useState('');
+    const [category, setCategory] = useState(null);
+    const [stop, setStop] = useState(null);
+    const [announced, setAnnounced] = useState('');
+    const drawn = EMOJI_SIZE[size];
+    // Every entry with its search words folded once, so a filter over the set is a
+    // comparison per term rather than a fold per term per entry. The id is the
+    // consumer's own key, so the flat list is also where the chosen entry is found.
+    const flat = useMemo(() => groups.flatMap((group) => group.items.map((item) => ({ item, hay: haystack(item) }))), [groups]);
+    // The showing category, falling back to the first when the state names one the
+    // consumer has since removed, so a picker survives its data changing under it
+    // rather than drawing an empty grid beside a rail whose buttons do nothing.
+    const shown = groups.find((group) => group.id === category) ?? groups[0];
+    const searching = query.trim() !== '';
+    const visible = useMemo(() => {
+        if (!searching)
+            return shown?.items ?? [];
+        // Every term has to match somewhere, so a two word query narrows rather than
+        // widens. That is the rule a reader expects from a search field and it is
+        // the one a consumer cannot change without losing the set.
+        const terms = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+        return flat
+            .filter((entry) => terms.every((term) => entry.hay.includes(term)))
+            .map((entry) => entry.item);
+    }, [flat, query, shown]);
+    const chosen = flat.find((entry) => entry.item.id === value)?.item;
+    // The stop is a derivation with a piece of state over it, and the derivation
+    // is what makes it self healing: a stop naming an entry the current query has
+    // filtered out falls back to the chosen entry and then to the first cell, so
+    // the grid always has exactly one Tab stop and never has none.
+    const current = visible.find((item) => item.id === stop) ??
+        visible.find((item) => item.id === chosen?.id) ??
+        visible[0];
+    const currentAt = current === undefined ? -1 : visible.indexOf(current);
+    // The grid is named by the category while the reader browses and by the search
+    // field's own label while a query is present, because those are the two sets
+    // on screen and each has a name the consumer already wrote. The scroll region
+    // takes the same one for the reason `ListPanel` gives: the region and the grid
+    // hold the same entries, and a reader who tabs into one and hears a different
+    // name from the other has been told two things about the same content.
+    //
+    // `aria-label` rather than a generated id pointing at the field's own label
+    // element, and the reason is a duplicate rather than a convenience: an
+    // `sr-only` copy of a label that is already on screen is a second copy of the
+    // same words in the accessibility tree, and a reader walking the page hears it
+    // twice. The name is a string here because the words are the same words the
+    // field shows, so there is nothing for a node to carry.
+    const regionName = searching || shown === undefined ? searchLabel : shown.name;
+    const cells = () => [
+        ...(gridRef.current?.querySelectorAll('[data-slot="emoji-picker-cell"]') ??
+            []),
+    ];
+    const move = (to) => {
+        const all = cells();
+        if (all.length === 0)
+            return;
+        const target = all[Math.min(Math.max(to, 0), all.length - 1)];
+        if (target === undefined)
+            return;
+        // Focus is what records the stop, through the cell's own onFocus, so there
+        // is one place that writes it and the arrow handler cannot move the stop to
+        // a cell the reader did not reach.
+        target.focus();
+    };
+    const onKeyDown = (event) => {
+        if (event.key === 'Escape') {
+            setQuery('');
+            onDismiss?.();
+            return;
+        }
+        const target = event.target;
+        if (target instanceof HTMLInputElement) {
+            // The one key a single line text field has no use for, and the one a
+            // reader expects to move from a search field into the results. Without it
+            // the field and the grid are two stops and the reader has to guess that
+            // Tab crosses between them.
+            if (event.key === 'ArrowDown' && currentAt !== -1) {
+                event.preventDefault();
+                move(currentAt);
+            }
+            return;
+        }
+        if (!(target instanceof HTMLButtonElement))
+            return;
+        if (target.dataset.slot !== 'emoji-picker-cell')
+            return;
+        const from = cells().indexOf(target);
+        if (from === -1)
+            return;
+        const steps = {
+            ArrowLeft: -1,
+            ArrowRight: 1,
+            ArrowUp: -drawn.columns,
+            ArrowDown: drawn.columns,
+        };
+        const step = steps[event.key];
+        if (step !== undefined) {
+            event.preventDefault();
+            move(from + step);
+            return;
+        }
+        if (event.key === 'Home' || event.key === 'End') {
+            event.preventDefault();
+            move(event.key === 'Home' ? 0 : cells().length - 1);
+        }
+    };
+    return (_jsxs("div", { "data-slot": "emoji-picker", onKeyDown: onKeyDown, className: cn('flex w-full items-start gap-3', className), children: [searching || groups.length === 0 ? null : (_jsx("div", { "data-slot": "emoji-picker-rail", className: "flex shrink-0 flex-col gap-0.5", children: groups.map((group) => {
+                    const currentCategory = group.id === shown?.id;
+                    return (_jsx("button", { type: "button", "data-slot": "emoji-picker-rail-item", "data-category": group.id, "aria-current": currentCategory ? true : undefined, onClick: () => {
+                            setCategory(group.id);
+                            setStop(null);
+                        }, className: cn('rounded-md px-2 py-1 text-left text-sm whitespace-nowrap outline-none', 'transition-colors duration-fast ease-out', 'focus-visible:ring-ring focus-visible:ring-[3px]', 'pointer-coarse:min-h-11', currentCategory
+                            ? 'bg-accent text-accent-foreground font-medium'
+                            : 'text-muted-foreground hover:text-foreground'), children: group.name }, group.id));
+                }) })), _jsxs("div", { "data-slot": "emoji-picker-panel", className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx(SearchField, { value: query, onValueChange: setQuery, label: searchLabel, placeholder: searchPlaceholder, clearLabel: clearLabel }), _jsx(ScrollArea, { label: regionName, orientation: "vertical", className: "min-h-0 flex-1", children: visible.length === 0 ? (_jsx("p", { "data-slot": "emoji-picker-empty", className: "text-muted-foreground p-3 text-sm", children: emptyLabel })) : (_jsx("div", { ref: gridRef, "data-slot": "emoji-picker-grid", role: "radiogroup", "aria-label": regionName, className: cn('grid gap-1 p-0.5', drawn.grid), children: visible.map((item) => {
+                                const checked = item.id === value;
+                                return (_jsx("button", { type: "button", "data-slot": "emoji-picker-cell", "data-item": item.id, role: "radio", "aria-checked": checked, 
+                                    // The roving tab stop. Exactly one cell is in the tab order,
+                                    // and `current` is a derivation that always resolves to one,
+                                    // so the grid can always be entered and never entered twice.
+                                    tabIndex: item.id === current?.id ? 0 : -1, onFocus: () => setStop(item.id), onClick: () => {
+                                        onValueChange(item.id);
+                                        setAnnounced(selectLabel(item));
+                                    }, className: cn('text-muted-foreground hover:bg-accent hover:text-accent-foreground flex aspect-square w-full min-w-0 items-center justify-center rounded-md outline-none', 
+                                    // The scale is the one spatial change in this Component, and
+                                    // it is guarded so a reader who asked for less movement gets
+                                    // the ink change at full strength and no movement. The colour
+                                    // changes are feedback and are not guarded, which is the
+                                    // position DESIGN.md takes on reduced motion.
+                                    'transition-[color,background-color,scale] duration-fast ease-out', 'active:scale-95', 'focus-visible:ring-ring focus-visible:ring-[3px]', drawn.cell, 'pointer-coarse:min-h-11', checked && 'bg-accent text-accent-foreground'), children: _jsx("span", { "data-slot": "emoji-picker-glyph", "aria-hidden": "true", className: cn('leading-none select-none', drawn.glyph), children: item.glyph }) }, item.id));
+                            }) })) }), _jsx("p", { "data-slot": "emoji-picker-announcement", "aria-live": "polite", className: "sr-only", children: announced })] })] }));
+}
+export { EmojiPicker };

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

@@ -75,6 +75,23 @@ export type FactListProps = ComponentProps<'dl'> & {
  * wraps and a value that does not are both common and centring one of them reads
  * as an error.
  *
+ * **The value is set flush left, and the reason is the values rather than the
+ * rows.** A right-aligned value is the right answer in a column of figures, where
+ * the digits are the same width and the comparison a reader makes is between the
+ * ends of them. This Component has no numeric mode, no `tabular-nums` and no
+ * monospaced arm, so nothing here is a figure and nothing lines up on its last
+ * digit: what lines up is the first letter of each answer, and right alignment
+ * moves that edge to a different place on every row. A value long enough to wrap
+ * is the case that shows it, because the second line starts wherever the first
+ * one ended and the column reads as a mistake rather than as a decision. `text-
+ * balance` stays, because it is the same reason it was there: a two-line answer
+ * should break where it breaks well, not where the measure runs out.
+ *
+ * A fact whose value *is* a figure is not the case this loses. A caller that wants
+ * a right-aligned figure column composes it: the value is a `ReactNode`, so a
+ * caller can pass the span it wants, and Prism holds no opinion about a value it
+ * did not lay out.
+ *
  * The hairline between rows is `border-border`, so a list of facts reads as a
  * table without becoming one: no header row, because a fact has no column
  * header, and no `Table` semantics, because these are terms and their answers

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

@@ -1 +1 @@
-{"version":3,"file":"fact-list.d.ts","sourceRoot":"","sources":["../../../src/components/ui/fact-list.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItD;;;;;;;GAOG;AACH,MAAM,MAAM,IAAI,GAAG;IACjB;;;;OAIG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,6DAA6D;IAC7D,KAAK,EAAE,SAAS,CAAA;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG;IACjD;;;;OAIG;IACH,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;IACtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,iBAAS,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,aAAa,sCAuCrE;AAED,OAAO,EAAE,QAAQ,EAAE,CAAA"}
+{"version":3,"file":"fact-list.d.ts","sourceRoot":"","sources":["../../../src/components/ui/fact-list.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItD;;;;;;;GAOG;AACH,MAAM,MAAM,IAAI,GAAG;IACjB;;;;OAIG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,6DAA6D;IAC7D,KAAK,EAAE,SAAS,CAAA;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG;IACjD;;;;OAIG;IACH,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;IACtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,iBAAS,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,aAAa,sCAuCrE;AAED,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/ui/fact-list.js

@@ -20,6 +20,23 @@ import { cn } from '../../lib/utils.js';
  * wraps and a value that does not are both common and centring one of them reads
  * as an error.
  *
+ * **The value is set flush left, and the reason is the values rather than the
+ * rows.** A right-aligned value is the right answer in a column of figures, where
+ * the digits are the same width and the comparison a reader makes is between the
+ * ends of them. This Component has no numeric mode, no `tabular-nums` and no
+ * monospaced arm, so nothing here is a figure and nothing lines up on its last
+ * digit: what lines up is the first letter of each answer, and right alignment
+ * moves that edge to a different place on every row. A value long enough to wrap
+ * is the case that shows it, because the second line starts wherever the first
+ * one ended and the column reads as a mistake rather than as a decision. `text-
+ * balance` stays, because it is the same reason it was there: a two-line answer
+ * should break where it breaks well, not where the measure runs out.
+ *
+ * A fact whose value *is* a figure is not the case this loses. A caller that wants
+ * a right-aligned figure column composes it: the value is a `ReactNode`, so a
+ * caller can pass the span it wants, and Prism holds no opinion about a value it
+ * did not lay out.
+ *
  * The hairline between rows is `border-border`, so a list of facts reads as a
  * table without becoming one: no header row, because a fact has no column
  * header, and no `Table` semantics, because these are terms and their answers
@@ -33,6 +50,6 @@ import { cn } from '../../lib/utils.js';
 function FactList({ facts, label, className, ...props }) {
     if (facts.length === 0)
         return null;
-    return (_jsxs("dl", { "data-slot": "fact-list", className: cn('flex w-full flex-col text-sm', className), ...props, children: [label ? (_jsx("dt", { className: "text-muted-foreground mb-2 text-xs font-medium tracking-wide uppercase", children: label })) : null, facts.map((fact, index) => (_jsxs("div", { "data-slot": "fact-list-row", className: "border-border flex items-start justify-between gap-6 border-b py-2 last:border-b-0", children: [_jsx("dt", { className: "text-muted-foreground shrink-0 font-medium", children: fact.label }), _jsx("dd", { className: "text-right text-balance", children: fact.href ? (_jsx("a", { href: fact.href, rel: fact.newTab ? 'noopener noreferrer' : undefined, target: fact.newTab ? '_blank' : undefined, className: "underline underline-offset-4 hover:underline", children: fact.value })) : (fact.value) })] }, index)))] }));
+    return (_jsxs("dl", { "data-slot": "fact-list", className: cn('flex w-full flex-col text-sm', className), ...props, children: [label ? (_jsx("dt", { className: "text-muted-foreground mb-2 text-xs font-medium tracking-wide uppercase", children: label })) : null, facts.map((fact, index) => (_jsxs("div", { "data-slot": "fact-list-row", className: "border-border flex items-start justify-between gap-6 border-b py-2 last:border-b-0", children: [_jsx("dt", { className: "text-muted-foreground shrink-0 font-medium", children: fact.label }), _jsx("dd", { className: "text-left text-balance", children: fact.href ? (_jsx("a", { href: fact.href, rel: fact.newTab ? 'noopener noreferrer' : undefined, target: fact.newTab ? '_blank' : undefined, className: "underline underline-offset-4 hover:underline", children: fact.value })) : (fact.value) })] }, index)))] }));
 }
 export { FactList };

package/dist/components/ui/file-upload.d.ts

@@ -0,0 +1,152 @@
+import { type ReactNode } from 'react';
+/** One file the reader has chosen, and everything the list knows about it. */
+export type FileUploadFile = {
+    /**
+     * The caller's own identity for the file, and what the remove control reports.
+     *
+     * Required, and required as a string rather than as the name: a reader who adds
+     * the same file twice has two rows with the same name, and a remove control
+     * named by the file would announce two identical buttons.
+     */
+    id: string;
+    /** The file's name as the platform reported it. A word, so it is not truncated. */
+    name: string;
+    /**
+     * The file's size, in bytes.
+     *
+     * A number and not a formatted string, and the difference is the whole
+     * interface. A caller that hands over "1.2 MB" has done the division, picked a
+     * unit, decided the rounding and written a separator, and has to do all four
+     * again in every locale the product ships in, and again in every language. The
+     * number is a fact about the file and the sentence is Prism's to write.
+     */
+    size: number;
+    /**
+     * How far this file has got, out of a hundred.
+     *
+     * Omit it and the row shows no meter, which is right for a file that has
+     * finished and for a file that was never going to be uploaded. A value of zero
+     * is drawn as an empty meter rather than as nothing, because a transfer that
+     * has not started and a transfer that does not exist are different facts.
+     */
+    progress?: number;
+    /**
+     * What went wrong with this file, drawn under it in the destructive token and
+     * announced as it appears.
+     *
+     * A node, and a sentence about the caller's own limits: "Larger than 10 MB",
+     * "That file type is not accepted here". Prism does not decide what may be
+     * uploaded and does not write the sentence when it goes wrong.
+     */
+    error?: ReactNode;
+};
+/** The props the File upload accepts. */
+export interface FileUploadProps {
+    /**
+     * The files, in the order they were chosen.
+     *
+     * Required, and order is the caller's because it is a claim about importance.
+     * A reader who chose three files expects to see three rows in the order they
+     * arrived, not sorted by size.
+     */
+    files: FileUploadFile[];
+    /**
+     * Called with a file's `id` when the reader removes it.
+     *
+     * Omit it and the list is read-only, which is a legitimate state: a receipt
+     * names the files that were sent, and offering to take one off a receipt is a
+     * promise the caller cannot keep. A caller whose files are still uploading
+     * should omit it too, because this Component cannot see the transfer and will
+     * not try to stop one.
+     */
+    onRemove?: (id: string) => void;
+    /**
+     * The accessible name of one row's remove control, given that row's file name.
+     *
+     * Required whenever `onRemove` is given, and a function because the name has to
+     * name the file and the file's name is the caller's string, not this package's
+     * sentence. The Component throws without it rather than drawing a button it
+     * cannot name, because a nameless button is announced as "button" and the
+     * reader is left to work out which of the rows it belongs to.
+     */
+    removeLabel?: (name: string) => string;
+    /**
+     * The list's own name, drawn above it and used as its accessible name.
+     *
+     * A node and not a string, so the element a sighted reader reads is the one a
+     * screen reader names the list by. Without it the list is announced as an
+     * unlabelled list and the reader is told nothing about what the files are.
+     */
+    label?: ReactNode;
+    /**
+     * What to draw when no file has been chosen.
+     *
+     * An empty list with no `empty` renders nothing at all, which is the choice
+     * `FactList` makes and the reason is the same: a bordered box with a heading
+     * above it and nothing in it reads as a rendering failure rather than as an
+     * absence. Never a placeholder row. A row with no file in it is a row a reader
+     * tries to remove, and a row whose progress meter is at zero is a transfer that
+     * is happening.
+     */
+    empty?: ReactNode;
+    /**
+     * Renders a size in bytes as the sentence a reader sees.
+     *
+     * The default divides by 1024, steps up to kilobytes and then to megabytes,
+     * and asks `Intl` for the number and its unit in the runtime's own locale, so
+     * the grouping separators and the unit spelling are the reader's. A caller that
+     * needs a fixed locale, a different base or a fourth rung passes a function
+     * that closes over the locale it wants.
+     */
+    formatSize?: (bytes: number) => string;
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * The list of files a reader has chosen, one row each.
+ *
+ * **A size is a number of bytes and never a formatted string.** That is the
+ * decision the whole interface rests on. A caller that formats the size itself
+ * has to reimplement the division, the unit ladder, the rounding at each rung and
+ * the grouping separator, and has to do it again for every locale the product
+ * ships in, and again the first time somebody asks for gigabytes. Prism owns one
+ * ladder and asks `Intl` for the sentence, so a locale change is a locale change
+ * and not an audit. The cost is that a caller who genuinely wants a different
+ * ladder writes a function, which is the right place for that decision.
+ *
+ * **The meter is `Progress` and the failure is `FieldError`, and they were not
+ * chosen together.** A bar that reports a position is a bar: `Progress` already
+ * exposes the value, the minimum and the maximum through ARIA, already draws at
+ * the authored heights and already animates the fill on the base duration, and a
+ * second meter written here would be a second answer to how far along a task is.
+ * The failure is the opposite case and deliberately is not an `Alert`. An Alert
+ * is a callout with its own border, its own padding and its own role, and one
+ * inside a bordered row is a card inside a card: it changes the height of the row
+ * that failed, it moves the remove control, and it announces a page-level problem
+ * for a problem with one file. `FieldError` is one line of destructive text with
+ * `role="alert"`, which is what a per-file failure is. The trade is that a reader
+ * gets no recovery beside the error, and the remedy for that is on the Dropzone
+ * beside the field, where the caller's own limits are stated.
+ *
+ * **The name is a word and the size is a number, and they are laid out that way
+ * on purpose.** The name takes what it needs and the size keeps its own width at
+ * the far edge, so a column of files reads as a column of names with a column of
+ * weights rather than as a ragged paragraph. The name truncates in the middle
+ * rather than at the end because a file extension is the part a reader recognises
+ * last, and a name cut before its extension is a name that could be anything.
+ *
+ * **An empty list renders `empty` or nothing, and never a placeholder row.** A
+ * row with no file in it is a row a reader will try to remove, and a row whose
+ * meter sits at zero is a transfer that is under way. The absence is either the
+ * caller's own sentence or no rows at all, which is what `FactList` does and for
+ * the same reason.
+ *
+ * It carries no directive. It holds no state: which files exist, how far each has
+ * got and which one is being removed are the caller's, and the meter it draws is
+ * a client Component that takes a number. A caller rendering a receipt from a
+ * server component gets a static list of what was sent, which is the right
+ * rendering of a receipt.
+ */
+declare function FileUpload({ files, onRemove, removeLabel, label, empty, formatSize, className, }: FileUploadProps): import("react").JSX.Element | null;
+export { FileUpload };
+//# sourceMappingURL=file-upload.d.ts.map

package/dist/components/ui/file-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-upload.d.ts","sourceRoot":"","sources":["../../../src/components/ui/file-upload.tsx"],"names":[],"mappings":"AACA,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAM7C,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;OAQG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB,CAAA;AAED,yCAAyC;AACzC,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,KAAK,EAAE,cAAc,EAAE,CAAA;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,iBAAS,UAAU,CAAC,EAClB,KAAK,EACL,QAAQ,EACR,WAAW,EACX,KAAK,EACL,KAAK,EACL,UAA8B,EAC9B,SAAS,GACV,EAAE,eAAe,sCAoFjB;AAED,OAAO,EAAE,UAAU,EAAE,CAAA"}

package/dist/components/ui/file-upload.js

@@ -0,0 +1,101 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { XIcon } from 'lucide-react';
+import { useId } from 'react';
+import { FieldError } from './field.js';
+import { Progress } from './progress.js';
+import { cn } from '../../lib/utils.js';
+const KILOBYTE = 1024;
+const MEGABYTE = KILOBYTE * 1024;
+/**
+ * The default size sentence, in the runtime's locale.
+ *
+ * `Intl` is asked for the unit rather than for the abbreviation, because a unit
+ * has a localized spelling and an abbreviation does not: "kB" in one language is
+ * "Ko" in another and "KB" in a third, and hard-coding any of them ships one
+ * locale's abbreviation into every consumer's file list. The byte rung is first
+ * so that a four hundred byte file reads as four hundred bytes rather than as
+ * 0.4 of something, which is a number that looks like a measurement and is not
+ * one.
+ */
+const defaultFormatSize = (bytes) => {
+    const format = (unit, divisor) => new Intl.NumberFormat(undefined, {
+        style: 'unit',
+        unit,
+        maximumFractionDigits: divisor === 1 ? 0 : 1,
+    }).format(bytes / divisor);
+    if (bytes < KILOBYTE)
+        return format('byte', 1);
+    if (bytes < MEGABYTE)
+        return format('kilobyte', KILOBYTE);
+    return format('megabyte', MEGABYTE);
+};
+/**
+ * The remove control, drawn once and used by every row.
+ *
+ * The ink is the muted one and it is not themed per row, because every row is
+ * the same surface and a control that changed colour with the file's state would
+ * be a second thing to read. The target takes the 44px floor on a coarse pointer
+ * and the row grows to hold it, so a list of files on a phone is a list of rows
+ * a thumb can hit.
+ */
+const REMOVE_CONTROL = 'text-muted-foreground hover:text-foreground inline-flex size-5 shrink-0 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 list of files a reader has chosen, one row each.
+ *
+ * **A size is a number of bytes and never a formatted string.** That is the
+ * decision the whole interface rests on. A caller that formats the size itself
+ * has to reimplement the division, the unit ladder, the rounding at each rung and
+ * the grouping separator, and has to do it again for every locale the product
+ * ships in, and again the first time somebody asks for gigabytes. Prism owns one
+ * ladder and asks `Intl` for the sentence, so a locale change is a locale change
+ * and not an audit. The cost is that a caller who genuinely wants a different
+ * ladder writes a function, which is the right place for that decision.
+ *
+ * **The meter is `Progress` and the failure is `FieldError`, and they were not
+ * chosen together.** A bar that reports a position is a bar: `Progress` already
+ * exposes the value, the minimum and the maximum through ARIA, already draws at
+ * the authored heights and already animates the fill on the base duration, and a
+ * second meter written here would be a second answer to how far along a task is.
+ * The failure is the opposite case and deliberately is not an `Alert`. An Alert
+ * is a callout with its own border, its own padding and its own role, and one
+ * inside a bordered row is a card inside a card: it changes the height of the row
+ * that failed, it moves the remove control, and it announces a page-level problem
+ * for a problem with one file. `FieldError` is one line of destructive text with
+ * `role="alert"`, which is what a per-file failure is. The trade is that a reader
+ * gets no recovery beside the error, and the remedy for that is on the Dropzone
+ * beside the field, where the caller's own limits are stated.
+ *
+ * **The name is a word and the size is a number, and they are laid out that way
+ * on purpose.** The name takes what it needs and the size keeps its own width at
+ * the far edge, so a column of files reads as a column of names with a column of
+ * weights rather than as a ragged paragraph. The name truncates in the middle
+ * rather than at the end because a file extension is the part a reader recognises
+ * last, and a name cut before its extension is a name that could be anything.
+ *
+ * **An empty list renders `empty` or nothing, and never a placeholder row.** A
+ * row with no file in it is a row a reader will try to remove, and a row whose
+ * meter sits at zero is a transfer that is under way. The absence is either the
+ * caller's own sentence or no rows at all, which is what `FactList` does and for
+ * the same reason.
+ *
+ * It carries no directive. It holds no state: which files exist, how far each has
+ * got and which one is being removed are the caller's, and the meter it draws is
+ * a client Component that takes a number. A caller rendering a receipt from a
+ * server component gets a static list of what was sent, which is the right
+ * rendering of a receipt.
+ */
+function FileUpload({ files, onRemove, removeLabel, label, empty, formatSize = defaultFormatSize, className, }) {
+    const generated = useId();
+    const labelId = `${generated}-label`;
+    if (onRemove !== undefined && removeLabel === undefined) {
+        throw new Error('FileUpload: a removable list needs removeLabel, because the accessible name of a remove control has ' +
+            'to name the file it removes and this Component cannot write that sentence. Pass a function of ' +
+            'the file name, or drop onRemove for a list the reader cannot change.');
+    }
+    if (files.length === 0 && empty === undefined)
+        return null;
+    return (_jsxs("div", { "data-slot": "file-upload", className: cn('flex w-full flex-col gap-1', className), children: [label === undefined ? null : (_jsx("span", { id: labelId, "data-slot": "file-upload-label", className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: label })), files.length === 0 ? (_jsx("p", { "data-slot": "file-upload-empty", className: "text-muted-foreground text-sm", children: empty })) : (_jsx("ul", { "data-slot": "file-upload-list", "aria-labelledby": label === undefined ? undefined : labelId, className: "flex w-full flex-col", children: files.map((file) => (_jsxs("li", { "data-slot": "file-upload-file", "data-incomplete": (file.error !== undefined ||
+                        (file.progress !== undefined && file.progress < 100)) ||
+                        undefined, className: "border-border flex items-start gap-3 border-b py-2 last:border-b-0", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-1.5", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3", children: [_jsx("span", { "data-slot": "file-upload-name", className: "min-w-0 truncate text-sm font-medium", children: file.name }), _jsx("span", { "data-slot": "file-upload-size", className: "text-muted-foreground shrink-0 text-xs tabular-nums", children: formatSize(file.size) })] }), file.progress === undefined ? null : (_jsx(Progress, { value: file.progress, max: 100 })), file.error === undefined ? null : _jsx(FieldError, { children: file.error })] }), onRemove === undefined ? null : (_jsx("button", { type: "button", "data-slot": "file-upload-remove", "aria-label": removeLabel?.(file.name), onClick: () => onRemove(file.id), className: REMOVE_CONTROL, children: _jsx(XIcon, { className: "size-4", "aria-hidden": "true" }) }))] }, file.id))) }))] }));
+}
+export { FileUpload };