@nanisoft/prism-ui 0.13.0 → 0.16.0

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

@@ -0,0 +1,261 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One downloadable artefact: what it is, what shape it is, how big it is, what it
+ * hashes to, and where it goes.
+ *
+ * **`href` and `hrefLabel` are both required, and the second one is the reason
+ * this type is not a set of optional fields.** A download link whose accessible
+ * name is the file's name tells a screen reader user nothing about what activating
+ * it will do: they hear "token-contract.css, link" and the two facts they needed
+ * are the destination and the fact that a transfer is about to start, and the
+ * second of those is the one that decides whether they press it on a metered
+ * connection. "Download" is the word that tells them, so `hrefLabel` is required
+ * rather than defaulted, and the words are the caller's because a product whose
+ * interface says "Get" or "Fetch" has no way to override a default it cannot see.
+ *
+ * **`size` is a number of bytes and `formatSize` carries the ladder, and the
+ * precedent is `FileUploadFile`'s, named here rather than reinvented.** A caller
+ * that hands over "1.2 MB" has done the division, picked a unit, decided the
+ * rounding and written a separator, and has to do all four again in every locale
+ * the product ships in and in every language. The number is a fact about the file
+ * and the sentence is the consumer's. `FileUpload` states that at length and then
+ * carries a default that asks `Intl` for the number and its unit, so the grouping
+ * separators and the unit spelling are the reader's, because "kB" in one language
+ * is "Ko" in another and "KB" in a third.
+ *
+ * **There is no default formatter here, and that is a decision with a cost stated
+ * rather than hidden.** `FileUpload` can carry one because it is a Component and
+ * the ladder lives in the module that owns the row. This is a Block, it composes
+ * no Component that exports a formatter, and copying `FileUpload`'s ladder into a
+ * second module would put byte formatting in two places in one package, which is
+ * the exact shape of defect the token law exists to prevent. So `formatSize` is
+ * required whenever `size` is, the run fails without it, and the honest cost is
+ * that a consumer who wants a formatted size has to reach for the formatter rather
+ * than inherit it. The message names `FileUpload` and the alternative, so a caller
+ * who wants the default has one function to import and one line to write.
+ *
+ * **A checksum renders in the mono face beside the size, and a Block does not
+ * compute one.** A checksum is a fact about bytes, and the bytes this Block has are
+ * a string of source code in a file it does not read: hashing that string would be
+ * hashing the wrong thing, because the artefact a reader downloads is a build
+ * output, a generated file, a tarball of a hundred files, or a signed binary, and
+ * none of those is the string the caller passed in as `name` and `format`. A Block
+ * that computed a digest and printed it would be printing a claim about a file the
+ * reader has never seen, and a reader who checked it would find a mismatch and
+ * conclude the library was wrong, which is the right conclusion for the wrong
+ * reason. So the value is the caller's, and it came from the build that made the
+ * artefact.
+ *
+ * **`format` is a word and `checksum` is a hex string, and they are set
+ * differently on purpose.** A format is something a reader scans for: "PDF",
+ * "CSV", "gz" are three marks that a reader recognises without reading them, and
+ * the mono face is the face this repository annotates machine-readable values
+ * with, so it is machine notation. A checksum is the same face and the same
+ * reason, and it is the only place in this package where a long unbroken run of
+ * characters is a thing a reader is meant to read, which is why it is truncated
+ * rather than wrapped and why a caller who wants the whole digest has a `note`.
+ */
+export type Download01File = {
+    /** The artefact's stable key within the set. */
+    id: string;
+    /**
+     * The artefact's own name, as its authors spell it. It is the row's title, so
+     * it is a heading one step below the section.
+     */
+    name: string;
+    /**
+     * The shape of the artefact, in whatever form the caller's own set uses it.
+     *
+     * Optional, and its absence draws no line rather than an empty one: a set where
+     * every artefact is the same shape has said that in its heading.
+     */
+    format?: string;
+    /**
+     * The artefact's size, in bytes.
+     *
+     * A number and not a formatted string, and the difference is the whole
+     * interface. See `formatSize` on this type, and `FileUploadFile`'s `size` for
+     * the argument at length.
+     */
+    size?: number;
+    /**
+     * Renders this artefact's `size` as the sentence a reader sees.
+     *
+     * Required whenever `size` is, and the run fails without it, because a bare
+     * number in a row with no column header above it is a count with no unit and a
+     * reader cannot use it. `FileUpload` carries a default that asks `Intl` for the
+     * number and its unit in the runtime's own locale, so a caller who wants that
+     * behaviour passes that function, and a caller who wants a fixed locale, a
+     * different base or a fourth rung passes their own.
+     *
+     * It is per artefact rather than one formatter for the set, and the reason is
+     * that a downloads list is very often a mixed set: a byte count for a tarball, a
+     * page count for a guide, a record count for a dataset, and one formatter on
+     * the Block would have to be told to handle all three. The cost is that a caller
+     * who wants one formatter for eleven files writes it eleven times, and the
+     * honest answer is that they hold it in a variable and pass the variable.
+     */
+    formatSize?: (bytes: number) => string;
+    /**
+     * The digest of the artefact, as the build that made it printed it.
+     *
+     * Rendered verbatim beside the size, in the mono face, and never computed here.
+     * See this type's JSDoc for why hashing this Block's own input would be hashing
+     * the wrong bytes.
+     */
+    checksum?: string;
+    /** Where the artefact goes. Required, because this is a list of downloads. */
+    href: string;
+    /**
+     * The words on the download control, and required.
+     *
+     * Never the artefact's own name. See this type's JSDoc for what a screen reader
+     * user is missing when a link's name is the file's name.
+     */
+    hrefLabel: string;
+    /**
+     * A line under the row, for what a reader needs before they press it: a licence,
+     * a retention window, a note that the file is regenerated nightly.
+     *
+     * A node, because a licence is a link and a retention window is a sentence and
+     * a regeneration notice is a `RelativeTime` beside a word, and the three are not
+     * one shape.
+     */
+    note?: ReactNode;
+};
+/**
+ * How the artefacts are drawn: full-width rows or a grid of cards.
+ *
+ * **The type is `Download01Form` 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 the two 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. `ChartForm` and
+ * `ContentGrid01Form` are named the same way for the same reason.
+ */
+export type Download01Form = 'list' | 'cards';
+/** How many cards fit across, for the card arrangement only. */
+export type Download01Columns = 2 | 3;
+/**
+ * The props a Download01 takes.
+ *
+ * Every string is a prop and the Block ships none: no file name, no format, no
+ * size, no checksum, no note and not one word on a download control. A Block that
+ * shipped a download button labelled "Download" would put English into every
+ * consumer's page, and a Block that shipped a list of artefacts would be a
+ * downloads page about somebody else's build output.
+ */
+export type Download01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /**
+     * The section title, and required.
+     *
+     * Not optional as the other Blocks' titles are, because a list of downloads with
+     * no name above it is a column of file names a reader has to be told is a
+     * downloads column, and the artefact names alone are often indistinguishable
+     * from one another.
+     */
+    title: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /**
+     * The artefacts, in the order a reader should meet them.
+     *
+     * Order is the caller's, and the Block does not sort by name, by size or by
+     * date: a downloads list is very often already in the order a build produced and
+     * the most recent release belongs at the top rather than at the letter D.
+     */
+    files: Download01File[];
+    /**
+     * How the set is drawn.
+     *
+     * @defaultValue 'list'
+     *
+     * `list` is the default because a download row carries four facts beside the
+     * name and a row is the only arrangement that gives them a line each, and
+     * `cards` is for a set of two or three large artefacts, such as a report and its
+     * data, where the name and the note are longer than the digest.
+     */
+    variant?: Download01Form;
+    /**
+     * How many cards sit on one line in the `cards` variant. Ignored by `list`,
+     * which has one artefact per line by definition.
+     *
+     * @defaultValue 2
+     */
+    columns?: Download01Columns;
+    /** 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 list of downloadable artefacts: a name, a format, a size, a digest, a note and
+ * a control whose name is the caller's.
+ *
+ * **Every artefact has a control and the control has the caller's words on it,
+ * and that is what the type is built around.** A downloads list without a control
+ * per row is a table of file names, and the action a reader came for is one click
+ * they have to guess at. `hrefLabel` is required beside `href` rather than beside
+ * the type, so a caller cannot pass one without the other, and the reason is a
+ * specific thing a screen reader user is not told: a link named after its file
+ * gives them the destination and not the consequence, and on a metered connection
+ * the consequence is the fact that decides whether they press it. The words are
+ * the caller's rather than a default because a product whose interface says "Get"
+ * or "Fetch" cannot override a default it never sees.
+ *
+ * **`formatSize` is required whenever `size` is, and the run fails without it
+ * rather than printing a bare number.** The precedent is `FileUploadFile`'s and
+ * the ladder is `FileUpload`'s: a number of bytes is a fact about the artefact and
+ * a formatted size is a sentence in a locale, and a caller who has already done
+ * the division has to do it again in every language the product ships in. What is
+ * different here is that no default is carried, and the reason is one source of
+ * truth: `FileUpload` owns a ladder in the module that owns its row, and copying
+ * that ladder into a second module in the same package would be byte formatting
+ * in two places, which is the shape of defect the token law exists to prevent. The
+ * cost is real, and it is that a consumer who wants the default formatter writes
+ * the line rather than inheriting it. The diagnostic names the Component and the
+ * function, so the fix is one import and one line rather than a search.
+ *
+ * **A checksum is drawn and never computed, and the argument is about which bytes
+ * a digest is a fact about.** This Block holds a name, a format, a byte count and
+ * a URL. The artefact a reader downloads is a build output: a tarball of a
+ * hundred files, a generated CSS bundle, a signed binary, a zip with a manifest in
+ * it. None of those is the string this Block was handed, so a digest computed here
+ * would be a digest of nothing the reader can obtain, and a reader who checked it
+ * against the file they downloaded would find a mismatch and conclude the library
+ * was wrong. Which is the right conclusion for the wrong reason, and the worst
+ * outcome available. So the digest travels as a prop, from the build that made the
+ * artefact, and this Block's job is to set it in the mono face beside the size so
+ * a reader can see the two facts that belong together and copy the one they need.
+ *
+ * **The size and the digest are on the annotation line and the name is the
+ * heading, in both variants.** An artefact's name is what a reader is looking for
+ * and it is a heading one step below the section, derived rather than written, so
+ * a Block embedded one level deeper carries its names with it. Everything else is
+ * an annotation: a format, a size, a digest and a note, all in the muted face or
+ * the mono face, all in a line that is allowed to wrap and is never a heading. A
+ * long digest is truncated by the mono face's own overflow rather than wrapped,
+ * because a digest wrapped across two lines is a digest nobody can select and
+ * check, and a caller who needs the whole one in the text has `note`.
+ *
+ * **The two variants draw the same tree, not two.** The name, the annotation line,
+ * the note and the control are the same elements in the same order in both; the
+ * arrangement is carried by the classes on the `li` and the `ul`. Two trees would
+ * have put every artefact in the accessibility tree twice.
+ *
+ * It is a server Component: no hook, no state and no client code. A caller who
+ * wants a `RelativeTime` beside a note composes it there, and a caller who wants a
+ * copy control for a digest composes it there too, which is the arrangement a
+ * `ReactNode` slot exists for.
+ */
+export declare function Download01({ eyebrow, title, description, files, variant, columns, headingLevel, className, }: Download01Props): import("react").JSX.Element | null;
+export default Download01;
+//# sourceMappingURL=download.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../../src/blocks/download-01/download.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAGpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAA;IACV;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,CAAA;AAE7C,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,CAAC,CAAA;AAerC;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;;OAOG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;OAMG;IACH,KAAK,EAAE,cAAc,EAAE,CAAA;IACvB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,cAAc,CAAA;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,UAAU,CAAC,EACzB,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,OAAgB,EAChB,OAAW,EACX,YAAmB,EACnB,SAAS,GACV,EAAE,eAAe,sCA8FjB;AAED,eAAe,UAAU,CAAA"}

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

