@nanisoft/prism-ui 0.16.1 → 1.1.0

package/dist/blocks/auth-form-01/auth-form.js

@@ -1,49 +1,113 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { CircleAlert } from 'lucide-react';
+import { useId, useState } from 'react';
 import { Alert, AlertDescription } from '../../components/ui/alert.js';
 import { Button } from '../../components/ui/button.js';
 import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, } from '../../components/ui/card.js';
 import { Checkbox } from '../../components/ui/checkbox.js';
-import { Field, FieldDescription, FieldGroup, FieldLabel, } from '../../components/ui/field.js';
-import { Input } from '../../components/ui/input.js';
+import { Field, FieldDescription, FieldError, FieldGroup } from '../../components/ui/field.js';
+import { Label } from '../../components/ui/label.js';
+import { CHOICE_KINDS, fieldText, NEEDS_HIDDEN, renderControl, serialize, SELF_LABELLED, } from '../../lib/field-render.js';
 /**
- * A sign-in card.
+ * The two ways a caller's field declaration can be a form that cannot be filled,
+ * checked before anything is drawn so the run fails once with the name of the
+ * field rather than once per field with a nameless control on the page.
+ *
+ * Both reach a developer in a console rather than a reader, which is what makes
+ * them refusals rather than copy. The type catches both for a TypeScript caller,
+ * and the check is here for the JavaScript caller and for the value that came out
+ * of a database with the type's guarantee already gone.
+ */
+function assertGroups(groups) {
+    for (const group of groups) {
+        for (const field of group.fields) {
+            if (field.label === undefined || (typeof field.label === 'string' && field.label.trim() === '')) {
+                throw new Error(`AuthForm01: the field "${field.key}" declares no label, so its control would be announced with no name ` +
+                    'and two fields on this page would be announced identically. Every control this Block draws is named ' +
+                    'by its label, so there is no fallback to fall back to.');
+            }
+            if (CHOICE_KINDS.has(field.kind) &&
+                (field.options?.length ?? 0) === 0) {
+                throw new Error(`AuthForm01: the field "${field.key}" is a choice and passes no options, so it would render a control ` +
+                    'with nothing in it, which is a question no reader can answer and looks answered only because the ' +
+                    'control is there and focusable. Pass the choices, or declare the field as a text field and check the ' +
+                    'answer in your own handler.');
+            }
+        }
+    }
+}
+/**
+ * A sign-in card, or a registration or a recovery, rendered from the shared field
+ * specification.
  *
  * The block renders the card, the labelled fields, the remember row and the
- * submit control. It owns no credentials and no request: every field value and
- * the submit handler come from the consumer, and the error line is a prop so
- * the consumer's validation decides when it appears. Every string is a prop.
+ * submit control. It owns no credentials and no request: every field value comes
+ * from the controls the Block draws, the submit handler comes from the consumer,
+ * and a submission message is a prop so the consumer's validation decides when it
+ * appears. Every string is a prop.
+ *
+ * **It takes the shared field specification.** `groups` is an ordered list of
+ * `FieldSpecGroup`, each an optional heading and an ordered list of `FieldSpec`,
+ * and a field carries a stable `key`, a required `label` and a required `kind`
+ * drawn from Prism's own input vocabulary. A login, a registration and a password
+ * recovery are one Block and nothing forks here: asking for an email draws the
+ * `Input` this package ships and asking for a password draws its `PasswordField`,
+ * and a control this package does not ship is the `slot` arm rather than a second
+ * Block. The vocabulary a consumer learns on a record write form is the
+ * vocabulary here, and there is no second field declaration beside it.
+ *
+ * **An error is one message about the submission, and it marks no field.** A
+ * form-level sentence is usually not about a control at all: bad credentials, a
+ * locked account and a rate limit are all things no field is wrong about. The
+ * message is drawn in an `Alert`, which announces itself, and a message that
+ * belongs to one field is an entry in `issues`, drawn under that control and
+ * marking only it. A submission sentence never marks two fields, because a reader
+ * who is told two correctly filled fields are wrong stops trusting the rest of the
+ * form.
  *
- * **An error is one message about the submission, and it marks at most one field.**
- * The two are separate decisions because a form-level sentence is usually not about
- * a control at all: bad credentials, a locked account and a rate limit are all
- * things no field is wrong about. The message is drawn in an `Alert`, which
- * announces itself, and the field the caller names in `errorId` carries
- * `aria-invalid`, and every other field carries nothing. Marking them all was the
- * arrangement before, and it told a reader that two fields they had filled in
- * correctly were wrong.
+ * **A field's help is drawn under it and referred to by it.** The id is derived
+ * from the control's own `id`, which is stable for the life of the form, so the
+ * reference cannot collide and a screen reader hears what the field is for as it
+ * reaches it.
  *
- * **A field's description is drawn under it and referred to by it.** The id is
- * derived from the field's own `id`, which is already the one stable caller-owned
- * string on the field, so the reference costs a template and cannot collide.
+ * **It is uncontrolled where a Prism control can be.** The platform submits an
+ * `Input`, a `Textarea`, a `NativeSelect` and the controls that render their own
+ * input, so the caller reads the values out of the form element in `onSubmit`.
+ * The handful of Prism controls the platform will not submit on their own hold
+ * their value and carry a hidden input under the field's key, so the payload is
+ * complete either way.
  */
