@nanisoft/prism-ui 0.10.2 → 0.15.0

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

@@ -0,0 +1,262 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One dated entry, as the grid draws it.
+ *
+ * Only `id`, `title` and `summary` are required, and the three of them are the
+ * three things an entry is: something a reader can name, something they can read,
+ * and a stable key. Everything else is annotation, and an entry with no annotation
+ * renders the three it has rather than a card with a line of empty space where the
+ * annotation would have been. That is the whole rule for every optional field on
+ * this type: a field that is absent draws nothing, because a grid of six cards
+ * where four have a date and two have a blank under the title reads as two entries
+ * whose dates are lost rather than as a set where the dates vary.
+ */
+export type ContentGrid01Entry = {
+    /**
+     * The entry's stable key within the set.
+     *
+     * A key and not a label, for the reason `CaseStudies01` states: a grid of
+     * entries is reordered by a consumer as often as it is read, and a key made of
+     * the words means a rename in the copy is a rename in the key.
+     */
+    id: string;
+    /**
+     * The entry's own name, as a reader would name it in conversation. It is the
+     * heading of the card or the row and the first thing a reader reads.
+     */
+    title: string;
+    /**
+     * The line or two under the name.
+     *
+     * A node rather than a string, and the difference is that a caller may hand
+     * Prism a plain string, a `<p>`, a list of three points, or a `<dl>` it built
+     * itself, and the Block draws it inside the element it already styles. The
+     * Block wraps it in a `div` and not a `p`, so a caller that passes a paragraph
+     * does not get a paragraph inside a paragraph, and a caller that passes a list
+     * does not get a list inside a paragraph.
+     */
+    summary: ReactNode;
+    /**
+     * The moment, or the period, or the version, the entry belongs to.
+     *
+     * A string and not a `Date`, and the reason is `RelativeTime`'s: the absolute
+     * reading a reader should see is the platform's and the relative phrase beside
+     * it is the consumer's own sentence, so a Block that took a `Date` would have to
+     * invent a granularity and a locale in order to print it. The Block prints the
+     * string it was handed, in the mono face, because `2026-09-30`, `September 2026`,
+     * `Q3` and `2.4.0` are all readings a consumer writes and Prism parses none of
+     * them. A consumer that wants the platform's own formatting and a relative
+     * phrase composes `RelativeTime`, which is the Component that holds that
+     * decision, and renders the set itself where a relative phrase belongs.
+     */
+    at?: string;
+    /**
+     * The label for what kind of entry this is, drawn above the name.
+     *
+     * A word and not a tier, because a tier here would be Prism's vocabulary in a
+     * slot the consumer already has a name for. "Guide", "Release" and "Case study"
+     * are three different claims about the same set and the set's owner is the only
+     * party who can make them.
+     */
+    category?: string;
+    /** Where the entry goes. Its presence makes the card or the row carry a link. */
+    href?: string;
+    /**
+     * The words on the link, and required whenever `href` is.
+     *
+     * A link whose only words are the entry's name reads as a name: the reader sees
+     * the title, assumes it is the whole of what is there, and the page behind it is
+     * a click they were never invited to make. The words say what following it does,
+     * which is a claim about the destination and therefore about whoever wrote that
+     * destination, so they are the caller's.
+     */
+    hrefLabel?: string;
+    /**
+     * How long the entry takes, as the consumer writes it. Machine notation beside
+     * `at`, in the same face, because a duration is not prose either.
+     */
+    readingTime?: string;
+    /**
+     * A figure for the entry, drawn above the card's text.
+     *
+     * A slot and not an image prop, because the figure is the caller's: a
+     * screenshot, a chart, a diagram, a short video or a still from one are all
+     * things a dated entry may carry and none of them is the same shape. Drawn in the
+     * `cards` variant only. A row has no room for a figure, and a figure a variant
+     * quietly drops is a figure the caller thought was published, so a caller
+     * composing a `rows` or a `compact` set omits it.
+     */
+    media?: ReactNode;
+};
+/** How many entries a grid puts on one line. The tracks, not the entry count. */
+export type ContentGrid01Columns = 2 | 3 | 4;
+/**
+ * The three arrangements a set of dated entries can be read in.
+ *
+ * Three rather than one, and the reason is the question a reader is asking. `cards`
+ * is for choosing: a reader scanning a page is deciding which entry to open, and a
+ * comparison wants the peers visible at once. `rows` is for reading: a page that
+ * has already narrowed to one category gives each entry a full line and a summary
+ * with room. `compact` is for skimming: a long index where the reader wants the
+ * names and the dates and nothing else, and a card per entry would be four times
+ * the ink for a list they scan rather than read.
+ *
+ * **The type is `ContentGrid01Form` and the prop is `variant`, and the two names
+ * differing is the surface gate working rather than a slip.**
+ * `check-surface.mjs` refuses to let a public entry export a name ending in
+ * `Variant`, because in this package that shape names a cva map: a recipe a
+ * consumer could read and compose with. This union is not a recipe, it is the
+ * three arrangements the Block can draw, and it is named for the arrangement. The
+ * prop keeps the name `variant` because a Component is allowed to take one, which
+ * is the distinction `DESIGN.md`'s export surface draws: the prop is an input, a
+ * `*Variants` export is an API. `ChartForm` is named the same way for the same
+ * reason.
+ */
+export type ContentGrid01Form = 'cards' | 'rows' | 'compact';
+/**
+ * The props a ContentGrid01 takes.
+ *
+ * Every string, every figure and every annotation is a prop and the Block ships
+ * none: no entry, no date, no category, no reading time and no placeholder card. A
+ * grid that hardcoded its entries would hand every consumer a publication's
+ * back catalogue, and the corpus would publish it as the design system's own.
+ */
+export type ContentGrid01Props = {
+    /** 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 entries, in the order a reader should meet them.
+     *
+     * Order is the caller's, because a set of dated entries is already a claim about
+     * which one leads, and the grid does not sort by `at`. A consumer that wants
+     * newest first sorts before it renders; a consumer that wants the reverse
+     * chronological order that a case study set wants sorts by the same field.
+     */
+    entries: ContentGrid01Entry[];
+    /**
+     * How the set is drawn.
+     *
+     * @defaultValue 'cards'
+     *
+     * `cards` is the default because it is the arrangement in which a reader is
+     * choosing, and choosing is the question a set of dated entries on a page is
+     * most often there to answer.
+     */
+    variant?: ContentGrid01Form;
+    /**
+     * How many entries sit on one line in the `cards` variant. Ignored by `rows` and
+     * `compact`, which have one entry per line by definition.
+     *
+     * @defaultValue 3
+     */
+    columns?: ContentGrid01Columns;
+    /**
+     * What the grid shows when there is nothing in it.
+     *
+     * A node and not a sentence, for the reason every string on this type is a prop:
+     * a Block that rendered "No posts yet" would put a claim about a publication into
+     * four consumer sites, and it would be the wrong claim, because an empty set is
+     * a first run, a filter that matched nothing, and a feed that has been retired,
+     * and those three want three different sentences. Compose `EmptyState01` here and
+     * it asks for the reason and writes the words.
+     *
+     * Omit it and an empty set renders nothing at all, which is the right default
+     * for a section that should not appear until it has something in it.
+     */
+    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 grid of dated entries, as cards, as full-width rows, or as a compact index.
+ *
+ * **The name is the decision, and it is recorded here because a reader will ask.**
+ * Every other slug in this wave came off a published list, and this one did not.
+ * DESIGN.md's Known Open Items rules that the old `blog-layout` item never ships,
+ * and the reason it gives is that the blog does not exist. A dated-entry card grid
+ * is nevertheless needed, by four surfaces in this repository and by every product
+ * that keeps one: the changelog, the resources index, the case study set and this
+ * documentation site. So the shape ships and the word does not. Calling it
+ * `content-grid` is the claim: it is a grid of content, and the content is the
+ * caller's. Every consumer that has ever needed this band has needed it for
+ * something that is not a blog, and the four above are the proof, because a
+ * changelog is a dated record and a case study set is dated only sometimes and
+ * neither of them is a series of posts. The cost is real and worth naming: a slug
+ * a reader can recognise from a competitor's inventory is a slug a reader reaches
+ * for in a search box and does not find, and a consumer who wants the other name
+ * wraps this Block in their own. The alternative was the other name, and the
+ * alternative's cost was that a design system would then be claiming a publication
+ * it does not run, in a name every catalogue and every agent surface would then
+ * repeat.
+ *
+ * **A consumer composes it with a documentation changelog, a research index, a
+ * release history, or a case study set.** The four differ in their annotations
+ * rather than in their shape, which is the test the props were drawn around: the
+ * changelog passes `at` and nothing else, a research index passes `category` and
+ * `href` and `hrefLabel`, a release history passes `at` and `readingTime`, and a
+ * case study set passes `media` and `summary` and reaches for `variant="rows"`.
+ * Four surfaces, one record, and the difference is which annotations the reader
+ * needs beside the name.
+ *
+ * **The entry is a heading one step below the section, in all three variants.** A
+ * `cards` grid of six titles under one section is six children of that section, and
+ * a `rows` set of forty is forty, and both read correctly to a reader navigating by
+ * heading. The level is derived rather than written, so a Block embedded one level
+ * deeper than it was authored for carries its titles with it, which is the whole
+ * reason `headingLevel` is a prop. The cost of making the title a heading in the
+ * `compact` variant is an outline of one line per entry, and a forty entry index
+ * is a long outline; that is the price of letting a reader jump to an entry by
+ * heading rather than by scrolling, and it is the price a `rows` set already pays.
+ *
+ * **`at` and `readingTime` are strings, and Prism parses neither.** The Block prints
+ * what it was handed in the mono face. A consumer that wants the platform's own
+ * absolute reading and a relative phrase composes `RelativeTime` itself, because
+ * the date, the locale and the sentence are three facts about the consumer's
+ * content and not one fact about a Block. Formatting a `Date` here would have meant
+ * picking a granularity and a locale, and a consumer in a second locale would then
+ * have had a correct Block rendering its page in the wrong language.
+ *
+ * **The link carries the caller's words, and the Block refuses a link that carries
+ * none.** `href` without `hrefLabel` would render a card with a control on it that
+ * has no text, so the pair is checked before anything is drawn and the run fails
+ * with the name of the field. The pair is flat rather than a union in the way
+ * `CaseStudies01` spells its own, and that is a departure with its cost stated: the
+ * type will let a caller pass `href` alone, and the refusal arrives at render
+ * rather than at build. The reason is that `entries` is a flat list a caller maps
+ * from its own records rather than a set of arms the Block branches between, and a
+ * union on a mapped record is a shape every call site has to satisfy by hand for
+ * one optional pair. A union is the better type and this one is the cheaper
+ * interface, and the diagnostic is what keeps the cheaper one honest.
+ *
+ * **An empty set renders the caller's `empty` node, or nothing at all.** It never
+ * renders a frame, because a dashed box under a section title reads as a section
+ * whose contents failed to load rather than as a section with none, and the honest
+ * state for a set that has not started is for the set not to be there. When
+ * `empty` is passed the section title still draws, so the reader is told which
+ * section is empty and not merely that something is.
+ *
+ * **The three variants draw the same tree, not three trees.** The `li` is the same
+ * element and the entry's content is the same elements in the same order in all
+ * three; the arrangement is carried by the classes on the `li` and the `ul`. Two
+ * trees would have put the same entry in the accessibility tree twice and for a
+ * crawler twice, and a reader who narrowed the window would have watched one copy
+ * swap for the other.
+ *
+ * It is a server Component: no hook, no state and no client code. A caller that
+ * wants a card whose whole area is the link composes `CtaLink` itself in `media` or
+ * in `summary`, which is the arrangement a consumer reaches for when the tile is
+ * the target rather than the name.
+ */
+export declare function ContentGrid01({ eyebrow, title, description, entries, variant, columns, empty, headingLevel, className, }: ContentGrid01Props): import("react").JSX.Element | null;
+export default ContentGrid01;
+//# sourceMappingURL=content-grid.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"content-grid.d.ts","sourceRoot":"","sources":["../../../src/blocks/content-grid-01/content-grid.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAGpG;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;OASG;IACH,OAAO,EAAE,SAAS,CAAA;IAClB;;;;;;;;;;;;OAYG;IACH,EAAE,CAAC,EAAE,MAAM,CAAA;IACX;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB,CAAA;AAED,iFAAiF;AACjF,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAE5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAA;AAiB5D;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,+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;;;;;;;OAOG;IACH,OAAO,EAAE,kBAAkB,EAAE,CAAA;IAC7B;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,oBAAoB,CAAA;IAC9B;;;;;;;;;;;;OAYG;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;AAgDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,wBAAgB,aAAa,CAAC,EAC5B,OAAO,EACP,KAAK,EACL,WAAW,EACX,OAAO,EACP,OAAiB,EACjB,OAAW,EACX,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,kBAAkB,sCAuKpB;AAED,eAAe,aAAa,CAAA"}

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

@@ -0,0 +1,155 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Card, CardContent, CardHeader, CardTitle } from '../../components/ui/card.js';
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Section, SectionHeading, childLevel } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The tracks a grid of entries gets, from the caller's own column count.
+ *
+ * Spelled out per count, as `ProcessFlow01` does, so a grid has exactly as many
+ * tracks as it declared and not one empty at the end of a row. The `sm:` step is
+ * a narrowing rather than a widening: on a phone every arrangement is one entry
+ * per line, because a four-up row of titles and summaries at phone width is four
+ * columns of four words.
+ */
+const TRACKS = {
+    2: 'sm:grid-cols-2',
+    3: 'sm:grid-cols-2 lg:grid-cols-3',
+    4: 'sm:grid-cols-2 lg:grid-cols-4',
+};
+/**
+ * The annotation line on one entry: the reading, the category, the length.
+ *
+ * Drawn only when there is at least one of the three. An entry with none of them
+ * is a title and a summary and nothing else, and holding open a line for a
+ * category that is not there would push every other card's name down by one line
+ * and break the alignment the grid is scanned along.
+ */
+function EntryMeta({ entry }) {
+    if (entry.at === undefined && entry.category === undefined && entry.readingTime === undefined) {
+        return null;
+    }
+    return (_jsxs("div", { "data-slot": "content-grid-meta", className: "text-muted-foreground flex flex-wrap items-center gap-x-2 gap-y-1 text-xs", children: [entry.at ? (_jsx("span", { "data-slot": "content-grid-at", className: "font-mono", children: entry.at })) : null, entry.category ? (_jsx("span", { "data-slot": "content-grid-category", className: "font-medium tracking-wide uppercase", children: entry.category })) : null, entry.readingTime ? (_jsx("span", { "data-slot": "content-grid-reading-time", className: "font-mono", children: entry.readingTime })) : null] }));
+}
+/**
+ * A grid of dated entries, as cards, as full-width rows, or as a compact index.
+ *
+ * **The name is the decision, and it is recorded here because a reader will ask.**
+ * Every other slug in this wave came off a published list, and this one did not.
+ * DESIGN.md's Known Open Items rules that the old `blog-layout` item never ships,
+ * and the reason it gives is that the blog does not exist. A dated-entry card grid
+ * is nevertheless needed, by four surfaces in this repository and by every product
+ * that keeps one: the changelog, the resources index, the case study set and this
+ * documentation site. So the shape ships and the word does not. Calling it
+ * `content-grid` is the claim: it is a grid of content, and the content is the
+ * caller's. Every consumer that has ever needed this band has needed it for
+ * something that is not a blog, and the four above are the proof, because a
+ * changelog is a dated record and a case study set is dated only sometimes and
+ * neither of them is a series of posts. The cost is real and worth naming: a slug
+ * a reader can recognise from a competitor's inventory is a slug a reader reaches
+ * for in a search box and does not find, and a consumer who wants the other name
+ * wraps this Block in their own. The alternative was the other name, and the
+ * alternative's cost was that a design system would then be claiming a publication
+ * it does not run, in a name every catalogue and every agent surface would then
+ * repeat.
+ *
+ * **A consumer composes it with a documentation changelog, a research index, a
+ * release history, or a case study set.** The four differ in their annotations
+ * rather than in their shape, which is the test the props were drawn around: the
+ * changelog passes `at` and nothing else, a research index passes `category` and
+ * `href` and `hrefLabel`, a release history passes `at` and `readingTime`, and a
+ * case study set passes `media` and `summary` and reaches for `variant="rows"`.
+ * Four surfaces, one record, and the difference is which annotations the reader
+ * needs beside the name.
+ *
+ * **The entry is a heading one step below the section, in all three variants.** A
+ * `cards` grid of six titles under one section is six children of that section, and
+ * a `rows` set of forty is forty, and both read correctly to a reader navigating by
+ * heading. The level is derived rather than written, so a Block embedded one level
+ * deeper than it was authored for carries its titles with it, which is the whole
+ * reason `headingLevel` is a prop. The cost of making the title a heading in the
+ * `compact` variant is an outline of one line per entry, and a forty entry index
+ * is a long outline; that is the price of letting a reader jump to an entry by
+ * heading rather than by scrolling, and it is the price a `rows` set already pays.
+ *
+ * **`at` and `readingTime` are strings, and Prism parses neither.** The Block prints
+ * what it was handed in the mono face. A consumer that wants the platform's own
+ * absolute reading and a relative phrase composes `RelativeTime` itself, because
+ * the date, the locale and the sentence are three facts about the consumer's
+ * content and not one fact about a Block. Formatting a `Date` here would have meant
+ * picking a granularity and a locale, and a consumer in a second locale would then
+ * have had a correct Block rendering its page in the wrong language.
+ *
+ * **The link carries the caller's words, and the Block refuses a link that carries
+ * none.** `href` without `hrefLabel` would render a card with a control on it that
+ * has no text, so the pair is checked before anything is drawn and the run fails
+ * with the name of the field. The pair is flat rather than a union in the way
+ * `CaseStudies01` spells its own, and that is a departure with its cost stated: the
+ * type will let a caller pass `href` alone, and the refusal arrives at render
+ * rather than at build. The reason is that `entries` is a flat list a caller maps
+ * from its own records rather than a set of arms the Block branches between, and a
+ * union on a mapped record is a shape every call site has to satisfy by hand for
+ * one optional pair. A union is the better type and this one is the cheaper
+ * interface, and the diagnostic is what keeps the cheaper one honest.
+ *
+ * **An empty set renders the caller's `empty` node, or nothing at all.** It never
+ * renders a frame, because a dashed box under a section title reads as a section
+ * whose contents failed to load rather than as a section with none, and the honest
+ * state for a set that has not started is for the set not to be there. When
+ * `empty` is passed the section title still draws, so the reader is told which
+ * section is empty and not merely that something is.
+ *
+ * **The three variants draw the same tree, not three trees.** The `li` is the same
+ * element and the entry's content is the same elements in the same order in all
+ * three; the arrangement is carried by the classes on the `li` and the `ul`. Two
+ * trees would have put the same entry in the accessibility tree twice and for a
+ * crawler twice, and a reader who narrowed the window would have watched one copy
+ * swap for the other.
+ *
+ * It is a server Component: no hook, no state and no client code. A caller that
+ * wants a card whose whole area is the link composes `CtaLink` itself in `media` or
+ * in `summary`, which is the arrangement a consumer reaches for when the tile is
+ * the target rather than the name.
+ */
+export function ContentGrid01({ eyebrow, title, description, entries, variant = 'cards', columns = 3, empty, headingLevel = 'h2', className, }) {
+    // Every entry's name is a heading one step below the section that introduces the
+    // set, so a reader navigating by heading meets the entries under the section
+    // rather than as siblings of it.
+    const Title = childLevel(headingLevel);
+    const asCards = variant === 'cards';
+    const asCompact = variant === 'compact';
+    // Checked before anything is drawn, so the run fails once with the name of the
+    // field rather than once per entry with a card that has an unnamed control on it.
+    for (const entry of entries) {
+        if (entry.href !== undefined && entry.hrefLabel === undefined) {
+            throw new Error('ContentGrid01: an entry passed an href with no hrefLabel, so the card would carry a link with no ' +
+                'words on it at all, 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.');
+        }
+    }
+    // An empty set with nothing to say in place of it draws nothing, which is the
+    // state a section that has not started is honestly in.
+    if (entries.length === 0 && empty === undefined)
+        return null;
+    return (_jsxs(Section, { children: [title ? (_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-12" })) : null, entries.length === 0 ? (_jsx("div", { "data-slot": "content-grid-empty", children: empty })) : (_jsx("ul", { "data-slot": "content-grid", "data-variant": variant, className: cn(asCards ? 'grid gap-6' : 'flex flex-col', asCards && TRACKS[columns], className), children: entries.map((entry) => {
+                    const hasMeta = entry.at !== undefined ||
+                        entry.category !== undefined ||
+                        entry.readingTime !== undefined;
+                    const link = entry.href === undefined || entry.hrefLabel === undefined ? null : (_jsx(CtaLink, { href: entry.href, variant: "ghost", size: "sm", className: "self-start", children: entry.hrefLabel }));
+                    return (_jsx("li", { "data-slot": "content-grid-entry", className: cn(asCards && 'h-full', 
+                        // A hairline above every row and none above the first, in both of
+                        // the full-width variants. The rule rather than a border on the
+                        // list, because the list wraps in the cards variant and a rule
+                        // across four columns is four rules.
+                        !asCards && 'border-border border-t pt-4 first:border-t-0', asCompact && 'pb-4'), children: asCards ? (_jsxs(Card, { className: "h-full gap-4 py-5", children: [entry.media ? (_jsx("div", { "data-slot": "content-grid-media", className: "min-w-0", children: entry.media })) : null, _jsxs(CardHeader, { className: "gap-2", children: [_jsx(EntryMeta, { entry: entry }), _jsx(CardTitle, { className: "text-base leading-snug", children: _jsx(Title, { children: entry.title }) })] }), _jsxs(CardContent, { className: "flex flex-col gap-3", children: [_jsx("div", { "data-slot": "content-grid-summary", className: "text-muted-foreground text-pretty text-sm", children: entry.summary }), link] })] })) : (_jsxs("div", { "data-slot": "content-grid-row", className: cn('flex min-w-0 flex-col gap-1.5', asCompact
+                                ? 'sm:grid sm:grid-cols-[minmax(0,1fr)_auto] sm:items-baseline sm:gap-6'
+                                : 'sm:flex-row sm:items-baseline sm:justify-between sm:gap-8'), children: [_jsxs("div", { className: cn('flex min-w-0 flex-col gap-1.5', 
+                                    // The compact arrangement is one line of text rather than
+                                    // two, so the name and the summary sit beside each other and
+                                    // the name takes a fixed share of the width. The row form
+                                    // stacks them, because there the summary is a paragraph and
+                                    // a paragraph beside a title is a column.
+                                    asCompact && 'sm:flex-row sm:items-baseline sm:gap-4'), children: [asCompact ? null : _jsx(EntryMeta, { entry: entry }), _jsx(Title, { className: cn('font-semibold', asCompact ? 'text-sm sm:w-48 sm:shrink-0' : 'text-base'), children: entry.title }), _jsx("div", { "data-slot": "content-grid-summary", className: "text-muted-foreground min-w-0 text-pretty text-sm", children: entry.summary })] }), link !== null || (asCompact && hasMeta) ? (_jsxs("div", { "data-slot": "content-grid-aside", className: "flex shrink-0 items-center gap-3 sm:justify-end", children: [asCompact ? _jsx(EntryMeta, { entry: entry }) : null, link] })) : null] })) }, entry.id));
+                }) }))] }));
+}
+export default ContentGrid01;

