@nanisoft/prism-ui 0.16.1 → 1.1.0

package/dist/blocks/activity-feed-01/activity-feed-01.js

@@ -5,140 +5,151 @@ import { Section, SectionHeading, childLevel, } from '../../components/ui/sectio
 import { Status } from '../../components/ui/status.js';
 import { dayKey } from '../../lib/utils.js';
 /**
- * The refusals, as checks, so a row that would render a link nobody can name, or a
- * moment with no machine value, is a diagnostic in a console rather than a rendered
- * control.
+ * The refusals, as checks, so a row that would render a link nobody can name, a
+ * tone with no words beside it, or a moment with no machine value, is a
+ * diagnostic in a console rather than a rendered control.
  *
- * The pair rule is the one `Changelog01` and `ContentGrid01` make, and the moment
- * rule is `RelativeTime`'s: a value the platform cannot read has nothing to put in a
- * `dateTime`, and a `time` element with no value in it claims to be a moment and is
- * not one. Both diagnostics name the field so a caller knows which of their own
- * values to fix.
+ * **Two of these four pairs are already held by the type and the checks exist for
+ * the caller the type never saw.** `EventSpec` names both pairs as unions, but
+ * `tone` and `href` are each optional and their labels are optional beside them,
+ * so a typed caller can reach neither diagnostic and a JavaScript caller can. The
+ * moment rule is `RelativeTime`'s: a value the platform cannot read has nothing to
+ * put in a `dateTime`, and a `time` element with no value in it claims to be a
+ * moment and is not one. Every diagnostic names the field so a caller knows which
+ * of their own values to fix.
  */
 function assertEvent(event) {
+    if ((event.tone === undefined) !== (event.toneLabel === undefined)) {
+        throw new Error(`ActivityFeed01: the event "${event.key}" declares one of tone and toneLabel without the other, so the row ` +
+            'would carry a colour with no words beside it, or words with no colour. A tone is a colour and the words ' +
+            'are the information, so on a record a reader may be checking a claim against, a colour alone is worse ' +
+            'than anywhere else. Pass the words the tone means, or omit the tone.');
+    }
     if ((event.href === undefined) !== (event.hrefLabel === undefined)) {
-        throw new Error(`ActivityFeed01: the event "${event.actor} ${event.action}" declares one of href and hrefLabel without the ` +
-            'other, so the row would carry a link with no words on it, or a name with no link beside it. Pass the words ' +
-            'that say what following it does, or omit the href.');
+        throw new Error(`ActivityFeed01: the event "${event.key}" declares one of href and hrefLabel without the other, so the row ` +
+            'would carry a link with no words on it, or a name with no link beside it. Pass the words that say what ' +
+            'following it does, or omit the href.');
     }
     if (!Number.isFinite(new Date(event.at).getTime())) {
-        throw new Error(`ActivityFeed01: the event "${event.actor} ${event.action}" passes an at the platform cannot read, so there is ` +
-            'no value to put in the time element and the row would claim to be a moment it cannot name. Pass epoch ' +
-            'milliseconds, or a string the platform parses.');
+        throw new Error(`ActivityFeed01: the event "${event.key}" passes an at the platform cannot read, so there is no value to ` +
+            'put in the time element and the row would claim to be a moment it cannot name. Pass epoch milliseconds, ' +
+            'or a string the platform parses.');
     }
 }
 /**
  * The class list every row shares, so the selectable and the plain row are the same
  * row with a different element and cannot drift apart.
- *
- * One constant rather than two, and the alternative was a function returning a
- * `ReactNode` per element shape. There are two shapes, so a constant is the cheaper
- * way to be sure they are identical, and a third shape would be the moment to reach
- * for the function.
  */
 const ROW = 'flex w-full flex-col gap-1 border-b py-4 first:border-t last:border-b-0';
 /**
- * One record: the four fields, the detail line, and the destination.
+ * One record: the shared event's fields, drawn as one run of words, with the
+ * moment under it and the destination beside it.
  *
  * **The element is a decision about what a reader can do with the row, and the body
  * is built once and placed in one of two so the two cannot disagree.** A row with an
  * `onSelect` and no destination is a `button`; a row with neither is a `li`. The
  * destination is never the whole row, and that is the second decision here: a link
- * whose only words are the record's own three fields tells a reader nothing about
- * what following it does, so the destination is a control with the caller's words and
- * it sits under the record. Putting it inside the row's own control was the
- * alternative and it is invalid markup, since an anchor inside a button is neither
- * focusable in the way a reader expects nor announced as two things.
+ * whose only words are the record's own fields tells a reader nothing about what
+ * following it does, so the destination is a control with the caller's words and it
+ * sits under the record. Putting it inside the row's own control was the alternative
+ * and it is invalid markup, since an anchor inside a button is neither focusable in
+ * the way a reader expects nor announced as two things.
  *
  * **The body is phrasing content only, so a button can hold it.** A `button` may
  * contain phrasing content and nothing else, so the record, the moment and the
  * detail line are spans and the column arrangement is a flex `span` rather than the
- * list item's own layout. That is the one place this Block is shaped by what an
- * element is allowed to contain rather than by what it looks like, and it is why the
- * two shapes are the same height.
+ * list item's own layout.
+ *
+ * **The tone is drawn with its words and never without them.** The `tone` is a
+ * `Status` and the `toneLabel` is the text beside it, and the type pairs them; a
+ * caller who sets one without the other reaches `assertEvent` rather than a row
+ * with a coloured dot no screen reader can read.
  */
 function EventRow({ event, onSelect, }) {
-    const record = (_jsxs(_Fragment, { children: [_jsxs("span", { "data-slot": "activity-feed-01-record", className: "flex flex-wrap items-baseline gap-x-2 text-sm", children: [event.tone === undefined ? null : (_jsx(Status, { "data-slot": "activity-feed-01-tone", tone: event.tone, label: event.tone, size: "sm" })), _jsx("span", { className: "font-medium", children: event.actor }), _jsx("span", { className: "text-muted-foreground", children: event.action }), event.target === undefined ? null : (_jsx("span", { className: "font-medium", children: event.target }))] }), _jsx("span", { "data-slot": "activity-feed-01-at", className: "text-muted-foreground font-mono text-xs", children: _jsx("time", { dateTime: new Date(event.at).toISOString(), children: event.at }) }), event.detail === undefined ? null : (_jsx("span", { "data-slot": "activity-feed-01-detail", className: "text-muted-foreground text-sm", children: event.detail }))] }));
-    return (_jsxs("li", { "data-slot": "activity-feed-01-event", "data-event": event.id, className: ROW, children: [onSelect === undefined ? (record) : (_jsx("button", { type: "button", "data-slot": "activity-feed-01-select", onClick: () => onSelect(event.id), className: "w-full rounded-sm text-left focus-visible:ring-ring focus-visible:ring-[3px] focus-visible:outline-none", children: _jsx("span", { className: "flex flex-col gap-1", children: record }) })), event.href === undefined ? null : (_jsx(CtaLink, { "data-slot": "activity-feed-01-link", href: event.href, variant: "ghost", size: "sm", className: "self-start", children: event.hrefLabel }))] }));
+    const record = (_jsxs(_Fragment, { children: [_jsxs("span", { "data-slot": "activity-feed-01-record", className: "flex flex-wrap items-baseline gap-x-2 text-sm", children: [event.tone === undefined ? null : (_jsx(Status, { "data-slot": "activity-feed-01-tone", tone: event.tone, label: event.toneLabel, size: "sm" })), _jsx("span", { className: "font-medium", children: event.actor }), _jsx("span", { className: "text-muted-foreground", children: event.action }), event.target === undefined ? null : (_jsx("span", { className: "font-medium", children: event.target }))] }), _jsx("span", { "data-slot": "activity-feed-01-at", className: "text-muted-foreground font-mono text-xs", children: _jsx("time", { dateTime: new Date(event.at).toISOString(), children: event.at }) }), event.detail === undefined ? null : (_jsx("span", { "data-slot": "activity-feed-01-detail", className: "text-muted-foreground text-sm", children: event.detail }))] }));
+    return (_jsxs("li", { "data-slot": "activity-feed-01-event", "data-event": event.key, className: ROW, children: [onSelect === undefined ? (record) : (_jsx("button", { type: "button", "data-slot": "activity-feed-01-select", onClick: () => onSelect(event.key), className: "w-full rounded-sm text-left focus-visible:ring-ring focus-visible:ring-[3px] focus-visible:outline-none", children: _jsx("span", { className: "flex flex-col gap-1", children: record }) })), event.href === undefined ? null : (_jsx(CtaLink, { "data-slot": "activity-feed-01-link", href: event.href, variant: "ghost", size: "sm", className: "self-start", children: event.hrefLabel }))] }));
 }
 /**
- * A chronological list of what happened: an actor, an action, a target, a moment,
- * and an optional line under the record.
+ * A chronological list of what happened: the shared event specification, one record
+ * per entry, with an optional line under each.
  *
- * **The words are the caller's and the shape is Prism's, and that is the whole of the
- * design.** A feed that composed the sentence would ship English into every
- * consumer's product: "Ada published a release four hours ago" is a word order, an
- * article, an inflected verb and a relative phrase, and a Block that assembled it
- * would have assembled the English one and given the consumer no way to translate
- * it, inflect it or reorder it, because the string would be inside a package rather
- * than inside their own code. So this Block takes the three parts as three props and
- * draws them as one run of words, which is the most a design system can do without
- * writing a sentence.
+ * **The trail's entry declaration is `EventSpec`, and this Block mints no second
+ * event shape beside it.** `@nanisoft/prism-ui/spec` is the one declaration of a
+ * dated attributed occurrence in this package, so a shipment scan, a sign in and a
+ * permission change are one type and the vocabulary a consumer learns on this Block
+ * is the vocabulary everywhere an occurrence is drawn. An event carries a stable
+ * `key` that is never the words of a label, a moment printed exactly as the caller
+ * passed it with the machine value on the element, a required `actor` and `action`,
+ * an optional `target`, an optional `detail` node for the diff, the payload or the
+ * composed reading that four fields cannot hold, a `tone` whose label is required
+ * wherever the tone is set, and a destination whose words are required wherever it
+ * is set.
  *
- * **The four fields are four because a record of what happened has four parts and no
- * others.** Who, what they did, to what, and when. Each is required except the target,
- * and the target's absence is a real state rather than a gap: a sign-in, a logout, a
- * nightly job that names no document. The fifth field every similar surface reaches
- * for, a source or a category or a severity, is `tone` and `detail`, both optional
- * and one of them a node. A closed shape of four with two slots is the answer to a
- * feed that has grown a sixth field because the Block could not say no.
+ * **It names no vocabulary of what happened, and there is no `kind` member.** An
+ * event's kind would name what somebody's product calls a thing that happened, and
+ * no enumeration of those is this package's to publish: a member on a Prism type
+ * would be promising that every consumer's world is this one. A caller needing one
+ * puts the word in `action` or composes a `Status` into `detail`. It carries no
+ * `progress`, no `severity`, no `duration` and no `role`, each refused for a reason
+ * rather than left out, and the specification module's own JSDoc is the whole of
+ * that argument.
+ *
+ * **The words are the caller's and the shape is Prism's.** A feed that composed the
+ * sentence would ship English into every consumer's product: "Ada published a
+ * release four hours ago" is a word order, an article, an inflected verb and a
+ * relative phrase, and a Block that assembled it would have assembled the English
+ * one and given the consumer no way to translate it, inflect it or reorder it. So
+ * this Block takes the parts as the caller's own nodes and draws them as one run of
+ * words, which is the most a design system can do without writing a sentence.
  *
  * **`at` is printed exactly as passed, and the Block formats no moment.** A Block
  * that formatted one would have to pick a locale, a calendar and a granularity, and
- * `relative-time` already holds that decision and holds it well: it formats the
- * absolute reading with the platform and hands the sentence back rather than writing
- * it, which is the only arrangement a shared package can offer a product shipping in
- * more than one language. So this Block prints the caller's value, puts the ISO form
- * on the `time` element's `dateTime` so a crawler and a screen reader get a timestamp
- * whatever the visible reading says, and says in the prop's own note that a caller
- * who wants a relative phrase composes the node beside the record in `detail`. The
- * cost is named rather than hidden: a caller who passes epoch milliseconds gets epoch
- * milliseconds, which is honest and almost never what was wanted.
+ * `relative-time` already holds that decision: it formats the absolute reading with
+ * the platform and hands the sentence back. So this Block prints the caller's value,
+ * puts the ISO form on the `time` element's `dateTime` so a crawler and a screen
+ * reader get a timestamp whatever the visible reading says, and a caller who wants a
+ * relative phrase composes the node beside the record in `detail`.
+ *
+ * **A vertical arrangement's only spatial claim is order, and this Block draws no
+ * length.** There is no scale, no range, no bar and no axis: a bar's length is a
+ * claim about a difference between two caller moments, and time as an axis belongs
+ * to a screen that composes `Gantt01` or `Calendar01` instead. Append only is a
+ * rendering fact and nothing more: what is rendered is the entries it was handed, in
+ * the order it was handed, with no control that edits one, removes one or reorders
+ * one, and that absence is what append only means. What the Block cannot render is
+ * that the record is immutable, tamper evident, signed, sealed or retained, because
+ * a Block has no authority over the store behind it: so there is no `immutable`
+ * prop, no seal glyph and no verification mark, and no retention window, archive,
+ * purge, legal hold, export, freshness or as-of clock. A consumer whose domain
+ * requires one enforces it in its own store and shows what the store says.
  *
- * **A row is a control only when there is something for it to do.** An event with no
- * handler renders as a `li`, which is a record a reader reads and not a thing they
- * act on. The destination is a separate control carrying the caller's own words, so a
- * row can be selectable and linked at once, which is the arrangement a feed actually
- * wants: a reader activates the row to open the thing, and the caller marks it read on
- * the way past. The alternative was to make every row a link, and a feed of forty
- * links is a page where the tab order runs down the whole feed before it reaches
- * anything after it.
+ * **A row is a control only when there is something for it to do.** An event with
+ * no handler renders as a `li`, which is a record a reader reads and not a thing
+ * they act on. The destination is a separate control carrying the caller's own
+ * words, so a row can be selectable and linked at once, which is the arrangement a
+ * feed actually wants: a reader activates the row to open the thing, and the caller
+ * marks it read on the way past.
  *
  * **A day group is a list item holding a heading and a nested list, and not a merged
  * row.** The structure is an `ol` of `li` and each `li` is a heading plus its own
  * `ol`, because a reader moving by list item should hear how many days there are and
- * then how many records are in the day they are reading. The alternative was a table
- * with a row spanning every column, which is a table and not a feed, and which would
- * have given four unrelated fields column semantics they do not have. The day heading
- * is at `childLevel(headingLevel)`, so a feed embedded one level deeper carries its
- * outline with it, and the day groups themselves are not headings at the same level,
- * which is what makes a list of days a list rather than a flat run of headings.
- *
- * **The order is the caller's and the Block never sorts.** A feed is the surface
- * where the exceptions live: a pinned event, a run that arrived late, a record the
- * caller wants beside its own retry. A Block that sorted by moment would move the
- * pin, and the caller would have to add a flag and this Block would have to know what
- * the flag meant. The groups follow the order the days first appear, so a pinned
- * event from yesterday puts yesterday first, which is the only arrangement that
- * survives a pin.
+ * then how many records are in the day they are reading. The day heading is at
+ * `childLevel(headingLevel)`, so a feed embedded one level deeper carries its outline
+ * with it, and the groups follow the order the days first appear, so a pinned event
+ * from yesterday keeps yesterday where the caller put it.
  *
- * **The tone is a mark with a machine word beside it, and the cost is that word.** A
- * feed is a scanning surface, so the mark has to be there, and a mark that is colour
- * alone is invisible to a reader who cannot separate the tones and unreadable to a
- * screen reader whatever the tones are. So the tone is drawn by `Status` with the
- * machine value as its label, which is what `Changelog01` does with a change's kind
- * and the reason is the same: a tone is a judgement about urgency that only the
- * caller can make, and a Block that wrote the sentence for it would be picking an
- * alarm for four products at once. A caller whose product words these states
- * differently composes its own mark into `detail` and leaves `tone` unset. That is
- * the cost of the split, stated rather than hidden.
+ * **The order is the caller's and the Block never sorts, groups or aggregates.** A
+ * feed is the surface where the exceptions live: a pinned event, a run that arrived
+ * late, a record the caller wants beside its own retry. The day grouping is content
+ * rather than structure, a caller-supplied key with a caller-supplied label, and the
+ * Block owns no count, no rate and no elapsed figure. It owns no navigation and no
+ * address, so the only route out of an entry is the caller's `href`, and it holds no
+ * selection state, because a trail is read and the index holds the set a batch action
+ * acts on.
  *
  * It is a client Component, and the reason is the handler rather than the state, as
  * in `data-table-01`: `onSelect` is a function, a function is a piece of state, and
- * state is a client module. The cost is stated rather than implied: a feed with no
- * `onSelect` is a static list that ships this file's client runtime for nothing, and
- * the fix for a consumer who needs that surface to be static is a `ReactNode` slot of
- * their own rather than a Block that attaches a handler to every row.
+ * state is a client module.
  */
 export function ActivityFeed01({ eyebrow, title, description, events, onSelect, limit, empty, groupBy = 'none', dayLabel, headingLevel = 'h2', className, }) {
     // A day's heading is one step below the section that introduces the feed, so a
@@ -153,8 +164,7 @@ export function ActivityFeed01({ eyebrow, title, description, events, onSelect,
       The test is on `dayLabel` and not on `groupBy` alone, because destructuring the
       props loses the discriminant the union carries: a caller who wrote
       `groupBy="day"` without the label has a type error rather than a runtime one, and
-      this is the guard for a JavaScript caller who did not get that far. The grouped
-      branch is built once and the two arms below are the two renderings of it.
+      this is the guard for a JavaScript caller who did not get that far.
     */
     const grouped = groupBy === 'day' && dayLabel !== undefined;
     const heading = title === undefined ? null : (_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-10" }));
@@ -178,8 +188,8 @@ export function ActivityFeed01({ eyebrow, title, description, events, onSelect,
             else
                 found.push(event);
         }
-        return (_jsxs(Section, { "data-slot": "activity-feed-01", className: className, children: [heading, _jsx("ol", { "data-slot": "activity-feed-01-days", className: "flex flex-col", children: [...days].map(([key, inDay]) => (_jsxs("li", { "data-slot": "activity-feed-01-day", "data-day": key, className: "flex flex-col gap-3 py-2 first:pt-0", children: [_jsx(GroupHeading, { "data-slot": "activity-feed-01-day-label", className: "text-muted-foreground text-sm font-medium", children: dayLabel(key) }), _jsx("ol", { "data-slot": "activity-feed-01-events", className: "flex flex-col", children: inDay.map((event) => (_jsx(EventRow, { event: event, onSelect: onSelect }, event.id))) })] }, key))) })] }));
+        return (_jsxs(Section, { "data-slot": "activity-feed-01", className: className, children: [heading, _jsx("ol", { "data-slot": "activity-feed-01-days", className: "flex flex-col", children: [...days].map(([key, inDay]) => (_jsxs("li", { "data-slot": "activity-feed-01-day", "data-day": key, className: "flex flex-col gap-3 py-2 first:pt-0", children: [_jsx(GroupHeading, { "data-slot": "activity-feed-01-day-label", className: "text-muted-foreground text-sm font-medium", children: dayLabel(key) }), _jsx("ol", { "data-slot": "activity-feed-01-events", className: "flex flex-col", children: inDay.map((event) => (_jsx(EventRow, { event: event, onSelect: onSelect }, event.key))) })] }, key))) })] }));
     }
-    return (_jsxs(Section, { "data-slot": "activity-feed-01", className: className, children: [heading, _jsx("ol", { "data-slot": "activity-feed-01-events", className: "flex flex-col", children: shown.map((event) => (_jsx(EventRow, { event: event, onSelect: onSelect }, event.id))) })] }));
+    return (_jsxs(Section, { "data-slot": "activity-feed-01", className: className, children: [heading, _jsx("ol", { "data-slot": "activity-feed-01-events", className: "flex flex-col", children: shown.map((event) => (_jsx(EventRow, { event: event, onSelect: onSelect }, event.key))) })] }));
 }
 export default ActivityFeed01;

package/dist/blocks/activity-feed-01/index.d.ts

@@ -1,3 +1,3 @@
 export { ActivityFeed01, default } from './activity-feed-01.js';
-export type { ActivityFeed01Event, ActivityFeed01Props } from './activity-feed-01.js';
+export type { ActivityFeed01Props } from './activity-feed-01.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/blocks/activity-feed-01/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/activity-feed-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AAK5D,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/activity-feed-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AAK5D,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA"}

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

@@ -1,37 +1,29 @@
 import type { FormEvent, ReactNode } from 'react';
 import type { HeadingLevel } from '../../components/ui/section.js';
-export type AuthFormField = {
-    id: string;
-    label: string;
-    type?: 'text' | 'email' | 'password';
-    placeholder?: string;
-    autoComplete?: string;
-    value?: string;
-    defaultValue?: string;
-    onChange?: (value: string) => void;
-    required?: boolean;
-    disabled?: boolean;
-    description?: string;
-    /**
-     * This field is the one the form-level `error` is about.
-     *
-     * A form-level message with no field named is a statement about the submission:
-     * "those credentials do not match" is not a claim about the password field any
-     * more than it is a claim about the email field, and marking both of them
-     * `aria-invalid` tells a reader that two correctly filled fields are wrong. So the
-     * Block marks the field the caller names and no other, and a caller with nothing
-     * to name leaves every field unmarked, which is the honest state: the message
-     * still sits above the fields in an `Alert`, so it is still announced and still
-     * identified, and WCAG 3.3.1 is answered by the message rather than by a mark on a
-     * control that is not the problem.
-     *
-     * Omit it rather than setting it on every field. That was the arrangement this
-     * replaces and it is the arrangement a reader pays for, because the first thing a
-     * screen reader says about each field is "invalid" and a reader who is told two
-     * correct answers are wrong stops trusting the rest of the form.
-     */
-    errorId?: string;
+import type { FieldSpecGroup } from '../../lib/spec.js';
+/**
+ * One thing wrong with the form, in the caller's own words.
+ *
+ * `field` is the `key` of the field the message belongs to, and the key rather
+ * than the label because it is what the caller's values and the form's own
+ * `FormData` are keyed by. The shape is the one the write form, the dialog and
+ * the wizard already publish, so this Block mints no fifth spelling of an issue.
+ */
+export type AuthForm01Issue = {
+    /** The `key` of the field this message belongs to. */
+    field: string;
+    /** The message, in the product's own words. */
+    message: string;
 };
+/**
+ * The remember-me row.
+ *
+ * It is not a field of the shared specification, and the reason is that it is a
+ * control this Block owns rather than one the caller declares: a sign-in screen
+ * has a remember row and the row is one control with a sentence and a starting
+ * state, so a caller who wants a second one draws it in the footer rather than
+ * widening the field vocabulary for a shape one screen has.
+ */
 export type AuthFormRemember = {
     id: string;
     label: string;
@@ -52,17 +44,31 @@ export type AuthForm01Props = {
      */
     headingLevel?: HeadingLevel;
     description?: string;
-    /** The credential fields, in order. */
-    fields: AuthFormField[];
+    /**
+     * The credential fields, grouped and ordered, as the shared field specification.
+     *
+     * A field carries a stable `key`, a required `label`, a required `kind` drawn
+     * from Prism's own input vocabulary, and optional help, hint, placeholder,
+     * autofill hint, disabled flag and starting value. A control this package does
+     * not ship is the `slot` arm, and the Block still draws the label, the help and
+     * the error around the caller's node. Asking for an email is an `Input` and
+     * asking for a password is the `PasswordField` this package ships, so the
+     * vocabulary is the same one a record write form takes.
+     */
+    groups: readonly FieldSpecGroup[];
+    /** The issues to draw, keyed by field. Drawn under the control that owns them. */
+    issues?: readonly AuthForm01Issue[];
     /**
      * An error message shown above the fields.
      *
      * A sentence about the submission rather than about a control, which is why
-     * naming the field it concerns is a separate decision: pass the same id as one
-     * field's `errorId` and that field carries `aria-invalid`, and pass nothing and
-     * none does. See `AuthFormField.errorId`.
+     * naming a field it concerns is a separate decision: an entry in `issues` marks
+     * its own field, and a message here marks none. Telling a reader that two
+     * correctly filled fields are wrong is how they learn to stop trusting the rest
+     * of the form, so a submission sentence never marks more than the issue list
+     * already did.
      */
-    error?: string;
+    submitError?: ReactNode;
     /** A remember-me row under the fields. */
     remember?: AuthFormRemember;
     /** The submit button label. */
@@ -71,31 +77,58 @@ export type AuthForm01Props = {
     pendingLabel?: string;
     /** Disables the submit control while a request is in flight. */
     pending?: boolean;
+    /**
+     * Called when the reader submits, with the form's own element.
+     *
+     * The Block is uncontrolled where a Prism control can be, so the caller reads
+     * the values out of the form element: the field keys are on the controls and a
+     * control the platform will not submit carries a hidden input under its key.
+     */
     onSubmit?: (event: FormEvent<HTMLFormElement>) => void;
     /** A row under the submit button, e.g. a link to another screen. */
     footer?: ReactNode;
 };
 /**
- * A sign-in card.
+ * 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 declare function AuthForm01({ title, description, fields, error, remember, submitLabel, pendingLabel, pending, onSubmit, footer, headingLevel, }: AuthForm01Props): import("react").JSX.Element;
+export declare function AuthForm01({ title, description, groups, issues, submitError, remember, submitLabel, pendingLabel, pending, onSubmit, footer, headingLevel, }: AuthForm01Props): import("react").JSX.Element;
 export default AuthForm01;
 //# sourceMappingURL=auth-form.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"auth-form.d.ts","sourceRoot":"","sources":["../../../src/blocks/auth-form-01/auth-form.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAoBjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAE/D,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CAAA;IACpC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uCAAuC;IACvC,MAAM,EAAE,aAAa,EAAE,CAAA;IACvB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IAC3B,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,eAAe,CAAC,KAAK,IAAI,CAAA;IACtD,oEAAoE;IACpE,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,WAAW,EACX,MAAM,EACN,KAAK,EACL,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,OAAe,EACf,QAAQ,EACR,MAAM,EACN,YAAmB,GACpB,EAAE,eAAe,+BAyFjB;AAED,eAAe,UAAU,CAAA"}
+{"version":3,"file":"auth-form.d.ts","sourceRoot":"","sources":["../../../src/blocks/auth-form-01/auth-form.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAgBjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAU/D,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE/D;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAA;IACb,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,SAAS,cAAc,EAAE,CAAA;IACjC,kFAAkF;IAClF,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;IACnC;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IAC3B,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,eAAe,CAAC,KAAK,IAAI,CAAA;IACtD,oEAAoE;IACpE,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAqCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,WAAW,EACX,MAAM,EACN,MAAM,EACN,WAAW,EACX,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,OAAe,EACf,QAAQ,EACR,MAAM,EACN,YAAmB,GACpB,EAAE,eAAe,+BAkIjB;AAED,eAAe,UAAU,CAAA"}