@nanisoft/prism-ui 0.13.0 → 0.16.0

package/dist/components/ui/repeatable-rows.d.ts

@@ -0,0 +1,241 @@
+import { type ReactNode } from 'react';
+/**
+ * What the Component hands a row's own render prop alongside the row.
+ *
+ * Two facts, and neither of them is the row. `index` is the row's position in the
+ * caller's array, counted from zero, because that is the number a caller needs to
+ * index their own array with and a one-based ordinal would be a second convention
+ * to remember. `fieldId` is the id this row's first control should carry, and it
+ * is the only part of the Component that reaches into the caller's markup.
+ */
+export type RepeatableRowInfo = {
+    /**
+     * The row's position in `rows`, counting from zero.
+     *
+     * Zero-based on purpose, and it is worth saying why twice: the row is the
+     * caller's object and the caller's array is the caller's, so the number that
+     * helps is the one that indexes it. It renumbers on every removal, and so does
+     * everything derived from it, which is the point of the Component.
+     */
+    index: number;
+    /**
+     * A generated id for this row's first control, for the caller's own `htmlFor`
+     * and `aria-describedby`.
+     *
+     * Generated rather than derived from the position, and the difference between
+     * those two is the whole accessibility story of this Component: an id that
+     * followed the index would change on every removal, and every `for` pointing at
+     * it would point at the next row's control by the time a reader clicked the
+     * label. This one is bound to the row, so it survives the rows around it moving.
+     */
+    fieldId: string;
+};
+/**
+ * The props the Repeatable rows accepts.
+ *
+ * The props interface is generic over the row type rather than typed as `object`,
+ * because a row is the caller's own domain value: a line item, a recipient, a
+ * scheduled window, a matching rule. A Component that took a shape of its own
+ * would make every caller restate their type to satisfy a form, and the row's
+ * fields are the caller's business rather than this Component's. A consumer who
+ * wants the type end to end writes their own typed wrapper over
+ * `RepeatableRowsProps<TheirRow>`, which is one line and is why the interface
+ * rather than a fixed shape is what is exported.
+ */
+export interface RepeatableRowsProps<TRow extends object> {
+    /**
+     * The rows, in the order they are shown.
+     *
+     * Required, and the objects must be the same objects across renders. The
+     * Component keys each row by its identity rather than by its position, which is
+     * what lets a middle row leave without the rows around it losing their
+     * controls, and identity is only stable if the caller holds the rows somewhere
+     * rather than rebuilding them. A caller that writes `rows.map((r) => ({ ...r }))`
+     * on every render hands over a new object each time and every row remounts on
+     * every keystroke, which is a cost worth knowing about before it is paid. The
+     * same requirement React's own `key` has, met by the same arrangement: rows in
+     * state.
+     */
+    rows: readonly TRow[];
+    /**
+     * Called when the reader asks for another row.
+     *
+     * Required, and the Component appends nothing itself. A row is a record with
+     * fields the caller defines and defaults the caller decides, so a Component
+     * that manufactured an empty one would have to invent those defaults. The
+     * callback is also what tells the Component a row is coming, which is the only
+     * way it can put the reader's cursor in the right place afterwards.
+     */
+    onAdd: () => void;
+    /**
+     * The visible label of the add affordance, in the product's own words.
+     *
+     * Required and never defaulted: "Add recipient", "Add a line" and "Ajouter un
+     * destinataire" are three products' answers, and the affordance is where a
+     * reader decides whether the set is one they can extend.
+     */
+    addLabel: ReactNode;
+    /**
+     * Called with the row to take off the set.
+     *
+     * The row and not its index, because the caller's array is the caller's and an
+     * index is only meaningful to whoever wrote the array. The Component keeps the
+     * index for itself, for the two things it has to do with it that a caller cannot:
+     * renumber what remains, and move focus to a neighbour.
+     */
+    onRemove: (row: TRow) => void;
+    /**
+     * The accessible name of one row's remove control, given that row's position.
+     *
+     * Required, and a function of the position rather than of the row, for the same
+     * reason `rowLabel` is: the sentence has to be true after a removal, and a
+     * sentence written from the row's own fields is a sentence that goes stale the
+     * moment the rows move. Written as the action and the position, the way a reader
+     * counts: "Remove stop 2".
+     */
+    removeLabel: (index: number) => string;
+    /**
+     * The visible position label of one row, and the accessible name of that row's
+     * region, given the row's position.
+     *
+     * Required, and it is one string in one place for two jobs on purpose. The
+     * number a sighted reader reads and the name a screen reader announces come from
+     * the same call, so they cannot disagree, and both are recomputed from the
+     * position on every render, so a removal in the middle renumbers the rows below
+     * it rather than leaving a gap. Return the bare ordinal when the set is
+     * self-evidently numbered, and a noun with it when it is not: `"2"`, or
+     * `` `Stop ${index + 1}` ``.
+     */
+    rowLabel: (index: number) => string;
+    /**
+     * The row's own cells, given the row and its facts.
+     *
+     * A render prop rather than a slot, and the reason is that the Component has to
+     * hand the row's cells a generated `id` for their labels to point at. A `children`
+     * slot receives the row and nothing else, which leaves the caller minting ids
+     * per row and reintroducing exactly the arrangement this Component exists to
+     * hold still. Everything inside is the caller's: which controls a row has, what
+     * they are called, how they are arranged.
+     */
+    children: (row: TRow, info: RepeatableRowInfo) => ReactNode;
+    /**
+     * The set's own name, drawn above it and used as its accessible name.
+     *
+     * Optional, and the omission is deliberate rather than an oversight: this is
+     * the one place in the package where a region may arrive anonymous, and
+     * `ListPanel` says why at length. A set called "Rows" is a claim that is wrong
+     * in every consumer's product, and a screen reader user hearing a generic name
+     * learns less than hearing none. Pass one when the set sits among several.
+     */
+    label?: ReactNode;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+}
+/**
+ * A variable-length set of row objects: add one, take one away, and keep every
+ * label, every name and the reader's focus pointing at the right row.
+ *
+ * **It is a set of objects and not a set of values, and that is the first thing
+ * that makes it a Component rather than a loop.** A list of strings is a
+ * `TagGroup`, and a list of values with no fields at all is a `ListPanel` of
+ * `Item` rows. What this is for is a set of records the reader is editing one at
+ * a time, where each record needs a stable identity that the caller's type does
+ * not carry. A line item, a recipient, a scheduled window: the domain object is
+ * what the caller's store already holds, and asking for a `key` field on it means
+ * either a new field on a type the caller does not own or a parallel array the
+ * caller has to keep in step with a second time. So the Component mints the
+ * identity, keyed to the row object's own identity, and the caller never sees it.
+ *
+ * **The generated key follows the object, and that is what makes a middle removal
+ * survivable.** The key is held in a `WeakMap` against the row object itself, so
+ * a row that stays where it is keeps its key, its element, its control values and
+ * its caret, however many rows are taken out above it. A key derived from the
+ * index would reuse one element for a different record, which is invisible in a
+ * controlled field and destructive in an uncontrolled one. The honest cost is on
+ * the other side of the same decision: the map is keyed by identity, so the row
+ * objects have to be the same objects across renders, and a caller who rebuilds
+ * them on every render pays a remount on every keystroke. The prop says so where
+ * a caller will read it.
+ *
+ * **The generated id follows the row and the ordinal follows the position, and a
+ * removal has to move one without moving the other.** This is the accessibility
+ * argument for the whole Component, so it is worth being exact. A field label's
+ * `for` resolves to a control's `id`; if that `id` carried the position, removing
+ * the second of three rows would renumber the third row's control, and every
+ * label pointing at the old id would then name the wrong control, silently, on a
+ * form that still looks correct. So `fieldId` is derived from the row's key and
+ * survives everything that happens around it. The number the reader reads and the
+ * name the screen reader announces are the opposite: they are the position, they
+ * are recomputed from the index on every render, and the group around each row is
+ * named by that same visible label through `aria-labelledby` rather than by a
+ * second string. One string, two jobs, so the two can never disagree, and a
+ * removal in the middle renumbers the rows below it instead of leaving a hole
+ * where a number used to be.
+ *
+ * **Adding moves the reader into the new row, and it moves them into the first
+ * cell rather than onto the row.** A row that receives focus and nothing else is
+ * a reader who is told "stop 4" and then has to Tab to find out what is in it,
+ * which is the same dead end as focus landing on `body`: the work of finding the
+ * first control is pushed back onto the person who just asked for the row. So the
+ * Component looks for the row's first focusable cell and puts the reader in it.
+ * When there is none, because the caller's row is a read-only summary or a row of
+ * custom controls, the focus lands on the row itself, which carries
+ * `tabindex="-1"` and the row's own name so the reader at least hears where they
+ * are. The cost of that fallback is stated rather than hidden: a container
+ * focused by script draws its ring only when the browser believes the reader is
+ * navigating by keyboard, which is the same rule every programmatically focused
+ * container follows, and a caller who needs a guaranteed visible landing point
+ * gives the row a real control first.
+ *
+ * **Removing moves the reader to a neighbour, because the button they pressed is
+ * about to stop existing.** Same argument as the field, and the destination is
+ * the same one: the row that moved up into the removed row's place, or the row
+ * above it when the removed row was last, and the add control when the set is now
+ * empty. A set whose last row is removed leaves one operable thing in the
+ * Component, and it is the one the reader will press next.
+ *
+ * **The Component owns the row's frame and the caller owns the row's cells, which
+ * is the same division `Item` draws one level up.** The position label, the
+ * remove control and the region semantics are Prism's, because they are the parts
+ * that have to stay consistent across every set in every consumer and they are
+ * the parts a caller gets wrong. The controls are the caller's, because what a
+ * row contains is a fact about the caller's record. `Button` draws the add
+ * affordance rather than this Component re-deriving a control's metrics, and the
+ * focus targets are the Component's own `data-slot` values read back through one
+ * root ref, because a ref per row would be a second bookkeeping list to reconcile
+ * against the caller's array on every commit.
+ *
+ * **It draws no empty state, and the omission is a decision.** A repeatable set
+ * with no rows is the ordinary first state of every form that has one, and a
+ * sentence about it is a claim about the caller's form that Prism cannot make. A
+ * bordered box with a heading above it and nothing in it reads as a rendering
+ * failure, so with no rows the Component draws no frame at all, and the add
+ * affordance is the only thing on the page.
+ *
+ * **It is a client Component**, because both focus moves happen after the reader
+ * acts and neither can be known at a server render, and because every one of its
+ * value props is a function the caller hands it, which is a client-to-client
+ * boundary wherever it is written. What that costs is the price of every client
+ * field: a server Component may render the set once with the rows already in
+ * place, and what it may not do is offer the add and remove affordances with
+ * focus that behaves.
+ *
+ * **The row type is not a type parameter of this function, and the reason is a
+ * gate rather than a preference, so it is worth stating exactly.** A Component
+ * declared as `function RepeatableRows<TRow>(...)` is invisible to
+ * `check-item-docs.mjs`, which finds an Item's declaration by matching a function
+ * name followed by an open parenthesis; a generic's angle bracket sits between the
+ * two, so the gate reports the module as declaring no Item at all and the build
+ * fails. The whole Component layer of this package is therefore written without
+ * generics, and this Component pays for it in exactly one place: the props
+ * interface is generic, and the exported function instantiates it without a row
+ * type. The cost is that a caller's render prop receives its row untyped, so a
+ * caller who wants the type either annotates the parameter in the prop, which is
+ * one word, or writes their own wrapper over `RepeatableRowsProps<TheirRow>`,
+ * which is one line. The benefit is that the Item stays a documented Item with an
+ * interface the corpus can read, and that is worth more than inference on a
+ * callback whose row the caller has just handed the Component themselves.
+ */
+declare function RepeatableRows({ rows, onAdd, addLabel, onRemove, removeLabel, rowLabel, children, label, className, }: RepeatableRowsProps<any>): import("react").JSX.Element;
+export { RepeatableRows };
+//# sourceMappingURL=repeatable-rows.d.ts.map