@@ -0,0 +1,115 @@
+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 artefacts gets.
+ *
+ * Spelled out per count 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, because a three-up row of file names, formats and digests at phone
+ * width is three columns of two words each.
+ */
+const TRACKS = {
+    2: 'sm:grid-cols-2',
+    3: 'sm:grid-cols-2 lg:grid-cols-3',
+};
+/**
+ * The annotation line on one artefact: the format, the size and the digest.
+ *
+ * Drawn only when there is at least one of the three, for the same reason
+ * `ContentGrid01`'s annotation line is: a row with a reserved line for a format
+ * nobody passed is a list whose names sit at two different heights.
+ */
+function FileMeta({ file }) {
+    if (file.format === undefined && file.size === undefined && file.checksum === undefined) {
+        return null;
+    }
+    return (_jsxs("div", { "data-slot": "download-meta", className: "text-muted-foreground flex flex-wrap items-center gap-x-2 gap-y-1 text-xs", children: [file.format ? (_jsx("span", { "data-slot": "download-format", className: "font-mono", children: file.format })) : null, file.size !== undefined && file.formatSize !== undefined ? (_jsx("span", { "data-slot": "download-size", className: "font-mono", children: file.formatSize(file.size) })) : null, file.checksum ? (_jsx("span", { "data-slot": "download-checksum", className: "font-mono", children: file.checksum })) : null] }));
+}
+/**
+ * A list of downloadable artefacts: a name, a format, a size, a digest, a note and
+ * a control whose name is the caller's.
+ *
+ * **Every artefact has a control and the control has the caller's words on it,
+ * and that is what the type is built around.** A downloads list without a control
+ * per row is a table of file names, and the action a reader came for is one click
+ * they have to guess at. `hrefLabel` is required beside `href` rather than beside
+ * the type, so a caller cannot pass one without the other, and the reason is a
+ * specific thing a screen reader user is not told: a link named after its file
+ * gives them the destination and not the consequence, and on a metered connection
+ * the consequence is the fact that decides whether they press it. The words are
+ * the caller's rather than a default because a product whose interface says "Get"
+ * or "Fetch" cannot override a default it never sees.
+ *
+ * **`formatSize` is required whenever `size` is, and the run fails without it
+ * rather than printing a bare number.** The precedent is `FileUploadFile`'s and
+ * the ladder is `FileUpload`'s: a number of bytes is a fact about the artefact and
+ * a formatted size is a sentence in a locale, and a caller who has already done
+ * the division has to do it again in every language the product ships in. What is
+ * different here is that no default is carried, and the reason is one source of
+ * truth: `FileUpload` owns a ladder in the module that owns its row, and copying
+ * that ladder into a second module in the same package would be byte formatting
+ * in two places, which is the shape of defect the token law exists to prevent. The
+ * cost is real, and it is that a consumer who wants the default formatter writes
+ * the line rather than inheriting it. The diagnostic names the Component and the
+ * function, so the fix is one import and one line rather than a search.
+ *
+ * **A checksum is drawn and never computed, and the argument is about which bytes
+ * a digest is a fact about.** This Block holds a name, a format, a byte count and
+ * a URL. The artefact a reader downloads is a build output: a tarball of a
+ * hundred files, a generated CSS bundle, a signed binary, a zip with a manifest in
+ * it. None of those is the string this Block was handed, so a digest computed here
+ * would be a digest of nothing the reader can obtain, and a reader who checked it
+ * against the file they downloaded would find a mismatch and conclude the library
+ * was wrong. Which is the right conclusion for the wrong reason, and the worst
+ * outcome available. So the digest travels as a prop, from the build that made the
+ * artefact, and this Block's job is to set it in the mono face beside the size so
+ * a reader can see the two facts that belong together and copy the one they need.
+ *
+ * **The size and the digest are on the annotation line and the name is the
+ * heading, in both variants.** An artefact's name is what a reader is looking for
+ * and it is a heading one step below the section, derived rather than written, so
+ * a Block embedded one level deeper carries its names with it. Everything else is
+ * an annotation: a format, a size, a digest and a note, all in the muted face or
+ * the mono face, all in a line that is allowed to wrap and is never a heading. A
+ * long digest is truncated by the mono face's own overflow rather than wrapped,
+ * because a digest wrapped across two lines is a digest nobody can select and
+ * check, and a caller who needs the whole one in the text has `note`.
+ *
+ * **The two variants draw the same tree, not two.** The name, the annotation line,
+ * the note and the control are the same elements in the same order in both; the
+ * arrangement is carried by the classes on the `li` and the `ul`. Two trees would
+ * have put every artefact in the accessibility tree twice.
+ *
+ * It is a server Component: no hook, no state and no client code. A caller who
+ * wants a `RelativeTime` beside a note composes it there, and a caller who wants a
+ * copy control for a digest composes it there too, which is the arrangement a
+ * `ReactNode` slot exists for.
+ */
+export function Download01({ eyebrow, title, description, files, variant = 'list', columns = 2, headingLevel = 'h2', className, }) {
+    // An artefact's name is a heading one step below the section that introduces the
+    // set, so a reader navigating by heading meets the artefacts under the section
+    // rather than as siblings of it.
+    const Title = childLevel(headingLevel);
+    const asCards = variant === 'cards';
+    // Checked before anything is drawn, so the run fails once with the name of the
+    // field rather than once per artefact with a row that shows a bare number.
+    for (const file of files) {
+        if (file.size !== undefined && file.formatSize === undefined) {
+            throw new Error(`Download01: the artefact "${file.name}" passed a size with no formatSize, so the row would print a bare ` +
+                'number, and a number with no unit and no column header above it is a count a reader cannot use. Pass a ' +
+                'formatSize, or pass a preformatted size and leave the byte count out. FileUpload carries the default ' +
+                'that asks the platform for the number and its unit in the reader own locale, and its formatSize is the ' +
+                'one to pass here.');
+        }
+    }
+    if (files.length === 0)
+        return null;
+    return (_jsxs(Section, { children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-12" }), _jsx("ul", { "data-slot": "download-list", "data-variant": variant, className: cn(asCards ? 'grid gap-4' : 'flex flex-col', asCards && TRACKS[columns], className), children: files.map((file) => {
+                    const control = (_jsx(CtaLink, { href: file.href, variant: "outline", size: "sm", className: "self-start", children: file.hrefLabel }));
+                    return (_jsx("li", { "data-slot": "download-item", className: cn(asCards && 'h-full', !asCards && 'border-border border-t pt-4 first:border-t-0'), children: asCards ? (_jsxs(Card, { className: "h-full gap-3 py-5", children: [_jsxs(CardHeader, { className: "gap-2", children: [_jsx(FileMeta, { file: file }), _jsx(CardTitle, { className: "text-sm leading-snug", children: _jsx(Title, { children: file.name }) })] }), _jsxs(CardContent, { className: "flex flex-col gap-3", children: [file.note ? (_jsx("div", { "data-slot": "download-note", className: "text-muted-foreground text-pretty text-sm", children: file.note })) : null, control] })] })) : (_jsxs("div", { "data-slot": "download-row", className: "flex min-w-0 flex-col gap-2 sm:flex-row sm:items-baseline sm:justify-between sm:gap-8", children: [_jsxs("div", { className: "flex min-w-0 flex-col gap-1.5", children: [_jsx(FileMeta, { file: file }), _jsx(Title, { className: "text-sm font-semibold", children: file.name }), file.note ? (_jsx("div", { "data-slot": "download-note", className: "text-muted-foreground text-pretty text-sm", children: file.note })) : null] }), _jsx("div", { "data-slot": "download-aside", className: "flex shrink-0 items-center", children: control })] })) }, file.id));
+                }) })] }));
+}
+export default Download01;

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