package/dist/blocks/content-grid-01/index.d.ts

@@ -0,0 +1,3 @@
+export { ContentGrid01, default } from './content-grid.js';
+export type { ContentGrid01Props, ContentGrid01Entry, ContentGrid01Form, ContentGrid01Columns, } from './content-grid.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/content-grid-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/content-grid-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAMvD,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,gBAAgB,CAAA"}

package/dist/blocks/content-grid-01/index.js

@@ -0,0 +1 @@
+export { ContentGrid01, default } from './content-grid.js';

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

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import { type HeadingLevel } from '../../components/ui/section';
+import { type HeadingLevel } from '../../components/ui/section.js';
 /**
  * One closing action.
  *
@@ -24,23 +24,28 @@ export type Cta01Action = {
     /**
      * Which weight this action draws at, when the caller does not say.
      *
-     * **A panel wants `default` or `secondary`, never `outline`.** This Block draws
-     * its band as a filled `bg-primary` surface and sets the band's ink to
-     * `--primary-foreground`, so every ink inside it is inherited from that panel
-     * rather than from the page. An `outline` action sets its own fill
-     * (`bg-background`) and, before this was settled, left its ink inherited, which
-     * put `--background` behind `--primary-foreground`. In the lavender pack's dark
-     * mode that is `#19171b` behind `#210c33`, or 1.01:1: a focusable, announced,
-     * unreadable button.
+     * **A filled panel wants `secondary` or `outline`, and never `default`.** The
+     * property that decides it is not the ink but the fill: this Block draws its
+     * band as a filled `bg-primary` surface, and `default` fills with `--primary`,
+     * so a `default` action on this band is the band's own colour against the
+     * band's own colour. Its label is legible, because `primary-foreground` on
+     * `primary` is a gated pair, and the control has no edge, which is a different
+     * defect and the reason this sentence is about the fill rather than the text.
      *
-     * Both defaults below are self-contained, which is the property that matters:
-     * `default` pairs `--primary` with `--primary-foreground` and `secondary`
-     * pairs `--secondary` with `--secondary-foreground`, and a pair the Block
-     * chooses cannot be changed by whatever surface the Block is placed on. The
-     * `outline` variant is fixed too, in `cta-link.tsx`, because a variant that
-     * sets a fill should set the matching ink rather than inherit whatever it lands
-     * on. It is kept in the type because a caller may want it once the ink is
-     * explicit, and dropping it would be a smaller answer than the defect.
+     * `secondary` and `outline` are the two that answer, and what makes them
+     * answer is that each states its own ink rather than inheriting one. That is
+     * the part that was broken and is now settled: `outline` carried `bg-background`
+     * with no `text-` of its own, so inside this band it was `--background` behind
+     * the inherited `--primary-foreground`, which in lavender's dark mode measured
+     * 1.01:1 and in the base pack's light mode 1.00:1, a focusable, announced,
+     * unreadable button. The variant is fixed in `cta-link.tsx`, where a variant
+     * that sets a fill now states the matching ink, and
+     * `packages/ui/scripts/check-variant-ink.mjs` is the gate that holds it there.
+     *
+     * So a panel may take all three, and the settled defaults are the two that
+     * carry a fill distinct from the band. Which of the two a given action wants is
+     * the caller's: `secondary` for the one ask, `outline` for the alternative
+     * beside it.
      */
     variant?: 'default' | 'secondary' | 'outline';
 };