package/dist/components/ui/repeatable-rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repeatable-rows.d.ts","sourceRoot":"","sources":["../../../src/components/ui/repeatable-rows.tsx"],"names":[],"mappings":"AAGA,OAAO,EAA4B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAKhE;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;OASG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAmB,CAAC,IAAI,SAAS,MAAM;IACtD;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,SAAS,IAAI,EAAE,CAAA;IACrB;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB;;;;;;OAMG;IACH,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;;;;OAOG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,IAAI,CAAA;IAC7B;;;;;;;;OAQG;IACH,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC;;;;;;;;;;;OAWG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACnC;;;;;;;;;OASG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,iBAAiB,KAAK,SAAS,CAAA;IAC3D;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAmCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwGG;AACH,iBAAS,cAAc,CAAC,EACtB,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,SAAS,GACV,EAAE,mBAAmB,CAAC,GAAG,CAAC,+BA8K1B;AAED,OAAO,EAAE,cAAc,EAAE,CAAA"}

package/dist/components/ui/repeatable-rows.js

@@ -0,0 +1,221 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PlusIcon, XIcon } from 'lucide-react';
+import { useEffect, useId, useRef } from 'react';
+import { Button } from './button.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The remove control, drawn once and used by every row.
+ *
+ * The muted ink because every row is the same surface and a control that changed
+ * colour with its row's state would be a second thing to read, and the 44px
+ * coarse-pointer floor so a set of five rows on a phone is a set of rows a thumb
+ * can hit. Duplicated as a constant rather than imported, because the remove
+ * controls in this package are each drawn inside the module that owns them and
+ * there is no shared recipe on the surface: a caller cannot reach into another
+ * Component's row geometry, and a design system that exported one class string as
+ * a public API 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 first control in a row, found by asking the row rather than by being told.
+ *
+ * The Component cannot be told which of the caller's cells is first, because a
+ * cell is whatever the caller's render prop returned and the Component never sees
+ * the caller's field. So it asks the row. Three groups are excluded and each
+ * exclusion is a real case: a hidden input is focusable and invisible, a
+ * disabled control refuses focus, and a control already opted out with
+ * `tabindex="-1"` asked not to be.
+ */
+const FIRST_FOCUSABLE = 'input:not([type="hidden"]),select:not([disabled]),textarea:not([disabled]),button:not([disabled]),[contenteditable],[tabindex]:not([tabindex="-1"])';
+/** The Component's own slots, read back through one root ref after a change. */
+const ROW_SLOT = '[data-slot="repeatable-rows-row"]';
+const REMOVE_SLOT = '[data-slot="repeatable-rows-remove"]';
+const ADD_SLOT = '[data-slot="repeatable-rows-add"]';
+/**
+ * A variable-length set of row objects: add one, take one away, and keep every
+ * label, every name and the reader's focus pointing at the right row.
+ *
+ * **It is a set of objects and not a set of values, and that is the first thing
+ * that makes it a Component rather than a loop.** A list of strings is a
+ * `TagGroup`, and a list of values with no fields at all is a `ListPanel` of
+ * `Item` rows. What this is for is a set of records the reader is editing one at
+ * a time, where each record needs a stable identity that the caller's type does
+ * not carry. A line item, a recipient, a scheduled window: the domain object is
+ * what the caller's store already holds, and asking for a `key` field on it means
+ * either a new field on a type the caller does not own or a parallel array the
+ * caller has to keep in step with a second time. So the Component mints the
+ * identity, keyed to the row object's own identity, and the caller never sees it.
+ *
+ * **The generated key follows the object, and that is what makes a middle removal
+ * survivable.** The key is held in a `WeakMap` against the row object itself, so
+ * a row that stays where it is keeps its key, its element, its control values and
+ * its caret, however many rows are taken out above it. A key derived from the
+ * index would reuse one element for a different record, which is invisible in a
+ * controlled field and destructive in an uncontrolled one. The honest cost is on
+ * the other side of the same decision: the map is keyed by identity, so the row
+ * objects have to be the same objects across renders, and a caller who rebuilds
+ * them on every render pays a remount on every keystroke. The prop says so where
+ * a caller will read it.
+ *
+ * **The generated id follows the row and the ordinal follows the position, and a
+ * removal has to move one without moving the other.** This is the accessibility
+ * argument for the whole Component, so it is worth being exact. A field label's
+ * `for` resolves to a control's `id`; if that `id` carried the position, removing
+ * the second of three rows would renumber the third row's control, and every
+ * label pointing at the old id would then name the wrong control, silently, on a
+ * form that still looks correct. So `fieldId` is derived from the row's key and
+ * survives everything that happens around it. The number the reader reads and the
+ * name the screen reader announces are the opposite: they are the position, they
+ * are recomputed from the index on every render, and the group around each row is
+ * named by that same visible label through `aria-labelledby` rather than by a
+ * second string. One string, two jobs, so the two can never disagree, and a
+ * removal in the middle renumbers the rows below it instead of leaving a hole
+ * where a number used to be.
+ *
+ * **Adding moves the reader into the new row, and it moves them into the first
+ * cell rather than onto the row.** A row that receives focus and nothing else is
+ * a reader who is told "stop 4" and then has to Tab to find out what is in it,
+ * which is the same dead end as focus landing on `body`: the work of finding the
+ * first control is pushed back onto the person who just asked for the row. So the
+ * Component looks for the row's first focusable cell and puts the reader in it.
+ * When there is none, because the caller's row is a read-only summary or a row of
+ * custom controls, the focus lands on the row itself, which carries
+ * `tabindex="-1"` and the row's own name so the reader at least hears where they
+ * are. The cost of that fallback is stated rather than hidden: a container
+ * focused by script draws its ring only when the browser believes the reader is
+ * navigating by keyboard, which is the same rule every programmatically focused
+ * container follows, and a caller who needs a guaranteed visible landing point
+ * gives the row a real control first.
+ *
+ * **Removing moves the reader to a neighbour, because the button they pressed is
+ * about to stop existing.** Same argument as the field, and the destination is
+ * the same one: the row that moved up into the removed row's place, or the row
+ * above it when the removed row was last, and the add control when the set is now
+ * empty. A set whose last row is removed leaves one operable thing in the
+ * Component, and it is the one the reader will press next.
+ *
+ * **The Component owns the row's frame and the caller owns the row's cells, which
+ * is the same division `Item` draws one level up.** The position label, the
+ * remove control and the region semantics are Prism's, because they are the parts
+ * that have to stay consistent across every set in every consumer and they are
+ * the parts a caller gets wrong. The controls are the caller's, because what a
+ * row contains is a fact about the caller's record. `Button` draws the add
+ * affordance rather than this Component re-deriving a control's metrics, and the
+ * focus targets are the Component's own `data-slot` values read back through one
+ * root ref, because a ref per row would be a second bookkeeping list to reconcile
+ * against the caller's array on every commit.
+ *
+ * **It draws no empty state, and the omission is a decision.** A repeatable set
+ * with no rows is the ordinary first state of every form that has one, and a
+ * sentence about it is a claim about the caller's form that Prism cannot make. A
+ * bordered box with a heading above it and nothing in it reads as a rendering
+ * failure, so with no rows the Component draws no frame at all, and the add
+ * affordance is the only thing on the page.
+ *
+ * **It is a client Component**, because both focus moves happen after the reader
+ * acts and neither can be known at a server render, and because every one of its
+ * value props is a function the caller hands it, which is a client-to-client
+ * boundary wherever it is written. What that costs is the price of every client
+ * field: a server Component may render the set once with the rows already in
+ * place, and what it may not do is offer the add and remove affordances with
+ * focus that behaves.
+ *
+ * **The row type is not a type parameter of this function, and the reason is a
+ * gate rather than a preference, so it is worth stating exactly.** A Component
+ * declared as `function RepeatableRows<TRow>(...)` is invisible to
+ * `check-item-docs.mjs`, which finds an Item's declaration by matching a function
+ * name followed by an open parenthesis; a generic's angle bracket sits between the
+ * two, so the gate reports the module as declaring no Item at all and the build
+ * fails. The whole Component layer of this package is therefore written without
+ * generics, and this Component pays for it in exactly one place: the props
+ * interface is generic, and the exported function instantiates it without a row
+ * type. The cost is that a caller's render prop receives its row untyped, so a
+ * caller who wants the type either annotates the parameter in the prop, which is
+ * one word, or writes their own wrapper over `RepeatableRowsProps<TheirRow>`,
+ * which is one line. The benefit is that the Item stays a documented Item with an
+ * interface the corpus can read, and that is worth more than inference on a
+ * callback whose row the caller has just handed the Component themselves.
+ */
+function RepeatableRows({ rows, onAdd, addLabel, onRemove, removeLabel, rowLabel, children, label, className, }) {
+    const generated = useId();
+    const labelId = `${generated}-label`;
+    const rootRef = useRef(null);
+    // One generated key per row object, held against the object rather than
+    // against the position. A `WeakMap` rather than a counter keyed by index is the
+    // whole difference between "the third row is still the third row" and "the
+    // third slot is still the third slot", and the second one silently moves a
+    // caller's control values when a row above it is removed.
+    const keys = useRef(new WeakMap());
+    const minted = useRef(0);
+    // The row to put the reader in after the caller's value settles: a position, or
+    // `'add'` for the row the caller has been asked to append. 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 seen = useRef(rows.length);
+    useEffect(() => {
+        const target = pending.current;
+        const count = rows.length;
+        if (target === null) {
+            seen.current = count;
+            return;
+        }
+        // An add that the caller has not acted on yet stays armed. The alternative is
+        // to focus the row that is currently last, which is the worst outcome
+        // available: the reader is typing into a record they did not ask for.
+        if (target === 'add' && count <= seen.current)
+            return;
+        pending.current = null;
+        seen.current = count;
+        const root = rootRef.current;
+        if (root === null)
+            return;
+        if (target === 'add') {
+            const row = root.querySelectorAll(ROW_SLOT).item(count - 1);
+            if (row === null)
+                return;
+            const cell = row.querySelector(FIRST_FOCUSABLE);
+            (cell ?? row).focus();
+            return;
+        }
+        // A removal: the row that moved up into the removed row's place, or the one
+        // above it when the removed row was the last. An empty set has no row to land
+        // on and the add control is the only operable thing left in the Component.
+        if (count === 0) {
+            root.querySelector(ADD_SLOT)?.focus();
+            return;
+        }
+        const buttons = root.querySelectorAll(REMOVE_SLOT);
+        const button = buttons.item(Math.min(target, buttons.length - 1));
+        if (button === null)
+            root.querySelector(ADD_SLOT)?.focus();
+        else
+            button.focus();
+    });
+    const keyFor = (row) => {
+        const known = keys.current.get(row);
+        if (known !== undefined)
+            return known;
+        minted.current += 1;
+        const made = `row-${minted.current}`;
+        keys.current.set(row, made);
+        return made;
+    };
+    const removeAt = (index) => {
+        const row = rows[index];
+        if (row === undefined)
+            return;
+        pending.current = index;
+        onRemove(row);
+    };
+    return (_jsxs("div", { ref: rootRef, "data-slot": "repeatable-rows", role: "group", "aria-labelledby": label === undefined ? undefined : labelId, className: cn('flex w-full flex-col gap-2', className), children: [label === undefined ? null : (_jsx("span", { id: labelId, "data-slot": "repeatable-rows-label", className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: label })), _jsx("ol", { "data-slot": "repeatable-rows-list", className: "flex w-full flex-col gap-2", children: rows.map((row, index) => {
+                    const key = keyFor(row);
+                    const fieldId = `${generated}-field-${key}`;
+                    return (_jsxs("li", { "data-slot": "repeatable-rows-item", className: "border-border bg-card flex items-end gap-2 rounded-md border px-3 py-2", children: [_jsxs("div", { "data-slot": "repeatable-rows-row", role: "group", tabIndex: -1, "aria-labelledby": `${generated}-label-${key}`, className: cn('flex min-w-0 flex-1 flex-wrap items-end gap-2 rounded-sm outline-none', 'focus-visible:ring-ring focus-visible:ring-[3px]'), children: [_jsx("span", { id: `${generated}-label-${key}`, "data-slot": "repeatable-rows-position", className: "text-muted-foreground shrink-0 text-xs font-medium tabular-nums", children: rowLabel(index) }), children(row, { index, fieldId })] }), _jsx("button", { type: "button", "data-slot": "repeatable-rows-remove", "aria-label": removeLabel(index), onClick: () => removeAt(index), className: REMOVE_CONTROL, children: _jsx(XIcon, { className: "size-4", "aria-hidden": "true" }) })] }, key));
+                }) }), _jsx("div", { "data-slot": "repeatable-rows-actions", className: "flex items-center", children: _jsxs(Button, { "data-slot": "repeatable-rows-add", type: "button", variant: "outline", size: "sm", onClick: () => {
+                        pending.current = 'add';
+                        onAdd();
+                    }, children: [_jsx(PlusIcon, { "aria-hidden": "true" }), addLabel] }) })] }));
+}
+export { RepeatableRows };