@@ -0,0 +1,3 @@
+export { Download01, default } from './download.js';
+export type { Download01Props, Download01File, Download01Form, Download01Columns } from './download.js';
+//# sourceMappingURL=index.d.ts.map

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

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

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

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

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

@@ -0,0 +1,128 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One question and the answer to it, and both are the caller's.
+ *
+ * `question` is a string because a question is one sentence and a question mark
+ * ends it, and a node here would let a caller compose a heading out of an emphasis
+ * and a link, which is a different Item. `answer` is a node because an answer is
+ * rarely one sentence: three of the four products that would install this put a
+ * link or a code sample inside it.
+ */
+export type Faq01Question = {
+    /** Stable identity, and the accordion item's value. */
+    id: string;
+    /** The question, as the caller writes it. */
+    question: string;
+    /** The answer, as the caller composes it. */
+    answer: ReactNode;
+};
+/**
+ * The props a Faq01 takes.
+ *
+ * Every string is a prop and the Block ships none: no question, no answer and no
+ * contact label. The contact label in particular is a sentence, and it is the
+ * sentence that says what a reader gets by asking, which is the sentence a
+ * marketing page most often gets wrong and never on purpose.
+ */
+export type Faq01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: ReactNode;
+    /**
+     * The section title.
+     *
+     * Required, unlike most Blocks in this package, and the reason is short: a
+     * question list with no heading is a set of questions floating on a page, and a
+     * reader who arrived from a search has nothing to orient against. A page that
+     * already owns a heading for these questions composes `Accordion` directly
+     * instead, and that is the honest answer rather than making this Block render
+     * nothing useful under no title.
+     */
+    title: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /**
+     * The questions, in the order a reader should meet them.
+     *
+     * Order is the caller's and it is not a small thing: a list of questions is a
+     * set of objections, and the order is the answer to which objection the reader
+     * has by the third row.
+     */
+    questions: readonly Faq01Question[];
+    /**
+     * Which form the list takes.
+     *
+     * `accordion` is the default because most of a FAQ is a set of questions a
+     * reader has not thought of yet, and a collapsed answer is a question they have
+     * not decided to spend anything on. `list` is for the reader who has already
+     * scanned the page and wants to compare two answers at once, and no single
+     * rendering serves both.
+     *
+     * @defaultValue 'accordion'
+     */
+    format?: 'accordion' | 'list';
+    /**
+     * The way out for a reader whose question is not on this page.
+     *
+     * A label and a destination rather than a node, because the honest contact
+     * control is always a link to a place a human reads, and a node here would let a
+     * consumer ship a control that goes nowhere. The label is a prop because it is a
+     * sentence: "Still stuck, talk to us" and "Ask an engineer" are two products'
+     * voices, and a button is the worst place for Prism to have one.
+     */
+    contact?: {
+        label: string;
+        href: string;
+    };
+    /** Heading level for the section title. See `HeadingLevel`. */
+    headingLevel?: HeadingLevel;
+    /** Layout classes for the list. Layout only; every visual property is Prism's. */
+    className?: string;
+};
+/**
+ * A question and answer list, with the section heading and an optional way to ask
+ * a question that is not on the page.
+ *
+ * **The accordion is the default, and the list form exists for the reader the
+ * accordion cannot serve.** A reader who has just arrived at this section has not
+ * decided what they want to know, so a collapsed answer is a question they have not
+ * chosen to spend anything on, and asking four questions costs four taps. A reader
+ * who has scanned the page and wants to weigh two answers against each other wants
+ * them all open at once, and a design system that only ships the accordion makes
+ * that reader open four panels by hand to get there. Both are real readers, the
+ * two forms cost about a page of CSS between them, and picking one would have meant
+ * the other reader was worse served by a decision made once in a design system
+ * rather than once in a page.
+ *
+ * **The keyboard model is `Accordion`'s and this Block does not re-derive it.** The
+ * trigger is a real button, the panel is linked to it by the library, Enter or
+ * Space opens the focused item, and the header announces its expanded state. The
+ * cost of composing rather than deriving is that this Block cannot add a behaviour
+ * to the accordion without forking the Component, and the benefit is that the
+ * behaviour a keyboard reader meets here is the one they meet in a settings panel,
+ * which is the entire reason this package has a Component layer.
+ *
+ * **The list form is a definition list, and that is `NoteGrid01`'s decision
+ * borrowed rather than a new one.** A question is a term and its answer is that
+ * term's explanation, and a `dl` is what tells a screen reader so: it announces
+ * "the question, the answer" per pair rather than reading eight questions and then
+ * eight paragraphs and leaving a reader to pair them up. The alternative was a
+ * `ul` of `li`s with a bold line and a paragraph in each, which is the same
+ * document with the structure taken out of it.
+ *
+ * **The contact control is a real `CtaLink`, under the last answer, and its label
+ * is a prop.** It is a link rather than a button because it goes somewhere, and a
+ * button that navigates nothing is announced as a command that does nothing. It
+ * sits under the list rather than beside the heading because a reader who has read
+ * eight answers and found none of them is in a different frame of mind from one
+ * who has read nothing, and the sentence they need is the one that acknowledges
+ * it.
+ *
+ * It is a server Component: no hook, no state and no client code of its own. The
+ * `accordion` form composes `Accordion`, which ships its own client directive
+ * because it owns the open set, so a consumer pays for the accordion and not for
+ * this Block, and a consumer who uses `format="list"` pays for neither.
+ */
+export declare function Faq01({ eyebrow, title, description, questions, format, contact, headingLevel, className, }: Faq01Props): import("react").JSX.Element;
+export default Faq01;
+//# sourceMappingURL=faq.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"faq.d.ts","sourceRoot":"","sources":["../../../src/blocks/faq-01/faq.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAStC,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAGxF;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAA;IACV,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAA;IAChB,6CAA6C;IAC7C,MAAM,EAAE,SAAS,CAAA;CAClB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;;;OASG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;OAMG;IACH,SAAS,EAAE,SAAS,aAAa,EAAE,CAAA;IACnC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC7B;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACzC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,KAAK,CAAC,EACpB,OAAO,EACP,KAAK,EACL,WAAW,EACX,SAAS,EACT,MAAoB,EACpB,OAAO,EACP,YAAmB,EACnB,SAAS,GACV,EAAE,UAAU,+BA+CZ;AAED,eAAe,KAAK,CAAA"}

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

