@nanisoft/prism-ui 0.13.0 → 0.16.0

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

@@ -0,0 +1,255 @@
+import { type ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * The seven things a retention row can say, and the cell each one draws.
+ *
+ * A closed set, and the closure is the point, for the reason
+ * `ResourceListCell` gives: the cells are the Block's, so a column naming a
+ * seventh would be a column with nothing to put in it. The names above them are the
+ * caller's, which is the other half of the same thing. A compliance surface has one
+ * column whose name is genuinely worth arguing over, the period column, and a
+ * product that calls it "Retention" and a product that calls it "How long we keep
+ * it" are both right, and a product that calls the same column "TTL" has meant
+ * something slightly different by it.
+ *
+ * The last-review cell is `last-reviewed` and the row field it draws is
+ * `reviewedAt`, and the two names are not the same on purpose. The cell id is a
+ * machine name that travels through a union and through markup, and a machine name
+ * in this package is lowercase; the field is the caller's data and keeps the
+ * spelling a reader of their own code expects.
+ */
+export type RetentionColumnId = 'subject' | 'kind' | 'period' | 'region' | 'policy' | 'last-reviewed' | 'href';
+/**
+ * One column of a retention schedule, and the words above it.
+ *
+ * A cell id rather than a renderer, for the reason the closure above gives: the
+ * cells are the Block's so that the schedule reads the same in every consumer, and
+ * only the words travel. A column that took a renderer would be a table the
+ * consumer drew, and this Item would be a bordered `div`.
+ */
+export type RetentionColumn = {
+    /** Which cell the column draws. */
+    id: RetentionColumnId;
+    /** The heading above the column. */
+    header: ReactNode;
+    /** Layout only: a width, or an alignment. */
+    className?: string;
+};
+/**
+ * One thing that is kept, for how long, where, and under which policy.
+ *
+ * Every word in every field here is a representation the caller makes to a
+ * regulator, to a customer or to an auditor, and Prism composes none of them. See
+ * the Block's JSDoc for why that sentence is load-bearing on this surface rather
+ * than a formality.
+ */
+export type RetentionRow = {
+    /** A stable key for the row, and carried on the markup as `data-retention`. */
+    id: string;
+    /**
+     * What is kept, in the publisher's own words.
+     *
+     * The anchor of the row and the row header the table announces with it. It is the
+     * phrase a reader checks against the sentence beside it, so it is not shortened,
+     * softened or rewritten here.
+     */
+    subject: string;
+    /**
+     * The kind of thing: a category that groups the subjects, such as the records a
+     * category of data lives in.
+     *
+     * Optional, and its absence is meaningful rather than a gap: a subject with no
+     * kind is a subject the publisher has chosen not to categorise, which is itself a
+     * statement and not a formatting gap.
+     */
+    kind?: string;
+    /**
+     * How long it is kept, as a number of days and nothing else.
+     *
+     * A `number` rather than a sentence, and the argument is the whole of the Block's
+     * JSDoc: the sentence is `periodLabel`, and a Block that printed one of the three
+     * English forms would be asserting a retention period nobody agreed to.
+     */
+    period?: number;
+    /**
+     * The words for the period, given the number of days.
+     *
+     * Required, and a function because the sentence is the caller's. "30 days", "one
+     * month" and "a month" are three sentences, and a compliance surface that printed
+     * one of them in English would be asserting a period the reader never agreed to,
+     * which is the one thing a retention schedule exists not to do.
+     */
+    periodLabel: (period: number) => string;
+    /**
+     * Where the data is kept, in the publisher's own terms.
+     *
+     * Optional, and a compliance surface with no region is a claim about everywhere,
+     * which is a stronger claim than any publisher can usually support, so the Block
+     * does not write one for them.
+     */
+    region?: string;
+    /** The policy the period comes from, named so a reader can go and read it. */
+    policy?: string;
+    /**
+     * When the schedule was last reviewed, already written as it should be read.
+     *
+     * A moment rather than a reading, and the reading is `reviewedAtLabel`. The Block
+     * prints the value exactly as passed when no formatter is given, which is the
+     * arrangement `compliance-01` and `member-list-01` both take.
+     */
+    reviewedAt?: number | string;
+    /** The words for the review, given the moment. A function because the honest reading is a sentence. */
+    reviewedAtLabel?: (value: number | string) => string;
+    /** Where the policy is read in full, rendered as a native anchor. */
+    href?: string;
+    /**
+     * The words on that link. Required whenever `href` is set, and a thrown diagnostic
+     * rather than a silent absence: a link announced by its address is punctuation
+     * rather than a name.
+     */
+    hrefLabel?: string;
+};
+/**
+ * One figure about the schedule as a whole, and the words under it.
+ *
+ * A node for the value and a string for the label, which is `metric`'s own split
+ * and the reason it is composed here rather than being drawn: a figure in a
+ * compliance summary is a number the publisher has already formatted, in a unit
+ * only the publisher knows, and a Block that printed a bare numeral would be
+ * claiming the unit.
+ */
+export type RetentionSummary = {
+    /** What the figure measures, read under it. */
+    label: string;
+    /** The figure, already in the publisher's own units. */
+    value: ReactNode;
+};
+/**
+ * The props a Retention01 takes.
+ *
+ * Every string is a prop and the Block ships none. There is no schedule, no
+ * subject, no period, no region, no policy, no review reading, no link name and not
+ * one of the three sentences a retention period can be written as. A retention
+ * schedule is a set of representations made to regulators, to customers and to
+ * auditors, and a design system that contributed a word to one of them would be
+ * publishing a representation it has no standing to make.
+ */
+export type Retention01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: ReactNode;
+    /**
+     * The section title, required.
+     *
+     * Required because this is the one surface in the system where an unlabelled
+     * table of retentions is a defect rather than a layout: a schedule with no
+     * statement of whose it is reads as a document nobody issued.
+     */
+    title: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /** The column names, in the order a reader should meet them. */
+    columns: readonly RetentionColumn[];
+    /** The rows, in the order a reader should meet them. The Block does not sort. */
+    rows: readonly RetentionRow[];
+    /**
+     * The figures about the schedule as a whole.
+     *
+     * Drawn as the table's own summary row, so they travel with the table in the
+     * accessibility tree rather than sitting in a band below it that a reader
+     * navigating the table never meets.
+     */
+    summary?: readonly RetentionSummary[];
+    /**
+     * What the surface shows when there are no rows.
+     *
+     * Required, and the reason is the one `compliance-01` states against itself: a
+     * retention schedule with a heading and no rows says the publisher retains
+     * nothing, and hiding the section would leave a reader wondering whether it was
+     * missed. The sentence is the caller's because only the caller knows whether the
+     * answer is "we keep nothing" or "this has not been written yet".
+     */
+    empty: ReactNode;
+    /** Heading level for the section title. @defaultValue 'h2' */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Block. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A retention schedule: what is kept, for how long, in which region, under which
+ * policy, and when it was last reviewed, as a real table with a summary row.
+ *
+ * **Every word in every cell is the publisher's own representation, and on this
+ * surface that is not a formality.** A retention schedule is a document made to
+ * regulators, to customers and to auditors, and a design system that contributed a
+ * single word to one of them would be publishing a representation it has no
+ * standing to make. There is no schedule here, no subject, no region, no policy and
+ * not one of the three sentences a retention period can be written as. The cost is
+ * real and worth stating: a consumer wiring this Block up writes every label
+ * themselves, and a half-built schedule is a build error rather than a page that
+ * ships six confident numbers.
+ *
+ * **`period` is a number of days and the sentence is the caller's, and the reason
+ * is that a Block cannot know which sentence is right.** "30 days", "one month" and
+ * "a month" are three sentences for the same number, and they are not variants of
+ * one another. The first is a measurement and it is the one a regulator will check
+ * against a system configuration. The second is a rounding of that measurement to
+ * a calendar unit, and it is a different promise, because thirty days is not a
+ * month and a reader who is told "one month" and is then deleted from on the
+ * thirty-first day has been told something the schedule did not say. The third is
+ * the same promise as the second with the article left off, which matters because
+ * a period is a noun phrase in one column and a verb phrase in a table caption. So
+ * the Block holds the number and hands back the sentence, and a compliance surface
+ * that printed one of the three in English would be asserting a retention period
+ * the reader never agreed to, which is the one thing this table exists not to do.
+ * The same argument is why the function is on the row rather than on the Block: the
+ * sentence may be per product, per row, or per language, and none of those is a
+ * fact this package can hold.
+ *
+ * **It is a real table, for the same reason `compliance-01` is one.** A schedule
+ * is read down the subject column and across the period, region and policy columns,
+ * and the reader's question is almost always a comparison: is this kept longer than
+ * that, is it in the same place, is it under the same policy. A reader using a
+ * screen reader navigates a table by asking for a column and hearing its heading,
+ * and this is the table where a header the reader cannot ask for is a cell they
+ * cannot place. The cost of the table is the one every real table carries:
+ * `Table` wraps the whole thing in a horizontally scrollable container, because
+ * seven columns do not fit a phone, and a schedule that reflowed into a stack would
+ * no longer be comparable.
+ *
+ * **The subject is the row header, so the table announces it with every cell.** The
+ * subject cell is a `th` with `scope="row"`, which is what lets a screen reader say
+ * which subject each period, region and policy belongs to. The row header and the
+ * cells carry `whitespace-normal`, because `TableHead` and `TableCell` set
+ * `whitespace-nowrap` and that is right for a figure in a data grid and wrong for a
+ * phrase that is a representation. That is the one place in this Block where a
+ * `className` changes a Prism-owned property rather than placing something, and it
+ * is stated here rather than left to be discovered.
+ *
+ * **The summary is the table's own row, and its figures are `metric`s.** Drawing
+ * the figures with the same Component every other figure in this package uses is
+ * the small half of the decision. The large half is the placement: the summary is
+ * a `tfoot`, so it is inside the table and travels with it, rather than a band of
+ * figures below the table that a reader navigating the table never meets and a
+ * crawler reads as unrelated to the rows above it. Each figure takes a node for its
+ * value, because the number is the publisher's and is usually in a unit only the
+ * publisher knows, and a Block that printed a bare numeral next to the word
+ * "records" would be claiming the unit.
+ *
+ * **An empty schedule renders the table with no rows and the caller's sentence,
+ * which is the opposite of the rule every other Block in this package follows, and
+ * deliberately so.** A retention schedule with a heading and no rows says the
+ * publisher retains nothing, and hiding the section would leave a reader wondering
+ * whether it was missed. The cost is that a heading can survive on a page whose
+ * schedule has been withdrawn, so a consumer who would rather see nothing should
+ * not render the Block. That is the honest trade and it is the one `compliance-01`
+ * takes for the same reason.
+ *
+ * It is a server Component: no hook, no state, no client code and no router. The
+ * values are printed exactly as passed and the arithmetic is the caller's.
+ */
+export declare function Retention01({ eyebrow, title, description, columns, rows, summary, empty, headingLevel, className, }: Retention01Props): import("react").JSX.Element;
+export default Retention01;
+//# sourceMappingURL=retention.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../../../src/blocks/retention-01/retention.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAG7C,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAYxF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,eAAe,GACf,MAAM,CAAA;AAEV;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,mCAAmC;IACnC,EAAE,EAAE,iBAAiB,CAAA;IACrB,oCAAoC;IACpC,MAAM,EAAE,SAAS,CAAA;IACjB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,+EAA+E;IAC/E,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;OAOG;IACH,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAA;IACvC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC5B,uGAAuG;IACvG,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,KAAK,MAAM,CAAA;IACpD,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAA;IACb,wDAAwD;IACxD,KAAK,EAAE,SAAS,CAAA;CACjB,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,gEAAgE;IAChE,OAAO,EAAE,SAAS,eAAe,EAAE,CAAA;IACnC,iFAAiF;IACjF,IAAI,EAAE,SAAS,YAAY,EAAE,CAAA;IAC7B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAErC;;;;;;;;OAQG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AA6CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,KAAK,EACL,WAAW,EACX,OAAO,EACP,IAAI,EACJ,OAAO,EACP,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,gBAAgB,+BAmMlB;AAED,eAAe,WAAW,CAAA"}

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

@@ -0,0 +1,145 @@
+import { jsx as _jsx, jsxs as _jsxs } 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, TableFooter, TableHead, TableHeader, TableRow, } from '../../components/ui/table.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The two refusals, so that a compliance surface never renders a cell it cannot
+ * justify.
+ *
+ * A column naming a cell this Block does not draw, and a link with no name. Both
+ * are a caller's mistake rather than a request, so both throw in a console rather
+ * than rendering the quiet version of themselves.
+ */
+function assertProps(props) {
+    const known = [
+        'subject',
+        'kind',
+        'period',
+        'region',
+        'policy',
+        'last-reviewed',
+        'href',
+    ];
+    for (const column of props.columns) {
+        if (!known.includes(column.id)) {
+            throw new Error(`Retention01: a column names the cell ${JSON.stringify(column.id)}, which is not one of the seven ` +
+                'cells this schedule can draw. A column with nothing to put in it is a column a reader counts past, ' +
+                'so add the cell rather than the heading.');
+        }
+    }
+    for (const row of props.rows) {
+        if (row.href !== undefined && (row.hrefLabel === undefined || row.hrefLabel.trim() === '')) {
+            throw new Error(`Retention01: the row ${JSON.stringify(row.subject)} carries an href with no hrefLabel, so the link ` +
+                'would be announced by its address, which is punctuation rather than a name. Pass the words that say ' +
+                'which document it is.');
+        }
+    }
+}
+/**
+ * A retention schedule: what is kept, for how long, in which region, under which
+ * policy, and when it was last reviewed, as a real table with a summary row.
+ *
+ * **Every word in every cell is the publisher's own representation, and on this
+ * surface that is not a formality.** A retention schedule is a document made to
+ * regulators, to customers and to auditors, and a design system that contributed a
+ * single word to one of them would be publishing a representation it has no
+ * standing to make. There is no schedule here, no subject, no region, no policy and
+ * not one of the three sentences a retention period can be written as. The cost is
+ * real and worth stating: a consumer wiring this Block up writes every label
+ * themselves, and a half-built schedule is a build error rather than a page that
+ * ships six confident numbers.
+ *
+ * **`period` is a number of days and the sentence is the caller's, and the reason
+ * is that a Block cannot know which sentence is right.** "30 days", "one month" and
+ * "a month" are three sentences for the same number, and they are not variants of
+ * one another. The first is a measurement and it is the one a regulator will check
+ * against a system configuration. The second is a rounding of that measurement to
+ * a calendar unit, and it is a different promise, because thirty days is not a
+ * month and a reader who is told "one month" and is then deleted from on the
+ * thirty-first day has been told something the schedule did not say. The third is
+ * the same promise as the second with the article left off, which matters because
+ * a period is a noun phrase in one column and a verb phrase in a table caption. So
+ * the Block holds the number and hands back the sentence, and a compliance surface
+ * that printed one of the three in English would be asserting a retention period
+ * the reader never agreed to, which is the one thing this table exists not to do.
+ * The same argument is why the function is on the row rather than on the Block: the
+ * sentence may be per product, per row, or per language, and none of those is a
+ * fact this package can hold.
+ *
+ * **It is a real table, for the same reason `compliance-01` is one.** A schedule
+ * is read down the subject column and across the period, region and policy columns,
+ * and the reader's question is almost always a comparison: is this kept longer than
+ * that, is it in the same place, is it under the same policy. A reader using a
+ * screen reader navigates a table by asking for a column and hearing its heading,
+ * and this is the table where a header the reader cannot ask for is a cell they
+ * cannot place. The cost of the table is the one every real table carries:
+ * `Table` wraps the whole thing in a horizontally scrollable container, because
+ * seven columns do not fit a phone, and a schedule that reflowed into a stack would
+ * no longer be comparable.
+ *
+ * **The subject is the row header, so the table announces it with every cell.** The
+ * subject cell is a `th` with `scope="row"`, which is what lets a screen reader say
+ * which subject each period, region and policy belongs to. The row header and the
+ * cells carry `whitespace-normal`, because `TableHead` and `TableCell` set
+ * `whitespace-nowrap` and that is right for a figure in a data grid and wrong for a
+ * phrase that is a representation. That is the one place in this Block where a
+ * `className` changes a Prism-owned property rather than placing something, and it
+ * is stated here rather than left to be discovered.
+ *
+ * **The summary is the table's own row, and its figures are `metric`s.** Drawing
+ * the figures with the same Component every other figure in this package uses is
+ * the small half of the decision. The large half is the placement: the summary is
+ * a `tfoot`, so it is inside the table and travels with it, rather than a band of
+ * figures below the table that a reader navigating the table never meets and a
+ * crawler reads as unrelated to the rows above it. Each figure takes a node for its
+ * value, because the number is the publisher's and is usually in a unit only the
+ * publisher knows, and a Block that printed a bare numeral next to the word
+ * "records" would be claiming the unit.
+ *
+ * **An empty schedule renders the table with no rows and the caller's sentence,
+ * which is the opposite of the rule every other Block in this package follows, and
+ * deliberately so.** A retention schedule with a heading and no rows says the
+ * publisher retains nothing, and hiding the section would leave a reader wondering
+ * whether it was missed. The cost is that a heading can survive on a page whose
+ * schedule has been withdrawn, so a consumer who would rather see nothing should
+ * not render the Block. That is the honest trade and it is the one `compliance-01`
+ * takes for the same reason.
+ *
+ * It is a server Component: no hook, no state, no client code and no router. The
+ * values are printed exactly as passed and the arithmetic is the caller's.
+ */
+export function Retention01({ eyebrow, title, description, columns, rows, summary, empty, headingLevel = 'h2', className, }) {
+    // The handle a table below takes its name from; see the note on the table.
+    const headingId = useId();
+    assertProps({ columns, rows });
+    return (_jsxs(Section, { className: className, "data-slot": "retention", children: [_jsx(SectionHeading, { as: headingLevel, id: headingId, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-10" }), _jsx("div", { "data-slot": "retention-table", className: "flex flex-col gap-4", children: _jsx("div", { className: "border-border overflow-hidden rounded-xl border", children: _jsxs(Table, { "aria-labelledby": headingId, children: [_jsx(TableHeader, { children: _jsx(TableRow, { children: columns.map((column) => (_jsx(TableHead, { scope: "col", "data-column": column.id, className: cn('whitespace-normal', column.className), children: column.header }, column.id))) }) }), _jsx(TableBody, { children: rows.length === 0 ? (_jsx(TableRow, { "data-slot": "retention-empty", children: _jsx(TableCell, { colSpan: Math.max(columns.length, 1), className: "text-muted-foreground whitespace-normal", children: empty }) })) : (rows.map((row) => (_jsx(TableRow, { "data-slot": "retention-row", "data-retention": row.id, children: columns.map((column) => {
+                                        if (column.id === 'subject') {
+                                            return (_jsx(TableHead, { scope: "row", "data-column": column.id, className: cn('text-foreground h-auto whitespace-normal font-medium', column.className), children: row.subject }, column.id));
+                                        }
+                                        if (column.id === 'kind') {
+                                            return (_jsx(TableCell, { "data-column": column.id, className: cn('whitespace-normal', column.className), children: row.kind ?? null }, column.id));
+                                        }
+                                        if (column.id === 'period') {
+                                            return (_jsx(TableCell, { "data-column": column.id, className: cn('whitespace-normal', column.className), children: row.period === undefined
+                                                    ? null
+                                                    : row.periodLabel(row.period) }, column.id));
+                                        }
+                                        if (column.id === 'region') {
+                                            return (_jsx(TableCell, { "data-column": column.id, className: cn('whitespace-normal', column.className), children: row.region ?? null }, column.id));
+                                        }
+                                        if (column.id === 'policy') {
+                                            return (_jsx(TableCell, { "data-column": column.id, className: cn('whitespace-normal', column.className), children: row.policy ?? null }, column.id));
+                                        }
+                                        if (column.id === 'last-reviewed') {
+                                            return (_jsx(TableCell, { "data-column": column.id, className: cn('whitespace-normal tabular-nums', column.className), children: row.reviewedAt === undefined
+                                                    ? null
+                                                    : row.reviewedAtLabel === undefined
+                                                        ? row.reviewedAt
+                                                        : row.reviewedAtLabel(row.reviewedAt) }, column.id));
+                                        }
+                                        return (_jsx(TableCell, { "data-column": column.id, className: cn('whitespace-normal', column.className), children: row.href === undefined ? null : (_jsx("a", { "data-slot": "retention-href", href: row.href, className: "text-foreground focus-visible:ring-ring rounded-sm underline underline-offset-4 transition-colors duration-fast ease-out focus-visible:ring-[3px] focus-visible:outline-none", children: row.hrefLabel })) }, column.id));
+                                    }) }, row.id)))) }), summary === undefined || summary.length === 0 ? null : (_jsx(TableFooter, { children: _jsx(TableRow, { "data-slot": "retention-summary", children: _jsx(TableCell, { colSpan: Math.max(columns.length, 1), className: "whitespace-normal", children: _jsx("span", { className: "flex flex-wrap items-start gap-x-10 gap-y-4", children: summary.map((figure) => (_jsx(Metric, { "data-slot": "retention-summary-figure", value: figure.value, label: figure.label, className: "min-w-32" }, figure.label))) }) }) }) }))] }) }) })] }));
+}
+export default Retention01;

