@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/blocks/auth-form-01/auth-form.js

@@ -14,13 +14,36 @@ import { Input } from '../../components/ui/input.js';
  * submit control. It owns no credentials and no request: every field value and
  * the submit handler come from the consumer, and the error line is a prop so
  * the consumer's validation decides when it appears. Every string is a prop.
+ *
+ * **An error is one message about the submission, and it marks at most one field.**
+ * The two are separate decisions because a form-level sentence is usually not about
+ * a control at all: bad credentials, a locked account and a rate limit are all
+ * things no field is wrong about. The message is drawn in an `Alert`, which
+ * announces itself, and the field the caller names in `errorId` carries
+ * `aria-invalid`, and every other field carries nothing. Marking them all was the
+ * arrangement before, and it told a reader that two fields they had filled in
+ * correctly were wrong.
+ *
+ * **A field's description is drawn under it and referred to by it.** The id is
+ * derived from the field's own `id`, which is already the one stable caller-owned
+ * string on the field, so the reference costs a template and cannot collide.
  */
 export function AuthForm01({ title, description, fields, error, remember, submitLabel, pendingLabel, pending = false, onSubmit, footer, headingLevel = 'h2', }) {
     // This Block draws no section heading, so the card title is the one heading it
     // renders and takes the level directly rather than a step below one.
     const Title = headingLevel;
-    return (_jsx("form", { onSubmit: onSubmit, className: "w-full", children: _jsxs(Card, { children: [_jsxs(CardHeader, { children: [_jsx(CardTitle, { children: _jsx(Title, { children: title }) }), description ? _jsx(CardDescription, { children: description }) : null] }), _jsxs(CardContent, { className: "flex flex-col gap-4", children: [error ? (_jsxs(Alert, { variant: "destructive", children: [_jsx(CircleAlert, {}), _jsx(AlertDescription, { children: error })] })) : null, _jsx(FieldGroup, { children: fields.map((field) => (_jsxs(Field, { children: [_jsx(FieldLabel, { htmlFor: field.id, children: field.label }), _jsx(Input, { id: field.id, type: field.type ?? 'text', placeholder: field.placeholder, autoComplete: field.autoComplete, value: field.value, defaultValue: field.defaultValue, onChange: field.onChange
-                                            ? (event) => field.onChange?.(event.target.value)
-                                            : undefined, required: field.required, disabled: field.disabled, "aria-invalid": error ? true : undefined }), field.description ? (_jsx(FieldDescription, { children: field.description })) : null] }, field.id))) }), remember ? (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Checkbox, { id: remember.id, checked: remember.checked, defaultChecked: remember.defaultChecked, onCheckedChange: remember.onCheckedChange, disabled: remember.disabled }), _jsx(FieldLabel, { htmlFor: remember.id, children: remember.label })] })) : null] }), _jsxs(CardFooter, { className: "flex-col gap-3", children: [_jsx(Button, { type: "submit", className: "w-full", disabled: pending, children: pending ? (pendingLabel ?? submitLabel) : submitLabel }), footer] })] }) }));
+    return (_jsx("form", { onSubmit: onSubmit, className: "w-full", children: _jsxs(Card, { children: [_jsxs(CardHeader, { children: [_jsx(CardTitle, { children: _jsx(Title, { children: title }) }), description ? _jsx(CardDescription, { children: description }) : null] }), _jsxs(CardContent, { className: "flex flex-col gap-4", children: [error ? (_jsxs(Alert, { variant: "destructive", children: [_jsx(CircleAlert, {}), _jsx(AlertDescription, { children: error })] })) : null, _jsx(FieldGroup, { children: fields.map((field) => {
+                                /*
+                                 * Derived from the field's own id rather than from a `useId`, because
+                                 * `field.id` is already the one stable, caller-owned string on the
+                                 * field and a generated one would have to be threaded through the
+                                 * description and the input to meet itself.
+                                 */
+                                const descriptionId = field.description === undefined ? undefined : `${field.id}-description`;
+                                const marked = error !== undefined && field.errorId === field.id;
+                                return (_jsxs(Field, { children: [_jsx(FieldLabel, { htmlFor: field.id, children: field.label }), _jsx(Input, { id: field.id, type: field.type ?? 'text', placeholder: field.placeholder, autoComplete: field.autoComplete, value: field.value, defaultValue: field.defaultValue, onChange: field.onChange
+                                                ? (event) => field.onChange?.(event.target.value)
+                                                : undefined, required: field.required, disabled: field.disabled, "aria-invalid": marked ? true : undefined, ...(descriptionId === undefined ? null : { 'aria-describedby': descriptionId }) }), field.description === undefined ? null : (_jsx(FieldDescription, { id: descriptionId, children: field.description }))] }, field.id));
+                            }) }), remember ? (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Checkbox, { id: remember.id, checked: remember.checked, defaultChecked: remember.defaultChecked, onCheckedChange: remember.onCheckedChange, disabled: remember.disabled }), _jsx(FieldLabel, { htmlFor: remember.id, children: remember.label })] })) : null] }), _jsxs(CardFooter, { className: "flex-col gap-3", children: [_jsx(Button, { type: "submit", className: "w-full", disabled: pending, children: pending ? (pendingLabel ?? submitLabel) : submitLabel }), footer] })] }) }));
 }
 export default AuthForm01;

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

