@nanisoft/prism-ui 0.16.1 → 1.0.0

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

@@ -1,81 +1,6 @@
 import type { ReactNode } from 'react';
 import { type HeadingLevel } from '../../components/ui/section.js';
-/**
- * One choice in a `select` field, and nothing else.
- *
- * A native `<option>` holds text and nothing more, which is the whole reason an
- * account form's select is a `NativeSelect` rather than the Base UI one. The two
- * values are a string and its label, so a caller who needs a description beside an
- * option, a count, or anything nested is reaching for a control the platform cannot
- * render, and `Signup01` does not pretend otherwise: it names `NativeSelect`'s own
- * argument in its JSDoc and stops there.
- */
-export type SignupOption = {
-    /** What the form submits for this choice, which is a key and not a sentence. */
-    value: string;
-    /** The words the reader sees, in the product's own language. */
-    label: string;
-};
-/**
- * What every account field carries, whichever control it draws.
- *
- * `required` is a boolean rather than an optional prop because there is no third
- * state worth having: a field is one the reader must fill or one they may leave, and
- * a `required?: boolean` leaves a caller who passed nothing unable to say which of
- * the two they meant. A field is a data declaration and nothing else, and the two
- * arms below differ only in which control is drawn and in the one property that
- * control needs and the other has no use for.
- */
-type SignupFieldBase = {
-    /** The caller's key for this field, and the key the value arrives under. */
-    id: string;
-    /** The field's visible name, and the accessible name its control announces. */
-    label: string;
-    /** Whether the reader may submit the form without filling it. */
-    required: boolean;
-    /**
-     * A line under the control, announced with it rather than printed under the row.
-     *
-     * A node, because the honest line in this position is often not one sentence: a
-     * caller's hint, a link to the document that says why a field is being asked for,
-     * a piece of the page's own copy. It is wired to the control through
-     * `aria-describedby`, so a screen reader hears what this field is for as the reader
-     * reaches it rather than as a footnote they have to go back for.
-     */
-    description?: ReactNode;
-    /** What the control shows while it is empty. A hint, not a name. */
-    placeholder?: string;
-    /** The platform's own autofill hint for this field. */
-    autoComplete?: string;
-};
-/**
- * One field of the caller's account form, and the control it draws.
- *
- * **A union and not one type with an optional `options`, and that is the shape of
- * the whole argument in this Block.** An account form's fields are the caller's
- * declaration, not this package's opinion about what a person may be asked, and the
- * one place that shows is the select: a select with no options is a control with
- * nothing in it, which is a question no reader can answer, so `options` is required
- * inside the select arm and forbidden beside the other three. A `options?: string[]`
- * on one type would typecheck the defect and only the diagnostic at run time would
- * catch it, which is one gate too late. The union is the same mechanism
- * `ContactField` uses for the same reason: the shape that requires something declares
- * it, and the shape that forbids it says so in the type rather than in prose.
- *
- * The cost of the union is that a caller who wants to build a field list
- * generically, from a schema, has to narrow before it can type the result, and the
- * answer to that is a narrowing function in the caller's own code rather than a
- * looser type here.
- */
-export type SignupField = (SignupFieldBase & {
-    type: 'select';
-    /** The choices, in the order the reader should meet them. */
-    options: readonly SignupOption[];
-}) | (SignupFieldBase & {
-    type: 'text' | 'email' | 'tel';
-    /** A select with no options is a question nobody can answer, so it is not one here. */
-    options?: never;
-});
+import type { FieldSpecGroup } from '../../lib/spec.js';
 /**
  * One reading of the secret the reader is typing, in the caller's own words and on
  * the caller's own scale.
@@ -237,7 +162,7 @@ export type Signup01Props = {
      */
     onSubmit: (value: SignupValue) => void;
     /**
-     * The fields, in the order the reader should meet them.
+     * The fields, grouped and ordered, as the shared field specification.
      *
      * **Required, and this list is the whole design rather than a convenience.** An
      * account form with a fixed set of fields is a form that decides what a person may
@@ -247,13 +172,14 @@ export type Signup01Props = {
      * where every entity is scoped to one, a form that cannot ask for a job title
      * guarantees a sales team three weeks of discovery calls, and a form that cannot
      * ask which estate somebody is observing sends a half a dozen accounts onto a
-     * queue that belongs to one. So `fields` is the caller's declaration, Prism names
-     * the four controls it can draw and supplies no field at all. The cost is stated
-     * rather than hidden: one column in the order the list gives, so a consumer that
-     * wants a two-column form for a subset composes two of these or reaches for a
-     * `Page`.
+     * queue that belongs to one. The fields arrive as `FieldSpecGroup`, the same type
+     * a record write form takes, so the vocabulary a consumer learns on one screen is
+     * the vocabulary here and a control this package does not ship is the `slot` arm.
+     * The cost is stated rather than hidden: one column in the order the list gives,
+     * so a consumer that wants a two-column form for a subset composes two of these
+     * or reaches for a `Page`.
      */