package/dist/components/ui/repo-stars.d.ts

@@ -0,0 +1,165 @@
+import type { ComponentProps, ReactNode } from 'react';
+/**
+ * The two steps a star readout is drawn at, as frame and figure together.
+ *
+ * The pair moves as one because a readout is a figure with a unit attached to it
+ * and the two are read as one sentence: a count at the `sm` step beside a noun
+ * at the `md` step is a count and a caption, and a reader scanning a page of them
+ * sees the numbers at one height and the nouns at another. `sm` is for a footer,
+ * a table row and a card description, and `md` is for a card header and a page
+ * header. There is no third step because a star count is never the headline
+ * figure of a page, and a Component that could be drawn at the title step would
+ * be a Component asking to be the thing it annotates.
+ */
+declare const REPO_STARS_SIZE: {
+    readonly sm: "items-center gap-1 text-xs";
+    readonly md: "items-center gap-1.5 text-sm";
+};
+/**
+ * The two steps a star readout is drawn at.
+ *
+ * @defaultValue 'md'
+ */
+export type RepoStarsSize = keyof typeof REPO_STARS_SIZE;
+/** The props a RepoStars accepts. */
+export type RepoStarsProps = {
+    /**
+     * The number of stars, exactly as the host reported it.
+     *
+     * Required, and a `number` rather than the formatted string for the reason the
+     * whole `format` argument is about: a count is a fact the host owns, and a
+     * Component that accepted a string would be accepting a rendering and calling
+     * it a fact. A count nobody has fetched yet is a consumer's problem and not a
+     * Component's, and a `null` is refused by the type rather than drawn as a zero
+     * that nobody earned.
+     */
+    count: number;
+    /**
+     * The noun the count carries, and where the repository is named when the
+     * surrounding surface does not name it.
+     *
+     * Required, and required as a `string` because it is the whole of what the
+     * readout says about itself: a number beside no unit is a number the reader has
+     * to guess the meaning of, which is the one thing a headline figure cannot
+     * afford, and it is the same argument `Metric` makes about its own label. It is
+     * also where the repository goes when a link's accessible name would otherwise
+     * not say where the link leads, so a caller on a page that names the repository
+     * already writes "stars" and a caller on a page that does not writes "stars on
+     * this repository". The words are the consumer's, in their own language.
+     */
+    label: string;
+    /**
+     * The host's own mark, passed in and never drawn by this package.
+     *
+     * Required, and a slot rather than an asset, for the reason the package states
+     * everywhere it has a mark to fill: Prism's icon lane is Lucide, and Lucide has
+     * no repository host in it. A host's mark is a licensed trademark with rules
+     * governing its clear space, its colour, its minimum size and its use on a third
+     * party's surface, and a package that shipped one would be shipping an asset it
+     * was not entitled to and that is out of date the moment the host redraws it.
+     * So the space is here and the frame around it is a size and a clip and nothing
+     * else, so a consumer's vector mark and a consumer's raster asset come out the
+     * same height whichever they pass.
+     *
+     * Required rather than optional, and that is a decision with a cost. A readout
+     * with no mark beside it is a number and a noun and nothing saying which host
+     * they are about, so the mark is what makes the number mean what it claims to.
+     * The cost is that a consumer hosting their own repository, with no third party
+     * brand to point at, has no mark to pass and so has no use for this Component:
+     * the honest answer for them is a `Metric`, which is a figure that needs no
+     * host.
+     */
+    mark: ReactNode;
+    /**
+     * The words the count is drawn through, given the count.
+     *
+     * Optional, and there is no default that abbreviates, because "1.2k" is two
+     * decisions rather than one. It is a locale, because the compact form a reader
+     * expects in English is not the one a German or a Japanese reader expects, and
+     * it is a judgement, because a count of 1,204 reads as a large project on a
+     * repository page and as a rounding error beside a funding total, and only the
+     * consumer knows which page it is on. So the number is printed exactly as
+     * given when this is absent, which is honest and usually not what was wanted
+     * for a six figure count, and a consumer who wants grouping or a compact form
+     * passes the formatter that has it.
+     *
+     * **`Intl` is deliberately not the fallback.** A server-rendered figure
+     * formatted in the runtime's own locale is a figure that changes when the
+     * deployment region changes, and a number that reads "1,204" in one build and
+     * "1.204" in another is a number two readers were told different things about.
+     * The fallback is `String(count)`, which is what `Metric` prints for a delta
+     * with no formatter, and it has the same property: the same bytes everywhere.
+     */
+    format?: (count: number) => string;
+    /**
+     * Where the readout leads, when the reader may follow it.
+     *
+     * Optional, and a plain `href` rather than a router link, because this package
+     * imports no router and a Page is what a consumer's router renders. With it
+     * the mark, the count and the noun are one thing to follow rather than three
+     * things to read, and the whole readout is the anchor's hit area. Without it the
+     * readout is a span, and that is a legitimate state rather than a missing prop:
+     * a page footer that reports a project's popularity is reporting it, and
+     * offering a link there invites a reader off a page they are reading.
+     */
+    href?: string;
+    /** The drawn step, as frame and figure together. @defaultValue 'md' */
+    size?: RepoStarsSize;
+} & Omit<ComponentProps<'span'>, 'children'>;
+/**
+ * How many people starred a source repository, beside the host's own mark.
+ *
+ * **The mark is a slot and the reason is a licence, not a preference.** Prism's
+ * icon lane is Lucide, and Lucide draws interface glyphs rather than other
+ * companies' trademarks, and a repository host's mark is a licensed asset with
+ * rules about its clear space, its colour, its minimum size and where it may
+ * appear. A package that shipped one would be distributing an asset it does not
+ * own, and it would be wrong within a year as hosts redraw. So the consumer passes
+ * the mark and this Component draws the frame around it. The cost is stated
+ * rather than hidden: a consumer who wants the readout in an afternoon has to
+ * source the mark, and a consumer with no host to point at cannot use this
+ * Component at all.
+ *
+ * **The count is printed by a callback and the fallback is the bare number.**
+ * There is no `Intl` default and the omission is the decision, for the reason
+ * `format` states: a compact count is a locale and a judgement, and a figure
+ * formatted in the runtime's locale changes when the deployment region changes.
+ * The visible cost is that a consumer with a six figure count and no formatter
+ * draws all six digits, which is honest and wider than they wanted.
+ *
+ * **There is no navigation region and no landmark, and the reason is that a
+ * count is not a place.** A `<nav>` is a set of routes and this is one figure
+ * beside a mark, so the readout renders a span or an anchor and nothing else. A
+ * consumer who puts one inside their own `<nav>` has made a claim about their own
+ * page that Prism neither makes nor checks, and the `href` is the consumer's to
+ * resolve: this Component validates nothing about it, and the package is router
+ * free and transport free by design.
+ *
+ * **A link here is an anchor, so there is no `target` and no `rel`.** Both belong
+ * to the anchor and the anchor is inside the readout, and an anchor-shaped root
+ * that changed element with `href` would put `rel` and `target` onto a `span` on
+ * every readout that has no link, which is invalid markup for a control Prism
+ * did not draw. A consumer who needs a new tab or a referrer policy writes their
+ * own anchor around the readout, which is one element and keeps every class here.
+ *
+ * **The link's ink is `brand-ink` and the readout's is `foreground`, and that
+ * split is DESIGN.md's Brand Ink Rule rather than a preference.** A readout that
+ * is not a link is a figure and takes the page's ink. A readout that is a link
+ * has to read as something a reader may follow, and the token gate measures
+ * `brand-ink` at 4.5:1 against the page, a card and the accent surface in both
+ * modes of all six sources. The focus ring is drawn at full strength on the
+ * anchor rather than left to the browser, so the indicator this Component owns
+ * is the indicator the gate can check.
+ *
+ * **It is a server Component, and the reason is that everything it draws is
+ * decided from props.** No hook, no state, no effect, no handler and no directive,
+ * so a page with four star readouts ships no JavaScript for them at all. The
+ * consequence worth stating is the one a reader would otherwise have to work out:
+ * with no `href` there is no interaction, and with one the only behaviour is the
+ * browser's own navigation, so there is nothing this Component could need a client
+ * runtime to do. The cost is that a consumer who wants the count to refresh
+ * itself is reaching for a `live` surface and a subscription Prism does not own.
+ */
+declare function RepoStars({ count, label, mark, format, href, size, className, ...props }: RepoStarsProps): import("react").JSX.Element;
+export { RepoStars };
+//# sourceMappingURL=repo-stars.d.ts.map

package/dist/components/ui/repo-stars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-stars.d.ts","sourceRoot":"","sources":["../../../src/components/ui/repo-stars.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItD;;;;;;;;;;;GAWG;AACH,QAAA,MAAM,eAAe;;;CAGX,CAAA;AAEV;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,eAAe,CAAA;AAExD,qCAAqC;AACrC,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;;OAYG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,IAAI,EAAE,SAAS,CAAA;IACf;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,uEAAuE;IACvE,IAAI,CAAC,EAAE,aAAa,CAAA;CAMrB,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,CAAA;AA2C5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,iBAAS,SAAS,CAAC,EACjB,KAAK,EACL,KAAK,EACL,IAAI,EACJ,MAAM,EACN,IAAI,EACJ,IAAW,EACX,SAAS,EACT,GAAG,KAAK,EACT,EAAE,cAAc,+BAsBhB;AAED,OAAO,EAAE,SAAS,EAAE,CAAA"}