@nanisoft/prism-ui 0.10.2 → 0.15.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/empty-state-01/empty-state.d.ts

@@ -0,0 +1,143 @@
+import type { ReactNode } from 'react';
+/**
+ * The three reasons a region has nothing in it.
+ *
+ * **Three, and the set is closed because the three want different words and
+ * different actions, so a consumer who cannot say which one they have writes
+ * "No data".** That is the whole failure this Block exists to prevent, and it is
+ * a failure rather than a style preference because the three are answers to three
+ * different questions and the reader acts on each one differently:
+ *
+ * - `first-run` - nothing has ever existed here. The reader is not blocked, they
+ *   are at the beginning, and the action is to *make the first one*. A sentence
+ *   that says nothing is available and an action that creates is the whole state.
+ * - `no-match` - things exist and the reader's own filter removed all of them.
+ *   The reader is not at the beginning and nothing is missing; the action is to
+ *   *widen or clear the filter*, and offering to create something here invents
+ *   work the reader does not need.
+ * - `not-permitted` - things exist and this reader may not see them. The action
+ *   is to *ask for access or change context*, and a create action here is a lie
+ *   about what the reader can do, which is worse than no action at all.
+ *
+ * A fourth such as `error` or `loading` is deliberately absent: those are states
+ * the surrounding surface already owns, and a region that is erroring has an
+ * `Alert` and a region that is loading has a `Spinner`. A Block that drew them
+ * would give a consumer two places to put the same fact.
+ *
+ * @see EMPTY_REASONS
+ */
+export declare const EMPTY_REASONS: readonly ["first-run", "no-match", "not-permitted"];
+/**
+ * One of the three reasons a region has nothing in it.
+ *
+ * The reason is a machine value and never reader-facing text. The words are the
+ * consumer's: two products call the same state "Nothing here yet" and "Your
+ * account is new", and neither sentence is Prism's to publish.
+ */
+export type EmptyReason = (typeof EMPTY_REASONS)[number];
+/**
+ * The props an EmptyState01 takes.
+ *
+ * Every string is a prop and the Block ships none: no headline, no sentence, no
+ * action label and no reason word. A Block that rendered "No data" would put a
+ * sentence about a product that is not its own into four consumer sites, and the
+ * corpus publishes it as the design system's own voice.
+ */
+export type EmptyState01Props = {
+    /**
+     * Which of the three situations this is. Required rather than defaulted,
+     * because the default would be the one that hides the bug: a Block that
+     * defaulted to `first-run` would render a create action beside a permission
+     * boundary, and a Block that defaulted to `no-match` would tell every reader
+     * their own filter removed something on their first visit. Making the caller
+     * name the reason is what stops either from happening quietly.
+     */
+    reason: EmptyReason;
+    /**
+     * The headline: what is not here, in the reader's own words. Required, because
+     * the Block's only job is to carry a sentence and a reason together, and a
+     * region with a frame and no words is a box a reader has to interpret.
+     */
+    title: string;
+    /**
+     * The sentence under the headline, for the part the headline cannot fit: what
+     * to do about it, or what the reader should know before they act. Omit it when
+     * the headline is the whole message.
+     */
+    body?: string;
+    /**
+     * The label of the one action, in the product's own words.
+     *
+     * Optional, and its absence is a legitimate state rather than a gap: a region
+     * a reader cannot act on - a permission boundary, an archived-only view, a
+     * feature that is switched off for their plan - has no next step, and inventing
+     * one is how an empty state ends up offering a reader a button that cannot
+     * help them. `reason` does not require it either, because the same rule applies
+     * across the three: the action exists when the reader has something to do.
+     */
+    actionLabel?: string;
+    /**
+     * The handler for `actionLabel`. Required whenever `actionLabel` is passed, and
+     * the Block throws without it rather than rendering a button that does nothing:
+     * a disabled-looking control with no `disabled` is a control that lies.
+     */
+    onAction?: () => void;
+    /**
+     * The mark above the words, as a slot.
+     *
+     * A slot and not an icon the Block picks, because the mark that means "nothing
+     * here yet" and the mark that means "you cannot see this" are different marks,
+     * and a Block that chose one would give four products an icon that is wrong for
+     * one of the three reasons. It is `aria-hidden` wherever a consumer puts it: the
+     * reason is carried by the words, and an icon a screen reader reads is a second
+     * announcement of the same sentence.
+     */
+    icon?: ReactNode;
+    /**
+     * Layout only, exactly as on every Component and Block. Changing a Prism-owned
+     * visual property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * The state a region shows when it has nothing in it: a framed mark, a headline,
+ * a sentence and at most one action.
+ *
+ * **The design decision is the `reason` prop, and it is the reason this is a Block
+ * rather than a Component.** An empty state looks like one thing, which is why it
+ * has been written by hand in every product that has one, and it is actually three
+ * things that need different words and different actions. A component with a
+ * `title` and a `body` and an `action` cannot express the difference, so every
+ * consumer re-decides it in their own words and at least one of them gets it
+ * wrong: a permission boundary that offers "Create your first project", or a
+ * first-run state that says "No results found". Naming the reason forces the
+ * decision into the open and gives the Block something to enforce.
+ *
+ * **A Block and not a Component because it is a composition of five decisions
+ * rather than one control.** A mark, a headline, a sentence, an action and a
+ * region-sized frame: each of those has been re-decided by hand in every product
+ * that has an empty state, and `DESIGN.md` records the resolution of the retired
+ * `empty` Component as exactly this shape. It ships no copy, takes no data and
+ * fetches nothing.
+ *
+ * **The region keeps its size.** The frame is a `min-h-*` and a dashed border
+ * rather than a fixed height, and it is drawn with `size-*` on the mark, because
+ * an empty state is what a region looks like *before* its content arrives. A
+ * region that is one line tall while it is empty and forty lines tall once it is
+ * full moves everything below it twice, and the reader's eye has to find the
+ * thing twice. This is the same layout shift the `Spinner` records as its own
+ * honest cost, and the reason a `first-run` frame wants a floor under it.
+ *
+ * **The action is one, and it is not required.** An empty state offering three
+ * actions is a form, and a form in a region that has nothing in it is a form with
+ * nothing to submit. One action is the next step; the rest belong in the
+ * surrounding surface, where the reader can see them without this region
+ * competing.
+ *
+ * It is a server Component. It holds no state and imports no client code, so a
+ * consumer that passes a client action inside it pays for the action and not for
+ * the frame.
+ */
+export declare function EmptyState01({ reason, title, body, actionLabel, onAction, icon, className, }: EmptyState01Props): import("react").JSX.Element;
+export default EmptyState01;
+//# sourceMappingURL=empty-state.d.ts.map

package/dist/blocks/empty-state-01/empty-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty-state.d.ts","sourceRoot":"","sources":["../../../src/blocks/empty-state-01/empty-state.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,aAAa,qDAAsD,CAAA;AAEhF;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AAuBxD;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;OAOG;IACH,MAAM,EAAE,WAAW,CAAA;IACnB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EACN,KAAK,EACL,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,IAAI,EACJ,SAAS,GACV,EAAE,iBAAiB,+BAoEnB;AAED,eAAe,YAAY,CAAA"}

package/dist/blocks/empty-state-01/empty-state.js

@@ -0,0 +1,104 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from '../../components/ui/button.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The three reasons a region has nothing in it.
+ *
+ * **Three, and the set is closed because the three want different words and
+ * different actions, so a consumer who cannot say which one they have writes
+ * "No data".** That is the whole failure this Block exists to prevent, and it is
+ * a failure rather than a style preference because the three are answers to three
+ * different questions and the reader acts on each one differently:
+ *
+ * - `first-run` - nothing has ever existed here. The reader is not blocked, they
+ *   are at the beginning, and the action is to *make the first one*. A sentence
+ *   that says nothing is available and an action that creates is the whole state.
+ * - `no-match` - things exist and the reader's own filter removed all of them.
+ *   The reader is not at the beginning and nothing is missing; the action is to
+ *   *widen or clear the filter*, and offering to create something here invents
+ *   work the reader does not need.
+ * - `not-permitted` - things exist and this reader may not see them. The action
+ *   is to *ask for access or change context*, and a create action here is a lie
+ *   about what the reader can do, which is worse than no action at all.
+ *
+ * A fourth such as `error` or `loading` is deliberately absent: those are states
+ * the surrounding surface already owns, and a region that is erroring has an
+ * `Alert` and a region that is loading has a `Spinner`. A Block that drew them
+ * would give a consumer two places to put the same fact.
+ *
+ * @see EMPTY_REASONS
+ */
+export const EMPTY_REASONS = ['first-run', 'no-match', 'not-permitted'];
+/**
+ * The one thing that differs between the three frames.
+ *
+ * **The frame is shared and the difference is an ink, and that is a decision
+ * about honesty rather than about looks.** All three get the same dashed edge and
+ * the same floor under them, because all three mean *there is nothing here to
+ * read*. What they must not share is a claim about why, and a tint or a border
+ * hue would be one: a region drawn in a warning colour tells the reader their
+ * filter, or their permissions, is a problem, and in the second case it is not.
+ *
+ * So only `not-permitted` carries an ink, and it is `muted-foreground` rather
+ * than a destructive tone. A permission boundary is not a failure, and painting
+ * it red teaches a reader to ignore red for the things that are urgent. The
+ * distinction the reader actually needs is *you cannot see this* against *this is
+ * broken*, and the words carry it; the frame says only that the region is empty,
+ * which is true of all three.
+ */
+const REASON_INK = {
+    'not-permitted': 'text-muted-foreground',
+};
+/**
+ * The state a region shows when it has nothing in it: a framed mark, a headline,
+ * a sentence and at most one action.
+ *
+ * **The design decision is the `reason` prop, and it is the reason this is a Block
+ * rather than a Component.** An empty state looks like one thing, which is why it
+ * has been written by hand in every product that has one, and it is actually three
+ * things that need different words and different actions. A component with a
+ * `title` and a `body` and an `action` cannot express the difference, so every
+ * consumer re-decides it in their own words and at least one of them gets it
+ * wrong: a permission boundary that offers "Create your first project", or a
+ * first-run state that says "No results found". Naming the reason forces the
+ * decision into the open and gives the Block something to enforce.
+ *
+ * **A Block and not a Component because it is a composition of five decisions
+ * rather than one control.** A mark, a headline, a sentence, an action and a
+ * region-sized frame: each of those has been re-decided by hand in every product
+ * that has an empty state, and `DESIGN.md` records the resolution of the retired
+ * `empty` Component as exactly this shape. It ships no copy, takes no data and
+ * fetches nothing.
+ *
+ * **The region keeps its size.** The frame is a `min-h-*` and a dashed border
+ * rather than a fixed height, and it is drawn with `size-*` on the mark, because
+ * an empty state is what a region looks like *before* its content arrives. A
+ * region that is one line tall while it is empty and forty lines tall once it is
+ * full moves everything below it twice, and the reader's eye has to find the
+ * thing twice. This is the same layout shift the `Spinner` records as its own
+ * honest cost, and the reason a `first-run` frame wants a floor under it.
+ *
+ * **The action is one, and it is not required.** An empty state offering three
+ * actions is a form, and a form in a region that has nothing in it is a form with
+ * nothing to submit. One action is the next step; the rest belong in the
+ * surrounding surface, where the reader can see them without this region
+ * competing.
+ *
+ * It is a server Component. It holds no state and imports no client code, so a
+ * consumer that passes a client action inside it pays for the action and not for
+ * the frame.
+ */
+export function EmptyState01({ reason, title, body, actionLabel, onAction, icon, className, }) {
+    if (actionLabel !== undefined && onAction === undefined) {
+        throw new Error(`EmptyState01: an actionLabel of '${actionLabel}' was passed with no onAction, so the button ` +
+            'would read as available and do nothing. Pass the handler, or drop the label and leave the ' +
+            'region without a next step.');
+    }
+    return (_jsxs("div", { "data-slot": "empty-state", "data-reason": reason, className: cn(
+        // Centred and given a floor under it, because this is the whole of the
+        // region rather than a note beside content. `min-h-64` is roughly six
+        // lines, which is what a full page of rows costs; a shorter empty state
+        // makes the region jump when its content arrives.
+        'border-border bg-card flex min-h-64 flex-col items-center justify-center gap-3 rounded-xl border border-dashed p-8 text-center', REASON_INK[reason], className), children: [icon === undefined ? null : (_jsx("div", { "data-slot": "empty-state-icon", "aria-hidden": true, className: "text-muted-foreground flex-none", children: icon })), _jsx("p", { "data-slot": "empty-state-title", className: "text-base font-semibold text-balance", children: title }), body === undefined ? null : (_jsx("p", { "data-slot": "empty-state-body", className: "text-muted-foreground max-w-measure-narrow text-pretty text-sm", children: body })), actionLabel === undefined ? null : (_jsx(Button, { "data-slot": "empty-state-action", type: "button", className: "mt-2", onClick: onAction, children: actionLabel }))] }));
+}
+export default EmptyState01;

package/dist/blocks/empty-state-01/index.d.ts

@@ -0,0 +1,3 @@
+export { EmptyState01, EMPTY_REASONS, default } from './empty-state.js';
+export type { EmptyState01Props, EmptyReason } from './empty-state.js';
+//# sourceMappingURL=index.d.ts.map