-    fields: readonly SignupField[];
+    groups: readonly FieldSpecGroup[];
     /** The secret, and the caller's own reading of it. See `Signup01Password`. */
     password: Signup01Password;
     /**
@@ -400,6 +326,6 @@ export type Signup01Props = {
  * function to a prop, so a caller rendering this from a server component gets a form
  * that submits and calls nothing and a reading that never appears.
  */
-export declare function Signup01({ eyebrow, title, description, onSubmit, fields, password, terms, submitLabel, submitting, status, signIn, headingLevel, className, }: Signup01Props): import("react").JSX.Element;
+export declare function Signup01({ eyebrow, title, description, onSubmit, groups, password, terms, submitLabel, submitting, status, signIn, headingLevel, className, }: Signup01Props): import("react").JSX.Element;
 export default Signup01;
 //# sourceMappingURL=signup-01.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"signup-01.d.ts","sourceRoot":"","sources":["../../../src/blocks/signup-01/signup-01.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"signup-01.d.ts","sourceRoot":"","sources":["../../../src/blocks/signup-01/signup-01.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAa,SAAS,EAAE,MAAM,OAAO,CAAA;AAWjD,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAQxF,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAG/D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,gGAAgG;IAChG,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAA;IACnB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,eAAe,CAAA;IAC7C;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;CACxB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAA;IAC5C,4DAA4D;IAC5D,OAAO,EAAE,SAAS,CAAA;CACnB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAA;IACb,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,qEAAqE;IACrE,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,kFAAkF;IAClF,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IACtC;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,EAAE,SAAS,cAAc,EAAE,CAAA;IACjC,8EAA8E;IAC9E,QAAQ,EAAE,gBAAgB,CAAA;IAC1B;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,gFAAgF;IAChF,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,gEAAgE;IAChE,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAqFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG;AACH,wBAAgB,QAAQ,CAAC,EACvB,OAAO,EACP,KAAK,EACL,WAAW,EACX,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,KAAK,EACL,WAAW,EACX,UAAkB,EAClB,MAAM,EACN,MAAM,EACN,YAAmB,EACnB,SAAS,GACV,EAAE,aAAa,+BAqOf;AAED,eAAe,QAAQ,CAAA"}

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

@@ -4,13 +4,13 @@ import { useId, useState } from 'react';
 import { Button } from '../../components/ui/button.js';
 import { Card } from '../../components/ui/card.js';
 import { CtaLink } from '../../components/ui/cta-link.js';
-import { Field, FieldDescription, FieldGroup, FieldLabel } from '../../components/ui/field.js';
-import { Input } from '../../components/ui/input.js';
+import { Field, FieldDescription, FieldGroup } from '../../components/ui/field.js';
+import { Label } from '../../components/ui/label.js';
 import { LiveRegion } from '../../components/ui/live-region.js';
-import { NativeSelect } from '../../components/ui/native-select.js';
 import { PasswordField } from '../../components/ui/password-field.js';
 import { Progress } from '../../components/ui/progress.js';
 import { Section, SectionHeading } from '../../components/ui/section.js';