@@ -0,0 +1,156 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One recognition: the body that gave it, the organisation they gave it to, the
+ * year, and where the record is.
+ *
+ * The field called `body` is the work, not a sentence describing it. A reader
+ * checks the name of the work first, so the work is the anchor of the row and the
+ * awarding body and the date are the two facts that sit beside it.
+ */
+export type Awards01Award = {
+    /**
+     * A stable key for the row.
+     *
+     * Required, and carried on the markup as `data-award`, so a test can name one
+     * recognition rather than the first one and two recognitions in one list are
+     * individually addressable. Two bodies can win the same recognition in the
+     * same year, which is the case a name used as a key fails on.
+     */
+    id: string;
+    /**
+     * The work that was recognised, named as the awarding body names it.
+     *
+     * The anchor of the row and the card title. It is a public claim: a name that
+     * is not the body's own spelling of the work reads as a correction of the record.
+     */
+    body: string;
+    /**
+     * The organisation that gave the recognition.
+     *
+     * Not the body that received it and not the publisher of the list. This is who
+     * decided, which is the half of a recognition a reader cannot infer from the
+     * name of the work.
+     */
+    organisation: string;
+    /**
+     * The year the recognition was given, as the awarding body writes it.
+     *
+     * Required, and required by law rather than by habit: see the Block's JSDoc for
+     * why an undated award is a logo with words. A body that gives an award every
+     * year writes a year, a season or a date. A body that has not published since
+     * has not given one, and the honest entry for that is not an award.
+     */
+    year: string;
+    /**
+     * The category or track, when the awarding body splits its recognition into
+     * more than one.
+     *
+     * Rendered as an outlined `Badge` rather than as another line of copy, because
+     * a category is a label a reader scans past rather than a sentence they read.
+     * The words are the caller's own, since a body names its own tracks.
+     */
+    category?: string;
+    /**
+     * Where the record is.
+     *
+     * A native anchor `href`, so the whole row is a link with the browser's own
+     * affordances. Omit it for a recognition whose record is not public, and the
+     * row is then read rather than followed; nothing about a missing destination is
+     * inferred.
+     */
+    href?: string;
+};
+/**
+ * The props an Awards01 takes.
+ *
+ * Every string is a prop and the Block ships none: no body, no year, no category
+ * and not one award. A list of recognitions that hardcoded any of them would hand
+ * every consumer who installed it a claim about that consumer's own work.
+ */
+export type Awards01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /** The section title. Omit it for a list composed under its own heading. */
+    title?: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /**
+     * The recognitions, in the order a reader should meet them.
+     *
+     * Order is a claim about what the reader should see first, and the Block does
+     * not sort. A caller who wants recency has a year on every row and can sort on
+     * it in one line of their own code; a Block that sorted would be deciding what
+     * a consumer is proudest of.
+     */
+    awards: readonly Awards01Award[];
+    /**
+     * `list` draws hairline rows. `cards` draws a card per recognition with the
+     * work as its title.
+     *
+     * @defaultValue 'list'
+     */
+    layout?: 'list' | 'cards';
+    /** Heading level for the section title. See `HeadingLevel`. */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Component. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A list of recognitions: who gave it, what for, and the year it was given.
+ *
+ * **This is a separate Item from `logo-cloud-01` because a logo and an award are
+ * not the same kind of claim.** A logo is a mark, and a mark says only who works
+ * with us, which is a fact about a relationship and one that does not expire. An
+ * award is a sentence: a body decided something about a piece of work, on a
+ * date, and wrote it down. A consumer can show a mark they were given this
+ * morning or a recognition from eleven years ago; they cannot show an award
+ * without the year, because the year is the part of the sentence that is a fact
+ * about when it was true, and the part that goes out of date. So the date is a
+ * required field here, set in the mono face beside the organisation rather than
+ * inside the body copy, which is what separates the two Blocks visually as well
+ * as factually.
+ *
+ * **A missing year is a thrown diagnostic, and that is the Block's whole argument.**
+ * An award with no date is not an award: it is a logo with words attached, and
+ * the words are the half that would let a reader believe it. The date is the part
+ * that expires and the part a reader checks, because a recognition has a
+ * currency, and an undated one cannot be stale, so it never goes out of date and
+ * therefore never has to be withdrawn. A consumer who wants a band of marks
+ * already has `logo-cloud-01`, where no date is required because no date is
+ * claimed, so there is nothing here for the undated case to fall back on.
+ *
+ * **`trust-strip-01` is the same content without the date, and it is a different
+ * Item because it makes a weaker claim.** The strip is one line, undated,
+ * unlinked, and reads as a general assurance, so it can hold "Recognised by
+ * leading industry bodies" where a dated record would be a claim nobody has
+ * checked. Both are correct and neither is interchangeable: a consumer who swaps
+ * one for the other is upgrading an assurance into a record, which is an
+ * editorial and legal decision rather than a layout one. So the two Blocks do
+ * not merge and neither takes the fields of the other.
+ *
+ * **A row with a destination is a native anchor and a row without one is not a
+ * disabled link.** The whole row is the anchor in the list arrangement and the
+ * whole card is the anchor in the cards arrangement, so the destination shows in
+ * the status bar, a context menu can copy it and middle click opens it. The card
+ * arrangement puts the anchor outside the card rather than inside it, so the
+ * focus ring bounds the card rather than the words in it, which is the argument
+ * `Item` states in full: a ring around a box that sized itself to its own text is
+ * not an indicator.
+ *
+ * The list arrangement is a `ul`, so a reader hears how many recognitions there
+ * are before the first one. A card title is composed at `childLevel(headingLevel)`
+ * rather than at a fixed level, so a set embedded one level deeper than it was
+ * written for carries its titles with it. An empty set renders nothing, for the
+ * reason `ProductSwitcher` and `AvatarGroup` each state: an empty frame is worse
+ * than an absent one.
+ *
+ * It is a server Component: no hook, no state, no client code and no motion
+ * beyond the transition on a row that is a link.
+ */
+export declare function Awards01({ eyebrow, title, description, awards, layout, headingLevel, className, }: Awards01Props): import("react").JSX.Element | null;
+export default Awards01;
+//# sourceMappingURL=awards.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"awards.d.ts","sourceRoot":"","sources":["../../../src/blocks/awards-01/awards.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAEpG;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;;;;OAOG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;OAOG;IACH,MAAM,EAAE,SAAS,aAAa,EAAE,CAAA;IAChC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACzB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAqDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,QAAQ,CAAC,EACvB,OAAO,EACP,KAAK,EACL,WAAW,EACX,MAAM,EACN,MAAe,EACf,YAAmB,EACnB,SAAS,GACV,EAAE,aAAa,sCAsGf;AAED,eAAe,QAAQ,CAAA"}

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