@@ -73,10 +78,10 @@ export type Cta01Props = {
      *
      * Its default weight is `outline`, which is the settled answer for the pair:
      * the primary action is filled and this one is not, so the two read as one
-     * decision and one alternative rather than as two competing asks. What `outline`
-     * may not do is inherit its ink from the filled band behind it, and that is
-     * now a property of the variant rather than of where a caller puts it. See
-     * `Cta01Action`'s `variant` for the measurement.
+     * decision and one alternative rather than as two competing asks. It is safe on
+     * the filled band because the variant carries its own ink rather than
+     * inheriting the band's, which is a property of the variant and no longer of
+     * where a caller puts it. See `Cta01Action`'s `variant` for the measurement.
      */
     secondaryAction?: Cta01Action;
     /**
@@ -90,7 +95,13 @@ export type Cta01Props = {
      * here is where to watch it".
      */
     note?: ReactNode;
-    /** Heading level for the headline. See `HeadingLevel`. */
+    /**
+     * Heading level for the headline. See `HeadingLevel`.
+     *
+     * It picks the headline's size as well as its tag, from the table in
+     * `headingSizeClass`, so a banner composed at the default `h2` reads as the
+     * section it is rather than as a second page heading.
+     */
     headingLevel?: HeadingLevel;
 };
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"cta.d.ts","sourceRoot":"","sources":["../../../src/blocks/cta-01/cta.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,OAAO,EAAW,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAExE;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAA;CAC9C,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,SAAS,CAAA;IACtB;;;;;;;;;;;;;;;;;OAiBG;IACH,eAAe,CAAC,EAAE,WAAW,CAAA;IAC7B;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,EACpB,KAAK,EACL,WAAW,EACX,MAAM,EACN,UAAU,EACV,eAAe,EACf,IAAI,EACJ,YAAmB,GACpB,EAAE,UAAU,+BAyDZ;AAED,eAAe,KAAK,CAAA"}
+{"version":3,"file":"cta.d.ts","sourceRoot":"","sources":["../../../src/blocks/cta-01/cta.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,OAAO,EAA6B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAG1F;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAA;CAC9C,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,SAAS,CAAA;IACtB;;;;;;;;;;;;;;;;;OAiBG;IACH,eAAe,CAAC,EAAE,WAAW,CAAA;IAC7B;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,EACpB,KAAK,EACL,WAAW,EACX,MAAM,EACN,UAAU,EACV,eAAe,EACf,IAAI,EACJ,YAAmB,GACpB,EAAE,UAAU,+BAmEZ;AAED,eAAe,KAAK,CAAA"}

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

@@ -1,7 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ArrowRight } from 'lucide-react';
-import { CtaLink } from '../../components/ui/cta-link';
-import { Section } from '../../components/ui/section';
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Section, headingSizeClass } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
 /**
  * A closing call to action on a filled primary surface.
  *
@@ -22,8 +23,16 @@ export function Cta01({ title, description, action, actionSlot, secondaryAction,
      * `SectionHeading`'s muted-surface description colour and `gap-4` would be
      * wrong. So the tag is resolved here and the classes stay surface-specific
      * rather than the heading level being the reason the markup stays hardcoded.
+     *
+     * The size is asked of `headingSizeClass` rather than written here, and that
+     * line is the reason it is not written here. This block drew its heading at one
+     * size for every level, which is the defect `SectionHeading` had too, so a page
+     * whose closing banner sat at the default `h2` would have shown that banner a
+     * step above every other section title on the page and the same size as the
+     * page's own `h1`. Two surfaces answering one question separately is how it
+     * reached two surfaces.
      */
     const Heading = headingLevel;