package/dist/blocks/run-console-01/run-console.d.ts

@@ -1,3 +1,4 @@
+import { type HeadingLevel } from '../../components/ui/section.js';
 import { type TimelineEntry } from '../../components/ui/timeline.js';
 /**
  * The words the Block does not have.
@@ -69,6 +70,18 @@ export interface RunConsole01Props {
      * caller knows whether the transport has finished.
      */
     streaming?: boolean;
+    /**
+     * Heading level for the run's heading. @defaultValue 'h2'
+     *
+     * A prop for the reason every Block's is: the surrounding document decides where
+     * this lands in the outline, not the Block. The heading was a hard-coded `<h2>`,
+     * which is right at the top of a page and wrong anywhere else, because a run
+     * console is a panel a product opens beside something. Three Blocks in this
+     * package held that level and `SiteFooter` and `DataTable01` already take this
+     * prop, so this is the fourth name being spelled the same way rather than a new
+     * convention.
+     */
+    headingLevel?: HeadingLevel;
     /** Layout only. */
     className?: string;
 }
@@ -106,6 +119,6 @@ export interface RunConsole01Props {
  * a blank frame in that moment reads as a broken surface rather than as a run that
  * has not started.
  */
-export declare function RunConsole01({ title, copy, steps, budget, detail, streaming, className, }: RunConsole01Props): import("react").JSX.Element;
+export declare function RunConsole01({ title, copy, steps, budget, detail, streaming, headingLevel, className, }: RunConsole01Props): import("react").JSX.Element;
 export default RunConsole01;
 //# sourceMappingURL=run-console.d.ts.map

package/dist/blocks/run-console-01/run-console.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-console.d.ts","sourceRoot":"","sources":["../../../src/blocks/run-console-01/run-console.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,8BAA8B,CAAA;AAG3E;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAA;IACnB,0EAA0E;IAC1E,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAA;IACnD,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAA;IAClB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,0CAA0C;IAC1C,IAAI,EAAE,gBAAgB,CAAA;IACtB,oDAAoD;IACpD,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;IAC/B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE;QACP,2BAA2B;QAC3B,KAAK,EAAE,MAAM,CAAA;QACb,mBAAmB;QACnB,GAAG,EAAE,MAAM,CAAA;QACX,2EAA2E;QAC3E,UAAU,CAAC,EAAE,SAAS;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAA;SAAE,EAAE,CAAA;KAChG,CAAA;IACD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,IAAI,EACJ,KAAK,EACL,MAAM,EACN,MAAM,EACN,SAAiB,EACjB,SAAS,GACV,EAAE,iBAAiB,+BAgFnB;AAED,eAAe,YAAY,CAAA"}
+{"version":3,"file":"run-console.d.ts","sourceRoot":"","sources":["../../../src/blocks/run-console-01/run-console.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AACjF,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,8BAA8B,CAAA;AAG3E;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAA;IACnB,0EAA0E;IAC1E,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAA;IACnD,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAA;IAClB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,0CAA0C;IAC1C,IAAI,EAAE,gBAAgB,CAAA;IACtB,oDAAoD;IACpD,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;IAC/B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE;QACP,2BAA2B;QAC3B,KAAK,EAAE,MAAM,CAAA;QACb,mBAAmB;QACnB,GAAG,EAAE,MAAM,CAAA;QACX,2EAA2E;QAC3E,UAAU,CAAC,EAAE,SAAS;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAA;SAAE,EAAE,CAAA;KAChG,CAAA;IACD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,IAAI,EACJ,KAAK,EACL,MAAM,EACN,MAAM,EACN,SAAiB,EACjB,YAAmB,EACnB,SAAS,GACV,EAAE,iBAAiB,+BAkGnB;AAED,eAAe,YAAY,CAAA"}

package/dist/blocks/run-console-01/run-console.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { LiveRegion } from '../../components/ui/live-region.js';
 import { Meter } from '../../components/ui/meter.js';
+import { headingSizeClass } from '../../components/ui/section.js';
 import { Timeline } from '../../components/ui/timeline.js';
 import { cn } from '../../lib/utils.js';
 /**
@@ -37,12 +38,13 @@ import { cn } from '../../lib/utils.js';
  * a blank frame in that moment reads as a broken surface rather than as a run that
  * has not started.
  */
-export function RunConsole01({ title, copy, steps, budget, detail, streaming = false, className, }) {
+export function RunConsole01({ title, copy, steps, budget, detail, streaming = false, headingLevel = 'h2', className, }) {
     const waiting = steps.length === 0;
+    const Heading = headingLevel;
     // Built once and placed in one of two places, so the streaming and the finished
     // rendering cannot drift apart. Two copies of this markup would be two answers
     // to what a run looks like, and the second one is the one that goes stale.
     const body = waiting ? (_jsx("p", { "data-slot": "run-console-01-waiting", className: "text-muted-foreground text-sm", children: copy.waiting })) : (_jsx(Timeline, { entries: steps, label: copy.stepsLabel, empty: copy.waiting }));
-    return (_jsxs("div", { "data-slot": "run-console-01", className: cn('border-border bg-card flex flex-col gap-6 rounded-lg border p-5', className), children: [_jsxs("header", { "data-slot": "run-console-01-header", className: "flex flex-col gap-1", children: [_jsx("h2", { className: "text-foreground text-base font-semibold tracking-tight", children: title }), detail === undefined ? null : (_jsx("p", { className: "text-muted-foreground text-sm", children: detail }))] }), budget === undefined ? null : (_jsx("div", { "data-slot": "run-console-01-budget", children: _jsx(Meter, { value: budget.value, max: budget.max, label: copy.budgetLabel, valueText: copy.budgetValue(budget.value, budget.max), thresholds: budget.thresholds, children: _jsx("span", { children: copy.budgetValue(budget.value, budget.max) }) }) })), streaming ? (_jsx(LiveRegion, { busy: true, label: copy.stepsLabel, className: "min-w-0", children: body })) : (body)] }));
+    return (_jsxs("div", { "data-slot": "run-console-01", className: cn('border-border bg-card flex flex-col gap-6 rounded-lg border p-5', className), children: [_jsxs("header", { "data-slot": "run-console-01-header", className: "flex flex-col gap-1", children: [_jsx(Heading, { className: cn('text-foreground font-semibold tracking-tight text-balance', headingSizeClass(headingLevel)), children: title }), detail === undefined ? null : (_jsx("p", { className: "text-muted-foreground text-sm", children: detail }))] }), budget === undefined ? null : (_jsx("div", { "data-slot": "run-console-01-budget", children: _jsx(Meter, { value: budget.value, max: budget.max, label: copy.budgetLabel, valueText: copy.budgetValue(budget.value, budget.max), thresholds: budget.thresholds, children: _jsx("span", { children: copy.budgetValue(budget.value, budget.max) }) }) })), streaming ? (_jsx(LiveRegion, { busy: true, label: copy.stepsLabel, className: "min-w-0", children: body })) : (body)] }));
 }
 export default RunConsole01;

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

@@ -0,0 +1,3 @@
+export { Services01, default } from './services.js';
+export type { Services01Props, Service, ServiceLink } from './services.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/services-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAMhD,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

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

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

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

@@ -0,0 +1,159 @@
+import type { ReactNode } from 'react';
+import type { LucideIcon } from 'lucide-react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * The link arm and the no-link arm of one engagement, as a union.
+ *
+ * The same agreement `CaseStudies01`, `Careers01` and `Industries01` make, for the
+ * same reason: the words that say what following a link does are a claim about
+ * the destination, so they belong to whoever wrote it.
+ */
+export type ServiceLink = {
+    /** Where the engagement's own page is. Present makes the card carry a link. */
+    href: string;
+    /** The words on the link, and what following it does. */
+    hrefLabel: string;
+    /** Opens the destination in a new browsing context, with the matching `rel`. */
+    newTab?: boolean;
+} | {
+    href?: never;
+    hrefLabel?: never;
+    newTab?: never;
+};
+/**
+ * One engagement or capability: what it is called, what it does, what the reader
+ * gets, and what it is for.
+ *
+ * `deliverables` is a `string[]` and not a node, and the reason is that a
+ * deliverables list is a set of short noun phrases the reader is checking off
+ * against their own situation. A node would let a caller put a paragraph in one
+ * entry, and one paragraph in a five-item list is a list the reader stops
+ * scanning. The order is the caller's because it is a claim about what arrives
+ * first, and an empty array renders nothing at all rather than an empty heading
+ * and an empty list.
+ *
+ * `outcome` is separate from `body` for the same reason the deliverables are
+ * separate: a body says what the work is and an outcome says what came of it, and
+ * a reader comparing two engagements needs the second without reading past the
+ * first. `icon` is optional and additive, and a card that reserves room for a mark
+ * that is not there is a hole.
+ */
+export type Service = {
+    /** A stable key for the engagement. */
+    id: string;
+    /** What the engagement is called. */
+    title: string;
+    /** What the work is, in a few sentences. */
+    body: ReactNode;
+    /** What the reader gets, as short noun phrases. Omit it, or pass an empty array. */
+    deliverables?: string[];
+    /** What it is for, stated as an effect rather than as a feature. */
+    outcome?: ReactNode;
+    /** The engagement's mark, from the icon set this system uses. */
+    icon?: LucideIcon;
+} & ServiceLink;
+/**
+ * The props a Services01 takes.
+ *
+ * Every string, every deliverable and every outcome is a prop and the Block ships
+ * none: no engagement, no ordinal, no deliverable and no default set of services.
+ * A list that hardcoded its engagements would hand every consumer a menu of
+ * somebody else's work.
+ */
+export type Services01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /** The section title. Omit it for a set composed under its own heading. */
+    title?: string;
+    /** One or two sentences under the title. */
+    description?: string;
+    /**
+     * The engagements, in the order a reader should meet them. Order is the
+     * caller's, and it is load-bearing twice over: it is the order the work is
+     * offered in, and in the `numbered` variant it is the order the ordinals are
+     * derived from.
+     */
+    services: Service[];
+    /**
+     * Whether each engagement is numbered or not.
+     *
+     * `numbered` is opt-in for the reason `FeatureGrid01` states for the same prop
+     * and for the same claim, read here from the other side: a number on a card is
+     * a claim that the set is a sequence. Engagements and capabilities are usually
+     * a set, and a set with numbers on it is read as a set with an order, which
+     * makes a reader who disagrees with the order argue with the numbering rather
+     * than with the content. So the numbers are the caller's decision.
+     */
+    variant?: 'numbered' | 'plain';
+    /** 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;
+};
+/**
+ * What the product does, as a set of engagements: a title, a body, a list of what
+ * the reader gets, and an outcome, optionally numbered.
+ *
+ * **The NaniSoft framing is in this JSDoc and in the Demo, and nowhere in the
+ * Block.** What these engagements are is the work of a system that runs: read the
+ * estate, capture the market as it moves, decide what changed, and hand the
+ * finding to an agent that can act on it. That is a sequence, which is why the
+ * `numbered` variant exists and why the Demo uses it, and it is four `title`s,
+ * four `body`s and four deliverables lists at the call site. A Block that shipped
+ * them would put one company's way of working into every consumer's services page,
+ * and a services page is the page a reader is most likely to believe.
+ *
+ * **The ordinal is derived from the position, never taken from the item, and that
+ * is the whole of why it is safe to show at all.** A list that carried its own
+ * numbers is a list whose numbers can disagree with its order after a sort, a
+ * filter, a CMS re-publish or an insertion, and nothing in the rendering would
+ * catch it: the cards would read `03, 01, 02`. Rendering from the index means the
+ * numbers and the order cannot come apart, because they are the same value. The
+ * cost of deriving it is that a caller who wants the sequence to start at zero, or
+ * to skip a retired engagement, cannot, and the honest way to express that is to
+ * filter the list before it reaches the Block, which is a decision a consumer can
+ * see in its own data rather than one buried in a `number` field.
+ *
+ * **It is opt-in because a number on a card claims the set is a sequence, and a
+ * set of capabilities usually is not.** An engagement a reader buys is a sequence
+ * they can follow, and a page listing four capabilities is a set they are
+ * comparing. Numbering the second makes a reader look for the one they are missing
+ * and for a reason the numbering does not carry. So `plain` is the default, the
+ * numbers are the caller's decision, and the mono face is the same annotation the
+ * rest of this system uses for a machine value, which is what a position in a
+ * list is.
+ *
+ * **`deliverables` renders as a real list, and an empty array renders nothing.**
+ * A `<ul>` rather than a stack of paragraphs, because a reader checks the set off
+ * against their own situation and a list is what can be checked off; the marker is
+ * suppressed so the list reads as a set of terms under a heading rather than as
+ * bullets competing with the body above it. The empty case is worth stating
+ * because the alternative is a heading with nothing under it: an array of zero is a
+ * caller who has nothing to promise, and the honest rendering of that is absence
+ * rather than a titled gap.
+ *
+ * **The body, the deliverables and the outcome are three elements and not one,
+ * because a reader comparing two engagements reads them in that order and at
+ * different speeds.** The body says what the work is, the deliverables say what
+ * arrives, and the outcome says what it is for. Merging them gives a card whose
+ * last paragraph has to carry the effect as well as the description, and a reader
+ * scanning for the effect has to read the description to find it. The cost of
+ * three is that a caller with one paragraph to say has to choose which element it
+ * is, and choosing is the right pressure.
+ *
+ * A grid of engagements is three across, so a card holds a title, a body of two or
+ * three lines, a list and one line of outcome. A card that needs a fifth element
+ * is a page, and `PageHeader01` and this Block composed together is the honest
+ * arrangement for it.
+ *
+ * A service's title is a heading one step below the section, derived rather than
+ * written, so a Block embedded one level deeper carries its card titles with it.
+ *
+ * It is a server Component: no hook, no state and no client code.
+ */
+export declare function Services01({ eyebrow, title, description, services, variant, headingLevel, className, }: Services01Props): import("react").JSX.Element;
+export default Services01;
+//# sourceMappingURL=services.d.ts.map