@@ -0,0 +1,102 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Badge } from '../../components/ui/badge.js';
+import { Card, CardHeader, CardTitle } from '../../components/ui/card.js';
+import { Section, SectionHeading, childLevel } from '../../components/ui/section.js';
+/**
+ * The two facts that sit beside the work: who decided, and when.
+ *
+ * Two elements rather than one joined string, and the reason is the mono stack.
+ * The organisation is the interface face and the year is set in mono, because a
+ * year is a machine reading and this system annotates those in mono everywhere
+ * else. A single string could not be both, and a year set in the interface face
+ * beside a wordmark stops reading as a value. The pair is a `flex` column in the
+ * list arrangement and a baseline row in the cards arrangement, and both read in
+ * the same order: who, then when, then what for.
+ */
+function AwardAttribution({ organisation, year, }) {
+    return (_jsxs(_Fragment, { children: [_jsx("span", { "data-slot": "awards-organisation", className: "text-sm font-semibold", children: organisation }), _jsx("span", { "data-slot": "awards-year", className: "text-muted-foreground font-mono text-xs", children: year })] }));
+}
+/**
+ * The check that makes this Block an argument rather than a list.
+ *
+ * A year that is absent or blank throws, and the diagnostic names the reason in
+ * the words a developer needs: an undated award is a logo with words attached. A
+ * throw rather than a fallback because there is no fallback that is not a claim.
+ * An empty year cell is a visible gap in the middle of a public record, and a
+ * year this Block invented would be worse than either. Rendering nothing would
+ * be quietest and worst, because a consumer who published the page would never
+ * learn that their record was incomplete.
+ */
+function assertYear(award) {
+    if (typeof award.year !== 'string' || award.year.trim() === '') {
+        throw new Error('Awards01: an award declares no year, and an undated award is a logo with words attached. Pass the year ' +
+            'the awarding body published, or use a block that makes no dated claim, such as a logo cloud or a trust ' +
+            'strip.');
+    }
+}
+/**
+ * A list of recognitions: who gave it, what for, and the year it was given.
+ *
+ * **This is a separate Item from `logo-cloud-01` because a logo and an award are
+ * not the same kind of claim.** A logo is a mark, and a mark says only who works
+ * with us, which is a fact about a relationship and one that does not expire. An
+ * award is a sentence: a body decided something about a piece of work, on a
+ * date, and wrote it down. A consumer can show a mark they were given this
+ * morning or a recognition from eleven years ago; they cannot show an award
+ * without the year, because the year is the part of the sentence that is a fact
+ * about when it was true, and the part that goes out of date. So the date is a
+ * required field here, set in the mono face beside the organisation rather than
+ * inside the body copy, which is what separates the two Blocks visually as well
+ * as factually.
+ *
+ * **A missing year is a thrown diagnostic, and that is the Block's whole argument.**
+ * An award with no date is not an award: it is a logo with words attached, and
+ * the words are the half that would let a reader believe it. The date is the part
+ * that expires and the part a reader checks, because a recognition has a
+ * currency, and an undated one cannot be stale, so it never goes out of date and
+ * therefore never has to be withdrawn. A consumer who wants a band of marks
+ * already has `logo-cloud-01`, where no date is required because no date is
+ * claimed, so there is nothing here for the undated case to fall back on.
+ *
+ * **`trust-strip-01` is the same content without the date, and it is a different
+ * Item because it makes a weaker claim.** The strip is one line, undated,
+ * unlinked, and reads as a general assurance, so it can hold "Recognised by
+ * leading industry bodies" where a dated record would be a claim nobody has
+ * checked. Both are correct and neither is interchangeable: a consumer who swaps
+ * one for the other is upgrading an assurance into a record, which is an
+ * editorial and legal decision rather than a layout one. So the two Blocks do
+ * not merge and neither takes the fields of the other.
+ *
+ * **A row with a destination is a native anchor and a row without one is not a
+ * disabled link.** The whole row is the anchor in the list arrangement and the
+ * whole card is the anchor in the cards arrangement, so the destination shows in
+ * the status bar, a context menu can copy it and middle click opens it. The card
+ * arrangement puts the anchor outside the card rather than inside it, so the
+ * focus ring bounds the card rather than the words in it, which is the argument
+ * `Item` states in full: a ring around a box that sized itself to its own text is
+ * not an indicator.
+ *
+ * The list arrangement is a `ul`, so a reader hears how many recognitions there
+ * are before the first one. A card title is composed at `childLevel(headingLevel)`
+ * rather than at a fixed level, so a set embedded one level deeper than it was
+ * written for carries its titles with it. An empty set renders nothing, for the
+ * reason `ProductSwitcher` and `AvatarGroup` each state: an empty frame is worse
+ * than an absent one.
+ *
+ * It is a server Component: no hook, no state, no client code and no motion
+ * beyond the transition on a row that is a link.
+ */
+export function Awards01({ eyebrow, title, description, awards, layout = 'list', headingLevel = 'h2', className, }) {
+    if (awards.length === 0)
+        return null;
+    const Title = childLevel(headingLevel);
+    return (_jsxs(Section, { className: className, children: [title ? (_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-12" })) : null, layout === 'cards' ? (_jsx("ul", { "data-slot": "awards", "data-layout": layout, className: "grid gap-6 sm:grid-cols-2", children: awards.map((award) => {
+                    assertYear(award);
+                    const card = (_jsx(Card, { className: "h-full gap-4 py-6", children: _jsxs(CardHeader, { className: "gap-2.5", children: [_jsx(CardTitle, { as: Title, children: award.body }), _jsx("div", { className: "flex flex-wrap items-baseline gap-x-2 gap-y-1", children: _jsx(AwardAttribution, { organisation: award.organisation, year: award.year }) }), award.category === undefined ? null : (_jsx(Badge, { variant: "outline", children: award.category }))] }) }));
+                    return (_jsx("li", { "data-slot": "awards-item", "data-award": award.id, className: "h-full", children: award.href === undefined ? (card) : (_jsx("a", { "data-slot": "awards-link", href: award.href, className: "focus-visible:ring-ring block h-full rounded-xl transition-opacity duration-fast ease-out hover:opacity-80 focus-visible:ring-[3px] focus-visible:outline-none", children: card })) }, award.id));
+                }) })) : (_jsx("ul", { "data-slot": "awards", "data-layout": layout, className: "flex flex-col", children: awards.map((award) => {
+                    assertYear(award);
+                    return (_jsx("li", { "data-slot": "awards-item", "data-award": award.id, className: "border-border border-b first:border-t", children: award.href === undefined ? (_jsxs("div", { className: "flex flex-col gap-1.5 px-2 py-5 sm:flex-row sm:items-baseline sm:gap-6", children: [_jsx("span", { className: "flex shrink-0 flex-col gap-0.5 sm:w-64", children: _jsx(AwardAttribution, { organisation: award.organisation, year: award.year }) }), _jsxs("span", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("span", { className: "text-pretty text-sm", children: award.body }), award.category === undefined ? null : (_jsx(Badge, { variant: "outline", children: award.category }))] })] })) : (_jsxs("a", { "data-slot": "awards-link", href: award.href, className: "hover:bg-accent/50 focus-visible:ring-ring flex flex-col gap-1.5 rounded-sm px-2 py-5 transition-colors duration-fast ease-out focus-visible:ring-[3px] focus-visible:outline-none sm:flex-row sm:items-baseline sm:gap-6", children: [_jsx("span", { className: "flex shrink-0 flex-col gap-0.5 sm:w-64", children: _jsx(AwardAttribution, { organisation: award.organisation, year: award.year }) }), _jsxs("span", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("span", { className: "text-pretty text-sm", children: award.body }), award.category === undefined ? null : (_jsx(Badge, { variant: "outline", children: award.category }))] })] })) }, award.id));
+                }) }))] }));
+}
+export default Awards01;

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

