@nanisoft/prism-ui 0.13.0 → 0.16.0

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

@@ -0,0 +1,155 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Section, SectionHeading, childLevel } from '../../components/ui/section.js';
+import { Status } from '../../components/ui/status.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The tone each kind draws, from the contract's own five.
+ *
+ * **This is a reading order and not a severity scale, and the difference is the
+ * whole argument for the `security` line below.** A tone here says how loudly the
+ * kind is announced when a reader scans a page of releases; it does not say how much
+ * attention the entry deserves, because that is a fact about the reader's exposure
+ * and not about the record. The five, in the order a reader meets them:
+ *
+ * - `added` takes `success`, which is the one tone in the contract that means a
+ *   good outcome. Something is now here that was not, and that is the kind a
+ *   reader scans a changelog for first.
+ * - `changed` takes `info`. It is the most common kind and the least consequential
+ *   of the five, and `info` is the tone that means "not an alarm" without claiming
+ *   anything either.
+ * - `fixed` takes `info` as well, and sharing it with `changed` is deliberate
+ *   rather than an omission. Both kinds describe something that already existed:
+ *   a change is a different thing and a fix is the same thing working. Which of the
+ *   two a reader cares about is a fact about their product, and a page that drew
+ *   them in different colours would be making that call on their behalf. The dot
+ *   tells them there is a record and the kind beside it tells them which kind it
+ *   is, which is what `Status` is for.
+ * - `removed` takes `neutral` and not `destructive`, and this is the second
+ *   decision worth arguing. A removal is a fact about the past: it is very often
+ *   the end of a migration the reader asked for and is entirely good news for
+ *   them, and painting it in the contract's alarm colour would put a red dot on a
+ *   release note that deserves a green one. `neutral` is also honest about the
+ *   tense. Nothing is wrong. Something is gone.
+ * - `security` takes `warning`. See below.
+ *
+ * The tones are the Block's because a tone is a visual decision, and the words are
+ * the kind the caller chose. `Status` is the right Component for that split: the
+ * dot is `aria-hidden` and the label carries the meaning, so a reader who cannot
+ * separate `warning` from `neutral` still reads which kind each entry is.
+ */
+const KIND_TONE = {
+    added: 'success',
+    changed: 'info',
+    fixed: 'info',
+    removed: 'neutral',
+    security: 'warning',
+};
+/**
+ * The share of the line the kind mark takes in the wider of the two arrangements.
+ *
+ * Two tracks rather than one, so the entry text starts at the same place on every
+ * row and the dots line up down the page. A grid whose first track is the mark's
+ * own width would put every entry's text at a different offset by the length of
+ * its kind, and a changelog is scanned down that edge.
+ */
+const TRACKS = {
+    kinds: 'sm:grid-cols-[7rem_minmax(0,1fr)] sm:gap-4',
+    plain: 'grid-cols-1',
+};
+/**
+ * A dated record of what changed, grouped by release, each record carrying a
+ * version, a kind, a line about what changed, and the sentence under it.
+ *
+ * **The five kinds and their tones are stated out loud in the `KIND_TONE` note
+ * above, and `security` takes `warning` rather than `destructive`, and the reason
+ * is the one thing a Block cannot know.** Severity is the reader's judgement, not
+ * the record's property. A `security` entry is the only one of the five that
+ * carries an implied claim about urgency, and a design system that coloured it
+ * destructively would be making that claim for every consumer in every release
+ * for ever. The concrete cost is easy to name: a product that publishes a routine
+ * dependency bump under `security` would have a red dot on it, and a reader
+ * trained by that page would learn to skip the red, and the day the product had a
+ * real advisory there would be nothing louder left to spend. The other side of
+ * that is the cost of `warning` and it is worth naming too: a consumer who needs a
+ * genuinely serious advisory to be unmistakable has no louder mark available to
+ * them, because the tone is fixed by the kind. The answer is that a serious
+ * advisory is a sentence, and the sentence is the `title` and the `body` the
+ * caller wrote. A design system has no standing to decide how alarming a
+ * consumer's release history is.
+ *
+ * **The kind is the taxonomy and the tones are the Block's, and neither is the
+ * caller's words.** The five kinds are closed because they are a vocabulary of
+  change that a reader learns once and then scans by, and a per-product vocabulary
+ * would be a column no reader could scan. What the caller owns is the tone's
+ * absence or presence and the sentence beside the mark, which is why the mark is
+ * `Status` and not a `Badge`: `Status` takes a tone and a label, its dot is
+  `aria-hidden`, and the label carries the meaning, so a reader who cannot separate
+  * `warning` from `neutral` still hears which kind each record is. The five words
+  * themselves are rendered from the value the caller passed, which is what a tier
+  * is: a machine value in a closed set, drawn as it was given, exactly as a
+ * version, a file name or a tier in any other Block is drawn.
+ *
+ * **The outline is section, then release, then record, and all three levels are
+ * derived.** A release is a heading one step below the section and a record is a
+ * heading one step below the release, which is `childLevel` applied twice rather
+ * than a literal `h3` in either place. The reason the record is not a sibling of
+ * the release is the shape of the data: a changelog is a set of groups, and a
+ * reader who navigates by heading is looking for a version, and then for a record
+ * inside it. A changelog with forty records directly under the section is an
+ * outline of forty peers and no grouping, which is a list of flat entries and not
+ * a record of releases. The cost is real: a reader on a page with a hundred
+  * releases meets a hundred headings before any record, which is the price of a
+ * structure they can jump through and the price a `Story01` already pays.
+ *
+ * **A release with no records draws its version and its date and no list.** An
+ * empty array is a legitimate state rather than a gap: a release that was cut
+  before anything landed, a release whose records were all withdrawn, a milestone
+  with a name and nothing under it. What it must not draw is a frame. A bordered
+  empty group under a version reads as content that failed to load, which is the
+ * one thing a changelog must never suggest about a release, and a
+ * "no changes" line would be a sentence Prism does not have the standing to
+ * write, because whether an empty release is a mistake or a policy is the
+ * product's business. So the list element is not drawn at all, and the release
+  * reads as a version with nothing under it, which is what it is.
+ *
+ * **A release is one `section`-less group of the section it sits in, and the
+ * versions are a list.** The releases are drawn in a `div` rather than a nested
+ * `<section>` because a `<section>` is a landmark and forty landmarks with no
+ * accessible name is forty announcements of nothing; the version is the heading and
+ * the heading is the name. The records inside a release are one `ul`, so a reader
+ * hears one list per release rather than one list for the page, and a list that
+ * spans a group boundary is a list whose items are not all the same kind of thing.
+ *
+ * **A record with no link draws no link, and one with a link carries the caller's
+ * words.** The pair is checked before anything is drawn, the same refusal
+ * `ContentGrid01` makes and for the same reason, and the message names the field.
+ * A per-record link is the difference between a changelog and a set of titles: it
+ * is where a reader goes for the migration steps, the diff, or the issue, and a
+ * changelog that cannot link out is a list of assertions.
+ *
+ * It is a server Component: no hook, no state and no client code. A consumer that
+ * wants a record's body to hold a control composes the control itself in `body`,
+ * which is the arrangement a `ReactNode` slot exists for.
+ */
+export function Changelog01({ eyebrow, title, description, releases, showKinds = true, headingLevel = 'h2', className, }) {
+    // Two derived levels rather than one. The release names a group of records and
+    // the record is one thing inside it, so the release is a heading under the
+    // section and the record is a heading under the release. Both follow the section
+    // when the Block is composed one level deeper than it was authored for.
+    const Release = childLevel(headingLevel);
+    const Entry = childLevel(childLevel(headingLevel));
+    for (const release of releases) {
+        for (const entry of release.entries) {
+            if (entry.href !== undefined && entry.hrefLabel === undefined) {
+                throw new Error(`Changelog01: the record "${entry.title}" in ${release.version} passed an href with no hrefLabel, so ` +
+                    'the entry would carry a link with no words on it, and a link a reader cannot name is a control they ' +
+                    'cannot act on with confidence. Pass the words that say what following it does, or omit the href.');
+            }
+        }
+    }
+    if (releases.length === 0)
+        return null;
+    return (_jsxs(Section, { children: [title ? (_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-12" })) : null, _jsx("div", { "data-slot": "changelog-01", className: cn('flex flex-col gap-12', className), children: releases.map((release) => (_jsxs("div", { "data-slot": "changelog-01-release", className: "flex flex-col gap-4", children: [_jsxs("div", { className: "flex flex-wrap items-baseline gap-x-3 gap-y-1", children: [_jsx(Release, { "data-slot": "changelog-01-version", className: "font-mono text-sm font-semibold tracking-tight", children: release.version }), release.at ? (_jsx("span", { "data-slot": "changelog-01-at", className: "text-muted-foreground font-mono text-xs", children: release.at })) : null] }), release.summary ? (_jsx("div", { "data-slot": "changelog-01-summary", className: "text-muted-foreground text-pretty text-sm", children: release.summary })) : null, release.entries.length === 0 ? null : (_jsx("ul", { "data-slot": "changelog-01-entries", className: "flex flex-col gap-4", children: release.entries.map((entry) => (_jsxs("li", { "data-slot": "changelog-01-entry", "data-kind": entry.kind, className: cn('flex flex-col gap-1.5', TRACKS[showKinds ? 'kinds' : 'plain']), children: [showKinds ? (_jsx(Status, { "data-slot": "changelog-01-kind", tone: KIND_TONE[entry.kind], label: entry.kind, size: "sm" })) : null, _jsxs("div", { "data-slot": "changelog-01-record", className: "flex min-w-0 flex-col gap-1.5", children: [_jsx(Entry, { className: "text-sm font-semibold tracking-tight", children: entry.title }), entry.body ? (_jsx("div", { "data-slot": "changelog-01-body", className: "text-muted-foreground text-pretty text-sm", children: entry.body })) : null, entry.href !== undefined && entry.hrefLabel !== undefined ? (_jsx(CtaLink, { href: entry.href, variant: "ghost", size: "sm", className: "self-start", children: entry.hrefLabel })) : null] })] }, entry.id))) }))] }, release.id))) })] }));
+}
+export default Changelog01;

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

@@ -0,0 +1,3 @@
+export { Changelog01, default } from './changelog.js';
+export type { Changelog01Props, Changelog01Kind, Changelog01Entry, Changelog01Release, } from './changelog.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/changelog-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAKlD,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAA"}

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

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

package/dist/blocks/chart-card-01/chart-card-01.d.ts

@@ -0,0 +1,149 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * How much of a six-track grid one card takes.
+ *
+ * Three names rather than a number, for the reason `Bento01`'s span states in full: a
+ * `colSpan: number` hands the Block a grid instead of a panel, because a number
+ * type-checks and renders whatever it is told to and produces an arrangement nobody
+ * can reason about when it does not fit. A third, a half and the whole are the three
+ * relationships a set of cards can have to each other, and they add up by arithmetic
+ * the caller never performs.
+ *
+ * `full` is the empty string rather than `col-span-6`, and that is the decision worth
+ * stating: a card that fills its track needs no placement at all, and a card that
+ * declares `col-span-6` in a three-track grid is a card that has silently left two
+ * tracks empty in every grid but the one it was written for. So the ordinary case
+ * places nothing, and the two narrower spans place themselves in whatever six-track
+ * grid the caller composed them into.
+ */
+export type ChartCard01Span = 'full' | 'half' | 'third';
+/**
+ * One figure the card states about what the figure shows.
+ *
+ * A node and not a number for the reason `Metric` gives: a caller's figure is often a
+ * value it formatted itself, and a number prop would make it either ship that as a
+ * string outside the Component or lose the unit it belongs to. `deltaFormat` is here
+ * for the same reason: Prism formats the delta and nothing else, and a delta of `0.12`
+ * is twelve percent, twelve cents or twelve milliseconds.
+ */
+export type ChartCard01Reading = {
+    /** 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. */
+    delta?: number;
+    /** The words for the delta, given the number. See the note on this type. */
+    deltaFormat?: (value: number) => string;
+};
+/**
+ * The props a ChartCard01 takes. Every string is a prop and the Block ships none.
+ */
+export type ChartCard01Props = {
+    /**
+     * The card's title, rendered as a heading one step below the section that
+     * introduces the card.
+     */
+    title: ReactNode;
+    /** One line under the title, for what the figure is a reading of. */
+    description?: ReactNode;
+    /**
+     * The figure itself, and the caller's own.
+     *
+     * A slot rather than a prop with a variant, and the whole of the reason is in the
+     * Block's JSDoc: a Block that named a chart type would be choosing the caller's
+     * data shape, and a chart is the one thing on an operate screen a consumer most
+     * often replaces once they know what they are measuring. Compose `chart`,
+     * `chart-frame`, a `pulse-series`, an image, or anything else.
+     */
+    figure: ReactNode;
+    /**
+     * The key for the figure, wherever the caller wants it.
+     *
+     * A slot rather than a rendered legend, because `chart` already exports
+     * `ChartLegend` as its own Item for exactly this reason: a legend is a layout
+     * decision the surrounding design usually has an opinion about, and a card that
+     * fixed one position made the other two a workaround. A caller who wants it in
+     * this slot passes `legend={false}` to `chart` and renders the same `series` array
+     * here, which is the only reason the swatch and the mark cannot disagree.
+     */
+    legend?: ReactNode;
+    /** The figures this card states about what the figure shows. */
+    reading?: ChartCard01Reading[];
+    /** The controls that act on the figure: a range, a segment, a download. */
+    actions?: ReactNode;
+    /** The band under the figure, for the line that qualifies it. */
+    footer?: ReactNode;
+    /** How much of a six-track grid the card takes. See `ChartCard01Span`. */
+    span?: ChartCard01Span;
+    /**
+     * The level of the heading that introduces this card, so the card's own title
+     * nests one step below it. See `HeadingLevel`.
+     */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Block. Changing a Prism-owned visual property
+     * from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A titled panel holding one figure, the key for it, the controls that act on it, and
+ * the figures the card states about it.
+ *
+ * **The figure is a slot, and the reason is one sentence long: a Block that named a
+ * chart type would be choosing the caller's data shape, and a chart is the one thing
+ * on an operate screen a consumer most often replaces once they know what they are
+ * measuring.** Every product that installs this card knows something this package
+ * does not, which is whether a bar or a line or a table of numbers is the honest
+ * rendering of their own series. A `figureVariant` prop would be a Block guessing,
+ * and a guess here is not a wrong colour: a bar chart of weekly signups invites a
+ * comparison of lengths that only means something when the value starts at zero, so
+ * the mark a caller never thought about is the mark that makes the chart wrong. So
+ * the card takes the figure as a node, and `chart` holds the decisions it does own,
+ * which are the mark it was given, the axis derived from the data, and the table.
+ *
+ * **Whatever the figure is, it must also be readable as numbers, and this Block does
+ * not check that.** `chart` states the rule in full: a chart is a picture whose entire
+ * content is a position, and a position is the one thing a screen reader, a crawler
+ * and a print stylesheet cannot read, so the marks and the cells are two renderings
+ * of one `series` array and the table is in the document whether or not anybody can
+ * see it. That rule holds for the caller's figure and this Block cannot see inside a
+ * slot to find out whether the caller honoured it. The duty passes to the caller, and
+ * this JSDoc says so rather than pretending the Block verified it. The cost of a slot
+ * is named here rather than hidden: a caller who passes a hand-rolled SVG gets a
+ * panel with an unreadable figure in it and no warning, and the only reason that is
+ * acceptable is that a Block cannot see inside a slot, so a warning would be a warning
+ * about the wrong thing.
+ *
+ * **The card title is a heading one step below the section that introduces it, and
+ * the level is derived rather than written.** Three cards in a grid are three regions
+ * a reader can jump between, and the step is `childLevel` rather than a literal `h3`
+ * so a card composed one level deeper carries its outline with it instead of
+ * announcing three siblings of the section that introduces them.
+ *
+ * **The readings sit in a flex row that wraps, and they share the width rather than
+ * holding a fixed one.** The measurement that decides it: a `third` card at the
+ * 72rem container is about 22rem wide, so three readings across it are about 7rem
+ * each, which holds a four character figure and nothing else. Sharing the width
+ * means one reading is as wide as the figure above it, which is what a single reading
+ * wants, and two share, which is what two want. The cost is stated rather than hidden:
+ * a caller with three long figures wants `span="half"`, and a caller who needs a fixed
+ * column is looking for a table under the figure rather than a reading line.
+ *
+ * **The card is a `Card` and not a `Section`, and that is what makes it a card.** A
+ * `Section` owns the container and the vertical rhythm, and a panel that owns a
+ * container cannot be a grid item in somebody else's, because a `Section` inside a
+ * grid cell is a second `max-w-page` at one third of the width. So this Block
+ * composes the card and takes the rhythm from whatever composed it, which is
+ * `chart-group-01` for the ordinary case and the caller's own grid otherwise.
+ *
+ * It is a server Component: no hook, no state, no client code and no motion. The
+ * figure decides whether it is one: a caller who passes a figure that animates is
+ * passing a client Component in a slot, which is the arrangement a `ReactNode` exists
+ * for, and this file is not what puts it in the client graph.
+ */
+export declare function ChartCard01({ title, description, figure, legend, reading, actions, footer, span, headingLevel, className, }: ChartCard01Props): import("react").JSX.Element;
+export default ChartCard01;
+//# sourceMappingURL=chart-card-01.d.ts.map

package/dist/blocks/chart-card-01/chart-card-01.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-card-01.d.ts","sourceRoot":"","sources":["../../../src/blocks/chart-card-01/chart-card-01.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAWtC,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAG3E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAEvD;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,KAAK,EAAE,SAAS,CAAA;IAChB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;CACxC,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,qEAAqE;IACrE,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;;OAQG;IACH,MAAM,EAAE,SAAS,CAAA;IACjB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,gEAAgE;IAChE,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAA;IAC9B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,iEAAiE;IACjE,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,eAAe,CAAA;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,WAAW,EACX,MAAM,EACN,MAAM,EACN,OAAY,EACZ,OAAO,EACP,MAAM,EACN,IAAa,EACb,YAAmB,EACnB,SAAS,GACV,EAAE,gBAAgB,+BAmElB;AAED,eAAe,WAAW,CAAA"}

package/dist/blocks/chart-card-01/chart-card-01.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, } from '../../components/ui/card.js';
+import { Metric } from '../../components/ui/metric.js';
+import { childLevel } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * What each named span takes of a six-track grid, at the breakpoint the grid appears.
+ *
+ * A map of machine values rather than three conditional class strings, so the
+ * relationship between a span name and a track count is one table a reader can check
+ * in one place. Every value is a `col-span` utility and nothing else, and `full` is
+ * the empty string because a card that fills its track needs no placement.
+ */
+const SPAN = {
+    full: '',
+    half: 'lg:col-span-3',
+    third: 'lg:col-span-2',
+};
+/**
+ * A titled panel holding one figure, the key for it, the controls that act on it, and
+ * the figures the card states about it.
+ *
+ * **The figure is a slot, and the reason is one sentence long: a Block that named a
+ * chart type would be choosing the caller's data shape, and a chart is the one thing
+ * on an operate screen a consumer most often replaces once they know what they are
+ * measuring.** Every product that installs this card knows something this package
+ * does not, which is whether a bar or a line or a table of numbers is the honest
+ * rendering of their own series. A `figureVariant` prop would be a Block guessing,
+ * and a guess here is not a wrong colour: a bar chart of weekly signups invites a
+ * comparison of lengths that only means something when the value starts at zero, so
+ * the mark a caller never thought about is the mark that makes the chart wrong. So
+ * the card takes the figure as a node, and `chart` holds the decisions it does own,
+ * which are the mark it was given, the axis derived from the data, and the table.
+ *
+ * **Whatever the figure is, it must also be readable as numbers, and this Block does
+ * not check that.** `chart` states the rule in full: a chart is a picture whose entire
+ * content is a position, and a position is the one thing a screen reader, a crawler
+ * and a print stylesheet cannot read, so the marks and the cells are two renderings
+ * of one `series` array and the table is in the document whether or not anybody can
+ * see it. That rule holds for the caller's figure and this Block cannot see inside a
+ * slot to find out whether the caller honoured it. The duty passes to the caller, and
+ * this JSDoc says so rather than pretending the Block verified it. The cost of a slot
+ * is named here rather than hidden: a caller who passes a hand-rolled SVG gets a
+ * panel with an unreadable figure in it and no warning, and the only reason that is
+ * acceptable is that a Block cannot see inside a slot, so a warning would be a warning
+ * about the wrong thing.
+ *
+ * **The card title is a heading one step below the section that introduces it, and
+ * the level is derived rather than written.** Three cards in a grid are three regions
+ * a reader can jump between, and the step is `childLevel` rather than a literal `h3`
+ * so a card composed one level deeper carries its outline with it instead of
+ * announcing three siblings of the section that introduces them.
+ *
+ * **The readings sit in a flex row that wraps, and they share the width rather than
+ * holding a fixed one.** The measurement that decides it: a `third` card at the
+ * 72rem container is about 22rem wide, so three readings across it are about 7rem
+ * each, which holds a four character figure and nothing else. Sharing the width
+ * means one reading is as wide as the figure above it, which is what a single reading
+ * wants, and two share, which is what two want. The cost is stated rather than hidden:
+ * a caller with three long figures wants `span="half"`, and a caller who needs a fixed
+ * column is looking for a table under the figure rather than a reading line.
+ *
+ * **The card is a `Card` and not a `Section`, and that is what makes it a card.** A
+ * `Section` owns the container and the vertical rhythm, and a panel that owns a
+ * container cannot be a grid item in somebody else's, because a `Section` inside a
+ * grid cell is a second `max-w-page` at one third of the width. So this Block
+ * composes the card and takes the rhythm from whatever composed it, which is
+ * `chart-group-01` for the ordinary case and the caller's own grid otherwise.
+ *
+ * It is a server Component: no hook, no state, no client code and no motion. The
+ * figure decides whether it is one: a caller who passes a figure that animates is
+ * passing a client Component in a slot, which is the arrangement a `ReactNode` exists
+ * for, and this file is not what puts it in the client graph.
+ */
+export function ChartCard01({ title, description, figure, legend, reading = [], actions, footer, span = 'full', headingLevel = 'h2', className, }) {
+    // One step below the heading that introduces this card, so the card's own title
+    // nests under the section rather than beside it.
+    const Title = childLevel(headingLevel);
+    return (_jsx("div", { "data-slot": "chart-card-01", "data-span": span, className: cn(SPAN[span], className), children: _jsxs(Card, { className: "h-full gap-4 py-5", children: [_jsxs(CardHeader, { className: "grid-cols-[minmax(0,1fr)_auto] gap-x-3", children: [_jsxs("div", { "data-slot": "chart-card-01-head", className: "flex min-w-0 flex-col gap-1.5", children: [_jsx(CardTitle, { as: Title, className: "text-base", children: title }), description === undefined ? null : (_jsx(CardDescription, { className: "text-pretty", children: description }))] }), actions === undefined ? null : (_jsx("div", { "data-slot": "chart-card-01-actions", className: "flex shrink-0 items-center gap-2", children: actions }))] }), _jsxs(CardContent, { className: "flex flex-col gap-3", children: [_jsx("div", { "data-slot": "chart-card-01-figure", className: "min-w-0", children: figure }), legend === undefined ? null : (_jsx("div", { "data-slot": "chart-card-01-legend", className: "min-w-0", children: legend })), reading.length === 0 ? null : (_jsx("div", { "data-slot": "chart-card-01-reading", className: "border-border flex flex-wrap items-end gap-x-6 gap-y-3 border-t pt-4", children: reading.map((entry) => (_jsx("div", { className: "min-w-0 flex-1", children: _jsx(Metric, { value: entry.value, label: entry.label, delta: entry.delta, deltaFormat: entry.deltaFormat }) }, entry.label))) }))] }), footer === undefined ? null : (_jsx(CardFooter, { "data-slot": "chart-card-01-footer", children: footer }))] }) }));
+}
+export default ChartCard01;

package/dist/blocks/chart-card-01/index.d.ts

@@ -0,0 +1,3 @@
+export { ChartCard01, default } from './chart-card-01.js';
+export type { ChartCard01Props, ChartCard01Reading, ChartCard01Span, } from './chart-card-01.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/chart-card-01/index.d.ts.map

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

package/dist/blocks/chart-card-01/index.js

@@ -0,0 +1 @@
+export { ChartCard01, default } from './chart-card-01.js';

package/dist/blocks/chart-group-01/chart-group-01.d.ts

@@ -0,0 +1,138 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+import { type ChartCard01Reading } from '../chart-card-01/chart-card-01.js';
+/**
+ * One card in the grid: a title, a figure, and everything the card carries around it.
+ *
+ * The shape is `ChartCard01`'s own minus the placement, and the reason is in the
+ * Block's JSDoc: a card in a grid fills its track, so a width on the entry would be
+ * a fact about the grid rather than about the card, and the grid is derived here
+ * from the count.
+ */
+export type ChartGroup01Card = {
+    /**
+     * A key unique within the set, used as the list key and never rendered.
+     *
+     * A key and not a label, for the reason `CaseStudies01` states: a grid of figures is
+     * reordered by a consumer as often as it is read, and a key made of the words means
+     * a rename in the title is a rename in the key.
+     */
+    id: string;
+    /** The card's title, rendered as a heading one step below the section. */
+    title: ReactNode;
+    /** One line under the title, for what the figure is a reading of. */
+    description?: ReactNode;
+    /**
+     * The figure, and the caller's own.
+     *
+     * A slot rather than a `chart` with a `variant`, for the reason `chart`'s own
+     * JSDoc states: the mark is the claim the chart makes about the data, and a caller
+     * who never thought about the mark is exactly the caller who gets it wrong.
+     */
+    figure: ReactNode;
+    /** The key for the figure, wherever the caller wants it. */
+    legend?: ReactNode;
+    /** The figures this card states about what the figure shows. */
+    reading?: ChartCard01Reading[];
+    /** The controls that act on the figure: a range, a segment, a download. */
+    actions?: ReactNode;
+};
+/**
+ * The props a ChartGroup01 takes. Every string is a prop and the Block ships none.
+ */
+export type ChartGroup01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /** The section title. Omit it for a grid composed under its own heading. */
+    title?: string;
+    /** One or two sentences under the title. */
+    description?: string;
+    /**
+     * The cards, in the order a reader should meet them.
+     *
+     * Order is the caller's because it is a claim about which figure answers the
+     * question the reader arrived with, and a grid that sorted itself by size or by
+     * title would be making that claim on the caller's behalf.
+     */
+    cards: ChartGroup01Card[];
+    /**
+     * The most columns the grid takes at the wide breakpoint.
+     *
+     * Two or three and not a number, for the reason `Bento01`'s span states: a number
+     * type-checks and renders whatever it is told to, and a number of 5 in a grid of
+     * figures produces figures narrower than the legend under them. The default is 3,
+     * and it is a ceiling rather than a setting: the count can take fewer columns than
+     * this and never more, because a caller who wants six figures across a 68rem
+     * container is asking for 11rem figures, and the measurement in the Block's JSDoc
+     * says what 11rem buys.
+     */
+    columns?: 2 | 3;
+    /**
+     * What stands in for the grid when there are no cards.
+     *
+     * Optional, and the rule is `FactList`'s: an empty grid is a set of gaps a reader
+     * looks through, so nothing is drawn. A caller that wants a sentence there passes
+     * one, and a caller that wants nothing passes nothing and gets nothing.
+     */
+    empty?: ReactNode;
+    /** 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 responsive grid of chart cards whose column count is derived from how many there
+ * are rather than passed.
+ *
+ * **The layout is derived, and the measurement is why.** One card takes the full
+ * width, because a single figure in half a container is a figure with a card around
+ * it and no reason for the card. Two sit side by side, because two is the one count
+ * where a single column is worse than two. Three or more are three across at `lg` and
+ * one below it. The number that decides the ceiling is the width: the container is
+ * `Section`'s 72rem measure with 2rem of padding at each edge, so 68rem of content,
+ * and a four-across grid takes 1rem of gap three times over, which leaves about 16rem
+ * for each figure. `chart` then spends 3rem of that on a fixed axis gutter before any
+ * mark is drawn, so a four-across bar chart would be asked to draw into about 13rem
+ * while its category labels are truncated to 5rem each. The three-across arrangement
+ * this Block uses gives each figure about 22rem, which is about 19rem of plot, and
+ * that is the difference between reading a shape and guessing at one. Below `lg` there
+ * is one column, because a figure in a third of a phone is a figure nobody can read
+ * and the grid is the first thing to lose.
+ *
+ * **`columns` is a ceiling and the count can take fewer, never more.** A caller with
+ * four cards who wants two across says so, and a caller with six cannot ask for six,
+ * because a number of 6 would produce about 10rem figures and the honest answer to
+ * that is a Page over two groups rather than one grid of unreadable figures. The
+ * alternative was a plain number prop, and a plain number prop is a layout the Block
+ * would have to honour exactly, including the arrangements nobody can lay out.
+ *
+ * **Each card is `ChartCard01`, and the reason is that a second panel would be a
+ * second answer.** The title's element, the description's step, where the controls go,
+ * the rule above the readings and the gap between figure and key are all decisions
+ * `chart-card-01` has already made and argued, and a grid that re-derived them would
+ * put two panels on one page whose cards differ in ways no reader could name. So this
+ * Block composes the card and adds exactly one thing, which is the grid.
+ *
+ * **The heading level is passed straight through, and the card titles nest under it.**
+ * A card derives its own title level as one step below the heading that introduces
+ * it, so passing the section's level here puts three card titles one step below the
+ * section, which is what the outline should say. Passing a stepped-up level would put
+ * the cards at the section's own depth and announce them as siblings of the thing
+ * that introduces them.
+ *
+ * **An empty set draws no grid, and that is `FactList`'s rule rather than a new one.**
+ * A grid of nothing is a set of gaps a reader looks through and reads as a surface
+ * that failed, so the `empty` node stands where the grid would have been and a caller
+ * who passes nothing gets nothing. The cost is that a section heading can survive on
+ * a page whose figures have all been withdrawn, and a caller who would rather see
+ * nothing at all should not render the Block.
+ *
+ * It is a server Component: no hook, no state, no client code and no motion. A caller
+ * who wants a control in a card composes it in that card's own `actions` slot.
+ */
+export declare function ChartGroup01({ eyebrow, title, description, cards, columns, empty, headingLevel, className, }: ChartGroup01Props): import("react").JSX.Element;
+export default ChartGroup01;
+//# sourceMappingURL=chart-group-01.d.ts.map

package/dist/blocks/chart-group-01/chart-group-01.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-group-01.d.ts","sourceRoot":"","sources":["../../../src/blocks/chart-group-01/chart-group-01.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAExF,OAAO,EAAe,KAAK,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAErF;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,0EAA0E;IAC1E,KAAK,EAAE,SAAS,CAAA;IAChB,qEAAqE;IACrE,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;OAMG;IACH,MAAM,EAAE,SAAS,CAAA;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,gEAAgE;IAChE,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAA;IAC9B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,+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;;;;;;OAMG;IACH,KAAK,EAAE,gBAAgB,EAAE,CAAA;IACzB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAA;IACf;;;;;;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;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,YAAY,CAAC,EAC3B,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,OAAW,EACX,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,iBAAiB,+BA2CnB;AAED,eAAe,YAAY,CAAA"}

package/dist/blocks/chart-group-01/chart-group-01.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
+import { ChartCard01 } from '../chart-card-01/chart-card-01.js';
+/**
+ * The grid each column count takes, at the breakpoint the grid appears.
+ *
+ * A map of machine values rather than two conditional class strings, and the classes
+ * are literals rather than assembled, because Tailwind reads the source and a class
+ * built at runtime from a number is not in the sheet. Every value is a `grid-cols`
+ * utility and nothing else, which is what `className` being layout only is for.
+ */
+const GRID = {
+    2: 'grid gap-4 lg:grid-cols-2',
+    3: 'grid gap-4 lg:grid-cols-3',
+};
+/**
+ * A responsive grid of chart cards whose column count is derived from how many there
+ * are rather than passed.
+ *
+ * **The layout is derived, and the measurement is why.** One card takes the full
+ * width, because a single figure in half a container is a figure with a card around
+ * it and no reason for the card. Two sit side by side, because two is the one count
+ * where a single column is worse than two. Three or more are three across at `lg` and
+ * one below it. The number that decides the ceiling is the width: the container is
+ * `Section`'s 72rem measure with 2rem of padding at each edge, so 68rem of content,
+ * and a four-across grid takes 1rem of gap three times over, which leaves about 16rem
+ * for each figure. `chart` then spends 3rem of that on a fixed axis gutter before any
+ * mark is drawn, so a four-across bar chart would be asked to draw into about 13rem
+ * while its category labels are truncated to 5rem each. The three-across arrangement
+ * this Block uses gives each figure about 22rem, which is about 19rem of plot, and
+ * that is the difference between reading a shape and guessing at one. Below `lg` there
+ * is one column, because a figure in a third of a phone is a figure nobody can read
+ * and the grid is the first thing to lose.
+ *
+ * **`columns` is a ceiling and the count can take fewer, never more.** A caller with
+ * four cards who wants two across says so, and a caller with six cannot ask for six,
+ * because a number of 6 would produce about 10rem figures and the honest answer to
+ * that is a Page over two groups rather than one grid of unreadable figures. The
+ * alternative was a plain number prop, and a plain number prop is a layout the Block
+ * would have to honour exactly, including the arrangements nobody can lay out.
+ *
+ * **Each card is `ChartCard01`, and the reason is that a second panel would be a
+ * second answer.** The title's element, the description's step, where the controls go,
+ * the rule above the readings and the gap between figure and key are all decisions
+ * `chart-card-01` has already made and argued, and a grid that re-derived them would
+ * put two panels on one page whose cards differ in ways no reader could name. So this
+ * Block composes the card and adds exactly one thing, which is the grid.
+ *
+ * **The heading level is passed straight through, and the card titles nest under it.**
+ * A card derives its own title level as one step below the heading that introduces
+ * it, so passing the section's level here puts three card titles one step below the
+ * section, which is what the outline should say. Passing a stepped-up level would put
+ * the cards at the section's own depth and announce them as siblings of the thing
+ * that introduces them.
+ *
+ * **An empty set draws no grid, and that is `FactList`'s rule rather than a new one.**
+ * A grid of nothing is a set of gaps a reader looks through and reads as a surface
+ * that failed, so the `empty` node stands where the grid would have been and a caller
+ * who passes nothing gets nothing. The cost is that a section heading can survive on
+ * a page whose figures have all been withdrawn, and a caller who would rather see
+ * nothing at all should not render the Block.
+ *
+ * It is a server Component: no hook, no state, no client code and no motion. A caller
+ * who wants a control in a card composes it in that card's own `actions` slot.
+ */
+export function ChartGroup01({ eyebrow, title, description, cards, columns = 3, empty, headingLevel = 'h2', className, }) {
+    // One column for a single card, and otherwise the ceiling capped by the count, so
+    // two cards are two across whichever ceiling the caller passed and four are three
+    // across unless the caller asked for two.
+    const tracks = cards.length <= 1 ? 0 : Math.min(columns, cards.length);
+    return (_jsxs(Section, { "data-slot": "chart-group-01", className: className, children: [title ? (_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-10" })) : null, cards.length === 0 ? (_jsx("div", { "data-slot": "chart-group-01-empty", children: empty })) : (_jsx("div", { "data-slot": "chart-group-01-grid", "data-tracks": tracks, className: cn(tracks === 0 ? 'flex flex-col' : GRID[tracks === 2 ? 2 : 3]), children: cards.map((card) => (_jsx(ChartCard01, { title: card.title, description: card.description, figure: card.figure, legend: card.legend, reading: card.reading, actions: card.actions, headingLevel: headingLevel }, card.id))) }))] }));
+}
+export default ChartGroup01;