@nanisoft/prism-ui 0.16.0 → 1.0.0

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

@@ -1,14 +1,13 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useId } from 'react';
+import { useId, useState } from 'react';
 import { Button } from '../../components/ui/button.js';
 import { CtaLink } from '../../components/ui/cta-link.js';
-import { Field, FieldDescription, 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 { LiveRegion } from '../../components/ui/live-region.js';
-import { NativeSelect } from '../../components/ui/native-select.js';
 import { Section, SectionHeading } from '../../components/ui/section.js';
-import { Textarea } from '../../components/ui/textarea.js';
+import { CHOICE_KINDS, fieldText, NEEDS_HIDDEN, renderControl, serialize, SELF_LABELLED, } from '../../lib/field-render.js';
 import { cn } from '../../lib/utils.js';
 /**
  * Whether a caller-supplied string never arrived, arrived empty, or arrived as
@@ -41,19 +40,27 @@ function blankList(value) {
  *
  * Both reach a developer in a console rather than a reader, which is what makes
  * them refusals rather than copy: the message says what was passed and what to
- * pass instead, and neither of those sentences is ever shown to a reader.
+ * pass instead, and neither of those sentences is ever shown to a reader. 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 assertField(field) {
-    if (blank(field.label)) {
-        throw new Error(`Contact01: the field "${field.id}" declares no label, so the 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' && blankList(field.options)) {
-        throw new Error(`Contact01: 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.');
+function assertGroups(groups) {
+    for (const group of groups) {
+        for (const field of group.fields) {
+            if (blank(typeof field.label === 'string' ? field.label : undefined)) {
+                throw new Error(`Contact01: the field "${field.key}" declares no label, so the 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) &&
+                blankList(field.options)) {
+                throw new Error(`Contact01: 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.');
+            }
+        }
     }
 }
 /**
@@ -156,34 +163,56 @@ function assertField(field) {
  * nothing. The rest of the rendering is a section and five controls, which is the
  * price of the argument above and not a claim about what else this Block might do.
  */
-export function Contact01({ eyebrow, title, description, onSubmit, fields, submitLabel, consent, address, variant = 'split', status, headingLevel = 'h2', className, }) {
+export function Contact01({ eyebrow, title, description, onSubmit, groups, issues, submitLabel, consent, address, variant = 'split', status, headingLevel = 'h2', className, }) {
     const generated = useId();
     const sending = status?.state === 'sending';
-    for (const field of fields)
-        assertField(field);
+    const [values, setValues] = useState({});
+    const setValue = (key, value) => setValues((previous) => ({ ...previous, [key]: value }));
+    assertGroups(groups);
+    const fields = groups.flatMap((group) => group.fields);
     /*
      * The values are read out of the form rather than out of any prop, because a
      * contact form is uncontrolled by nature: there are as many fields as the caller
-     * declared and no state to hold them in. The keys are the caller's own `id`s, so
-     * the record that arrives is shaped like the declaration that produced it, and a
-     * caller that renames a field in one place renames it in one place.
+     * declared and no state to hold them in. The keys are the caller's own field
+     * `key`s, so the record that arrives is shaped like the declaration that produced
+     * it, and a caller that renames a field in one place renames it in one place. The
+     * handful of Prism controls the platform will not submit on their own hold their
+     * value here and carry a hidden input under the field's key.
      */
     const handleSubmit = (event) => {
         event.preventDefault();
         const read = new FormData(event.currentTarget);
         const next = {};
         for (const field of fields) {
-            const one = read.get(field.id);
+            const one = read.get(field.key);
             if (typeof one === 'string')
-                next[field.id] = one;
+                next[field.key] = one;
         }
         onSubmit(next);
     };
-    return (_jsx(Section, { "data-slot": "contact-01", className: cn(className), children: _jsxs("div", { "data-slot": "contact-01-body", className: "flex flex-col gap-8", children: [_jsx(SectionHeading, { eyebrow: eyebrow, title: title, description: description, align: "left", as: headingLevel }), _jsxs("div", { "data-slot": "contact-01-columns", "data-variant": variant, className: cn('grid items-start gap-10', variant === 'split' ? 'lg:grid-cols-[minmax(0,3fr)_minmax(0,2fr)] lg:gap-14' : null), children: [_jsxs("form", { "data-slot": "contact-01-form", onSubmit: handleSubmit, className: "flex w-full max-w-measure flex-col gap-4", children: [fields.map((field) => {
-                                    const controlId = `${generated}-${field.id}`;
-                                    const descriptionId = `${controlId}-description`;
-                                    return (_jsxs(Field, { "data-slot": "contact-01-field", "data-field": field.type, children: [_jsx(FieldLabel, { htmlFor: controlId, children: field.label }), field.type === 'textarea' ? (_jsx(Textarea, { id: controlId, name: field.id, rows: 4, placeholder: field.placeholder, required: field.required, "aria-describedby": field.description === undefined ? undefined : descriptionId })) : field.type === 'select' ? (_jsx(NativeSelect, { id: controlId, name: field.id, 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, required: field.required, "aria-describedby": field.description === undefined ? undefined : descriptionId })), field.description === undefined ? null : (_jsx(FieldDescription, { id: descriptionId, children: field.description }))] }, field.id));
-                                }), consent === undefined ? null : (_jsx("p", { "data-slot": "contact-01-consent", className: "text-muted-foreground text-sm", children: consent })), _jsxs("div", { "data-slot": "contact-01-actions", className: "flex flex-col gap-3", children: [_jsx(Button, { "data-slot": "contact-01-submit", type: "submit", disabled: sending, className: "self-start", children: submitLabel }), _jsx(LiveRegion, { politeness: status?.state === 'error' ? 'assertive' : 'polite', busy: sending, className: "text-sm", children: status?.message })] })] }), address === undefined ? null : (
+    return (_jsx(Section, { "data-slot": "contact-01", className: cn(className), children: _jsxs("div", { "data-slot": "contact-01-body", className: "flex flex-col gap-8", children: [_jsx(SectionHeading, { eyebrow: eyebrow, title: title, description: description, align: "left", as: headingLevel }), _jsxs("div", { "data-slot": "contact-01-columns", "data-variant": variant, className: cn('grid items-start gap-10', variant === 'split' ? 'lg:grid-cols-[minmax(0,3fr)_minmax(0,2fr)] lg:gap-14' : null), children: [_jsxs("form", { "data-slot": "contact-01-form", onSubmit: handleSubmit, className: "flex w-full max-w-measure flex-col gap-4", children: [groups.map((group, groupIndex) => (_jsxs(FieldGroup, { "data-slot": "contact-01-group", className: "flex flex-col gap-4", children: [group.label === undefined ? null : (_jsx("p", { "data-slot": "contact-01-group-label", className: "text-foreground text-sm font-medium", children: group.label })), group.description === undefined ? null : (_jsx("p", { "data-slot": "contact-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": "contact-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": "contact-01-issue", children: issue.message }, issueIndex))) }))] }, field.key));
+                                        })] }, group.id ?? groupIndex))), consent === undefined ? null : (_jsx("p", { "data-slot": "contact-01-consent", className: "text-muted-foreground text-sm", children: consent })), _jsxs("div", { "data-slot": "contact-01-actions", className: "flex flex-col gap-3", children: [_jsx(Button, { "data-slot": "contact-01-submit", type: "submit", disabled: sending, className: "self-start", children: submitLabel }), _jsx(LiveRegion, { politeness: status?.state === 'error' ? 'assertive' : 'polite', busy: sending, className: "text-sm", children: status?.message })] })] }), address === undefined ? null : (
                         /*
                          * An `address` element, because that is what this is: contact
                          * information for the organisation, which is what the element names and

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

@@ -1,3 +1,3 @@
 export { Contact01, default } from './contact.js';
-export type { Contact01Address, Contact01Option, Contact01Props, Contact01Status, ContactField, ContactValue, } from './contact.js';
+export type { Contact01Address, Contact01Issue, Contact01Props, Contact01Status, ContactValue, } from './contact.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/contact-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAM9C,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,eAAe,EACf,YAAY,EACZ,YAAY,GACb,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/contact-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAO9C,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,eAAe,EACf,YAAY,GACb,MAAM,WAAW,CAAA"}

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

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import { type HeadingLevel } from '../../components/ui/section.js';
+import type { MetricSpec } from '../../lib/spec.js';
 /**
  * How much of the six-track panel grid one panel takes.
  *
@@ -13,64 +14,6 @@ import { type HeadingLevel } from '../../components/ui/section.js';
  * full width under a row of thirds, two thirds above a row of halves.
  */
 export type Dashboard01Span = 'full' | 'half' | 'third';
-/**
- * One figure at the top of an overview, and the four optional things a figure
- * comes with.
- *
- * `label` and `value` are the two that make a figure a figure. The rest are
- * annotation, and a metric with no annotation renders the two it has rather than a
- * card with a line of empty space where the annotation would have been, which is
- * the rule every optional field on this type follows.
- *
- * `deltaFormat` is here for the reason `Metric` refuses to guess: a delta of `0.12`
- * is twelve percent, twelve cents or twelve milliseconds, and a Component that
- * attached a percent sign to it would be claiming a caller's units. The cost of the
- * refusal is that a caller who passes a fraction and no formatter gets `0.12`
- * printed, which is honest and almost never what was wanted, so the formatter is a
- * prop here and the alternative was a Block guessing on every consumer's behalf.
- */
-export type Dashboard01Metric = {
-    /** What the figure measures, read under the figure rather than above it. */
-    label: string;
-    /** The figure itself, in the caller's own units and the caller's own formatting. */
-    value: ReactNode;
-    /**
-     * The change against the previous reading, where the sign is the direction.
-     *
-     * A `number` and not an object with a `direction`, for the reason `Metric` states
-     * in full: a number has exactly one sign, and a shape with both lets a caller put
-     * a rising mark on a falling reading.
-     */
-    delta?: number;
-    /** The words for the delta, given the number. See the note on this type. */
-    deltaFormat?: (value: number) => string;
-    /** The line under the label: the period, the source, the caveat that matters. */
-    hint?: ReactNode;
-    /** The readings behind the figure, drawn small beside it. See `sparklineLabel`. */
-    sparkline?: number[];
-    /**
-     * The name of the series the sparkline draws, and the only thing a screen reader
-     * reads before the numbers.
-     *
-     * Required whenever `sparkline` is set, and the pair is checked together rather
-     * than left to the Component. `Sparkline` needs a name for the same reason `Chart`
-     * does: two sparklines in a row of four are two pictures a reader cannot tell
-     * apart, and a picture with no name is not announced and not linkable. Requiring
-     * it at the Block's own boundary rather than letting the Component throw means the
-     * diagnostic names the field the caller has to add.
-     */
-    sparklineLabel?: string;
-    /** Where the figure is kept. Its presence makes the tile carry a link. */
-    href?: string;
-    /**
-     * The words on the link, and required whenever `href` is.
-     *
-     * A link whose only words are the figure itself tells a reader nothing about what
-     * following it does, and the same rule holds in every Block in this package that
-     * draws a link.
-     */
-    hrefLabel?: string;
-};
 /**
  * One panel in the grid: an identifier, how much width it takes, and the caller's
  * own content.
@@ -130,13 +73,22 @@ export type Dashboard01Props = {
      */
     header?: ReactNode;
     /**
-     * The figures along the top, in the order a reader should meet them.
+     * The figures along the top, as the shared `MetricSpec` typed data, in the order
+     * a reader should meet them.
+     *
+     * **It is the shared specification 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 this row
+     * are the words on every other figure surface.
      *
      * Order is the caller's because it is a claim about what matters first. A row
      * that sorted itself by size or by name would be making that claim on the
      * caller's behalf, and on a dashboard the claim is the whole point.
      */
-    metrics?: Dashboard01Metric[];
+    metrics?: MetricSpec[];
     /** The panels, in the order a reader should meet them. See `Dashboard01Panel`. */
     panels?: Dashboard01Panel[];
     /**
@@ -179,17 +131,20 @@ export type Dashboard01Props = {
  * Prism happened to put first. So `panels` is a list with a width on each entry and
  * this Block's only remaining opinion is the six-track grid they are placed on.
  *
- * **The figures are `Metric` and `Sparkline`, and a dashboard that hand-drew its own
- * metric row would be a second implementation of a Component whose whole argument is
- * that the direction is derived rather than declared.** `Metric`'s delta is a
- * `number` and the sign is the direction, so a rising mark cannot be drawn on a
- * falling reading; a Block that took `{ value, direction }` could, and the mistake
- * would be invisible in review and visible to every reader of that dashboard. It
- * also puts the label under the value, which is the arrangement a dashboard row
- * wants, because a row is scanned by its figures and settled by its names. And
- * `Sparkline` draws the numbers behind its shape as a table in the document, so a
- * metric row of six costs six tables in the accessibility tree rather than six
- * pictures nobody can query. The cost is stated rather than implied: a sparkline
+ * **The figures are typed by the shared `MetricSpec` and drawn by `Metric` and
+ * `Sparkline`, and a dashboard that hand-drew its own metric row would be a second
+ * implementation of a Component whose whole argument is that the direction is derived
+ * rather than declared.** The row is a list of the same specification every other
+ * figure surface takes, published as `@nanisoft/prism-ui/spec`, so a consumer that
+ * learned the shape here exports it unchanged to a project dashboard and a summary
+ * panel. `Metric`'s delta is a `number` and the sign is the direction, so a rising
+ * mark cannot be drawn on a falling reading; a Block that took `{ value, direction }`
+ * could, and the mistake would be invisible in review and visible to every reader of
+ * that dashboard. It also puts the label under the value, which is the arrangement a
+ * dashboard row wants, because a row is scanned by its figures and settled by its
+ * names. And `Sparkline` draws the numbers behind its shape as a table in the
+ * document, so a metric row of six costs six tables in the accessibility tree rather
+ * than six pictures nobody can query. The cost is stated rather than implied: a series
  * needs a name and a series that is not flat, and a caller who passes an empty array
  * or a series of one repeated value gets `Sparkline`'s own refusal, which is the
  * right place for it.

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

@@ -1 +1 @@
-{"version":3,"file":"dashboard-01.d.ts","sourceRoot":"","sources":["../../../src/blocks/dashboard-01/dashboard-01.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAWtC,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,6BAA6B,CAAA;AAIpC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAEvD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACvC,iFAAiF;IACjF,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAA;IACV,wEAAwE;IACxE,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,mEAAmE;IACnE,IAAI,CAAC,EAAE,eAAe,CAAA;IACtB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,4EAA4E;IAC5E,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC7B,kFAAkF;IAClF,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAA;IAC3B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AA+CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,KAAK,EACL,WAAW,EACX,MAAM,EACN,OAAY,EACZ,MAAW,EACX,IAAI,EACJ,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,gBAAgB,+BA+KlB;AAED,eAAe,WAAW,CAAA"}
+{"version":3,"file":"dashboard-01.d.ts","sourceRoot":"","sources":["../../../src/blocks/dashboard-01/dashboard-01.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAWtC,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,6BAA6B,CAAA;AAEpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAGhD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAEvD;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAA;IACV,wEAAwE;IACxE,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,mEAAmE;IACnE,IAAI,CAAC,EAAE,eAAe,CAAA;IACtB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,4EAA4E;IAC5E,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,EAAE,UAAU,EAAE,CAAA;IACtB,kFAAkF;IAClF,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAA;IAC3B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAiDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,KAAK,EACL,WAAW,EACX,MAAM,EACN,OAAY,EACZ,MAAW,EACX,IAAI,EACJ,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,gBAAgB,+BAoLlB;AAED,eAAe,WAAW,CAAA"}

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

@@ -23,24 +23,26 @@ const SPAN = {
  * The refusals, as checks, so a tile that would render a control nobody can name is
  * a diagnostic in a console rather than a rendered link.
  *
- * The pair rule is the same one `Changelog01` and `ContentGrid01` make: a link whose
- * only words are the figure's own value tells a reader nothing about what following
- * it does, and an accessible name that is an address is punctuation rather than a
- * name. The sparkline's label is checked here rather than left to the Component
- * because the Component's own message names a Component's field, and a caller who
- * wired a dashboard up would rather be told which of their own props to add.
+ * **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 tile 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 `Changelog01` and `ContentGrid01` make, and the series name is the one
+ * `Sparkline` gives in full.
  */
 function assertMetrics(metrics) {
     for (const metric of metrics) {
         if ((metric.href === undefined) !== (metric.hrefLabel === undefined)) {
-            throw new Error(`Dashboard01: the metric "${metric.label}" declares one of href and hrefLabel without the other, so the ` +
+            throw new Error(`Dashboard01: the metric "${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.sparkline !== undefined && metric.sparklineLabel === undefined) {
-            throw new Error(`Dashboard01: the metric "${metric.label}" passes a sparkline with no sparklineLabel, so the figure would ` +
-                'be a picture with no name, which a screen reader cannot announce and two sparklines in one row cannot be ' +
-                'told apart. Pass the series name in the words the product uses.');
+        if ((metric.series === undefined) !== (metric.seriesLabel === undefined)) {
+            throw new Error(`Dashboard01: the metric "${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.');
         }
     }
 }
@@ -60,17 +62,20 @@ function assertMetrics(metrics) {
  * Prism happened to put first. So `panels` is a list with a width on each entry and
  * this Block's only remaining opinion is the six-track grid they are placed on.
  *
- * **The figures are `Metric` and `Sparkline`, and a dashboard that hand-drew its own
- * metric row would be a second implementation of a Component whose whole argument is
- * that the direction is derived rather than declared.** `Metric`'s delta is a
- * `number` and the sign is the direction, so a rising mark cannot be drawn on a
- * falling reading; a Block that took `{ value, direction }` could, and the mistake
- * would be invisible in review and visible to every reader of that dashboard. It
- * also puts the label under the value, which is the arrangement a dashboard row
- * wants, because a row is scanned by its figures and settled by its names. And
- * `Sparkline` draws the numbers behind its shape as a table in the document, so a
- * metric row of six costs six tables in the accessibility tree rather than six
- * pictures nobody can query. The cost is stated rather than implied: a sparkline
+ * **The figures are typed by the shared `MetricSpec` and drawn by `Metric` and
+ * `Sparkline`, and a dashboard that hand-drew its own metric row would be a second
+ * implementation of a Component whose whole argument is that the direction is derived
+ * rather than declared.** The row is a list of the same specification every other
+ * figure surface takes, published as `@nanisoft/prism-ui/spec`, so a consumer that
+ * learned the shape here exports it unchanged to a project dashboard and a summary
+ * panel. `Metric`'s delta is a `number` and the sign is the direction, so a rising
+ * mark cannot be drawn on a falling reading; a Block that took `{ value, direction }`
+ * could, and the mistake would be invisible in review and visible to every reader of
+ * that dashboard. It also puts the label under the value, which is the arrangement a
+ * dashboard row wants, because a row is scanned by its figures and settled by its
+ * names. And `Sparkline` draws the numbers behind its shape as a table in the
+ * document, so a metric row of six costs six tables in the accessibility tree rather
+ * than six pictures nobody can query. The cost is stated rather than implied: a series
  * needs a name and a series that is not flat, and a caller who passes an empty array
  * or a series of one repeated value gets `Sparkline`'s own refusal, which is the
  * right place for it.
@@ -136,6 +141,12 @@ export function Dashboard01({ eyebrow, title, description, header, metrics = [],
                 // The gap between the header and the body is a fact about whether the lead
                 // drew anything, so it arrives with that fact rather than as a margin on
                 // two of the three possible children.
-                hasLead ? 'mt-8' : null, hasRail ? 'lg:grid lg:grid-cols-4 lg:items-start lg:gap-6' : null), children: [_jsxs("div", { "data-slot": "dashboard-01-main", className: cn('flex min-w-0 flex-col gap-6', hasRail ? 'lg:col-span-3' : null), children: [metrics.length > 0 ? (_jsx("div", { "data-slot": "dashboard-01-metrics", className: "grid gap-4 sm:grid-cols-2 lg:grid-cols-4", children: metrics.map((metric) => (_jsxs(Card, { "data-slot": "dashboard-01-metric", "data-metric": metric.label, className: "gap-4 py-5", children: [_jsxs(CardContent, { className: "flex flex-col gap-3", children: [_jsx(Metric, { value: metric.value, label: metric.label, delta: metric.delta, deltaFormat: metric.deltaFormat, hint: metric.hint }), metric.sparkline === undefined ? null : (_jsx("div", { "data-slot": "dashboard-01-sparkline", className: "flex", children: _jsx(Sparkline, { values: metric.sparkline, label: metric.sparklineLabel, className: "ms-auto" }) }))] }), metric.href === undefined ? null : (_jsx(CardFooter, { "data-slot": "dashboard-01-metric-link", className: "justify-end", children: _jsx(CtaLink, { href: metric.href, variant: "ghost", size: "sm", children: metric.hrefLabel }) }))] }, metric.label))) })) : null, panels.length > 0 ? (_jsx("div", { "data-slot": "dashboard-01-panels", className: "grid gap-4 lg:grid-cols-6", children: panels.map((panel) => (_jsx("div", { "data-slot": "dashboard-01-panel", "data-panel": panel.id, className: SPAN[panel.span ?? 'full'], children: _jsxs(Card, { className: "h-full gap-4 py-5", children: [panel.title === undefined && panel.toolbar === undefined ? null : (_jsxs(CardHeader, { className: "grid-cols-[minmax(0,1fr)_auto] gap-x-3", children: [panel.title === undefined ? null : (_jsx(CardTitle, { as: PanelTitle, className: "text-base", children: panel.title })), panel.toolbar === undefined ? null : (_jsx("div", { "data-slot": "dashboard-01-panel-toolbar", className: "flex min-w-0 items-center gap-2", children: panel.toolbar }))] })), _jsx(CardContent, { children: panel.children }), panel.footer === undefined ? null : (_jsx(CardFooter, { "data-slot": "dashboard-01-panel-footer", children: panel.footer }))] }) }, panel.id))) })) : null, hasBody ? null : _jsx("div", { "data-slot": "dashboard-01-empty", children: empty })] }), hasRail ? (_jsx("div", { "data-slot": "dashboard-01-rail", className: "flex min-w-0 flex-col gap-4 lg:col-span-1", children: rail })) : null] })] }));
+                hasLead ? 'mt-8' : null, hasRail ? 'lg:grid lg:grid-cols-4 lg:items-start lg:gap-6' : null), children: [_jsxs("div", { "data-slot": "dashboard-01-main", className: cn('flex min-w-0 flex-col gap-6', hasRail ? 'lg:col-span-3' : null), children: [metrics.length > 0 ? (_jsx("div", { "data-slot": "dashboard-01-metrics", className: "grid gap-4 sm:grid-cols-2 lg:grid-cols-4", children: metrics.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 (_jsxs(Card, { "data-slot": "dashboard-01-metric", "data-metric": metric.key, className: "gap-4 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": "dashboard-01-sparkline", className: "flex", children: _jsx(Sparkline, { values: metric.series, label: metric.seriesLabel, className: "ms-auto" }) }))] }), metric.href === undefined ? null : (_jsx(CardFooter, { "data-slot": "dashboard-01-metric-link", className: "justify-end", children: _jsx(CtaLink, { href: metric.href, variant: "ghost", size: "sm", children: metric.hrefLabel }) }))] }, metric.key));
+                                }) })) : null, panels.length > 0 ? (_jsx("div", { "data-slot": "dashboard-01-panels", className: "grid gap-4 lg:grid-cols-6", children: panels.map((panel) => (_jsx("div", { "data-slot": "dashboard-01-panel", "data-panel": panel.id, className: SPAN[panel.span ?? 'full'], children: _jsxs(Card, { className: "h-full gap-4 py-5", children: [panel.title === undefined && panel.toolbar === undefined ? null : (_jsxs(CardHeader, { className: "grid-cols-[minmax(0,1fr)_auto] gap-x-3", children: [panel.title === undefined ? null : (_jsx(CardTitle, { as: PanelTitle, className: "text-base", children: panel.title })), panel.toolbar === undefined ? null : (_jsx("div", { "data-slot": "dashboard-01-panel-toolbar", className: "flex min-w-0 items-center gap-2", children: panel.toolbar }))] })), _jsx(CardContent, { children: panel.children }), panel.footer === undefined ? null : (_jsx(CardFooter, { "data-slot": "dashboard-01-panel-footer", children: panel.footer }))] }) }, panel.id))) })) : null, hasBody ? null : _jsx("div", { "data-slot": "dashboard-01-empty", children: empty })] }), hasRail ? (_jsx("div", { "data-slot": "dashboard-01-rail", className: "flex min-w-0 flex-col gap-4 lg:col-span-1", children: rail })) : null] })] }));
 }
 export default Dashboard01;

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

@@ -1,3 +1,3 @@
 export { Dashboard01, default } from './dashboard-01.js';
-export type { Dashboard01Metric, Dashboard01Panel, Dashboard01Props, Dashboard01Span, } from './dashboard-01.js';
+export type { Dashboard01Panel, Dashboard01Props, Dashboard01Span } from './dashboard-01.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/dashboard-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAIrD,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/dashboard-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAIrD,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA"}