+import { CHOICE_KINDS, fieldText, renderControl, SELF_LABELLED, } from '../../lib/field-render.js';
 import { cn } from '../../lib/utils.js';
 /**
  * The empty form, which is an empty record and an empty secret.
@@ -47,18 +47,21 @@ function blank(value) {
  * reader is watching while they choose it.
  */
 function assertSignup(input) {
-    const { fields, password, signIn } = input;
-    for (const field of fields) {
-        if (blank(field.label)) {
-            throw new Error(`Signup01: the field "${field.id}" 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 (field.type === 'select' && (field.options === undefined || field.options.length === 0)) {
-            throw new Error(`Signup01: the field "${field.id}" is a select 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.');
+    const { groups, password, signIn } = input;
+    for (const group of groups) {
+        for (const field of group.fields) {
+            if (blank(typeof field.label === 'string' ? field.label : undefined)) {
+                throw new Error(`Signup01: 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(`Signup01: 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.');
+            }
         }
     }
     if (blank(password.label) || blank(password.revealLabel) || blank(password.hideLabel)) {
@@ -172,8 +175,8 @@ function assertSignup(input) {
  * function to a prop, so a caller rendering this from a server component gets a form
  * that submits and calls nothing and a reading that never appears.
  */
-export function Signup01({ eyebrow, title, description, onSubmit, fields, password, terms, submitLabel, submitting = false, status, signIn, headingLevel = 'h2', className, }) {
-    assertSignup({ fields, password, signIn });
+export function Signup01({ eyebrow, title, description, onSubmit, groups, password, terms, submitLabel, submitting = false, status, signIn, headingLevel = 'h2', className, }) {
+    assertSignup({ groups, password, signIn });
     const generated = useId();
     const working = submitting || status?.state === 'working';
     const done = status?.state === 'done';
@@ -193,17 +196,32 @@ export function Signup01({ eyebrow, title, description, onSubmit, fields, passwo
         if (done)
             setTyped(EMPTY_SIGNUP);
     }
-    const setField = (id) => (value) => setTyped((was) => ({ ...was, fields: { ...was.fields, [id]: value } }));
+    const setField = (id) => (value) => setTyped((was) => ({
+        ...was,
+        fields: { ...was.fields, [id]: value === undefined || value === null ? '' : String(value) },
+    }));
     const setSecret = (value) => setTyped((was) => ({ ...was, password: value }));
     const handleSubmit = (event) => {
         event.preventDefault();
         onSubmit(typed);
     };
     const reading = password.strength === undefined ? null : password.strength(typed.password);
-    return (_jsx(Section, { "data-slot": "signup-01", className: cn(className), children: _jsxs("div", { "data-slot": "signup-01-body", className: "flex flex-col gap-10", children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description }), _jsx(Card, { "data-slot": "signup-01-card", className: "max-w-measure-narrow gap-0 px-6", children: _jsxs("form", { "data-slot": "signup-01-form", onSubmit: handleSubmit, className: "flex w-full flex-col gap-5", children: [_jsxs(FieldGroup, { "data-slot": "signup-01-fields", children: [fields.map((field) => {
-                                        const controlId = `${generated}-${field.id}`;
-                                        const descriptionId = `${controlId}-description`;
-                                        return (_jsxs(Field, { "data-slot": "signup-01-field", "data-field": field.type, children: [_jsx(FieldLabel, { htmlFor: controlId, children: field.label }), field.type === 'select' ? (_jsx(NativeSelect, { id: controlId, name: field.id, value: typed.fields[field.id] ?? '', onChange: (event) => setField(field.id)(event.target.value), required: field.required, "aria-describedby": field.description === undefined ? undefined : descriptionId, children: field.options.map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value))) })) : (_jsx(Input, { id: controlId, name: field.id, type: field.type, placeholder: field.placeholder, autoComplete: field.autoComplete, value: typed.fields[field.id] ?? '', onChange: (event) => setField(field.id)(event.target.value), required: field.required, "aria-describedby": field.description === undefined ? undefined : descriptionId })), field.description === undefined ? null : (_jsx(FieldDescription, { id: descriptionId, children: field.description }))] }, field.id));
-                                    }), _jsx(PasswordField, { value: typed.password, onValueChange: setSecret, label: password.label, description: password.description, revealLabel: password.revealLabel, hideLabel: password.hideLabel, autoComplete: "new-password" })] }), reading === null ? null : (_jsxs("div", { "data-slot": "signup-01-strength", className: "flex flex-col gap-1.5", children: [_jsx(Progress, { value: reading.value, max: 100, valueText: reading.label }), _jsx("span", { "data-slot": "signup-01-strength-label", className: "text-muted-foreground text-sm", children: reading.label })] })), terms === undefined ? null : (_jsx("p", { "data-slot": "signup-01-terms", className: "text-muted-foreground text-sm text-pretty", children: terms })), _jsxs("div", { "data-slot": "signup-01-actions", className: "flex flex-col gap-3", children: [_jsx(Button, { "data-slot": "signup-01-submit", type: "submit", disabled: working, className: "w-full", children: submitLabel }), _jsx(LiveRegion, { "data-slot": "signup-01-status", politeness: status?.state === 'error' ? 'assertive' : 'polite', busy: working, className: cn('text-sm', status?.state === 'error' ? 'text-destructive font-medium' : 'text-muted-foreground'), children: status?.message })] })] }) }), signIn === undefined ? null : (_jsx(CtaLink, { "data-slot": "signup-01-sign-in", href: signIn.href, variant: "ghost", size: "sm", className: "self-start", children: signIn.label }))] }) }));
+    return (_jsx(Section, { "data-slot": "signup-01", className: cn(className), children: _jsxs("div", { "data-slot": "signup-01-body", className: "flex flex-col gap-10", children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description }), _jsx(Card, { "data-slot": "signup-01-card", className: "max-w-measure-narrow gap-0 px-6", children: _jsxs("form", { "data-slot": "signup-01-form", onSubmit: handleSubmit, className: "flex w-full flex-col gap-5", children: [_jsxs(FieldGroup, { "data-slot": "signup-01-fields", children: [groups.map((group, groupIndex) => (_jsxs(FieldGroup, { "data-slot": "signup-01-group", className: "flex flex-col gap-5", children: [group.label === undefined ? null : (_jsx("p", { "data-slot": "signup-01-group-label", className: "text-foreground text-sm font-medium", children: group.label })), group.description === undefined ? null : (_jsx("p", { "data-slot": "signup-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 kind = field.kind.toLowerCase();
+                                                const ctx = {
+                                                    id,
+                                                    labelId,
+                                                    describedBy: helpId,
+                                                    invalid: false,
+                                                    text: fieldText(field),
+                                                    values: typed.fields,
+                                                    setValue: (key, value) => setField(key)(value),
+                                                    controlled: true,
+                                                };
+                                                return (_jsxs(Field, { "data-slot": "signup-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), field.help === undefined ? null : (_jsx(FieldDescription, { id: helpId, children: field.help }))] }, field.key));
+                                            })] }, group.id ?? groupIndex))), _jsx(PasswordField, { value: typed.password, onValueChange: setSecret, label: password.label, description: password.description, revealLabel: password.revealLabel, hideLabel: password.hideLabel, autoComplete: "new-password" })] }), reading === null ? null : (_jsxs("div", { "data-slot": "signup-01-strength", className: "flex flex-col gap-1.5", children: [_jsx(Progress, { value: reading.value, max: 100, valueText: reading.label }), _jsx("span", { "data-slot": "signup-01-strength-label", className: "text-muted-foreground text-sm", children: reading.label })] })), terms === undefined ? null : (_jsx("p", { "data-slot": "signup-01-terms", className: "text-muted-foreground text-sm text-pretty", children: terms })), _jsxs("div", { "data-slot": "signup-01-actions", className: "flex flex-col gap-3", children: [_jsx(Button, { "data-slot": "signup-01-submit", type: "submit", disabled: working, className: "w-full", children: submitLabel }), _jsx(LiveRegion, { "data-slot": "signup-01-status", politeness: status?.state === 'error' ? 'assertive' : 'polite', busy: working, className: cn('text-sm', status?.state === 'error' ? 'text-destructive font-medium' : 'text-muted-foreground'), children: status?.message })] })] }) }), signIn === undefined ? null : (_jsx(CtaLink, { "data-slot": "signup-01-sign-in", href: signIn.href, variant: "ghost", size: "sm", className: "self-start", children: signIn.label }))] }) }));
 }
 export default Signup01;

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

@@ -1,10 +1,10 @@
 /**
- * The subpath exports the Block and its props, and the props are exported because
- * a caller that builds a `Stat[]` has to be able to name the type it is building.
+ * The subpath exports the Block and its props, and the props are exported because a
+ * caller that builds a `MetricSpec[]` has to be able to name the type it is building.
  * A Block whose prop types are only reachable through inference is a Block whose
- * callers annotate their arrays as `any`, which is the point at which a rename
- * stops being caught by the compiler.
+ * callers annotate their arrays as `any`, which is the point at which a rename stops
+ * being caught by the compiler.
  */
 export { Stats01, default } from './stats.js';
-export type { Stat, Stats01Props } from './stats.js';
+export type { Stats01Props } from './stats.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/stats-01/index.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAC1C,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/stats-01/index.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAC1C,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA"}

package/dist/blocks/stats-01/index.js

@@ -1,8 +1,8 @@
 /**
- * The subpath exports the Block and its props, and the props are exported because
- * a caller that builds a `Stat[]` has to be able to name the type it is building.
+ * The subpath exports the Block and its props, and the props are exported because a
+ * caller that builds a `MetricSpec[]` has to be able to name the type it is building.
  * A Block whose prop types are only reachable through inference is a Block whose
- * callers annotate their arrays as `any`, which is the point at which a rename
- * stops being caught by the compiler.
+ * callers annotate their arrays as `any`, which is the point at which a rename stops
+ * being caught by the compiler.
  */
 export { Stats01, default } from './stats.js';

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

@@ -1,27 +1,62 @@
 import { type HeadingLevel } from '../../components/ui/section.js';
-export type Stat = {
-    label: string;
-    value: string;
-    /** Percentage change. Positive reads as growth, negative as decline. */
-    delta?: number;
-    /** Period the delta compares against, e.g. "vs last month". */
-    hint?: string;
-};
+import type { MetricSpec } from '../../lib/spec.js';
+/**
+ * The props a Stats01 takes. Every string and every figure is a prop and the Block
+ * ships none.
+ */
 export type Stats01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
     eyebrow?: string;
+    /** The section title. Omit it for a row composed under its own heading. */
     title?: string;
-    stats: Stat[];
+    /**
+     * The figures, in the order a reader should meet them.
+     *
+     * **The shared `MetricSpec` and not a shape of this Block's own.** `key`,
+     * `label` and `value` are required on each figure, `delta` is a number whose sign
+     * is the direction, `deltaFormat` is the caller's own words for that change,
+     * `hint` carries the period or the caveat, and a `series` and an `href` each travel
+     * with the label or the words they cannot be read without. The type is published as
+     * `@nanisoft/prism-ui/spec`, so the words a caller learns on a summary are the
+     * words on this row.
+     */
+    stats: MetricSpec[];
     /** Heading level for the section title. See `HeadingLevel`. */
     headingLevel?: HeadingLevel;
 };
 /**
- * A KPI row. Every number is a prop.
+ * A KPI row whose figures are the shared `MetricSpec` drawn by `Metric` and
+ * `Sparkline`. Every figure is a prop.
  *
- * This block used to carry a hardcoded set reading "128 blocks shipped" and "9.4k
- * weekly installs". Those were invented figures about a library nobody installs
- * yet, and because they lived in the component rather than at the call site, a
- * consumer who installed the block shipped fabricated metrics into their own
+ * **This block used to carry a hardcoded set reading "128 blocks shipped" and
+ * "9.4k weekly installs".** Those were invented figures about a library nobody
+ * installs yet, and because they lived in the component rather than at the call site,
+ * a consumer who installed the block shipped fabricated metrics into their own
  * dashboard. A stat block with invented stats in it is worse than no stat block.
+ *
+ * **It declared its own statistic type and guessed the unit, and that guess is the
+ * reason it is in this migration.** Its `delta` was documented as a percentage change
+ * and the Block appended a percent sign to the number, which is the one guess
+ * `Metric` refuses to make, because a delta of `0.12` is twelve percent, twelve cents
+ * or twelve milliseconds. It also carried no series, so the trend a metric summary
+ * names had nowhere to go. After this migration a delta with no formatter prints the
+ * number the caller passed and a delta with a formatter prints the caller's words,
+ * and the same consumer stops seeing a formatted change on one screen and a bare
+ * number on another.
+ *
+ * **The Block keeps its own name, kind and arrangement.** It is the same job as a row
+ * of figures with less of it declared, and a consumer who wants figures above
+ * supporting detail composes the dashboard Block beside them rather than either
+ * becoming the other. Only the statistic shape moves, because a shape is shared and a
+ * screen is not.
+ *
+ * **It still aggregates nothing and judges nothing.** It does not sum, count,
+ * average, bucket, rank or divide, it owns no threshold, no target, no severity and
+ * no freshness, and it draws no period switcher, no comparison toggle and no export.
+ * The period is the caller's words, carried by the `hint` and the delta formatter,
+ * and no period member exists.
+ *
+ * It is a server Component: no hook, no state and no client code.
  */
 export declare function Stats01({ eyebrow, title, stats, headingLevel }: Stats01Props): import("react").JSX.Element;
 export default Stats01;

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

@@ -1 +1 @@
-{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../../src/blocks/stats-01/stats.tsx"],"names":[],"mappings":"AAGA,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAExF,MAAM,MAAM,IAAI,GAAG;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,IAAI,EAAE,CAAA;IACb,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AA2BD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,YAAmB,EAAE,EAAE,YAAY,+BAiCnF;AAED,eAAe,OAAO,CAAA"}
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../../src/blocks/stats-01/stats.tsx"],"names":[],"mappings":"AAGA,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAExF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAEhD;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;;;;OAUG;IACH,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAiCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,YAAmB,EAAE,EAAE,YAAY,+BAqDnF;AAED,eAAe,OAAO,CAAA"}

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

@@ -1,27 +1,77 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { ArrowDownRight, ArrowUpRight, Minus } from 'lucide-react';
 import { Card, CardContent } from '../../components/ui/card.js';
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Metric } from '../../components/ui/metric.js';
 import { Section, SectionHeading } from '../../components/ui/section.js';
-function Delta({ value }) {
-    if (value === 0) {
-        return (_jsxs("span", { className: "text-muted-foreground flex items-center gap-1 text-xs", children: [_jsx(Minus, { className: "size-3" }), "0%"] }));
+import { Sparkline } from '../../components/ui/sparkline.js';
+/**
+ * The refusals, as checks, so a tile that would render a link nobody can name is a
+ * diagnostic in a console rather than a rendered link.
+ *
+ * **The type already holds both pairs, and these checks exist for the caller the
+ * type never saw.** `MetricSpec` requires a destination's words wherever it has a
+ * destination and a series name wherever it has a series, so a typed caller cannot
+ * reach either diagnostic. A JavaScript caller can, and the cost of reaching one is
+ * a figure that draws a link with no words or a shape no reader can announce, so the
+ * same rule is stated once more where a runtime value can be read: the pair rule is
+ * the one `Dashboard01` makes.
+ */
+function assertMetrics(metrics) {
+    for (const metric of metrics) {
+        if ((metric.href === undefined) !== (metric.hrefLabel === undefined)) {
+            throw new Error(`Stats01: the statistic "${metric.key}" declares one of href and hrefLabel without the other, so the ` +
+                'tile 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 ((metric.series === undefined) !== (metric.seriesLabel === undefined)) {
+            throw new Error(`Stats01: the statistic "${metric.key}" declares one of series and seriesLabel without the other, so the ` +
+                'figure would be a picture with no name, which a screen reader cannot announce and two shapes in one row ' +
+                'cannot be told apart. Pass the series name in the words the product uses, or omit the series.');
+        }
     }
-    const up = value > 0;
-    const Icon = up ? ArrowUpRight : ArrowDownRight;
-    return (_jsxs("span", { className: up
-            ? 'text-success flex items-center gap-1 text-xs'
-            : 'text-destructive flex items-center gap-1 text-xs', children: [_jsx(Icon, { className: "size-3" }), Math.abs(value), "%"] }));
 }
 /**
- * A KPI row. Every number is a prop.
+ * A KPI row whose figures are the shared `MetricSpec` drawn by `Metric` and
+ * `Sparkline`. Every figure is a prop.
  *
- * This block used to carry a hardcoded set reading "128 blocks shipped" and "9.4k
- * weekly installs". Those were invented figures about a library nobody installs
- * yet, and because they lived in the component rather than at the call site, a
- * consumer who installed the block shipped fabricated metrics into their own
+ * **This block used to carry a hardcoded set reading "128 blocks shipped" and
+ * "9.4k weekly installs".** Those were invented figures about a library nobody
+ * installs yet, and because they lived in the component rather than at the call site,
+ * a consumer who installed the block shipped fabricated metrics into their own
  * dashboard. A stat block with invented stats in it is worse than no stat block.
+ *
+ * **It declared its own statistic type and guessed the unit, and that guess is the
+ * reason it is in this migration.** Its `delta` was documented as a percentage change
+ * and the Block appended a percent sign to the number, which is the one guess
+ * `Metric` refuses to make, because a delta of `0.12` is twelve percent, twelve cents
+ * or twelve milliseconds. It also carried no series, so the trend a metric summary
+ * names had nowhere to go. After this migration a delta with no formatter prints the
+ * number the caller passed and a delta with a formatter prints the caller's words,
+ * and the same consumer stops seeing a formatted change on one screen and a bare
+ * number on another.
+ *
+ * **The Block keeps its own name, kind and arrangement.** It is the same job as a row
+ * of figures with less of it declared, and a consumer who wants figures above
+ * supporting detail composes the dashboard Block beside them rather than either
+ * becoming the other. Only the statistic shape moves, because a shape is shared and a
+ * screen is not.
+ *
+ * **It still aggregates nothing and judges nothing.** It does not sum, count,
+ * average, bucket, rank or divide, it owns no threshold, no target, no severity and
+ * no freshness, and it draws no period switcher, no comparison toggle and no export.
+ * The period is the caller's words, carried by the `hint` and the delta formatter,
+ * and no period member exists.
+ *
+ * It is a server Component: no hook, no state and no client code.
  */
 export function Stats01({ eyebrow, title, stats, headingLevel = 'h2' }) {
-    return (_jsxs(Section, { children: [title ? (_jsx(SectionHeading, { as: headingLevel, eyebrow: eyebrow, title: title, align: "left", className: "mb-10" })) : null, _jsx("div", { className: "grid gap-4 sm:grid-cols-2 lg:grid-cols-4", children: stats.map((stat) => (_jsx(Card, { className: "gap-2 py-5", children: _jsxs(CardContent, { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-muted-foreground text-sm", children: stat.label }), _jsx("span", { className: "text-2xl font-semibold tracking-tight", children: stat.value }), stat.delta === undefined && !stat.hint ? null : (_jsxs("div", { className: "flex items-center gap-2", children: [stat.delta === undefined ? null : _jsx(Delta, { value: stat.delta }), stat.hint ? (_jsx("span", { className: "text-muted-foreground text-xs", children: stat.hint })) : null] }))] }) }, stat.label))) })] }));
+    assertMetrics(stats);
+    return (_jsxs(Section, { children: [title ? (_jsx(SectionHeading, { as: headingLevel, eyebrow: eyebrow, title: title, align: "left", className: "mb-10" })) : null, _jsx("div", { className: "grid gap-4 sm:grid-cols-2 lg:grid-cols-4", children: stats.map((metric) => {
+                    // The delta's words are the caller's own node, and `Metric` takes a
+                    // formatter, so the node is placed through one. A delta with no words is
+                    // left to `Metric`, which prints the number the caller passed.
+                    const deltaWords = metric.deltaFormat;
+                    return (_jsx(Card, { "data-slot": "stats-01-stat", "data-metric": metric.key, className: "gap-2 py-5", children: _jsxs(CardContent, { className: "flex flex-col gap-3", children: [_jsx(Metric, { value: metric.value, label: metric.label, delta: metric.delta, deltaFormat: deltaWords === undefined ? undefined : () => deltaWords, hint: metric.hint }), metric.series === undefined ? null : (_jsx("div", { "data-slot": "stats-01-sparkline", className: "flex", children: _jsx(Sparkline, { values: metric.series, label: metric.seriesLabel, className: "ms-auto" }) })), metric.href === undefined ? null : (_jsx(CtaLink, { href: metric.href, variant: "ghost", size: "sm", children: metric.hrefLabel }))] }) }, metric.key));
+                }) })] }));
 }
 export default Stats01;

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

@@ -1,3 +1,3 @@
 export { Trend01, default } from './trend.js';
-export type { Trend01Props, Trend01Item } from './trend.js';
+export type { Trend01Props } from './trend.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/trend-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAI1C,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/trend-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAC1C,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA"}

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

@@ -1,64 +1,6 @@
 import type { ReactNode } from 'react';
 import { type HeadingLevel } from '../../components/ui/section.js';
-/**
- * One row of a trend list: a name, what it is at now, how it moved, and a shape
- * beside it.
- *
- * Every field except `id` and `label` is optional because a trend list is
- * heterogeneous by nature. Some of the things a list tracks have a series behind
- * them and some have only a reading, some moved and some did not, and a shape
- * that made every field required would be a list where two thirds of every row is
- * an empty cell drawn as a placeholder.
- */
-export type Trend01Item = {
-    /** A stable key for the row. */
-    id: string;
-    /**
-     * The name of the thing being tracked, as a reader would name it in
-     * conversation. It is the label the metric carries, and it is the last thing
-     * read on the row because the figure and the direction come first.
-     */
-    label: string;
-    /**
-     * The current reading, already formatted by the caller.
-     *
-     * A `ReactNode` and not a `number`, for the reason `MetricProps.value` gives:
-     * a caller's figure is often a value it formatted itself, with its own grouped
-     * thousands, its own currency and its own unit, and a `number` here would push
-     * that formatting onto every call site twice. Prism takes the node and formats
-     * nothing.
-     */
-    value: ReactNode;
-    /**
-     * The change against the previous reading, as a number whose sign is the
-     * direction. See `MetricDelta` on the Component.
-     */
-    delta?: number;
-    /**
-     * The words for that change, given the number. Required whenever `delta` is
-     * set, and the Block throws without it. See the Component JSDoc for the full
-     * argument.
-     */
-    deltaLabel?: (delta: number) => string;
-    /**
-     * The readings behind the current one, oldest first, in the caller's own units.
-     *
-     * Raw magnitudes rather than percentages of a maximum, which is the contract
-     * `Sparkline` states: a caller that pre-normalises has two chances to get the
-     * shape wrong, and a series drawn against an axis nobody can see is a picture
-     * of somebody's arithmetic.
-     */
-    series?: number[];
-    /**
-     * The name of that series, and the only thing a screen reader reads from the
-     * shape. Required whenever `series` is set, and the Block throws without it.
-     */
-    seriesLabel?: string;
-    /** Where the row goes. Rendered as a native anchor, so the destination is real. */
-    href?: string;
-    /** The words on that link. Required whenever `href` is set. */
-    hrefLabel?: string;
-};
+import type { MetricSpec } from '../../lib/spec.js';
 /**
  * The props a Trend01 takes.
  *
@@ -78,8 +20,13 @@ export type Trend01Props = {
     /**
      * The rows, in the order a reader should meet them. See the Component JSDoc
      * for why the Block does not sort them.
+     *
+     * Each row is the shared `MetricSpec`: a stable `key` that is never the words of
+     * the label, a required `label` and `value`, a `delta` whose sign is the
+     * direction, an optional `deltaFormat` for the caller's own words, an optional
+     * `hint`, and an optional `series` and `href` with the names they travel with.
      */
-    items: readonly Trend01Item[];
+    items: readonly MetricSpec[];
     /**
      * How many rows to render. Defaults to the whole set.
      *
@@ -133,19 +80,25 @@ export type Trend01Props = {
  * implementation would be the one without the table, because the table is the part
  * nobody draws by hand and it is the part that matters.
  *
- * **`deltaLabel` is required whenever any row carries a `delta`, and the reason
- * is that the Block cannot know which of three sentences the caller means.**
- * "up 12 percent", "+12%" and "12 higher than last week" are three sentences
- * about one number, and they are not formats of one another: the first is a
- * phrase with a unit, the second is a signed figure for a reader who is already
- * looking at a number, and the third is a comparison against a named period that
- * a reader who cannot see the period will misread as a comparison against
- * whatever they assumed. Worse, the fallback a Block would reach for is the worst
- * of the three, because a bare "+12" printed beside a figure is a number with an
- * arithmetic symbol on it, and a screen reader reads that as a formula rather
- * than as a change. So the prop is required and the Block throws without it
- * rather than printing the sign itself, and the cost of the throw is that a
- * caller who genuinely has no unit has to write the formatter that says so.
+ * **The rows are the shared `MetricSpec`, so a row here and a figure on a summary
+ * are one shape rather than two that disagree.** Each row carries a stable `key`
+ * that is never the words of the label, a required `label` and `value`, an optional
+ * `delta` whose sign is the direction, an optional `deltaFormat` carrying the
+ * caller's own words for the change, an optional `hint` for the period or the
+ * caveat, and an optional `series` and `href` each travelling with the name it
+ * cannot be read without. This closes the absence that put this Block in the
+ * migration: a reading now has a place for a series and for a destination, so the
+ * trend a metric summary names has somewhere to go when the two sit on one screen.
+ *
+ * **The words for the change stay the caller's, and the Block mints no period and
+ * no arithmetic.** `deltaFormat` is the caller's own node rather than a formatter
+ * this Block could write, because "up 12 percent", "+12%" and "12 higher than last
+ * week" are three sentences about one number and no single fallback is right for
+ * all three. A delta with a formatter prints the caller's words and one without
+ * prints the number the caller passed, which is `Metric`'s own contract. There is
+ * no period member, no derived rate of change and no period-over-period arithmetic
+ * over the series the caller passed, because each of those is a second arithmetic
+ * this package would be doing over a population it never fetched.
  *
  * **`seriesLabel` is required whenever any row carries a `series`, for the reason
  * the `Sparkline` JSDoc gives in full: a figure with no name is not announced

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

@@ -1 +1 @@
-{"version":3,"file":"trend.d.ts","sourceRoot":"","sources":["../../../src/blocks/trend-01/trend.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAIxF;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,KAAK,EAAE,SAAS,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;OAGG;IACH,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;IAC7B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,wBAAgB,OAAO,CAAC,EACtB,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,KAAK,EACL,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,YAAY,sCA6Gd;AAED,eAAe,OAAO,CAAA"}
+{"version":3,"file":"trend.d.ts","sourceRoot":"","sources":["../../../src/blocks/trend-01/trend.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAExF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAkChD;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,KAAK,EAAE,SAAS,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;;OAQG;IACH,KAAK,EAAE,SAAS,UAAU,EAAE,CAAA;IAC5B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,wBAAgB,OAAO,CAAC,EACtB,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,KAAK,EACL,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,YAAY,sCA2Fd;AAED,eAAe,OAAO,CAAA"}