@nanisoft/prism-ui 0.13.0 → 0.16.0

package/dist/blocks/spec-table-01/spec-table.js

@@ -0,0 +1,217 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useId } from 'react';
+import { Metric } from '../../components/ui/metric.js';
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow, } from '../../components/ui/table.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The classes each cell takes, before the caller's own layout classes merge in.
+ *
+ * The value is tabular and the unit is mono, which are two different answers to two
+ * different questions. Tabular figures are for a column a reader compares down, and
+ * a unit is a short notation rather than a figure, so it takes the face this system
+ * annotates machine-readable values with. Neither is a raw ramp utility and both are
+ * authored steps.
+ */
+const CELL = {
+    label: 'text-foreground whitespace-normal',
+    value: 'tabular-nums whitespace-normal',
+    unit: 'text-muted-foreground font-mono whitespace-nowrap',
+    note: 'text-muted-foreground whitespace-normal',
+};
+/**
+ * A capability's limits as a real table, grouped, with a summary band underneath.
+ *
+ * **The storefront version of this pattern is a product's specification table, and
+ * the translation is what the numbers are about.** What that table publishes is a
+ * list of attributes for an item for sale: the material, the weight, the dimensions,
+ * the care instructions, in a two-column table under a heading, sometimes grouped
+ * into sections. Every part of the layout and every part of the accessibility work
+ * transfers without a change, because a specification is a table whichever subject it
+ * describes: a screen reader announces the row's name with every cell beneath it in
+ * one, and a table of key and value cells in a grid of `div`s does not. What does not
+ * transfer is the subject. The figures here are a capability's limits: what it
+ * handles, what it costs, what it will not do. A reader arrives at that table to
+ * decide whether the thing can carry their estate, their market or their run, and the
+ * only reason the pattern survives the translation intact is that the access work
+ * was never about the noun.
+ *
+ * **This Block will not derive a value, infer a unit, or round a number, and those
+ * three refusals are the reason it exists rather than a limitation of it.** A
+ * specification table is the one surface in this system where a number a reader
+ * cannot check is a liability rather than a convenience: every figure on it is
+ * something the reader is about to plan against, and a figure this package printed
+ * would be a measurement the product never made. So a throughput number is a node
+ * the caller composed, a unit is a string the caller wrote, and a precision is the
+ * caller's decision made in its own formatter before the value reached this Block.
+ * The alternatives were each rejected for the same reason and are worth naming. A
+ * `format` prop would move the arithmetic into this package and put a locale and a
+ * rounding rule into a Block that has no business choosing either. A `number` value
+ * would make the caller format outside the Block or lose the precision it belongs
+ * to, and a number prop is what produced a bare `12000` on a page that should have
+ * said `12,000`. And a `compact` or `approximate` boolean would be a rounding rule
+ * with no name, applied to a figure this package cannot see the meaning of, and a
+ * rounded retention window is a wrong retention window.
+ *
+ * **`unit` is a string beside the value and not part of it, because "12k", "12
+ * thousand" and "12000" are three renderings and the caller owns the precision as
+ * well as the number.** Which of the three is right is a fact about the measurement
+ * and the audience rather than about the measurement alone: a reader reconciling a
+ * bill wants the full number, a reader scanning a column of twelve wants the short
+ * one, and a machine reading an export wants neither. Concatenating the unit into
+ * the value would also make the unit unaddressable: a screen reader announces a run
+ * of characters, and a column of units aligned under a column of figures is a
+ * comparison a reader can make in a way a run of strings is not. The cost is that a
+ * caller who wants them joined has to join them, which is the right place for the
+ * decision because it is their figure and their audience.
+ *
+ * **A group is a body and not a merged cell, for the reason `ResourceList01` states
+ * in full.** A reader navigates a table by its headers, and a cell spanning every
+ * row of a group is a `<td rowspan="n">`, which is not a header at all. A group named
+ * in one such cell is announced once, to nobody in particular, and every row beneath
+ * it looks to a reader navigating by header like a row of the group above. The same
+ * set rendered as a sequence of bodies inside one table has the group as each body's
+ * own row-group header, and a reader hears the group before the first row of it
+ * every time.
+ *
+ * **It is one `<table>` and not one table per group.** The groups are facets of one
+ * set rather than separate documents, the columns are the same in each, and a reader
+ * who has learned the columns in the first body has learned them for the rest. The
+ * honest cost is that a reader navigating by column header meets the columns before
+ * the group, not after it. A caller whose groups are separate documents wants one
+ * table per group, which is two `SpecTable01`s.
+ *
+ * **The row header is the limit's own label and the note is the cell that
+ * qualifies it.** Neither is shortened here. A specification without its conditions
+ * is a claim about every case rather than about the one it was measured in, which is
+ * a stronger claim than a product can usually support, and this Block does not write
+ * the scope for them.
+ *
+ * **A specification with no rows renders the caller's `empty` sentence and no
+ * table at all**, which is the opposite of what `Compliance01` does with an empty
+ * claims table and the same argument applied to a different surface. A compliance
+ * section wants its heading visible so a reader can see that nothing is published
+ * there; a specification table with a header row and no body is four column names
+ * and nothing else, which tells a reader less than the sentence the caller wrote for
+ * exactly this case. The cost is that a heading can survive on a page whose limits
+ * have all been withdrawn, and a consumer who would rather see nothing should not
+ * render the Block.
+ *
+ * **The heading is aligned left**, because the table is content and it sits under the
+ * heading. `SectionHeading` states the rule and this Block has rows underneath it.
+ *
+ * It composes `Section` and `SectionHeading`, so it inherits the container and the
+ * vertical rhythm rather than re-deriving either, and it adds no container width and
+ * no section padding of its own.
+ *
+ * It is a server Component: no hook, no state, no client code and no motion. Every
+ * figure it draws is the caller's node, passed straight through.
+ */
+export function SpecTable01({ eyebrow, title, description, columns, groups, summary, empty, headingLevel = 'h2', className, }) {
+    // The handle a table below takes its name from; see the note on the table.
+    const headingId = useId();
+    const rows = groups.flatMap((group) => group.rows);
+    /*
+     * Checked before anything is drawn, so the run fails once with the name of the
+     * field rather than once per row with a malformed table on the page.
+     */
+    const seen = new Set();
+    for (const column of columns) {
+        const id = column.id;
+        if (seen.has(id)) {
+            throw new Error(`SpecTable01: the column "${id}" is declared twice, so the table would have two columns ` +
+                'reading the same value and every cell after the first would be read under the wrong name. ' +
+                'Declare each cell once.');
+        }
+        if (id !== 'label' && !rows.some((row) => carries(row, id))) {
+            throw new Error(`SpecTable01: the "${id}" column was declared and no limit carries it, so the table would ` +
+                'carry a column of empty cells, which is a column every reader scans twice. Pass the value on at ' +
+                'least one limit, or drop the column.');
+        }
+        seen.add(id);
+    }
+    if (!seen.has('label')) {
+        throw new Error('SpecTable01: the columns name no "label" cell, so the header row would have a cell fewer than every ' +
+            'body row and no row would have a header for a reader to navigate into. Declare the label column, ' +
+            'which is also the row header for every row.');
+    }
+    const rowIds = new Set();
+    for (const row of rows) {
+        if (rowIds.has(row.id)) {
+            throw new Error(`SpecTable01: two limits share the key "${row.id}", so one of them is drawn with the other's ` +
+                'identity and a test cannot name which is which. Give every limit its own key.');
+        }
+        rowIds.add(row.id);
+    }
+    // A group with no limits is not drawn: a group name over an empty body is a
+    // heading with nothing under it, which is the frame-with-nothing-in-it every list
+    // in this package refuses to render.
+    const drawn = groups.filter((group) => group.rows.length > 0);
+    return (_jsxs(Section, { "data-slot": "spec-table-01", className: className, children: [_jsx(SectionHeading, { as: headingLevel, id: headingId, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-10" }), drawn.length === 0 ? (
+            /*
+             * The caller's own sentence, drawn where the table would have been rather
+             * than above it, so a reader is not left with four column names and no rows.
+             * `text-pretty` because the honest empty line is sometimes a paragraph and
+             * `text-balance` would leave a one-word last line in it.
+             */
+            _jsx("p", { "data-slot": "spec-table-01-empty", className: "text-muted-foreground max-w-measure-narrow text-pretty", children: empty })) : (_jsxs(_Fragment, { children: [_jsx("div", { "data-slot": "spec-table-01-table", className: cn('border-border overflow-hidden rounded-xl border', className), children: _jsxs(Table, { "aria-labelledby": headingId, children: [_jsx(TableHeader, { children: _jsx(TableRow, { children: columns.map((column) => (_jsx(TableHead, { scope: "col", className: cn(CELL[column.id], column.className), children: column.header }, column.id))) }) }), drawn.map((group, groupIndex) => (
+                                // The group title is the caller's own and two groups may carry the
+                                // same one, so the position is part of the key rather than a second
+                                // identifier the Block would have to ask for.
+                                _jsxs(TableBody, { children: [_jsx(TableRow, { children: _jsx(TableHead, { scope: "rowgroup", colSpan: columns.length, className: "bg-muted/50", children: _jsx("span", { "data-slot": "spec-table-01-group", className: "text-foreground text-sm font-semibold", children: group.title }) }) }), group.rows.map((row) => (_jsx(TableRow, { "data-slot": "spec-table-01-row", "data-row": row.id, "data-emphasised": row.emphasis === true, children: columns.map((column) => 
+                                            /*
+                                             * The limit's own label is the row header, so a reader who
+                                             * navigates into a single cell is told what is being measured
+                                             * rather than hearing a figure with nothing to attach it to.
+                                             */
+                                            column.id === 'label' ? (_jsx(TableHead, { scope: "row", className: cn(CELL[column.id], 
+                                                // The emphasised row is the one a reader should land on,
+                                                // so it is drawn in the foreground ink at a heavier
+                                                // weight and nothing else is added to it.
+                                                row.emphasis === true ? 'text-foreground font-semibold' : null, column.className), children: row.label }, column.id)) : (_jsx(TableCell, { className: cn(CELL[column.id], column.id === 'value' && row.emphasis === true ? 'font-medium' : null, column.className), children: cellOf(column.id, row) }, column.id))) }, row.id)))] }, `${group.title}-${groupIndex}`)))] }) }), summary === undefined || summary.length === 0 ? null : (
+                    /*
+                     * The band of figures the table reduces to. `Metric` draws each one,
+                     * because a figure has an arrangement and a rule about the mono face and
+                     * a rule about where the label sits, and re-deriving any of those here
+                     * would be a second answer in one package.
+                     */
+                    _jsx("div", { "data-slot": "spec-table-01-summary", className: "border-border bg-muted/40 mt-6 grid gap-6 rounded-xl border px-6 py-5 sm:grid-cols-2 lg:grid-cols-3", children: summary.map((entry) => (_jsx(Metric, { value: entry.value, label: entry.label }, entry.label))) }))] }))] }));
+}
+/**
+ * Whether one limit carries the value a column draws.
+ *
+ * A separate step so the column check reads as a sentence rather than as a chain of
+ * optional fields, and so a fifth cell added later is one line here rather than four
+ * edits across the checks above.
+ */
+function carries(row, id) {
+    switch (id) {
+        case 'value':
+            return row.value !== undefined && row.value !== null;
+        case 'unit':
+            return row.unit !== undefined;
+        case 'note':
+            return row.note !== undefined;
+    }
+}
+/**
+ * The cell one column draws for one limit.
+ *
+ * A switch rather than a map of render functions, for the reason `FieldMap01`
+ * gives: a map keyed by cell id would be a second recipe of the kind this package
+ * keeps off the public surface, and a switch over four cases is the same table with
+ * the strings in the same file as the drawing that uses them.
+ */
+function cellOf(id, row) {
+    switch (id) {
+        case 'label':
+            return row.label;
+        case 'value':
+            return row.value;
+        case 'unit':
+            return row.unit ?? null;
+        case 'note':
+            return row.note ?? null;
+    }
+}
+export default SpecTable01;

package/dist/blocks/stack-grid-01/stack-grid.d.ts

@@ -129,6 +129,19 @@ export type StackGrid01Props = {
  * is a fill for a large area and never a signal, and a tile of pastel behind one
  * word is a signal a reader has to learn.
  *
+ * **The two groups set their type identically, and it is the same two steps in
+ * both.** They happened to agree on the steps and to be wrong on both of them,
+ * which is the harder defect to see: a grid whose second group is quieter than its
+ * first is a grid saying the in-house work matters less than the assembled parts,
+ * which is the opposite of what the group is for. A tile name is a card title, so
+ * it sits at Body the way `CardTitle` says a card title sits at Body, and a role
+ * and a blurb are both supporting copy at the step `DESIGN.md` gives supporting
+ * copy. Below those two floors was the measured state of both arms: names at
+ * fourteen pixels and the line under them at twelve, so a heading rendered smaller
+ * than the copy around it and the tile read as a caption rather than as a tile. The
+ * mono annotation over an in-house name and under a codename is left at `text-xs`
+ * on purpose, because that is a machine annotation and not a run of prose.
+ *
  * `ownLabel` is required when `own` is passed, because the group is a claim and
  * the claim is the caller's words. Three of the four sites write three different
  * ones, and the Block does not choose.

package/dist/blocks/stack-grid-01/stack-grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stack-grid.d.ts","sourceRoot":"","sources":["../../../src/blocks/stack-grid-01/stack-grid.tsx"],"names":[],"mappings":"AACA,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAGpG;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;IAC3B;;;;OAIG;IACH,GAAG,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAA;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,GAAG,EACH,QAAQ,EACR,OAAO,EACP,YAAmB,EACnB,SAAS,GACV,EAAE,gBAAgB,+BA6ElB;AAED,eAAe,WAAW,CAAA"}
+{"version":3,"file":"stack-grid.d.ts","sourceRoot":"","sources":["../../../src/blocks/stack-grid-01/stack-grid.tsx"],"names":[],"mappings":"AACA,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAGpG;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;IAC3B;;;;OAIG;IACH,GAAG,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAA;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,GAAG,EACH,QAAQ,EACR,OAAO,EACP,YAAmB,EACnB,SAAS,GACV,EAAE,gBAAgB,+BA6ElB;AAED,eAAe,WAAW,CAAA"}

package/dist/blocks/stack-grid-01/stack-grid.js

@@ -28,6 +28,19 @@ import { cn } from '../../lib/utils.js';
  * is a fill for a large area and never a signal, and a tile of pastel behind one
  * word is a signal a reader has to learn.
  *
+ * **The two groups set their type identically, and it is the same two steps in
+ * both.** They happened to agree on the steps and to be wrong on both of them,
+ * which is the harder defect to see: a grid whose second group is quieter than its
+ * first is a grid saying the in-house work matters less than the assembled parts,
+ * which is the opposite of what the group is for. A tile name is a card title, so
+ * it sits at Body the way `CardTitle` says a card title sits at Body, and a role
+ * and a blurb are both supporting copy at the step `DESIGN.md` gives supporting
+ * copy. Below those two floors was the measured state of both arms: names at
+ * fourteen pixels and the line under them at twelve, so a heading rendered smaller
+ * than the copy around it and the tile read as a caption rather than as a tile. The
+ * mono annotation over an in-house name and under a codename is left at `text-xs`
+ * on purpose, because that is a machine annotation and not a run of prose.
+ *
  * `ownLabel` is required when `own` is passed, because the group is a claim and
  * the claim is the caller's words. Three of the four sites write three different
  * ones, and the Block does not choose.
@@ -52,6 +65,6 @@ export function StackGrid01({ eyebrow, title, description, parts, own, ownLabel,
             '"this part is ours" in a shape and leave the words to a reader to infer. Pass the words you mean, ' +
             'or omit the group.');
     }
-    return (_jsxs(Section, { children: [title ? (_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-12" })) : null, _jsxs("div", { "data-slot": "stack-grid", className: cn('flex flex-col gap-10', className), children: [_jsx("ul", { className: "grid gap-3 sm:grid-cols-2 lg:grid-cols-4", children: parts.map((part) => (_jsx("li", { children: _jsxs(Card, { className: "bg-muted h-full gap-2 py-4", children: [_jsxs(CardHeader, { className: "gap-1", children: [_jsx(CardTitle, { className: "text-sm", children: _jsx(Title, { children: part.name }) }), part.realName ? (_jsx("span", { className: "text-muted-foreground font-mono text-xs", children: part.realName })) : null] }), _jsx(CardContent, { children: _jsx("p", { className: "text-muted-foreground text-pretty text-xs", children: part.role }) })] }) }, part.name))) }), own && own.length > 0 ? (_jsx("ul", { "data-slot": "stack-grid-own", className: "grid gap-3 sm:grid-cols-2 lg:grid-cols-4", children: own.map((entry) => (_jsx("li", { children: _jsxs(Card, { className: "border-primary shadow-md h-full gap-2 py-4", children: [_jsxs(CardHeader, { className: "gap-1", children: [_jsx("span", { className: "text-muted-foreground font-mono text-xs", children: ownLabel }), _jsx(CardTitle, { className: "text-sm", children: _jsx(Title, { children: entry.name }) })] }), _jsx(CardContent, { children: _jsx("p", { className: "text-muted-foreground text-pretty text-xs", children: entry.blurb }) })] }) }, entry.name))) })) : null] }), caption ? _jsx("p", { className: "text-muted-foreground mt-6 text-pretty text-sm", children: caption }) : null] }));
+    return (_jsxs(Section, { children: [title ? (_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-12" })) : null, _jsxs("div", { "data-slot": "stack-grid", className: cn('flex flex-col gap-10', className), children: [_jsx("ul", { className: "grid gap-3 sm:grid-cols-2 lg:grid-cols-4", children: parts.map((part) => (_jsx("li", { children: _jsxs(Card, { className: "bg-muted h-full gap-2 py-4", children: [_jsxs(CardHeader, { className: "gap-1", children: [_jsx(CardTitle, { className: "text-lg", children: _jsx(Title, { children: part.name }) }), part.realName ? (_jsx("span", { className: "text-muted-foreground font-mono text-xs", children: part.realName })) : null] }), _jsx(CardContent, { children: _jsx("p", { className: "text-muted-foreground text-pretty text-sm", children: part.role }) })] }) }, part.name))) }), own && own.length > 0 ? (_jsx("ul", { "data-slot": "stack-grid-own", className: "grid gap-3 sm:grid-cols-2 lg:grid-cols-4", children: own.map((entry) => (_jsx("li", { children: _jsxs(Card, { className: "border-primary shadow-md h-full gap-2 py-4", children: [_jsxs(CardHeader, { className: "gap-1", children: [_jsx("span", { className: "text-muted-foreground font-mono text-xs", children: ownLabel }), _jsx(CardTitle, { className: "text-lg", children: _jsx(Title, { children: entry.name }) })] }), _jsx(CardContent, { children: _jsx("p", { className: "text-muted-foreground text-pretty text-sm", children: entry.blurb }) })] }) }, entry.name))) })) : null] }), caption ? _jsx("p", { className: "text-muted-foreground mt-6 text-pretty text-sm", children: caption }) : null] }));
 }
 export default StackGrid01;

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

@@ -0,0 +1,3 @@
+export { Story01, default } from './story.js';
+export type { Story01Props, StoryMilestone } from './story.js';
+//# sourceMappingURL=index.d.ts.map

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

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

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

@@ -0,0 +1 @@
+export { Story01, default } from './story.js';

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

@@ -0,0 +1,153 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One milestone in a company's history: when it happened, what it was called,
+ * what it changed, and optionally a figure of the time.
+ *
+ * `at` is a `string` and not a `Date`, and the reason is the one this repository
+ * has already written down for the other half of the surface: a Block ships no
+ * formatting. A `Date` carries a timezone and a calendar and renders as
+ * `Wed Mar 04 2026 00:00:00 GMT+0000` unless something formats it, so a `Date`
+ * prop would push the formatting decision onto every consumer and make the
+ * wrong answer the easy one. As a string the Block prints what it was given,
+ * which is honest whether that is `2024`, `Q3 2024` or `Winter 2024`, and the
+ * honest way to render a date in a caller's own locale and script is the caller's
+ * to compose: `RelativeTime` for a localised absolute reading with relative words
+ * handed back, or the platform's own `Intl.DateTimeFormat` for a fixed one. A
+ * Block cannot know the locale, and a Block that guessed would ship English
+ * month names into every consumer's product.
+ *
+ * `mediaLabel` is the caption for `media`, and it is separate from `media` for the
+ * same reason every other slot is separate: a figure is the consumer's and a
+ * sentence describing it is the consumer's too, and a Block that required the
+ * two together would make a caption impossible for a figure that needs none and
+ * mandatory for one that needs a lot.
+ */
+export type StoryMilestone = {
+    /** A stable key for the milestone. */
+    id: string;
+    /** When it happened, already written the way the reader should see it. */
+    at: string;
+    /** What the milestone was called at the time. */
+    title: string;
+    /** What changed, in the reader's terms rather than the company's. */
+    body: ReactNode;
+    /** A figure of the time, composed by the caller. */
+    media?: ReactNode;
+    /** The caption for `media`, in the caller's words. */
+    mediaLabel?: string;
+};
+/**
+ * The props a Story01 takes.
+ *
+ * Every string, every date and every figure is a prop and the Block ships none:
+ * no milestone, no year, no caption and no default set of dates. A rail that
+ * hardcoded its milestones would hand every consumer a history that was not
+ * theirs, dated in years that were not theirs, which is the worst thing a
+ * company page can get wrong and the easiest thing for a component to do.
+ */
+export type Story01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /** The section title. Omit it for a rail composed under its own heading. */
+    title?: string;
+    /** One or two sentences under the title. */
+    description?: string;
+    /**
+     * The milestones, in the order they happened. Order is the caller's because it
+     * is a claim about what came first, and this Block would be making that claim
+     * for them if it sorted.
+     */
+    milestones: StoryMilestone[];
+    /**
+     * Whether the rail runs down the page or across it.
+     *
+     * `horizontal` collapses to the vertical rail below `md`, and that is the part
+     * worth reading twice: a five-milestone horizontal rail on a phone is five
+     * columns of unreadable text, so the width at which the horizontal form turns
+     * into the vertical one is a decision this Block makes once, here, rather than a
+     * decision four or five marketing pages each make differently and get wrong at
+     * the width below it. The cost of making it once is that the caller cannot put
+     * a horizontal rail on a narrow surface, and the reason that is acceptable is
+     * that there is no honest way to do so.
+     *
+     * @defaultValue 'vertical'
+     */
+    orient?: 'vertical' | 'horizontal';
+    /** Heading level for the section title. See `HeadingLevel`. */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Block. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A company's history as a reader walks it: a date, a title, what changed, and
+ * an optional figure, along a rail with a rule down one side.
+ *
+ * **It is a Block and not a component, and the difference is the subject.**
+ * `Timeline` draws a run's progress as it happens: it is fed events, it has four
+ * states, it scales durations against the longest step in the run, and one of its
+ * states moves. This arranges a sequence that has already finished, in a section
+ * that has content under its heading, and none of that machinery applies to it. A
+ * company history has no run state and no durations, and a reader who met a
+ * `Timeline` on an about page would be told a thing about the product is live and
+ * is not. So the two are different subjects, they compose as different things, and
+ * this is a section of a page rather than a shape inside one.
+ *
+ * **The NaniSoft framing is in this JSDoc and in the Demo, and nowhere in the
+ * Block.** The history these pages tell is the history of a pipeline that came to
+ * run, a market that came to be captured rather than reconstructed, an estate that
+ * came to be observed instead of visited, and work that came to be done by agents
+ * rather than filed for a person to pick up. Those are four claims, and every one
+ * of them is a `body` and a `title` at the call site. A Block that shipped them as
+ * strings would install one company's history into every consumer's page, so what
+ * travels is the shape: a date, a name, what changed, and a figure with a caption
+ * somebody had to write.
+ *
+ * **One `<ol>`, and the rail is not a second list.** A history that was drawn as
+ * a row per milestone group would be several lists, and a screen reader would
+ * announce it as three lists rather than one sequence. The milestones are one
+ * ordered list, the rail is a decorative span inside each entry, and it is marked
+ * `aria-hidden` so the sequence is read from the entries and not from a rule. The
+ * rule is what a sighted reader uses to see continuity; the order is what every
+ * other reader uses, and it comes from the element rather than from the drawing.
+ *
+ * **The dot is on the rail and the rail is behind it, which is what makes the
+ * vertical form read as one line rather than as a stack of rules.** The spine is
+ * drawn from the dot to the bottom of its own entry, so the last entry draws no
+ * spine and the line stops at the last dot instead of trailing past the end. That
+ * is the detail that separates a rail from a border, and it is the same detail
+ * `Timeline` states for its own spine.
+ *
+ * **The horizontal form is the one to watch, and the breakpoint is this Block's
+ * decision.** A five-milestone horizontal rail on a phone is five columns of
+ * unreadable text, so below `md` the horizontal form is the vertical form. The
+ * alternative was a prop for the width at which the rail turns, and it was
+ * refused: a consumer that set it too low would ship five columns of unreadable
+ * text, and a consumer that set it too high would get a vertical rail on a
+ * laptop. The honest answer is one breakpoint, made once, in the place that owns
+ * the layout.
+ *
+ * **Both forms are one set of elements.** The horizontal form is not a second
+ * tree rendered beside the first: it is the same `<ol>`, the same `<li>` and the
+ * same spine, with the track count and the spine's axis changed by utility
+ * classes at `md`. Two trees would have meant the history twice in the
+ * accessibility tree and twice for a crawler, and a reader who resized the window
+ * would have watched one copy of the section swap for the other. The cost of one
+ * tree is that the last milestone's rule is dropped on the vertical form and kept
+ * on the horizontal one, because a horizontal rail that stopped one column early
+ * reads as a rail that ran out.
+ *
+ * A milestone's title is a heading one step below the section, derived rather
+ * than written, so a Block embedded one level deeper carries its headings with
+ * it. A `body` that runs past four lines stops being a milestone body, and the
+ * detail belongs above the rail in `description` or in the `media` figure beside
+ * it.
+ *
+ * It is a server Component: no hook, no state and no client code.
+ */
+export declare function Story01({ eyebrow, title, description, milestones, orient, headingLevel, className, }: Story01Props): import("react").JSX.Element;
+export default Story01;
+//# sourceMappingURL=story.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../../src/blocks/story-01/story.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAGpG;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAA;IACV,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAA;IACV,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,IAAI,EAAE,SAAS,CAAA;IACf,oDAAoD;IACpD,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAcD;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,UAAU,EAAE,cAAc,EAAE,CAAA;IAC5B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,YAAY,CAAA;IAClC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,wBAAgB,OAAO,CAAC,EACtB,OAAO,EACP,KAAK,EACL,WAAW,EACX,UAAU,EACV,MAAmB,EACnB,YAAmB,EACnB,SAAS,GACV,EAAE,YAAY,+BA+Fd;AAED,eAAe,OAAO,CAAA"}

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

@@ -0,0 +1,103 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Section, SectionHeading, childLevel } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The tracks a horizontal rail gets, once the reader has stopped being on a
+ * phone.
+ *
+ * Two steps rather than a count, because the count is the caller's and a
+ * horizontal rail of eight milestones is eight cards and no reader reads eight
+ * cards. Two across at the width where the rail appears and three across at the
+ * width of the container, so a five-milestone history reads as three and then
+ * two, which is a shape rather than an orphan.
+ */
+const HORIZONTAL_TRACKS = 'md:grid-cols-2 lg:grid-cols-3';
+/**
+ * A company's history as a reader walks it: a date, a title, what changed, and
+ * an optional figure, along a rail with a rule down one side.
+ *
+ * **It is a Block and not a component, and the difference is the subject.**
+ * `Timeline` draws a run's progress as it happens: it is fed events, it has four
+ * states, it scales durations against the longest step in the run, and one of its
+ * states moves. This arranges a sequence that has already finished, in a section
+ * that has content under its heading, and none of that machinery applies to it. A
+ * company history has no run state and no durations, and a reader who met a
+ * `Timeline` on an about page would be told a thing about the product is live and
+ * is not. So the two are different subjects, they compose as different things, and
+ * this is a section of a page rather than a shape inside one.
+ *
+ * **The NaniSoft framing is in this JSDoc and in the Demo, and nowhere in the
+ * Block.** The history these pages tell is the history of a pipeline that came to
+ * run, a market that came to be captured rather than reconstructed, an estate that
+ * came to be observed instead of visited, and work that came to be done by agents
+ * rather than filed for a person to pick up. Those are four claims, and every one
+ * of them is a `body` and a `title` at the call site. A Block that shipped them as
+ * strings would install one company's history into every consumer's page, so what
+ * travels is the shape: a date, a name, what changed, and a figure with a caption
+ * somebody had to write.
+ *
+ * **One `<ol>`, and the rail is not a second list.** A history that was drawn as
+ * a row per milestone group would be several lists, and a screen reader would
+ * announce it as three lists rather than one sequence. The milestones are one
+ * ordered list, the rail is a decorative span inside each entry, and it is marked
+ * `aria-hidden` so the sequence is read from the entries and not from a rule. The
+ * rule is what a sighted reader uses to see continuity; the order is what every
+ * other reader uses, and it comes from the element rather than from the drawing.
+ *
+ * **The dot is on the rail and the rail is behind it, which is what makes the
+ * vertical form read as one line rather than as a stack of rules.** The spine is
+ * drawn from the dot to the bottom of its own entry, so the last entry draws no
+ * spine and the line stops at the last dot instead of trailing past the end. That
+ * is the detail that separates a rail from a border, and it is the same detail
+ * `Timeline` states for its own spine.
+ *
+ * **The horizontal form is the one to watch, and the breakpoint is this Block's
+ * decision.** A five-milestone horizontal rail on a phone is five columns of
+ * unreadable text, so below `md` the horizontal form is the vertical form. The
+ * alternative was a prop for the width at which the rail turns, and it was
+ * refused: a consumer that set it too low would ship five columns of unreadable
+ * text, and a consumer that set it too high would get a vertical rail on a
+ * laptop. The honest answer is one breakpoint, made once, in the place that owns
+ * the layout.
+ *
+ * **Both forms are one set of elements.** The horizontal form is not a second
+ * tree rendered beside the first: it is the same `<ol>`, the same `<li>` and the
+ * same spine, with the track count and the spine's axis changed by utility
+ * classes at `md`. Two trees would have meant the history twice in the
+ * accessibility tree and twice for a crawler, and a reader who resized the window
+ * would have watched one copy of the section swap for the other. The cost of one
+ * tree is that the last milestone's rule is dropped on the vertical form and kept
+ * on the horizontal one, because a horizontal rail that stopped one column early
+ * reads as a rail that ran out.
+ *
+ * A milestone's title is a heading one step below the section, derived rather
+ * than written, so a Block embedded one level deeper carries its headings with
+ * it. A `body` that runs past four lines stops being a milestone body, and the
+ * detail belongs above the rail in `description` or in the `media` figure beside
+ * it.
+ *
+ * It is a server Component: no hook, no state and no client code.
+ */
+export function Story01({ eyebrow, title, description, milestones, orient = 'vertical', headingLevel = 'h2', className, }) {
+    // A milestone title is a heading one step below the section that introduces the
+    // sequence, so a reader navigating by heading meets the history under the
+    // section that introduces it rather than as a set of its siblings.
+    const Title = childLevel(headingLevel);
+    const horizontal = orient === 'horizontal';
+    return (_jsxs(Section, { children: [title ? (_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-12" })) : null, _jsx("ol", { "data-slot": "story-01-rail", "data-orient": orient, className: cn('grid gap-x-8', horizontal && HORIZONTAL_TRACKS, className), children: milestones.map((milestone, index) => {
+                    const isLast = index === milestones.length - 1;
+                    return (_jsxs("li", { "data-slot": "story-01-milestone", className: cn(
+                        // One set of elements for both forms. Below the breakpoint the
+                        // marker is a narrow first track beside the text and the spine
+                        // runs down it; at and above it the marker track becomes a full
+                        // row above the text and the spine runs across it, which is a
+                        // rail the reader reads left to right.
+                        'grid grid-cols-[auto_minmax(0,1fr)] gap-x-4', horizontal && 'md:grid-cols-1 md:gap-x-0 md:gap-y-3'), children: [_jsxs("div", { "data-slot": "story-01-track", "aria-hidden": true, className: cn('flex flex-col items-center', horizontal && 'md:flex-row md:items-center md:gap-2'), children: [_jsx("span", { "data-slot": "story-01-marker", className: "bg-primary mt-2 size-2.5 shrink-0 rounded-full" }), _jsx("span", { "data-slot": "story-01-spine", className: cn('bg-border w-px flex-1', 
+                                        // The last entry has nothing under it on the vertical form, so
+                                        // its rule is dropped rather than trailing past the end of the
+                                        // history. The horizontal form keeps it, because a rail that
+                                        // stopped one column short reads as a rail that ran out.
+                                        isLast && 'md:hidden', horizontal && 'md:h-px md:w-auto') })] }), _jsxs("div", { "data-slot": "story-01-body", className: "flex min-w-0 flex-col gap-3 pb-10 last:pb-0 md:pb-0", children: [_jsx("span", { "data-slot": "story-01-at", className: "text-muted-foreground font-mono text-xs", children: milestone.at }), _jsx(Title, { className: "text-lg tracking-tight", children: milestone.title }), _jsx("p", { className: "text-muted-foreground text-pretty text-sm", children: milestone.body }), milestone.media ? (_jsxs("figure", { "data-slot": "story-01-media", className: "mt-1 flex flex-col gap-2", children: [milestone.media, milestone.mediaLabel ? (_jsx("figcaption", { className: "text-muted-foreground text-xs", children: milestone.mediaLabel })) : null] })) : null] })] }, milestone.id));
+                }) })] }));
+}
+export default Story01;

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

@@ -0,0 +1,3 @@
+export { Summary01, default } from './summary.js';
+export type { Summary01Props, SummaryCell, SummaryColumn, SummaryLine, SummaryLineState, } from './summary.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/summary-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAO9C,YAAY,EACV,cAAc,EACd,WAAW,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,GACjB,MAAM,WAAW,CAAA"}

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

@@ -0,0 +1 @@
+export { Summary01, default } from './summary.js';