@nanisoft/prism-ui 0.13.0 → 0.16.0

package/dist/blocks/offering-list-01/offering-list.js

@@ -0,0 +1,366 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useMemo } from 'react';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '../../components/ui/card.js';
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { FactList } from '../../components/ui/fact-list.js';
+import { Price } from '../../components/ui/price.js';
+import { SearchField } from '../../components/ui/search-field.js';
+import { Section, SectionHeading, childLevel } from '../../components/ui/section.js';
+import { Status } from '../../components/ui/status.js';
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow, } from '../../components/ui/table.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The tone each of a product's own capability words maps to.
+ *
+ * Whole words, matched whole rather than as substrings, so a state called
+ * `unavailable-for-maintenance` is not read as `available` and a state called
+ * `not-supported` is not read as `supported`. The table is a guess and says so, and
+ * anything it does not name comes out `neutral`, which is the design: `neutral` is
+ * the tone that asserts nothing, so a state this Block has never heard of costs a
+ * colour and not a lie. The words themselves are never changed.
+ */
+const STATE_TONE = new Map([
+    ['available', 'success'],
+    ['live', 'success'],
+    ['enabled', 'success'],
+    ['general-availability', 'success'],
+    ['production', 'success'],
+    ['ready', 'success'],
+    ['supported', 'success'],
+    ['beta', 'info'],
+    ['in-preview', 'info'],
+    ['limited', 'info'],
+    ['pilot', 'info'],
+    ['preview', 'info'],
+    ['trial', 'info'],
+    ['backlog', 'neutral'],
+    ['coming-soon', 'neutral'],
+    ['planned', 'neutral'],
+    ['roadmap', 'neutral'],
+    ['deprecated', 'destructive'],
+    ['discontinued', 'destructive'],
+    ['end-of-life', 'destructive'],
+    ['retired', 'destructive'],
+    ['sunset', 'destructive'],
+    ['unavailable', 'destructive'],
+    ['withdrawn', 'destructive'],
+]);
+/**
+ * The classes each cell takes, before the caller's own layout classes merge in.
+ *
+ * The name and the standfirst wrap because both are sentences, and the state, the
+ * price and the link do not because all three are short and a wrapping state mark
+ * reads as a second line of prose.
+ */
+const CELL = {
+    name: 'font-medium whitespace-normal',
+    standfirst: 'text-muted-foreground whitespace-normal',
+    state: 'whitespace-nowrap',
+    price: 'whitespace-nowrap',
+    facts: 'whitespace-normal',
+    href: 'text-right whitespace-nowrap',
+};
+/**
+ * The query in the form the match reads it: case folded, split on whitespace, with
+ * the empty tokens dropped.
+ *
+ * The tokens are AND rather than OR, for the reason `Help01` gives for the same
+ * step: a reader who types two words is narrowing, and with OR a catalogue returns
+ * nearly everything, which is not a result but a list the reader has to work through
+ * themselves.
+ */
+function tokensOf(query) {
+    return query.toLowerCase().split(/\s+/).filter((token) => token.length > 0);
+}
+/**
+ * Whether every token appears somewhere in one case-folded string.
+ *
+ * A substring test with no stemming and no typo tolerance, which is the same
+ * downgrade `SearchDialog` and `Help01` take and for the same reason: a fuzzy
+ * engine is a large dependency whose ranking a consumer cannot restyle, audit
+ * against this package's gates or replace without forking the Block.
+ */
+function containsAll(haystack, tokens) {
+    return tokens.every((token) => haystack.includes(token));
+}
+/**
+ * The tone one of the caller's own state words is drawn in.
+ *
+ * `STATE_TONE` when it recognises the word whole, and `neutral` when it does not.
+ * The neutral fallback is the design rather than an oversight: `Status` says
+ * `neutral` is the tone for a state with nothing to alarm about, so a word this
+ * Block has never heard of costs a colour and not a lie.
+ */
+function toneOf(state) {
+    return STATE_TONE.get(state.trim().toLowerCase()) ?? 'neutral';
+}
+/**
+ * The capability's limits in the shape `FactList` draws, which is what both
+ * arrangements use.
+ *
+ * A `FactList` inside a table cell is a definition list inside a cell, which is
+ * valid and is the reason the `facts` cell exists at all. The cost is stated rather
+ * than hidden: a table that carries a specification per row is a tall table, and a
+ * caller whose capabilities have three or four limits each is better served by the
+ * cards arrangement here or by a `spec-table-01` beside the list. Re-deriving a
+ * compact specification for the cell instead would put a second answer to "how does
+ * a specification read" in one package.
+ */
+function factsOf(offering) {
+    return (offering.facts ?? []).map((fact) => ({ label: fact.label, value: fact.value }));
+}
+/**
+ * The cell one column draws for one capability.
+ *
+ * A switch rather than a map of render functions, for the reason `FieldMap01`
+ * gives: a map keyed by cell id would be a second recipe of the kind this package
+ * keeps off the public surface, and a switch over six cases is the same table with
+ * the strings in the same file as the drawing that uses them.
+ */
+function cellOf(id, offering) {
+    switch (id) {
+        case 'standfirst':
+            return offering.standfirst ?? null;
+        case 'state':
+            if (offering.state === undefined)
+                return null;
+            return (_jsx(Status, { size: "sm", tone: toneOf(offering.state), label: offering.stateLabel ?? offering.state }));
+        case 'price':
+            if (offering.price === undefined)
+                return null;
+            return _jsx(Price, { ...offering.price, size: "md" });
+        case 'facts':
+            return _jsx(FactList, { facts: factsOf(offering) });
+        case 'href':
+            if (offering.href === undefined || offering.hrefLabel === undefined)
+                return null;
+            return (_jsx(CtaLink, { href: offering.href, variant: "ghost", size: "sm", children: offering.hrefLabel }));
+        case 'name':
+            return offering.name;
+    }
+}
+/**
+ * A set of capabilities as cards or as a real table, with an optional search, a
+ * filter slot and an empty state.
+ *
+ * **The storefront version of this pattern is a product listing page, and the
+ * translation is the noun.** What that page publishes is a grid of items for sale
+ * and, on the same surface, the category strip above it: a filter row, a sort
+ * control, a result count, and a card or a comparison table per item. Every part of
+ * the layout and every part of the accessibility work transfers unchanged, because a
+ * result count is a polite live region whichever set it counts and a comparison
+ * table is a table whichever things it compares. What does not transfer is the
+ * thing being listed. The rows here are capabilities a product offers: capture
+ * sources, agents, connectors, tiers. A reader is not choosing between things to
+ * buy, so there is no sort by price worth defaulting to and no add-to-basket in the
+ * card, and the state mark on each row answers a different question than stock ever
+ * does.
+ *
+ * **The search is optional as a pair, and the reason is the count of rows, which is
+ * a fact about the set rather than about the design.** A static list of twelve
+ * capabilities does not need one, because twelve rows are shorter than a phone
+ * screen at the size this Block draws them, so a reader who wants one of them either
+ * sees it or does not and scrolling is a shorter act than typing. Worse than
+ * useless, it is a claim: a search field says the set is too large to read, and a
+ * reader who believes it and finds twelve rows has been told the page is bigger
+ * than it is. A list of two hundred cannot do without one, because there the reader
+ * genuinely does not know whether the thing they want is present. So `value`,
+ * `onValueChange`, `label` and `clearLabel` travel together, the run throws when
+ * half a pair is passed, and the Block draws no field and filters nothing when the
+ * pair is absent. The rejected default was a field on every list, which is the shape
+ * most catalogue templates reach for first.
+ *
+ * **The state is an open string and the tones are still mapped, and the difference
+ * between those two facts is the argument.** A product has its own vocabulary for
+ * what a capability is doing, and between them the products that compose this Block
+ * already use more states than any closed set here could hold. A closed set would
+ * force every one of them to map its words onto ours and ship a translation nobody
+ * asked for, and the translation is the part that rots: the week a product adds a
+ * state, every map is a version behind and the table is confidently wrong about
+ * where its own capabilities are, with nothing on the page to say so. So the words
+ * cross the seam untouched, and the Block still colours the row, because a table of
+ * plain text is missing the one thing a reader was scanning for. The colouring is a
+ * whole-word match against the stated list above, and anything the list does not
+ * name comes out `neutral`, which is the tone that asserts nothing. The cost is
+ * named rather than hidden: a product whose states need different colours draws its
+ * own `Status` in a column of its own, and that costs the consumer a column rather
+ * than costing every consumer a wrong tone.
+ *
+ * **`Offering01` takes a closed union of four states and this Block takes an open
+ * string, and the two are not an inconsistency.** One capability in depth can be
+ * given a type that says which answers exist and a diagnostic when it is given
+ * none. A catalogue of forty rows cannot afford to refuse to render a row over a
+ * word it has not heard of, and the whole argument for a closed set evaporates at
+ * that size. Two answers, each right at its own scale.
+ *
+ * **The table is `table.tsx` and not a grid of `div`s, for the reason
+ * `ResourceList01` states in full.** Comparison is what a table is for, and the three
+ * things a `<div>` grid gets wrong are the three a reader comparing capabilities
+ * needs: there is no `th` to navigate by, there is no association between a row's
+ * name and its cells, and there is nothing for a browser's own table commands to
+ * act on. So every column header is a `th` with `scope="col"` and every capability
+ * name is a `th` with `scope="row"`, and the table is the one `table.tsx` draws in
+ * the one scroll container it draws.
+ *
+ * **The column names are the caller's and the cells are this Block's.** `columns` is
+ * required in the table arrangement and refused outside it, so a declared column
+ * set can never sit in the markup drawing nothing. What the Block does not do is
+ * accept a cell function the way `DataTableColumn` does, because the six cells are
+ * closed. The cost is real: a caller whose table needs a seventh fact per
+ * capability cannot render it here, and the answer is `DataTable01`, which is a
+ * table section with the caller's own cells and a toolbar, at the cost of every
+ * label on it.
+ *
+ * **The search composes `SearchField`, so the clear control, the one tab stop and
+ * the polite result region are that Component's rather than a second implementation
+ * here.** The result line is where `summary` goes when there is a search, and above
+ * the set when there is not, so a caller who passes it gets it either way and never
+ * sees it twice.
+ *
+ * **The card title is a heading one step below the section, derived rather than
+ * written.** A set of forty capabilities is forty titles under one heading, so they
+ * nest, and moving this Block from an `h2` section to an `h3` one carries them with
+ * it. In the table arrangement the names are row headers and not headings, because a
+ * table's names are not sections and forty of them in the outline is a list a reader
+ * has to walk past.
+ *
+ * **The heading is aligned left**, because the set is content and it sits under the
+ * heading. `SectionHeading` states the rule and this Block has rows underneath it.
+ *
+ * It is a client Component, and the reason is the filtering rather than the field:
+ * the query is a prop the caller holds, the set that results is derived from it on
+ * every keystroke, and a server Component cannot re-render its own children. It
+ * owns no state of its own, so the client cost is one `useMemo` over the rows the
+ * caller passed and not a running loop. Because it carries the directive, a
+ * consumer's server file can still render it: the directive puts this module in the
+ * client graph, and the props crossing into it are data.
+ */
+export function OfferingList01({ eyebrow, title, description, value, onValueChange, label, clearLabel, offerings, toolbar, filters, summary, empty, variant = 'cards', columns, headingLevel = 'h2', className, }) {
+    // The handle a table below takes its name from; see the note on the table.
+    const headingId = useId();
+    const searching = onValueChange !== undefined;
+    /*
+     * The search is a pair or it is nothing, and every half of that is a throw rather
+     * than a silent omission. A field with no handler cannot be typed into and does
+     * not filter, which is a control that looks live and is not. A handler with no
+     * name is announced as a search box. A handler with no clear label leaves the
+     * reader unable to empty the field except by selecting the text, which is the
+     * defect `SearchField` was made controlled to end. And a `value` with no handler
+     * is state that cannot change, which is the half of a controlled field that
+     * cannot be emptied.
+     */
+    if (searching && (label === undefined || label.trim() === '')) {
+        throw new Error('OfferingList01: onValueChange was passed with no label, so the search field would be announced as a ' +
+            'search box, which is the one name every other field of its kind on the page shares. Pass the words ' +
+            'that say what is being searched.');
+    }
+    if (searching && (clearLabel === undefined || clearLabel.trim() === '')) {
+        throw new Error('OfferingList01: onValueChange was passed with no clearLabel, so the field would carry no way to ' +
+            'empty it except selecting the text and deleting it a character at a time. Pass the words that name ' +
+            'the control that clears it.');
+    }
+    if (!searching && (label !== undefined || clearLabel !== undefined || value !== undefined)) {
+        throw new Error('OfferingList01: a label, a clear label or a query was passed with no onValueChange, so the field ' +
+            'would be drawn dead or not drawn at all while the props say the set is searchable. A search over a ' +
+            'set of a dozen rows is a control that does nothing useful; pass the whole pair or none of it.');
+    }
+    if (variant === 'table' && (columns === undefined || columns.length === 0)) {
+        throw new Error('OfferingList01: the table arrangement was chosen with no columns, so the header row would have no ' +
+            'words and a screen reader user would be told about four columns of values with no idea which is ' +
+            'which. Name the columns, or use the cards arrangement.');
+    }
+    if (variant !== 'table' && columns !== undefined) {
+        throw new Error('OfferingList01: columns were declared for the cards arrangement, where no column is drawn, so the ' +
+            'column names would be published in the documentation and rendered nowhere. Declare the columns, or ' +
+            'choose the table arrangement.');
+    }
+    /*
+     * Checked before anything is drawn, so the run fails once with the name of the
+     * field rather than once per row with a malformed table on the page.
+     */
+    if (columns !== undefined) {
+        const seen = new Set();
+        for (const column of columns) {
+            const id = column.id;
+            if (seen.has(id)) {
+                throw new Error(`OfferingList01: the column "${id}" is declared twice, so the table would have two columns ` +
+                    'reading the same value and every cell after the first would be read under the wrong name. ' +
+                    'Declare each cell once.');
+            }
+            if (id !== 'name' && !offerings.some((offering) => carries(offering, id))) {
+                throw new Error(`OfferingList01: the "${id}" column was declared and no capability carries it, so the ` +
+                    'table would carry a column of empty cells, which is a column every reader scans twice. Pass ' +
+                    'the value on at least one capability, or drop the column.');
+            }
+            seen.add(id);
+        }
+        if (!seen.has('name')) {
+            throw new Error('OfferingList01: the columns name no "name" cell, so the header row would have a cell fewer than ' +
+                'every body row and no row would have a header for a reader to navigate into. Declare the name ' +
+                'column, which is also the row header for every row.');
+        }
+    }
+    for (const offering of offerings) {
+        if (offering.href !== undefined && (offering.hrefLabel === undefined || offering.hrefLabel.trim() === '')) {
+            throw new Error(`OfferingList01: the capability "${offering.name}" declares an href with no hrefLabel, so the link ` +
+                'would carry no words of its own and a reader would not know what activating it does. Pass the ' +
+                'words that say what it does, or omit the href.');
+        }
+    }
+    // A card title nests one level below the section that introduces the set, so a
+    // reader who has learned the outline on one Block finds it the same on this one.
+    const Title = childLevel(headingLevel);
+    const tokens = useMemo(() => tokensOf(searching ? (value ?? '') : ''), [searching, value]);
+    const visible = useMemo(() => {
+        // No handler means no search, so the whole set is the resting state and the
+        // Block draws nothing that claims to narrow it. See the JSDoc for why.
+        if (!searching || tokens.length === 0)
+            return offerings;
+        /*
+         * Only the name is searched, and that is a limit rather than an oversight. The
+         * standfirst, the state and the price are all nodes, and matching them would mean
+         * walking the caller's markup for words, which is a Block reading somebody else's
+         * content looking for something to search. A caller who wants a standfirst
+         * searched passes a name that carries the words their readers would type, and the
+         * alternative is a search that matches on words nobody can see.
+         */
+        return offerings.filter((offering) => containsAll(offering.name.toLowerCase(), tokens));
+    }, [offerings, searching, tokens]);
+    const count = visible.length;
+    return (_jsxs(Section, { "data-slot": "offering-list-01", className: className, children: [_jsx(SectionHeading, { as: headingLevel, id: headingId, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-10" }), _jsxs("div", { "data-slot": "offering-list-01-controls", className: "mb-8 flex flex-col gap-4", children: [toolbar === undefined ? null : (_jsx("div", { "data-slot": "offering-list-01-toolbar", children: toolbar })), searching ? (_jsx("div", { "data-slot": "offering-list-01-search", className: "w-full max-w-measure-narrow", children: _jsx(SearchField, { value: value ?? '', onValueChange: onValueChange, label: label, clearLabel: clearLabel, resultSummary: summary === undefined ? undefined : summary(count) }) })) : summary === undefined ? null : (_jsx("p", { "data-slot": "offering-list-01-summary", className: "text-muted-foreground text-sm", children: summary(count) })), filters === undefined ? null : (_jsx("div", { "data-slot": "offering-list-01-filters", children: filters }))] }), count === 0 ? (
+            /*
+             * The caller's own sentence, drawn where the capabilities would have been
+             * rather than above them, so a reader is not told there is nothing at the
+             * foot of a page that shows a catalogue. `text-pretty` is here because the
+             * honest empty line is sometimes a paragraph and `text-balance` would leave
+             * a one-word last line in it.
+             */
+            _jsx("p", { "data-slot": "offering-list-01-empty", className: "text-muted-foreground max-w-measure-narrow text-pretty", children: empty })) : variant === 'table' && columns !== undefined ? (_jsx("div", { "data-slot": "offering-list-01-table", className: cn('border-border overflow-hidden rounded-xl border', className), children: _jsxs(Table, { "aria-labelledby": headingId, children: [_jsx(TableHeader, { children: _jsx(TableRow, { children: columns.map((column) => (_jsx(TableHead, { scope: "col", className: column.className, children: column.header }, column.id))) }) }), _jsx(TableBody, { children: visible.map((offering) => (_jsx(TableRow, { "data-slot": "offering-list-01-row", "data-offering": offering.id, children: columns.map((column) => 
+                                // The name is a row header, so a reader who navigates into a
+                                // single cell is told which capability they are looking at rather
+                                // than hearing a state with nothing to attach it to.
+                                column.id === 'name' ? (_jsx(TableHead, { scope: "row", className: cn(CELL[column.id], column.className), children: offering.name }, column.id)) : (_jsx(TableCell, { className: cn(CELL[column.id], column.className), children: cellOf(column.id, offering) }, column.id))) }, offering.id))) })] }) })) : (_jsx("ul", { "data-slot": "offering-list-01-cards", className: cn('grid gap-6', 'sm:grid-cols-2 lg:grid-cols-3', className), children: visible.map((offering) => (_jsx("li", { "data-slot": "offering-list-01-card", "data-offering": offering.id, className: "h-full", children: _jsxs(Card, { className: "h-full gap-4 py-6", children: [_jsxs(CardHeader, { children: [_jsx(CardTitle, { as: Title, children: offering.name }), offering.standfirst === undefined ? null : (_jsx(CardDescription, { children: offering.standfirst }))] }), _jsxs(CardContent, { className: "flex flex-1 flex-col gap-4", children: [offering.state === undefined ? null : (_jsx(Status, { size: "sm", tone: toneOf(offering.state), label: offering.stateLabel ?? offering.state })), offering.price === undefined ? null : (_jsx(Price, { ...offering.price, size: "md" })), _jsx(FactList, { facts: factsOf(offering) }), offering.href === undefined || offering.hrefLabel === undefined ? null : (_jsx(CtaLink, { href: offering.href, variant: "ghost", size: "sm", className: "self-start", children: offering.hrefLabel }))] })] }) }, offering.id))) }))] }));
+}
+/**
+ * Whether at least one capability carries the value a column draws.
+ *
+ * A separate step so the column check reads as a sentence rather than as a chain of
+ * optional fields, and so adding a seventh cell later is one line here rather than
+ * four edits across the checks above.
+ */
+function carries(offering, id) {
+    switch (id) {
+        case 'standfirst':
+            return offering.standfirst !== undefined;
+        case 'state':
+            return offering.state !== undefined;
+        case 'price':
+            return offering.price !== undefined;
+        case 'facts':
+            return offering.facts !== undefined;
+        case 'href':
+            return offering.href !== undefined;
+    }
+}
+export default OfferingList01;

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

@@ -0,0 +1,3 @@
+export { Onboarding01, default } from './onboarding.js';
+export type { OnboardingState, OnboardingStep, Onboarding01Props } from './onboarding.js';
+//# sourceMappingURL=index.d.ts.map

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

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

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

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

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

@@ -0,0 +1,199 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * The four states a setup step can be in.
+ *
+ * Four, and the fourth is the one this Block is most particular about. `done`,
+ * `current` and `upcoming` are the three a sequence has, and they are the three
+ * `steps.tsx` already draws. `blocked` is not a position in a sequence: it is a
+ * fact about this run, and it is here because a checklist that can only say done
+ * and not done and next will read as broken to a reader who is genuinely stuck. A
+ * reader who thinks a product is broken stops trusting the product, and they are
+ * right to, so a Block that cannot say "you are blocked here" is a Block that
+ * answers that reader with a lie by omission.
+ */
+export type OnboardingState = 'done' | 'current' | 'upcoming' | 'blocked';
+/**
+ * One thing the reader has to do, or has done, or will do.
+ *
+ * `state` is required because a step nobody has placed in the sequence is a
+ * reminder, and a reminder is a different surface. `stateLabel` is optional in the
+ * type and required in practice, and the run throws without it, for the reason
+ * every mark in this package is paired with words: a shape is not a sentence, and
+ * "Connected your warehouse" and "Waiting on your warehouse" are two different
+ * things to be done at the same step.
+ */
+export type OnboardingStep = {
+    /** A stable key for the step, and what `onSelect` reports. */
+    id: string;
+    /** What the step is, in the words a reader would use in conversation. */
+    name: string;
+    /**
+     * A line or two about what this step involves, for a reader who has arrived at
+     * it.
+     *
+     * A node and not a string, because the honest line is sometimes a link to the
+     * thing being asked about, a code sample, or a sentence with the caller's own
+     * product name in it, and a `string` would force a flattening that loses whichever
+     * of those it could not hold.
+     */
+    description?: ReactNode;
+    /**
+     * Where the step stands.
+     *
+     * `blocked` is a first-class state here and the JSDoc on `OnboardingState` says
+     * why in full: a checklist that cannot say a reader is stuck will read as broken
+     * to a reader who is, and a reader who thinks a product is broken stops trusting
+     * it.
+     */
+    state: OnboardingState;
+    /** The words for that state, in the product's own voice. */
+    stateLabel?: string;
+    /**
+     * The control that acts on this step, beside it.
+     *
+     * A slot and not a named button, because what a step offers is the caller's fact:
+     * a connect control, a documentation link, a "skip for now", a retry. Refused
+     * outright when `onSelect` is set, because a row cannot be a control and contain
+     * one, and the run says so rather than drawing a link inside a button.
+     */
+    action?: ReactNode;
+    /** Where the step goes. Rendered as a native anchor, so the destination is real. */
+    href?: string;
+    /** The words on that link. Required whenever `href` is set. */
+    hrefLabel?: string;
+};
+/**
+ * The props an Onboarding01 takes.
+ *
+ * Every string and every number is a prop and the Block ships none: no step, no
+ * state, no sentence, no count and not the sentence that says how far along the
+ * reader is. The progress figure is the sharpest version of the rule, because a
+ * checklist that shipped "3 of 6 complete" would put an English sentence and a
+ * plural rule into every consumer's product, and the reader's locale owns both.
+ */
+export type Onboarding01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /** The section title. Required, because a checklist with no heading is a fragment. */
+    title: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /**
+     * The steps, in the order the reader should do them.
+     *
+     * Order is the caller's and it is a claim: this is a route through a setup, and a
+     * list in an order the setup does not have is a wrong diagram rather than a layout
+     * problem.
+     */
+    steps: OnboardingStep[];
+    /**
+     * Called with a step's `id` when the reader picks one.
+     *
+     * Omit it and the checklist is a list of what is outstanding rather than a set of
+     * controls, which is a legitimate state and the right one for a checklist whose
+     * steps are done elsewhere.
+     */
+    onSelect?: (id: string) => void;
+    /**
+     * The sentence the progress figure is named by, given the counts.
+     *
+     * Required, and a function rather than a template string for the reason
+     * `RelativeTime` gives about a relative phrase: it has a plural, it changes shape
+     * past one, and every language words it differently. A Block that composed it
+     * would compose the English one and ship it into every consumer's product, where a
+     * reader in any other language would be shown a count they have to translate in
+     * their head.
+     */
+    progressLabel: (done: number, total: number) => string;
+    /**
+     * The note under the figure, for whatever the caller wants said about it: what
+     * happens when the last step is done, what a blocked step needs, where to read
+     * more. Omit it and the figure is the whole of the state, which is honest and
+     * thin.
+     */
+    completion?: ReactNode;
+    /**
+     * Whether the steps are a checklist of what is outstanding or a rail of the order.
+     *
+     * `checklist` is the default, and the reason is who is reading. A reader who has
+     * been here once is looking for the one thing left, and a rail of numbered steps
+     * answers a question they are not asking: it shows the whole route, which is a
+     * document about the order rather than a list of what is outstanding. `steps` is
+     * for the first run, when the order is the point and a reader who has never seen
+     * the setup needs to know what comes after what.
+     */
+    variant?: 'checklist' | 'steps';
+    /**
+     * What the Block renders in place of the steps when there are none.
+     *
+     * Required, and a slot rather than a string, because a setup with no steps is
+     * either a product that has nothing to set up or a caller whose query returned
+     * nothing, and those are opposite claims.
+     */
+    empty: ReactNode;
+    /** Heading level for the section title. See `HeadingLevel`. */
+    headingLevel?: HeadingLevel;
+    /** Layout only, exactly as on every Block. */
+    className?: string;
+};
+/**
+ * A setup checklist: the steps that are done, the one the reader is on, the one they
+ * are stuck on, and a figure that says how much is left.
+ *
+ * **A reader here is either on a first run or on a return visit, and the default
+ * form is the one for the return visit.** That is the whole argument for
+ * `checklist` being the default rather than the alternative: a reader who has been
+ * here once is looking for the one thing left, and a rail of numbered steps answers
+ * a question they are not asking. It shows the whole route, marks each step and
+ * draws a rule between them, which is a document about the order, and a document
+ * about the order is what a reader needs on a first run and is one screen too much
+ * on the second. So the default is a list of what is outstanding, where the one
+ * outstanding thing is findable in a glance, and `steps` is the rail for the first
+ * run.
+ *
+ * **`blocked` is a first-class state, and it is the decision this Block is most
+ * particular about.** A checklist that can only say done, and not done and next, is
+ * a checklist that will read as broken to a reader who is genuinely stuck: the step
+ * they are on looks exactly like the step they have not reached, and the honest
+ * reading of a setup that has not moved in a week is a broken product rather than a
+ * missing permission, a missing key or a colleague who has not got to it. A reader
+ * who believes the product is broken stops trusting the product, and they are not
+ * wrong to, so a Block that cannot say "you are blocked here" is answering that
+ * reader with a lie by omission. The mark is the one shape on this surface that is
+ * not a disc, so a reader who sees no colour at all still finds it, and the words
+ * beside it are the caller's because what a reader is waiting for is the
+ * product's own sentence about it.
+ *
+ * **The rail is `steps.tsx` for the `steps` form, because the rail is a Component
+ * and its three marks are already right.** A hand-drawn set of discs would be a
+ * second implementation of three things `Steps` has settled: that the states differ
+ * by shape before they differ by colour, that exactly one step carries
+ * `aria-current`, and that the rule between the steps carries how far along the
+ * reader is rather than a bar per step restating "done" once per step. The cost is
+ * the rail's own limitation rather than this Block's, and the run refuses it rather
+ * than dropping it: a rail has no room for a description, a control, a moment or a
+ * fourth state, so a step carrying any of those is a step the caller wants in the
+ * checklist, and the diagnostic says so.
+ *
+ * **The progress figure is `Metric`, and the sentence under it is the caller's.**
+ * `Metric` owns the arrangement a headline figure is read in, which puts the figure
+ * first and the name under it, and it owns the fact that a string figure is set in
+ * the mono face while a composed one is not. What it cannot do is name the figure,
+ * and the honest answer is that the name is `progressLabel`: "steps complete" is a
+ * claim about what a step is, and a checklist in a consumer's product may well be a
+ * checklist of deployments, of regions, or of approvals. So the figure is the count
+ * of what is done and the words under it are the caller's sentence, which is the
+ * same split `Waitlist01` makes about a position and for the same reason.
+ *
+ * **It is a client Component, and the reason is `onSelect` rather than any state of
+ * its own.** A handler is a function, a function is a piece of state, and state is a
+ * client module, so the directive is here. The cost is stated rather than hidden: a
+ * checklist that takes no `onSelect` is still a client Component, because the
+ * directive is a property of the module rather than of a call, and the alternative
+ * was a Block whose `onSelect` silently did nothing in a server render, which is
+ * worse than a client boundary nobody asked for.
+ */
+export declare function Onboarding01({ eyebrow, title, description, steps, onSelect, progressLabel, completion, variant, empty, headingLevel, className, }: Onboarding01Props): import("react").JSX.Element;
+export default Onboarding01;
+//# sourceMappingURL=onboarding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.d.ts","sourceRoot":"","sources":["../../../src/blocks/onboarding-01/onboarding.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAIxF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAA;AAsCzE;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAA;IACV,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;OAOG;IACH,KAAK,EAAE,eAAe,CAAA;IACtB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sFAAsF;IACtF,KAAK,EAAE,SAAS,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;OAMG;IACH,KAAK,EAAE,cAAc,EAAE,CAAA;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B;;;;;;;;;OASG;IACH,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACtD;;;;;OAKG;IACH,UAAU,CAAC,EAAE,SAAS,CAAA;IACtB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAA;IAC/B;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,YAAY,CAAC,EAC3B,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,QAAQ,EACR,aAAa,EACb,UAAU,EACV,OAAqB,EACrB,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,iBAAiB,+BAqOnB;AAED,eAAe,YAAY,CAAA"}