-export function AuthForm01({ title, description, fields, error, remember, submitLabel, pendingLabel, pending = false, onSubmit, footer, headingLevel = 'h2', }) {
+export function AuthForm01({ title, description, groups, issues, submitError, remember, submitLabel, pendingLabel, pending = false, onSubmit, footer, headingLevel = 'h2', }) {
+    const generated = useId();
+    const [values, setValues] = useState({});
+    const setValue = (key, value) => setValues((previous) => ({ ...previous, [key]: value }));
+    assertGroups(groups);
     // This Block draws no section heading, so the card title is the one heading it
     // renders and takes the level directly rather than a step below one.
     const Title = headingLevel;
-    return (_jsx("form", { onSubmit: onSubmit, className: "w-full", children: _jsxs(Card, { children: [_jsxs(CardHeader, { children: [_jsx(CardTitle, { children: _jsx(Title, { children: title }) }), description ? _jsx(CardDescription, { children: description }) : null] }), _jsxs(CardContent, { className: "flex flex-col gap-4", children: [error ? (_jsxs(Alert, { variant: "destructive", children: [_jsx(CircleAlert, {}), _jsx(AlertDescription, { children: error })] })) : null, _jsx(FieldGroup, { children: fields.map((field) => {
-                                /*
-                                 * Derived from the field's own id rather than from a `useId`, because
-                                 * `field.id` is already the one stable, caller-owned string on the
-                                 * field and a generated one would have to be threaded through the
-                                 * description and the input to meet itself.
-                                 */
-                                const descriptionId = field.description === undefined ? undefined : `${field.id}-description`;
-                                const marked = error !== undefined && field.errorId === field.id;
-                                return (_jsxs(Field, { children: [_jsx(FieldLabel, { htmlFor: field.id, children: field.label }), _jsx(Input, { id: field.id, type: field.type ?? 'text', placeholder: field.placeholder, autoComplete: field.autoComplete, value: field.value, defaultValue: field.defaultValue, onChange: field.onChange
-                                                ? (event) => field.onChange?.(event.target.value)
-                                                : undefined, required: field.required, disabled: field.disabled, "aria-invalid": marked ? true : undefined, ...(descriptionId === undefined ? null : { 'aria-describedby': descriptionId }) }), field.description === undefined ? null : (_jsx(FieldDescription, { id: descriptionId, children: field.description }))] }, field.id));
-                            }) }), remember ? (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Checkbox, { id: remember.id, checked: remember.checked, defaultChecked: remember.defaultChecked, onCheckedChange: remember.onCheckedChange, disabled: remember.disabled }), _jsx(FieldLabel, { htmlFor: remember.id, children: remember.label })] })) : null] }), _jsxs(CardFooter, { className: "flex-col gap-3", children: [_jsx(Button, { type: "submit", className: "w-full", disabled: pending, children: pending ? (pendingLabel ?? submitLabel) : submitLabel }), footer] })] }) }));
+    return (_jsx("form", { onSubmit: onSubmit, className: "w-full", children: _jsxs(Card, { children: [_jsxs(CardHeader, { children: [_jsx(CardTitle, { children: _jsx(Title, { children: title }) }), description ? _jsx(CardDescription, { children: description }) : null] }), _jsxs(CardContent, { className: "flex flex-col gap-4", children: [submitError ? (_jsxs(Alert, { variant: "destructive", children: [_jsx(CircleAlert, {}), _jsx(AlertDescription, { children: submitError })] })) : null, groups.map((group, groupIndex) => (_jsxs(FieldGroup, { "data-slot": "auth-form-01-group", className: "flex flex-col gap-4", children: [group.label === undefined ? null : (_jsx("p", { "data-slot": "auth-form-01-group-label", className: "text-foreground text-sm font-medium", children: group.label })), group.description === undefined ? null : (_jsx("p", { "data-slot": "auth-form-01-group-description", className: "text-muted-foreground text-sm", children: group.description })), group.fields.map((field, fieldIndex) => {
+                                    const id = `${generated}-${groupIndex}-${fieldIndex}`;
+                                    const labelId = `${id}-label`;
+                                    const helpId = field.help === undefined ? undefined : `${id}-help`;
+                                    const fieldIssues = (issues ?? []).filter((issue) => issue.field === field.key);
+                                    const errorId = fieldIssues.length > 0 ? `${id}-error` : undefined;
+                                    const describedBy = helpId === undefined
+                                        ? errorId
+                                        : errorId === undefined
+                                            ? helpId
+                                            : `${helpId} ${errorId}`;
+                                    const kind = field.kind.toLowerCase();
+                                    const ctx = {
+                                        id,
+                                        labelId,
+                                        describedBy,
+                                        invalid: fieldIssues.length > 0,
+                                        text: fieldText(field),
+                                        values,
+                                        setValue,
+                                    };
+                                    return (_jsxs(Field, { "data-slot": "auth-form-01-field", "data-field": field.kind, children: [SELF_LABELLED.has(kind) ? null : (_jsx(Label, { id: labelId, htmlFor: id, required: field.required, disabled: field.disabled, children: field.label })), renderControl(field, ctx), NEEDS_HIDDEN.has(kind) ? (_jsx("input", { type: "hidden", name: field.key, value: serialize(values[field.key] ?? field.defaultValue) })) : null, field.help === undefined ? null : (_jsx(FieldDescription, { id: helpId, children: field.help })), fieldIssues.length === 0 ? null : (_jsx(FieldError, { id: errorId, children: fieldIssues.map((issue, issueIndex) => (_jsx("span", { "data-slot": "auth-form-01-issue", children: issue.message }, issueIndex))) }))] }, field.key));
+                                })] }, group.id ?? groupIndex))), remember ? (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Checkbox, { id: remember.id, checked: remember.checked, defaultChecked: remember.defaultChecked, onCheckedChange: remember.onCheckedChange, disabled: remember.disabled }), _jsx(Label, { htmlFor: remember.id, children: remember.label })] })) : null] }), _jsxs(CardFooter, { className: "flex-col gap-3", children: [_jsx(Button, { type: "submit", className: "w-full", disabled: pending, children: pending ? (pendingLabel ?? submitLabel) : submitLabel }), footer] })] }) }));
 }
 export default AuthForm01;