@@ -0,0 +1,53 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger, } from '../../components/ui/accordion.js';
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * A question and answer list, with the section heading and an optional way to ask
+ * a question that is not on the page.
+ *
+ * **The accordion is the default, and the list form exists for the reader the
+ * accordion cannot serve.** A reader who has just arrived at this section has not
+ * decided what they want to know, so a collapsed answer is a question they have not
+ * chosen to spend anything on, and asking four questions costs four taps. A reader
+ * who has scanned the page and wants to weigh two answers against each other wants
+ * them all open at once, and a design system that only ships the accordion makes
+ * that reader open four panels by hand to get there. Both are real readers, the
+ * two forms cost about a page of CSS between them, and picking one would have meant
+ * the other reader was worse served by a decision made once in a design system
+ * rather than once in a page.
+ *
+ * **The keyboard model is `Accordion`'s and this Block does not re-derive it.** The
+ * trigger is a real button, the panel is linked to it by the library, Enter or
+ * Space opens the focused item, and the header announces its expanded state. The
+ * cost of composing rather than deriving is that this Block cannot add a behaviour
+ * to the accordion without forking the Component, and the benefit is that the
+ * behaviour a keyboard reader meets here is the one they meet in a settings panel,
+ * which is the entire reason this package has a Component layer.
+ *
+ * **The list form is a definition list, and that is `NoteGrid01`'s decision
+ * borrowed rather than a new one.** A question is a term and its answer is that
+ * term's explanation, and a `dl` is what tells a screen reader so: it announces
+ * "the question, the answer" per pair rather than reading eight questions and then
+ * eight paragraphs and leaving a reader to pair them up. The alternative was a
+ * `ul` of `li`s with a bold line and a paragraph in each, which is the same
+ * document with the structure taken out of it.
+ *
+ * **The contact control is a real `CtaLink`, under the last answer, and its label
+ * is a prop.** It is a link rather than a button because it goes somewhere, and a
+ * button that navigates nothing is announced as a command that does nothing. It
+ * sits under the list rather than beside the heading because a reader who has read
+ * eight answers and found none of them is in a different frame of mind from one
+ * who has read nothing, and the sentence they need is the one that acknowledges
+ * it.
+ *
+ * It is a server Component: no hook, no state and no client code of its own. The
+ * `accordion` form composes `Accordion`, which ships its own client directive
+ * because it owns the open set, so a consumer pays for the accordion and not for
+ * this Block, and a consumer who uses `format="list"` pays for neither.
+ */
+export function Faq01({ eyebrow, title, description, questions, format = 'accordion', contact, headingLevel = 'h2', className, }) {
+    return (_jsxs(Section, { children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-10" }), _jsxs("div", { "data-slot": "faq", "data-format": format, className: cn('flex max-w-measure flex-col', className), children: [format === 'accordion' ? (_jsx(Accordion, { className: "border-t", children: questions.map((item) => (_jsxs(AccordionItem, { value: item.id, children: [_jsx(AccordionTrigger, { children: item.question }), _jsx(AccordionContent, { children: item.answer })] }, item.id))) })) : (_jsx("dl", { "data-slot": "faq-list", className: "border-t", children: questions.map((item) => (_jsxs("div", { "data-slot": "faq-item", className: "border-border border-b py-5", children: [_jsx("dt", { className: "text-sm font-medium text-balance", children: item.question }), _jsx("dd", { className: "text-muted-foreground mt-2 text-pretty text-sm", children: item.answer })] }, item.id))) })), contact ? (_jsx("div", { "data-slot": "faq-contact", className: "mt-8", children: _jsx(CtaLink, { variant: "outline", href: contact.href, children: contact.label }) })) : null] })] }));
+}
+export default Faq01;

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

@@ -0,0 +1,3 @@
+export { Faq01, default } from './faq.js';
+export type { Faq01Props, Faq01Question } from './faq.js';
+//# sourceMappingURL=index.d.ts.map

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

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

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

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