@@ -0,0 +1,3 @@
+export { Awards01, default } from './awards.js';
+export type { Awards01Props, Awards01Award } from './awards.js';
+//# sourceMappingURL=index.d.ts.map

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

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

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

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

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

@@ -0,0 +1,268 @@
+import { type ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * The cycles a backdrop can run, named for the mechanism and not for a length.
+ *
+ * Seven members and six are the cycles the ambient scale authors in the token
+ * package. `rise` is the seventh because the stylesheet publishes a class for it
+ * beside the other six and a Block that offered six of seven would be making the
+ * caller find the seventh some other way.
+ *
+ * The value is the caller's choice and the names are Prism's, and that is the
+ * right way round. A field is which mechanism the reader is watching, which is a
+ * decision about the claim the figure makes; a length is which token prices it,
+ * and the stylesheet has already resolved that from `var(--ambient-*)`. Naming a
+ * keyframe in a shorthand with a length attached is what this set exists to make
+ * unnecessary, and a `duration` prop here would put the length back in a Block's
+ * source where a token owns it.
+ */
+export type Backdrop01Field = 'travel' | 'sweep' | 'drift' | 'scan' | 'pulse' | 'shimmer' | 'rise';
+/**
+ * How loud the field is behind the copy, as opacity on the layer that holds it.
+ *
+ * Two steps, and the names are Prism's while the choice is the caller's, for the
+ * same reason the seven cycle names are: which of the two is a decision about
+ * contrast between a field and the copy sitting on it, and a decision a Block can
+ * make from the two things it can see. The declared union rather than a lookup
+ * into the map below, so the emitted declaration the corpus reads says
+ * `'subtle' | 'present'` instead of referring to a constant it cannot name.
+ */
+export type Backdrop01Intensity = 'subtle' | 'present';
+/**
+ * The props a Backdrop01 takes.
+ *
+ * Every string is a prop and the Block ships none. There is no band headline, no
+ * default cycle, no default intensity sentence and no default pair of button
+ * labels, and the absence of the last two is the sharpest version of the rule: a
+ * backdrop that hardcoded "Pause" would put an English word on a control in every
+ * consumer's product, in every language, with no prop to change it.
+ */
+export type Backdrop01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /**
+     * The section title. Omit it for a band composed under its own heading, which
+     * is the usual case for something placed directly under a hero.
+     */
+    title?: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /**
+     * The band's own content, composed by the caller.
+     *
+     * A slot rather than a set of copy props, and the reason is that the content of
+     * a band is the only thing about it that Prism cannot know: it is a headline, a
+     * paragraph, two actions and a figure in some arrangement, and a Block that
+     * took a prop for each would be four arrangements wearing one name. The content
+     * sits over the field, which is why the band is a layout and not a template.
+     */
+    children: ReactNode;
+    /**
+     * The figure the field runs on, usually a `SignalField` or a `PulseGraph`.
+     *
+     * Required rather than optional, and the Block draws no figure of its own,
+     * because a field of invented marks is the retired line's defect rebuilt: the
+     * numbers were never collected and the motion says a system is running. A node
+     * is a node the caller named, a reading is a reading the caller holds, and an
+     * empty figure is an empty figure. What the Block owns is the layer the figure
+     * rides on, which is where a cycle can be applied without the figure having to
+     * know it is being animated.
+     */
+    figure: ReactNode;
+    /**
+     * The figure's accessible name, and the only thing a screen reader reads from
+     * the field.
+     *
+     * Required, and the reason this Block is the claim half of the two is on the
+     * Component's own JSDoc. See there for why the atmosphere half is not an arm
+     * here.
+     */
+    label: string;
+    /**
+     * Which cycle the field runs. See `Backdrop01Field`.
+     *
+     * Required rather than defaulted, because the cycle is a claim about the figure
+     * and only the caller knows what the figure claims. A default would be this
+     * Block choosing the mechanism a consumer's own claim gets made by, and a
+     * backdrop whose wavefront does not match its subject is a decoration wearing a
+     * caption.
+     */
+    field: Backdrop01Field;
+    /**
+     * How loud the field is behind the copy. @defaultValue 'subtle'
+     *
+     * Opacity on the layer, and the reasoning for it not being a length is on
+     * `INTENSITY` above, where the one-second floor is the reason.
+     */
+    intensity?: Backdrop01Intensity;
+    /**
+     * Whether the field is stopped. @defaultValue false
+     *
+     * The controlled arm. Pass it with `pauseControl={false}` and put the button in
+     * `children` when the state belongs to something larger than this band: a
+     * dashboard that stops every figure on the page together, or a settings toggle,
+     * is one state and several bands, and a state this Block owns would be a second
+     * copy of it that disagrees with the first.
+     *
+     * With `pauseControl` set, the same prop is the value the Block starts from and
+     * owns from then on, which is the usual defaultValue arrangement and is
+     * documented on the prop because it is the one place a reader of a call site
+     * could otherwise be surprised.
+     */
+    paused?: boolean;
+    /**
+     * Whether the Block draws the pause control. @defaultValue false
+     *
+     * Off by default because a control on every backdrop is a control on every page
+     * a consumer puts one on, and most of those pages have a figure that is worth
+     * stopping and no reason to offer it. See the Component JSDoc for why the
+     * control is this Block's own button rather than a slot, which is the decision
+     * this prop and the two labels after it exist to record.
+     */
+    pauseControl?: boolean;
+    /**
+     * The words on the control while the field runs. Required with `pauseControl`.
+     *
+     * A prop, not a default, for the reason every accessible name in this package
+     * is a prop: the control is a sentence a reader hears, every language words
+     * stopping differently, and a default here would be an English string in every
+     * consumer's product that they cannot translate without forking the library.
+     */
+    pauseLabel?: string;
+    /**
+     * The words on the control while the field is stopped. Required with
+     * `pauseControl`.
+     *
+     * A second prop rather than a second half of the first, because "Pause" and
+     * "Play" are not a pair in every language, and because a caller whose control
+     * says "Stop the sweep" and "Sweep stopped" is describing a figure rather than
+     * naming a transport control.
+     */
+    resumeLabel?: string;
+    /**
+     * Heading level for the section title. @defaultValue 'h2'
+     *
+     * See `HeadingLevel`.
+     */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Block. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A band with a live field running behind it, and a control that stops the field.
+ *
+ * **The test that decides whether motion belongs here at all, in the terms this
+ * repository uses. Stop the animation. Look at the band. Is the figure still
+ * true, and is every mark of it still readable?** If both answers are yes then
+ * the movement was emphasis and it belongs on a band, because emphasis is a thing
+ * a reader can lose and get back. If stopping it leaves an empty rectangle, then
+ * the thing this was built from was never a figure at all. It was a video with
+ * extra steps, it is the Component it was built with that is wrong, and no
+ * amount of restraint on the Block will turn it back into a drawing. So the
+ * question is asked of the figure and not of the band, which is why `figure` is a
+ * required slot: a backdrop is a frame for somebody else's drawing, and the only
+ * claim this Item makes is that the drawing survives being still.
+ *
+ * **Which of the two figures this Block is, and why it refuses to decide for the
+ * caller.** The motion law sorts figures into two, and the two are different
+ * things rather than one thing with a flag. A figure that carries a claim has to
+ * name itself to a screen reader, because the claim is the whole of what it is
+ * for, and `PulseGraph` and `PulseSeries` both require a label for that reason. A
+ * figure that is atmosphere names nothing, because a field of dots is not
+ * information and a screen reader being made to read one is a cost with no reader
+ * attached, and `SignalField` is `aria-hidden` by default for exactly that
+ * reason. This Block is the **claim** half: `label` is required and the field
+ * layer publishes it, so a caller who has a claim to make has a name for it here
+ * and never has to reach past the band. What it will not do is grow a
+ * `decorative` arm for the other half, and the reason is specific rather than
+ * cautious: the figure is the caller's and the caller's figure has already
+ * answered the question. `SignalField` arrives `aria-hidden` and `PulseGraph`
+ * arrives named, so a `decorative` prop here would be a second answer to a
+ * question two Components have already answered, and the disagreement between
+ * them would be invisible in the rendered result and audible in a screen reader.
+ * The atmosphere half is not missing from this system. It is `SignalField` with
+ * nothing passed, which is the cheapest way to draw it and needs no flag here.
+ *
+ * **Intensity is opacity on a wrapper, and that is the whole of the decision.**
+ * It is not a new token and not a new keyframe, and it is not a length. A length
+ * would be the failure the ambient scale was built to close: a cycle measured in
+ * hundreds of milliseconds is a flicker, the emitted-contract test fails every
+ * `ambient` member below 1000ms and says so in the failure, and an intensity that
+ * scaled the cycle would let a caller reach that floor by asking for a brighter
+ * backdrop. A demonstration that reads as a flicker is the one outcome the floor
+ * exists to prevent, so the second axis is the only one left that cannot produce
+ * it. What the prop actually decides is how present the field is behind the copy,
+ * which is a question about contrast between two things on one surface and
+ * nothing to do with time.
+ *
+ * **The pause control is a real button, and its two labels are props.** That is
+ * the decision, and the reason to state it is the alternative:
+ * `prism-ambient-paused` is a published utility in the one stylesheet, and it is
+ * published rather than left to each consumer because the alternative is four
+ * products each writing their own stop mechanism and at least one of them getting
+ * it wrong in the specific way of restarting the cycle when the figure scrolls
+ * back into view. So the stop mechanism is one class, in one place, and the thing
+ * that puts it on is this control. The two labels are the caller's because they
+ * are the sentences a reader hears, and because a band whose button says "Pause"
+ * in a product whose language has no word for pausing is a control the consumer
+ * cannot fix without forking the library. The Block throws without them rather
+ * than shipping an English button, for the same reason `InstrumentPanel01` throws
+ * on a state with no words beside it.
+ *
+ * **It is a client Component, and the rejected alternative is the interesting
+ * part.** The pause is state, so the module carries `'use client'`, and the
+ * first answer considered was to keep this a server Component and take the
+ * control as a `ReactNode` slot. That would have been wrong for a specific
+ * reason rather than a stylistic one, and the props are where the reason shows.
+ * `pauseControl` is a boolean and `pauseLabel` and `resumeLabel` are two
+ * strings, so a slot is not merely rejected, it is inexpressible: those three
+ * props describe a control this Block draws, and a Block that handed the button
+ * back would be asking the caller for a different set of props and getting a
+ * second decision about whether the stop mechanism exists at all. A slot hands
+ * the stop mechanism back to the consumer, which is exactly what publishing
+ * `prism-ambient-paused` was meant to stop, and it would have put two more
+ * invented sentences in front of every call site, so forty call sites would be
+ * forty chances to write "Pause animation" in English. A slot is the right
+ * shape for a control the consumer owns, such as a range selector or a
+ * fullscreen toggle, and the wrong shape for the one control whose entire
+ * behaviour is this Block's own published class. The cost of the client
+ * boundary is real and worth naming: the module is measured by
+ * `check-client-budget`, and a consumer who does not want the button can leave
+ * `pauseControl` off and never instantiate the state. The caller's `children`
+ * and `figure` cross the boundary as slots, so a server-rendered figure stays
+ * server-rendered and this band costs a consumer the module and not the
+ * drawing.
+ *
+ * **Nothing here is hidden and nothing waits for a script.** No rule in the
+ * ambient layer sets a resting `opacity: 0` and no figure this Block wraps waits
+ * for an intersection, a timer or a frame, so the band is complete and legible at
+ * first paint, to a reader with scripting off, in a print stylesheet, and to a
+ * crawler. The `prefers-reduced-motion` block in the stylesheet is one
+ * `animation: none`, and because every element's resting state is its full form,
+ * that reader gets the same band with the field still drawn. The pause control is
+ * the manual equivalent of the same thing, which is why it is a first-class state
+ * rather than a prop that hides a wrapper: hiding the wrapper would take the
+ * figure with it, and pausing keeps it.
+ *
+ * **What the cycle suits is the caller's figure, and this Block will not hide
+ * that.** `drift` and `pulse` are the two whose resting form is the figure's own
+ * full form, so they are safe on any drawing. `travel`, `sweep`, `scan` and
+ * `shimmer` carry something *across* a field, which is what the stylesheet says
+ * they are for, and a caller who puts one on a figure narrower than the band is
+ * asking for a marker to leave. The band clips, so nothing escapes the frame, and
+ * a caller who pauses and finds the field thin has learned which cycle their
+ * figure wanted. That is the falsifiable test above doing its job, and it is a
+ * better outcome than the alternative this Block refused: choosing the cycle for
+ * the caller, which is a claim about their figure that a component cannot check.
+ *
+ * It is a client Component in its entirety, and the only thing in it that needs a
+ * client is the pause. The frame, the field layer, the wash and the section
+ * around them are server-renderable markup, and the two slots a caller fills
+ * cross the boundary rather than dragging their own trees into it.
+ */
+export declare function Backdrop01({ eyebrow, title, description, children, figure, label, field, intensity, paused, pauseControl, pauseLabel, resumeLabel, headingLevel, className, }: Backdrop01Props): import("react").JSX.Element;
+export default Backdrop01;
+//# sourceMappingURL=backdrop.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backdrop.d.ts","sourceRoot":"","sources":["../../../src/blocks/backdrop-01/backdrop.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAGhD,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAGxF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,eAAe,GACvB,QAAQ,GACR,OAAO,GACP,OAAO,GACP,MAAM,GACN,OAAO,GACP,SAAS,GACT,MAAM,CAAA;AAwBV;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,SAAS,CAAA;AAmBtD;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;;OAQG;IACH,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,SAAS,CAAA;IACjB;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,KAAK,EAAE,eAAe,CAAA;IACtB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAA;IAC/B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+GG;AACH,wBAAgB,UAAU,CAAC,EACzB,OAAO,EACP,KAAK,EACL,WAAW,EACX,QAAQ,EACR,MAAM,EACN,KAAK,EACL,KAAK,EACL,SAAoB,EACpB,MAAc,EACd,YAAoB,EACpB,UAAU,EACV,WAAW,EACX,YAAmB,EACnB,SAAS,GACV,EAAE,eAAe,+BA8FjB;AAED,eAAe,UAAU,CAAA"}