-    return (_jsx(Section, { className: "py-20", children: _jsxs("div", { className: "bg-primary text-primary-foreground relative overflow-hidden rounded-2xl px-8 py-16 text-center", children: [_jsx("div", { "aria-hidden": true, className: "from-primary-foreground/15 pointer-events-none absolute inset-0 bg-gradient-to-tr to-transparent" }), _jsxs("div", { className: "relative flex flex-col items-center gap-6", children: [_jsx(Heading, { className: "max-w-2xl text-3xl font-semibold tracking-tight text-balance sm:text-4xl", children: title }), description ? (_jsx("p", { className: "max-w-xl text-lg text-pretty opacity-90", children: description })) : null, action ? (_jsxs("div", { className: "flex flex-col items-center gap-3 sm:flex-row", children: [_jsxs(CtaLink, { size: "lg", variant: action.variant ?? 'secondary', href: action.href, newTab: action.newTab, className: "group", children: [action.label, _jsx(ArrowRight, { className: "motion-safe:transition-transform size-4 group-hover:translate-x-0.5" })] }), secondaryAction ? (_jsx(CtaLink, { size: "lg", variant: secondaryAction.variant ?? 'outline', href: secondaryAction.href, newTab: secondaryAction.newTab, children: secondaryAction.label })) : null] })) : actionSlot ? (actionSlot) : null, note ? (_jsx("p", { className: "max-w-2xl text-pretty text-sm opacity-80", children: note })) : null] })] }) }));
+    return (_jsx(Section, { className: "py-20", children: _jsxs("div", { className: "bg-primary text-primary-foreground relative overflow-hidden rounded-2xl px-8 py-16 text-center", children: [_jsx("div", { "aria-hidden": true, className: "from-primary-foreground/15 pointer-events-none absolute inset-0 bg-gradient-to-tr to-transparent" }), _jsxs("div", { className: "relative flex flex-col items-center gap-6", children: [_jsx(Heading, { className: cn('max-w-measure font-semibold tracking-tight text-balance', headingSizeClass(headingLevel)), children: title }), description ? (_jsx("p", { className: "max-w-measure-narrow text-lg text-pretty opacity-90", children: description })) : null, action ? (_jsxs("div", { className: "flex flex-col items-center gap-3 sm:flex-row", children: [_jsxs(CtaLink, { size: "lg", variant: action.variant ?? 'secondary', href: action.href, newTab: action.newTab, className: "group", children: [action.label, _jsx(ArrowRight, { className: "transition-transform size-4 group-hover:translate-x-0.5" })] }), secondaryAction ? (_jsx(CtaLink, { size: "lg", variant: secondaryAction.variant ?? 'outline', href: secondaryAction.href, newTab: secondaryAction.newTab, children: secondaryAction.label })) : null] })) : actionSlot ? (actionSlot) : null, note ? (_jsx("p", { className: "max-w-measure text-pretty text-sm opacity-80", children: note })) : null] })] }) }));
 }
 export default Cta01;

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

@@ -1,3 +1,3 @@
-export { Cta01, default } from './cta';
-export type { Cta01Action, Cta01Props } from './cta';
+export { Cta01, default } from './cta.js';
+export type { Cta01Action, Cta01Props } from './cta.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-export { Cta01, default } from './cta';
+export { Cta01, default } from './cta.js';