package/dist/blocks/auth-form-01/index.d.ts

@@ -1,3 +1,3 @@
 export { AuthForm01, default } from './auth-form.js';
-export type { AuthForm01Props, AuthFormField, AuthFormRemember } from './auth-form.js';
+export type { AuthForm01Issue, AuthForm01Props, AuthFormRemember } from './auth-form.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/blocks/auth-form-01/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/auth-form-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACjD,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/auth-form-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAMjD,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA"}

package/dist/blocks/calendar-01/calendar.d.ts

@@ -47,6 +47,20 @@ export type CalendarItem = {
      * what activating it does, which is the same defect `Download01` refuses.
      */
     hrefLabel?: string;
+    /**
+     * The caller's own control for one item, drawn at the leading edge of its row.
+     *
+     * It exists for the one interaction a date view has that this Block does not
+     * own: a move. Rescheduling an item onto another day is a drag with a drop
+     * target, a new order, a write and a conflict, and all four are the consumer's,
+     * exactly as `Kanban01` leaves a board's drag to a control the caller writes into
+     * a card slot. So the Block places this node and the caller wires it to whatever
+     * owns their schedule: it draws no drag, reports no move and holds no order,
+     * because a drag is behaviour a Block does not hold and a move is a write to a
+     * store this package never sees. A handle a reader can hear carries its own
+     * words, and the Block adds none.
+     */
+    handle?: ReactNode;
 };
 /**
  * The props a Calendar01 takes.
@@ -230,6 +244,20 @@ export type CalendarBlock01Props = {
  * rejected alternative was to print the tone's name as a fallback, and that is the
  * defect `check-block-copy.mjs` exists to end.
  *
+ * **A move is the caller's, and the Block exposes a per-item node rather than a
+ * move callback.** Rescheduling an item onto another day is the one interaction a
+ * date view has that this Block does not own: a drag with a drop target, a new
+ * order, a write and a conflict, and every one of the four is the consumer's,
+ * exactly as `Kanban01` leaves a board's drag to a control the caller writes into
+ * a card. So a `CalendarItem` carries a `handle`, a node the caller fills with
+ * their own control and wires to whatever owns their schedule, and the Block
+ * places it and nothing more. The rejected alternative is an `onMove` the Block
+ * wires to a drop target, and it is refused for the reason the kanban refuses a
+ * drag: it would make the Block own an order, a target and a write, and the
+ * conflict two reschedules create is a case this package has no answer for. The
+ * cost is named: a caller who wants a move writes the drag itself, and the Block
+ * gives it a place to attach rather than a model to adopt.
+ *
  * **A day is a heading one level below the section, and the items are not
  * headings at all.** A month is a set of days and the days are the things a reader
  * navigates to, so they are headings at `childLevel(headingLevel)` and moving this

package/dist/blocks/calendar-01/calendar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../../src/blocks/calendar-01/calendar.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAGpE;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;;;;;OAUG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mFAAmF;IACnF,KAAK,EAAE,SAAS,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,kEAAkE;IAClE,YAAY,CAAC,EAAE,IAAI,CAAA;IACnB,oEAAoE;IACpE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,KAAK,IAAI,CAAA;IACrC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,CAAA;IACpB,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAA;IACrB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;;OASG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACxC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,wBAAgB,UAAU,CAAC,EACzB,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,YAAY,EACZ,aAAa,EACb,MAAM,EACN,YAAY,EACZ,aAAa,EACb,SAAS,EACT,KAAK,EACL,KAAK,EACL,QAAQ,EACR,SAAa,EACb,aAAa,EACb,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,oBAAoB,+BA2JtB;AA4CD,eAAe,UAAU,CAAA"}
+{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../../src/blocks/calendar-01/calendar.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAGpE;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;;;;;OAUG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mFAAmF;IACnF,KAAK,EAAE,SAAS,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,kEAAkE;IAClE,YAAY,CAAC,EAAE,IAAI,CAAA;IACnB,oEAAoE;IACpE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,KAAK,IAAI,CAAA;IACrC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,CAAA;IACpB,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAA;IACrB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;;OASG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACxC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,wBAAgB,UAAU,CAAC,EACzB,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,YAAY,EACZ,aAAa,EACb,MAAM,EACN,YAAY,EACZ,aAAa,EACb,SAAS,EACT,KAAK,EACL,KAAK,EACL,QAAQ,EACR,SAAa,EACb,aAAa,EACb,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,oBAAoB,+BAgKtB;AA4CD,eAAe,UAAU,CAAA"}

package/dist/blocks/calendar-01/calendar.js

@@ -97,6 +97,20 @@ function parseDay(value) {
  * rejected alternative was to print the tone's name as a fallback, and that is the
  * defect `check-block-copy.mjs` exists to end.
  *
+ * **A move is the caller's, and the Block exposes a per-item node rather than a
+ * move callback.** Rescheduling an item onto another day is the one interaction a
+ * date view has that this Block does not own: a drag with a drop target, a new
+ * order, a write and a conflict, and every one of the four is the consumer's,
+ * exactly as `Kanban01` leaves a board's drag to a control the caller writes into
+ * a card. So a `CalendarItem` carries a `handle`, a node the caller fills with
+ * their own control and wires to whatever owns their schedule, and the Block
+ * places it and nothing more. The rejected alternative is an `onMove` the Block
+ * wires to a drop target, and it is refused for the reason the kanban refuses a
+ * drag: it would make the Block own an order, a target and a write, and the
+ * conflict two reschedules create is a case this package has no answer for. The
+ * cost is named: a caller who wants a move writes the drag itself, and the Block
+ * gives it a place to attach rather than a model to adopt.
+ *
  * **A day is a heading one level below the section, and the items are not
  * headings at all.** A month is a set of days and the days are the things a reader
  * navigates to, so they are headings at `childLevel(headingLevel)` and moving this
@@ -165,7 +179,7 @@ export function Calendar01({ eyebrow, title, description, month, defaultMonth, o
     return (_jsxs(Section, { "data-slot": "calendar-01", className: cn(className), children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-10" }), _jsxs("div", { "data-slot": "calendar-01-body", className: "flex flex-col gap-8 lg:flex-row lg:items-start", children: [_jsx(MiniCalendar, { month: shown, onMonthChange: changeMonth, locale: locale, weekStartsOn: weekStartsOn, previousLabel: previousLabel, nextLabel: nextLabel, label: label, className: "w-full shrink-0 lg:w-64" }), _jsx("div", { "data-slot": "calendar-01-days", className: "min-w-0 flex-1", children: days.length === 0 ? (empty === undefined ? null : (_jsx("p", { "data-slot": "calendar-01-empty", className: "text-muted-foreground text-pretty text-sm", children: empty }))) : (_jsx("ul", { className: "flex flex-col gap-6", children: days.map((day) => {
                                 const visible = day.items.slice(0, maxPerDay);
                                 const held = day.items.length - visible.length;
-                                return (_jsxs("li", { "data-slot": "calendar-01-day", className: "flex flex-col gap-2", children: [_jsx(DayTitle, { className: "text-sm font-semibold", children: dayHeading.format(day.at) }), _jsx("ul", { className: "flex flex-col gap-1.5", children: visible.map((item) => (_jsxs("li", { "data-slot": "calendar-01-item", "data-state": item.state, className: "flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1", children: [activatorOf(item, onSelect), item.state === undefined || item.stateLabel === undefined ? null : (_jsx(Status, { size: "sm", tone: item.state, label: item.stateLabel })), item.href === undefined || item.hrefLabel === undefined ? null : (_jsx(CtaLink, { href: item.href, variant: "ghost", size: "sm", children: item.hrefLabel }))] }, item.id))) }), held > 0 ? (_jsx("p", { "data-slot": "calendar-01-overflow", className: "text-muted-foreground text-xs", children: overflowLabel(held) })) : null] }, dayKey(day.at)));
+                                return (_jsxs("li", { "data-slot": "calendar-01-day", className: "flex flex-col gap-2", children: [_jsx(DayTitle, { className: "text-sm font-semibold", children: dayHeading.format(day.at) }), _jsx("ul", { className: "flex flex-col gap-1.5", children: visible.map((item) => (_jsxs("li", { "data-slot": "calendar-01-item", "data-state": item.state, className: "flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1", children: [item.handle === undefined ? null : (_jsx("span", { "data-slot": "calendar-01-handle", className: "shrink-0", children: item.handle })), activatorOf(item, onSelect), item.state === undefined || item.stateLabel === undefined ? null : (_jsx(Status, { size: "sm", tone: item.state, label: item.stateLabel })), item.href === undefined || item.hrefLabel === undefined ? null : (_jsx(CtaLink, { href: item.href, variant: "ghost", size: "sm", children: item.hrefLabel }))] }, item.id))) }), held > 0 ? (_jsx("p", { "data-slot": "calendar-01-overflow", className: "text-muted-foreground text-xs", children: overflowLabel(held) })) : null] }, dayKey(day.at)));
                             }) })) })] })] }));
 }
 /**

package/dist/blocks/card-index-01/card-index.d.ts

@@ -0,0 +1,225 @@
+import { type ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/** One row of data. Identity comes from `getRowId`, not from the shape. */
+export type CardIndex01Row = Record<string, unknown>;
+/**
+ * Every string the block renders. Required because the block ships no copy of
+ * its own: a selection summary, a per card name and an empty-state line are the
+ * consumer's to write.
+ */
+export type CardIndex01Labels = {
+    /** The header's selection control, naming the page it covers. */
+    selectAll: string;
+    /**
+     * The name of one card's selection control, in the caller's words.
+     *
+     * A function of the row rather than a string, because a checkbox announced as
+     * "Select" on all forty cards is a checkbox no reader can tell from the one
+     * below it. The name must name the record this checkbox ticks.
+     */
+    selectCard: (row: CardIndex01Row) => string;
+    /** The name of the region a card's own controls sit in, when they are supplied. */
+    cardActions: string;
+    /**
+     * The selection summary and the announced number for the page scope.
+     *
+     * It should say the page, in the caller's words, because "24 selected" over a
+     * grid of twenty four cards is true and says nothing about whether there are
+     * more: the page is the one population this Block can count for itself.
+     */
+    selectedCount: (count: number) => string;
+    /**
+     * The selection summary and the announced number for the filter scope.
+     *
+     * Used when the caller reports that the whole matching population is selected
+     * through `selectionScope`, and it takes the caller's own `count` rather than
+     * the number of cards on screen.
+     */
+    selectedAllMatching: (count: number) => string;
+    /**
+     * The sentence spoken when the selection empties.
+     *
+     * Not a count of zero: "0 selected" is a number the reader already heard and
+     * says nothing about why the batch bar has gone. The emptying is its own
+     * sentence.
+     */
+    clearedSelection: string;
+    /** The accessible name of the batch bar's dismiss control. */
+    dismissSelection: string;
+    previous: string;
+    next: string;
+    /** Accessible name for one page control. */
+    page: (page: number) => string;
+    /** Shown in the body when `rows` is empty and `emptyMessage` is not set. */
+    empty: string;
+};
+/**
+ * Which population the current selection covers, because the two are announced
+ * differently.
+ *
+ * A selection of everything on the page is one the block can count, so the page
+ * arm needs nothing beyond the selection set and the block announces
+ * `labels.selectedCount`. A selection of everything matching the current filter
+ * is a population the block never fetched, so the filter arm carries the number
+ * from the caller and the block announces `labels.selectedAllMatching` instead
+ * of printing the page as if it were the total.
+ *
+ * It is the same union and the same rule `DataTable01` uses, because ticket 166
+ * made one selection and announcement contract the record index family's, and
+ * this Block is the index's second arrangement rather than a second index.
+ */
+export type CardIndex01SelectionScope = {
+    scope: 'page';
+} | {
+    scope: 'filter';
+    /**
+     * How many records match the current filter, in the caller's own count.
+     *
+     * Required, and never derived from the cards: the block holds one page and
+     * a count over that page says nothing about the population the reader
+     * asked for.
+     */
+    count: number;
+};
+/** The props every arm of the block shares, selection aside. */
+type CardIndex01SharedProps = {
+    title?: ReactNode;
+    description?: ReactNode;
+    /** Heading level for the block's own heading. @defaultValue 'h2' */
+    headingLevel?: HeadingLevel;
+    /** The cards for the current page, in the caller's own order. */
+    rows: readonly CardIndex01Row[];
+    /**
+     * Returns a stable identity for a row.
+     *
+     * Required rather than optional, because paging moves a row's index, so an
+     * index-keyed selection silently changes which records a batch action acts on.
+     */
+    getRowId: (row: CardIndex01Row) => string;
+    /**
+     * The caller's own node for one card's body: the picture, the name and the
+     * price.
+     *
+     * A node per card rather than a declared field list, because a picture, a name
+     * and a price are three different value shapes and the read vocabulary this
+     * package publishes (`ColumnKind`) describes a row of a table rather than the
+     * anatomy of a card. The caller composes the card and the block owns the
+     * arrangement, the selection and the announcement.
+     */
+    renderCard: (row: CardIndex01Row) => ReactNode;
+    /**
+     * The caller's own controls for one card, drawn in a trailing region.
+     *
+     * A node per card rather than a declared action list, because a block ships no
+     * behaviour and a control that looks like a command but carries none is a
+     * control a reader can focus and cannot act on.
+     */
+    renderCardActions?: (row: CardIndex01Row) => ReactNode;
+    /**
+     * How many cards sit in one row at the widest width.
+     *
+     * Layout, and the only density knob the block owns. The grid always falls to
+     * one column at the narrowest width and to two at the small breakpoint, so a
+     * card is never squeezed below the width its own picture needs.
+     *
+     * @defaultValue 3
+     */
+    columnsPerRow?: 2 | 3 | 4;
+    /** The current page, 1-based. */
+    page?: number;
+    defaultPage?: number;
+    /** How many pages exist. At least 1. */
+    pageCount: number;
+    onPageChange?: (page: number) => void;
+    /** Replaces the fallback empty line. */
+    emptyMessage?: ReactNode;
+    labels: CardIndex01Labels;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+};
+/**
+ * The record index as pictures, which owns a set of row keys and reports every
+ * change.
+ *
+ * The two arms make the contract the type's: a selectable index must be handed
+ * the callback that reports a change and the node the batch bar holds, and a
+ * plain grid may be handed neither, because a tick with nowhere to report is a
+ * checkbox that changes nothing a caller can hear. It is the same union
+ * `DataTable01` declares, because ticket 166 made one selection contract the
+ * record index family's.
+ */
+export type CardIndex01Props = (CardIndex01SharedProps & {
+    selectable?: false;
+    selectedIds?: never;
+    defaultSelectedIds?: never;
+    onSelectedIdsChange?: never;
+    batchActions?: never;
+    selectionScope?: never;
+}) | (CardIndex01SharedProps & {
+    selectable: true;
+    /** The selected keys, controlled. Omit it and the block holds the set. */
+    selectedIds?: readonly string[];
+    /** The selected keys the in-heart set starts from. */
+    defaultSelectedIds?: readonly string[];
+    /**
+     * Called with the whole set after every change, whether or not the caller
+     * is listening, so mirroring it costs one line and ignoring it costs zero.
+     */
+    onSelectedIdsChange: (ids: string[]) => void;
+    /**
+     * The caller's own controls for the batch bar, mounted only while a
+     * selection exists. The block draws the frame, the count and the dismiss
+     * and places this node; it never draws a command of its own.
+     */
+    batchActions: ReactNode;
+    /**
+     * Which population the selection covers. Absent means the page.
+     *
+     * The caller reports it when its own selection is the whole matching
+     * population rather than the rows on screen, and passes that population's
+     * count on the filter arm.
+     */
+    selectionScope?: CardIndex01SelectionScope;
+});
+/**
+ * The record index as a grid of picture cards a reader compares and acts on.
+ *
+ * **It is the record index's second arrangement, and the job-identity test is
+ * what settles it.** A reader here is doing the index's job, deciding which
+ * record to act on, and the difference from `DataTable01` is the arrangement
+ * rather than the content: records are compared as pictures rather than
+ * across columns, so a screen that wants this has not found the index with one
+ * more prop, it has found the picture arrangement. `DESIGN.md` names it as an
+ * arrangement that forces a second Item, and this is that Item. A card carries
+ * the caller's own picture, name and price through `renderCard`, and per card
+ * actions through `renderCardActions`.
+ *
+ * **It shares the record index's selection and announcement contract.** The
+ * same `selectable` union, the same held set, the same three-state header
+ * control, the same polite `LiveRegion` carrying a count, the same batch bar
+ * that mounts only while the set is non-empty, and the same `selectionScope`
+ * that distinguishes a page-wide selection from a filter-wide one, all because
+ * ticket 166 made one contract the law for the index family. The count is
+ * announced once, politely, and never assertively; when the set empties the
+ * region speaks its own sentence rather than a count of zero; and the visible
+ * summary and the announced count are the same string.
+ *
+ * **It draws the page of cards it was handed, and it fetches nothing.** It sorts
+ * nothing, filters nothing and slices nothing, and every control in the footer
+ * is a report. It owns no action, batch or per card, so it owns no confirmation
+ * dialog, no toast and no undo; the batch bar is the Block's region and the
+ * caller's controls, and the dismiss is the Block's one control because its
+ * whole body is a call on the set the Block already holds.
+ *
+ * **The card is the caller's composition, and the arrangement is the Block's.**
+ * A picture, a name and a price are three different value shapes, and the read
+ * vocabulary this package publishes (`ColumnSpec` and `ColumnKind`) describes a
+ * value a reader reads in a table rather than the anatomy of a card. So the card
+ * body is one node per record and the picture, the name and the price are the
+ * caller's own composition, exactly as a per card action is. The Block owns the
+ * grid, the selection set, the count, the batch bar and the page boundary, which
+ * is the whole of what makes this an index rather than a list of pictures.
+ */
+export declare function CardIndex01(props: CardIndex01Props): import("react").JSX.Element;
+export default CardIndex01;
+//# sourceMappingURL=card-index.d.ts.map

package/dist/blocks/card-index-01/card-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-index.d.ts","sourceRoot":"","sources":["../../../src/blocks/card-index-01/card-index.tsx"],"names":[],"mappings":"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"}