@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/blocks/forgot-password-01/forgot-password.js

@@ -0,0 +1,190 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useState } from 'react';
+import { Button } from '../../components/ui/button.js';
+import { Card } from '../../components/ui/card.js';
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Field, FieldDescription, FieldLabel } from '../../components/ui/field.js';
+import { Input } from '../../components/ui/input.js';
+import { LiveRegion } from '../../components/ui/live-region.js';
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * Whether a caller passed a word that is not there.
+ *
+ * Read as `string | undefined` rather than as the declared type, because the check
+ * is about the value that turned up rather than about what the type promised. A
+ * JavaScript caller and a value out of a session store both arrive with the type's
+ * guarantee already gone, and the diagnostic below is the last place that can still
+ * say what was wrong.
+ */
+function blank(value) {
+    return value === undefined || value.trim() === '';
+}
+/**
+ * The three refusals, checked before anything is drawn so a caller's mistake is one
+ * diagnostic in a console rather than a nameless control on the screen where a
+ * reader is about to type the one datum that ties them to an account.
+ */
+function assertForgot(input) {
+    const { identifier, sent, back } = input;
+    if (blank(identifier.label)) {
+        throw new Error('ForgotPassword01: the identifier field declares no label, so its control would be announced as a text ' +
+            'field, which is the same name every other field in the reader recovery flow is announced by. Pass the ' +
+            'words your product uses for a person or an operator.');
+    }
+    if (identifier.value !== undefined && identifier.onValueChange === undefined) {
+        throw new Error('ForgotPassword01: identifier.value was passed with no onValueChange, so the field would show the value ' +
+            'once and then stop telling the caller what is in it, which is a value the caller cannot clear when a ' +
+            'reader mistypes it. Pass the pair, or neither.');
+    }
+    if (back !== undefined && blank(back.label)) {
+        throw new Error(`ForgotPassword01: the link to ${JSON.stringify(back.href)} declares no label, so the anchor accessible ` +
+            'name would be its destination, which a screen reader reads as a run of characters and a mouse reader ' +
+            'cannot copy. Pass the sentence that says what following it does.');
+    }
+    if (sent !== undefined && (sent.resendLabel === undefined) !== (sent.onResend === undefined)) {
+        throw new Error('ForgotPassword01: the confirmation arm was passed one half of its resend control, so the screen would ' +
+            'either offer a button that does nothing or call a handler no control can reach. Pass resendLabel and ' +
+            'onResend together, or neither.');
+    }
+    if (sent !== undefined && blank(sent.resendLabel)) {
+        throw new Error('ForgotPassword01: the confirmation arm was passed a resend control with no words, so the one control on ' +
+            'the screen after a reader presses the button would be a button a screen reader announces as "button" ' +
+            'and a voice control user cannot say out loud.');
+    }
+}
+/**
+ * One identifier, one control, and a confirmation that says the same thing whether or
+ * not the account exists.
+ *
+ * **The translation, because the pattern is not ours and the framing is.** A
+ * storefront publishes a forgot-password card: an address field, one button, and a
+ * line that says to check your inbox, and its purpose is to get a shopper past a
+ * locked door so their order history is waiting on the other side. Prism's products
+ * observe a pipeline, capture a market, watch an estate and run agents, and a machine
+ * acting on behalf of a person is the whole subject, so this is the screen where
+ * somebody who is responsible for an instrument asks for a way back in to it. The
+ * composition is the storefront's and is deliberately unchanged: one labelled field,
+ * one control, one outcome line, one way off the screen. What is different is the
+ * sentence after the press, and the rest of this note is about that sentence.
+ *
+ * **What it assumes about the reader in front of it, because a recovery flow that
+ * assumes a careful reader is a flow that fails the one time it is needed.** It
+ * assumes the reader cannot get in, that they are often in a hurry, and that they
+ * may be on a machine they do not fully control. It assumes nothing about the state
+ * of their account, nothing about whether they know their own address by heart, and
+ * nothing about whether they will read the frame. It refuses to assume they typed
+ * correctly, because the whole design exists to make that assumption unnecessary.
+ *
+ * **The decision that makes this a separate Item from `contact-01` is that the
+ * confirmation is the same whether or not the account exists, and it is expressed in
+ * the shape rather than in the prose.** There is no `found` flag, no `unknown`, no
+ * `registered` and no second message. `sent.message` is one sentence, and the type
+ * has nowhere to put a second one. The alternative was a `status` that grew an arm
+ * for the negative case, which is a two-line change to the props and a permanent
+ * capability to leak in every product that installs this Block, and a leak that is
+ * cheap to add and expensive to remove once a product's support process depends on
+ * it.
+ *
+ * **The trade is real and it is argued in both directions, because it is not a
+ * clean win.** A message that differs leaks which addresses are registered, and that
+ * is an enumeration oracle: an attacker with any address list learns which of them
+ * hold an account here, and a reader with a mistyped address learns the same thing
+ * about themselves. A message that is identical teaches the reader that a mistyped
+ * address succeeded, and it is the version that is more often wrong in practice,
+ * because a recovery form is the one form a reader is most likely to fill from memory
+ * and most likely to get wrong. Both sentences are true. The resolution that does
+ * not pick a side is a confirmation that names the next step without confirming the
+ * account: it says what has been sent and where to look, and it does not say what was
+ * found. That is a sentence the caller's product can write in a way that is true of
+ * both cases, and it is the reason `sent.message` is a node and the whole of what the
+ * arm carries. **The words are the caller's.** A consumer that wants the other trade
+ * can write it in `sent.message` and the Block will not stop them, because the Block
+ * has no opinion about a disclosure decision; what it does is refuse to make the
+ * choice on their behalf by refusing to have a place to put it.
+ *
+ * **`status` and `sent` are two props because they answer two questions.** `status`
+ * is the announcement, and it is needed while the form is up and after it is
+ * replaced: a caller whose transport failed on the first press and then succeeded on
+ * the second needs a region in both arms. `sent` is the arm, and passing it is what
+ * takes the field and the control away. Merging them would force a caller to invent a
+ * confirmation sentence for a form that is still on the screen, which is the shape
+ * that makes designers add a placeholder they then ship. The corollary is the rule
+ * above: the arm reports the first press, and `status` reports everything after it,
+ * so the two never carry the same sentence and the reader never reads it twice.
+ *
+ * **The card stays and the form inside it is replaced, so the reader's page does not
+ * change size under them at the moment they are reading the one line that matters.**
+ * A recovery screen that reflows on success looks like a fault, and the reader who
+ * has just mistyped their address is the reader least able to tell a reflow from a
+ * failure.
+ *
+ * **The Block owns one string and hands it over, and it validates nothing.** There
+ * is no address format check, no rate limit, no redirect to a "did you mean" page and
+ * no enumeration defence beyond the shape of the confirmation, because each of those
+ * is a decision about the caller's product and its data. What the Block does about
+ * the request is the one thing that is rendering rather than policy: it refuses a
+ * second press while `submitting` is true, because a second press is a second message
+ * queued into somebody's inbox that nobody asked for.
+ *
+ * **There is no `Alert` in this file, and the alternative was a callout with
+ * `role="alert"` beside the live region.** That announces the same sentence twice, and
+ * on a screen where a reader is waiting for an answer about whether they can get in,
+ * a doubled announcement is the one place it is least forgivable. So the outcome is
+ * a `LiveRegion` whose politeness follows the caller's own state, and `assertive`
+ * only for the refusal.
+ *
+ * It is a client Component, and the directive is unconditional. `onSubmit` is a
+ * function, a function is a piece of state, and state is a client module: a server
+ * Component cannot hand an event handler to a `<form>`, so a caller rendering this
+ * from a server Component gets a form that submits and calls nothing. The cost is
+ * that the whole module is in the client graph even where a consumer never presses
+ * the button, and the price was judged worth paying for one boundary rather than
+ * two arrangements of the same screen.
+ */
+export function ForgotPassword01({ eyebrow, title, description, onSubmit, identifier, submitLabel, submitting = false, status, sent, back, headingLevel = 'h2', className, }) {
+    assertForgot({ identifier, sent, back });
+    const generated = useId();
+    const inputId = `${generated}-identifier`;
+    const descriptionId = `${generated}-identifier-description`;
+    /*
+     * The value lives here rather than only in the caller, for one reason: a field a
+     * caller cannot clear is a field a reader who mistyped their address has to reload
+     * the page to escape from, and the reader most likely to mistype it is the one who
+     * can least afford to lose the screen. The Block therefore holds the identifier
+     * itself, reports every change to the caller when one was asked for, and adopts a
+     * `value` prop the moment it changes, which is the arrangement React documents for
+     * a prop that can change under a stateful child. Both halves are adjusted during
+     * render rather than in an effect, because the trigger is a prop changing and a set
+     * during render is applied before the browser paints.
+     */
+    const [typed, setTyped] = useState(identifier.value ?? '');
+    const [seen, setSeen] = useState(identifier.value);
+    if (seen !== identifier.value) {
+        setSeen(identifier.value);
+        setTyped(identifier.value ?? '');
+    }
+    const setIdentifier = (value) => {
+        setTyped(value);
+        identifier.onValueChange?.(value);
+    };
+    const handleSubmit = (event) => {
+        event.preventDefault();
+        onSubmit({ identifier: typed });
+    };
+    return (_jsx(Section, { "data-slot": "forgot-password-01", className: cn(className), children: _jsxs("div", { "data-slot": "forgot-password-01-body", className: "flex flex-col gap-10", children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description }), _jsx(Card, { "data-slot": "forgot-password-01-card", className: "max-w-measure-narrow gap-0 px-6", children: sent === undefined ? (_jsxs("form", { "data-slot": "forgot-password-01-form", onSubmit: handleSubmit, className: "flex w-full flex-col gap-5", children: [_jsxs(Field, { "data-slot": "forgot-password-01-identifier", "data-field": "identifier", children: [_jsx(FieldLabel, { htmlFor: inputId, children: identifier.label }), _jsx(Input, { id: inputId, type: identifier.type ?? 'email', autoComplete: identifier.autoComplete, value: typed, onChange: (event) => setIdentifier(event.target.value), required: true, "aria-describedby": identifier.description === undefined ? undefined : descriptionId }), identifier.description === undefined ? null : (_jsx(FieldDescription, { id: descriptionId, children: identifier.description }))] }), _jsxs("div", { "data-slot": "forgot-password-01-actions", className: "flex flex-col gap-3", children: [_jsx(Button, { "data-slot": "forgot-password-01-submit", type: "submit", disabled: submitting, className: "w-full", children: submitLabel }), _jsx(LiveRegion, { "data-slot": "forgot-password-01-status", politeness: status?.state === 'error' ? 'assertive' : 'polite', busy: submitting, className: cn('text-sm', status?.state === 'error'
+                                            ? 'text-destructive font-medium'
+                                            : 'text-muted-foreground'), children: status?.message })] })] })) : (
+                    /*
+                     * The confirmation arm. The field and the control are gone and the card is
+                     * still there, and the region survives below it so a resend that fails has
+                     * somewhere to be announced. `sent.message` is the caller's sentence and
+                     * there is nowhere in this file to put a second one; that absence is the
+                     * Block's whole contribution to the decision the caller is making.
+                     */
+                    _jsxs("div", { "data-slot": "forgot-password-01-sent", className: "flex w-full flex-col gap-4", children: [_jsx("p", { "data-slot": "forgot-password-01-sent-message", className: "text-sm text-pretty", children: sent.message }), sent.resendLabel === undefined ? null : (_jsx(Button, { "data-slot": "forgot-password-01-resend", type: "button", variant: "outline", onClick: () => sent.onResend?.(), disabled: submitting, className: "self-start", children: sent.resendLabel })), _jsx(LiveRegion, { "data-slot": "forgot-password-01-status", politeness: status?.state === 'error' ? 'assertive' : 'polite', busy: submitting, className: cn('text-sm', status?.state === 'error'
+                                    ? 'text-destructive font-medium'
+                                    : 'text-muted-foreground'), children: status?.message })] })) }), back === undefined ? null : (_jsx(CtaLink, { "data-slot": "forgot-password-01-back", href: back.href, variant: "ghost", size: "sm", className: "self-start", children: back.label }))] }) }));
+}
+export default ForgotPassword01;

package/dist/blocks/forgot-password-01/index.d.ts

@@ -0,0 +1,3 @@
+export { ForgotPassword01, default } from './forgot-password.js';
+export type { ForgotPassword01Identifier, ForgotPassword01Link, ForgotPassword01Outcome, ForgotPassword01Props, ForgotPassword01Sent, ForgotPassword01Status, } from './forgot-password.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/forgot-password-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/forgot-password-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAQ7D,YAAY,EACV,0BAA0B,EAC1B,oBAAoB,EACpB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,mBAAmB,CAAA"}

package/dist/blocks/forgot-password-01/index.js

@@ -0,0 +1 @@
+export { ForgotPassword01, default } from './forgot-password.js';

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

@@ -0,0 +1,208 @@
+import { type ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * Every string the gallery and the lightbox it opens announce.
+ *
+ * Required, all four, for the reason `Lightbox` states and this Block inherits
+ * without softening: a hardcoded control label is a word a consumer cannot
+ * localise, so a product in any language but English inherits an English control
+ * in the middle of its own interface and the only fix is a fork. A required prop
+ * is a question asked at build time and an optional one is a question nobody
+ * asks, and this is the release where the four missing labels would otherwise have
+ * been discovered. Three of them are the lightbox's own controls and the fourth is
+ * the rail, and a gallery with one image still draws the zoom and the close, so
+ * there is no shape in which a label is genuinely absent.
+ */
+export type Gallery01Labels = {
+    /** The accessible name of the control that toggles fitted and actual size. */
+    zoom: string;
+    /** The accessible name of the control that shows the previous image. */
+    previous: string;
+    /** The accessible name of the control that shows the next image. */
+    next: string;
+    /** The accessible name of the control that closes the enlarged image. */
+    close: string;
+};
+/** How each shape is drawn, as the ratio the surface holds it at. */
+export type Gallery01Ratio = 'square' | 'landscape' | 'portrait';
+/** How many images a grid puts on one line. The tracks, not the image count. */
+export type Gallery01Columns = 2 | 3 | 4;
+/**
+ * One image in the grid: where it is, what it is, and the words that go under it.
+ *
+ * `src` and `alt` are required and `alt` is load bearing three times: it is the
+ * image's description on the enlarged surface, the name of the button that opens
+ * it, and the name of the button in the rail that moves between them. A gallery
+ * that shipped an unnamed image has a dialog with no title, a rail of identical
+ * buttons, and a reader who has paid a modal, a focus trap and an Escape key to
+ * look at something nobody described.
+ */
+export type Gallery01Item = {
+    /** The image's stable key within the set. */
+    id: string;
+    /** Where the image is. A path or a URL, the caller's own either way. */
+    src: string;
+    /**
+     * The image's description, in the caller's words.
+     *
+     * Required, and it is the button's accessible name as well as the image's. A
+     * reader who cannot see the picture reaches the enlarged one and is told what it
+     * is by this string, so it is a sentence about the content rather than a
+     * filename.
+     */
+    alt: string;
+    /**
+     * The words under the tile, drawn outside the button.
+     *
+     * A node, and the slot is where the caller's own link goes, for the reason the
+     * Item's JSDoc states at length: a tile cannot be both a trigger and a link. A
+     * caption is also the one place a reader gets a sentence about the set rather
+     * than a description of one picture, which is why it sits below the tile and
+     * not inside it.
+     */
+    caption?: ReactNode;
+    /**
+     * Refused.
+     *
+     * A tile is a button that opens the lightbox, and a link on the same tile is two
+     * controls inside one hit area, so the type says the field is never rather than
+     * the render dropping it quietly. Put the link in `caption`, where it is a
+     * control of its own with words on it that the caller chose.
+     */
+    href?: never;
+};
+/**
+ * The props a Gallery01 takes.
+ *
+ * Every string is a prop and the Block ships none: no image, no description, no
+ * caption and not one label for the four controls the enlarged image draws. A
+ * gallery that hardcoded its images would install a photograph nobody licensed
+ * into every consumer's page.
+ */
+export type Gallery01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /** The section title. Omit it for a gallery composed under its own heading. */
+    title?: string;
+    /** One or two sentences under the title. */
+    description?: string;
+    /**
+     * The images, in the order a reader should meet them.
+     *
+     * Order is the caller's, and it is also the order the lightbox's rail moves in,
+     * because the rail is this set: the Item hands the whole list over and the
+     * lightbox asks for an index rather than holding the images. A consumer whose
+     * set has a different order at full size than on the page owns `index` itself and
+     * this Block is the wrong Item.
+     */
+    items: Gallery01Item[];
+    /**
+     * How many images sit on one line.
+     *
+     * @defaultValue 3
+     */
+    columns?: Gallery01Columns;
+    /**
+     * The shape every tile is held at.
+     *
+     * @defaultValue 'landscape'
+     *
+     * Landscape is the default because the commonest thing a gallery holds is a
+     * screenshot or a photograph, and both have a shape wider than they are tall.
+     * `portrait` is for a set of pages or of people, and `square` is for a set of
+     * marks. A mixed set is a set whose images crop, because the surface is one
+     * ratio for every tile and `object-cover` fills it.
+     */
+    ratio?: Gallery01Ratio;
+    /**
+     * The accessible names of the four controls the enlarged image draws.
+     *
+     * Required, and it is the one departure from the shape the other Blocks in this
+     * wave use. The alternative was to draw the enlarged image without the
+     * lightbox, and that would have cost the focus trap, the restore of focus, the
+     * Escape key, the outside press, the scroll lock and the portal, every one of
+     * which is solved badly twice as often as it is solved well. So the surface is
+     * composed and the four words are asked for, the same way `DataTable01` asks for
+     * every string it renders rather than shipping twenty of them.
+     */
+    labels: Gallery01Labels;
+    /** Heading level for the section title. See `HeadingLevel`. */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Block. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A grid of images that opens one at full size, with a caption per tile and a
+ * count on the set.
+ *
+ * **The enlarged surface is `Lightbox`, and the argument for composing it rather
+ * than drawing a dialog is the same argument `Lightbox` makes about `Dialog`.**
+ * An image overlay built on a `div` and a `keydown` listener gets the Escape key
+ * and no focus trap, so a keyboard reader tabs behind the image into a page they
+ * cannot see, and the defect is invisible in review because the overlay works for
+ * the person writing it. The focus trap, the restore of focus to whatever opened
+ * it, the Escape key, the outside press, the scroll lock and the portal all come
+ * from `Dialog` and are all solved once. So this Block composes `Lightbox` and
+ * spends its own surface on the three things `Lightbox` does not know about: the
+ * set, the tile and the count. The cost is the four required labels, which is a
+ * real departure from the shape the rest of this wave uses and is stated in the
+ * props.
+ *
+ * **The tile is a real `<button>`, and a tile is not a link.** Each tile is one
+ * focusable control that opens the enlarged image, and the whole set is reachable
+ * by Tab in the order the caller passed it. The alternative, a tile that is an
+ * anchor to a full-size file, loses the zoom, the focus trap, the Escape key and
+ * the rail, and it makes the destination a thing the browser can navigate away
+ * from, which is a worse outcome for a reader who came to look rather than to
+ * leave. The count on the tile says how many there are rather than inviting a
+ * gesture, which is the arrangement that needs no discovery.
+ *
+ * **`href` on a tile is refused, and the type says `never`.** A tile that is both
+ * a lightbox trigger and a link is two controls in one hit area: a reader
+ * navigating by Tab meets one thing, activates it, and cannot tell whether they
+ * enlarged the picture or followed a link out of the page, and a reader using a
+ * switch control or a voice command has one target with two behaviours. The
+ * refusal is in the type rather than only in a diagnostic, so a caller finds out
+ * where they are looking rather than in a console. **The alternative is named and
+ * it is the one to use: the caller's own link in the caption under the tile.** The
+ * caption is drawn outside the button, so a link in it is a control of its own with
+ * its own accessible name, its own focus position after the tile rather than
+ * inside it, and the words the caller chose on it. A gallery of case studies is
+ * nine tiles with nine captions and nine links, and it is better for it than nine
+ * tiles that were also nine links.
+ *
+ * **The tile's accessible name is composed from the two values the caller passed
+ * and never from a word Prism chose.** With no caption it is the `alt`. With a
+ * string caption it is the caption and then the `alt`, because the caption is what
+ * the reader can already see and the description is what they cannot get from a
+ * thumbnail. Prism adds a separator and nothing else. See `nameOf` for why, and
+ * for what happens when the caption is a node rather than a string.
+ *
+ * **The count is drawn whenever there is more than one image, and there is no prop
+ * for it.** A count of one names nothing and a count of zero is not on the page,
+ * so the only state in which a count says anything is the state in which it is
+ * drawn. It is a number, so it is in the mono face and it is `aria-hidden`: it is
+ * machine notation about the set rather than part of any tile's name, and a reader
+ * who needs the position of the image they are looking at gets it from the rail,
+ * which names every image by its own description. If a consumer needs a count they
+ * can hide, the honest answer is that the number is not information and the set's
+ * own title is where its size belongs.
+ *
+ * **`ratio` is a number handed to `AspectRatio`, not a Tailwind keyword.** Prism's
+ * stylesheet is built by scanning this package's own source, so `aspect-square`
+ * written here would be a utility that appears in no Prism file and is therefore a
+ * utility no consumer's stylesheet contains, and a portrait ratio is not a keyword
+ * at all. So the three shapes are numbers this Block holds and passes.
+ *
+ * **The images belong to the caller, so this is the one Block in this wave that
+ * needs `'use client'`.** It owns the open index and nothing else, which is the
+ * smallest possible reason: the state is one number, and the data is not fetched
+ * or held, so the client JavaScript a consumer pays for here is the dialog stack
+ * `Lightbox` already brings and no more.
+ */
+export declare function Gallery01({ eyebrow, title, description, items, columns, ratio, labels, headingLevel, className, }: Gallery01Props): import("react").JSX.Element | null;
+export default Gallery01;
+//# sourceMappingURL=gallery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gallery.d.ts","sourceRoot":"","sources":["../../../src/blocks/gallery-01/gallery.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAIhD,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAGxF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,qEAAqE;AACrE,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAA;AAkBhE,gFAAgF;AAChF,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAiBxC;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAA;IACV,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;;OAOG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,KAAK,CAAA;CACb,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;OAQG;IACH,KAAK,EAAE,aAAa,EAAE,CAAA;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAA;IAC1B;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,eAAe,CAAA;IACvB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAkCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,wBAAgB,SAAS,CAAC,EACxB,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,OAAW,EACX,KAAmB,EACnB,MAAM,EACN,YAAmB,EACnB,SAAS,GACV,EAAE,cAAc,sCA4HhB;AAED,eAAe,SAAS,CAAA"}

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

@@ -0,0 +1,174 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { AspectRatio } from '../../components/ui/aspect-ratio.js';
+import { Lightbox } from '../../components/ui/lightbox.js';
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The three shapes, as numbers, because that is what `AspectRatio` takes.
+ *
+ * Numbers and not Tailwind's `aspect-square`, `aspect-video` keywords, for
+ * `AspectRatio`'s reason and it is the important one: this package's stylesheet is
+ * built by scanning this package's own source, so a utility that appears in no
+ * Prism file is a utility no consumer's stylesheet contains. `aspect-square`
+ * written here would be a silently missing rule, and a `3 / 4` portrait is not a
+ * keyword at all. So the ratio is a number this Block reads and hands over.
+ */
+const RATIOS = {
+    square: 1,
+    landscape: 16 / 9,
+    portrait: 3 / 4,
+};
+/**
+ * The tracks a grid of images gets, from the caller's own column count.
+ *
+ * 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 images at phone width is three thumbnails a
+ * reader cannot tell apart, and a gallery is a set of things they are choosing
+ * between.
+ */
+const TRACKS = {
+    2: 'sm:grid-cols-2',
+    3: 'sm:grid-cols-2 lg:grid-cols-3',
+    4: 'sm:grid-cols-2 lg:grid-cols-4',
+};
+/**
+ * A tile's accessible name, composed from the two values the caller passed.
+ *
+ * **The composition is the caller's two props and never a word Prism invented,
+ * and that is the whole rule on this line.** When there is no caption the name is
+ * the `alt` and there is nothing to compose. When there is a string caption the
+ * name is the caption followed by the `alt`, because the caption is the words the
+ * reader can already see and the description is the words they cannot get from the
+ * thumbnail. Prism adds a separator and nothing else: no "Open", no "View", no
+ * "image of". A name Prism invented is a word in this package that a consumer
+ * cannot translate, and a tile named "Open image" in a product whose interface
+ * says something else is a control the consumer has to patch the library to fix.
+ *
+ * A caption that is a node rather than a string contributes nothing to the name,
+ * and the tile's name is then the `alt` alone. That is a cost and it is the right
+ * one: a node may be a list, a button or a picture, and an accessible name is a
+ * string, so a name assembled from a node's text is a name this Block would have
+ * to compute by rendering the node somewhere it does not belong. A caller who
+ * wants their own words in the name passes the caption as a string.
+ *
+ * The inner image is marked decorative, so the button's name is the description
+ * and not a doubled reading of the same pixels. That is `Lightbox`'s own treatment
+ * of its thumbnails, and the reason is the same: a reader who has navigated to a
+ * tile is about to be told what the picture is, and hearing the alt twice is two
+ * sentences for one image.
+ */
+function nameOf(item) {
+    return typeof item.caption === 'string' && item.caption.trim() !== ''
+        ? `${item.caption}, ${item.alt}`
+        : item.alt;
+}
+/**
+ * A grid of images that opens one at full size, with a caption per tile and a
+ * count on the set.
+ *
+ * **The enlarged surface is `Lightbox`, and the argument for composing it rather
+ * than drawing a dialog is the same argument `Lightbox` makes about `Dialog`.**
+ * An image overlay built on a `div` and a `keydown` listener gets the Escape key
+ * and no focus trap, so a keyboard reader tabs behind the image into a page they
+ * cannot see, and the defect is invisible in review because the overlay works for
+ * the person writing it. The focus trap, the restore of focus to whatever opened
+ * it, the Escape key, the outside press, the scroll lock and the portal all come
+ * from `Dialog` and are all solved once. So this Block composes `Lightbox` and
+ * spends its own surface on the three things `Lightbox` does not know about: the
+ * set, the tile and the count. The cost is the four required labels, which is a
+ * real departure from the shape the rest of this wave uses and is stated in the
+ * props.
+ *
+ * **The tile is a real `<button>`, and a tile is not a link.** Each tile is one
+ * focusable control that opens the enlarged image, and the whole set is reachable
+ * by Tab in the order the caller passed it. The alternative, a tile that is an
+ * anchor to a full-size file, loses the zoom, the focus trap, the Escape key and
+ * the rail, and it makes the destination a thing the browser can navigate away
+ * from, which is a worse outcome for a reader who came to look rather than to
+ * leave. The count on the tile says how many there are rather than inviting a
+ * gesture, which is the arrangement that needs no discovery.
+ *
+ * **`href` on a tile is refused, and the type says `never`.** A tile that is both
+ * a lightbox trigger and a link is two controls in one hit area: a reader
+ * navigating by Tab meets one thing, activates it, and cannot tell whether they
+ * enlarged the picture or followed a link out of the page, and a reader using a
+ * switch control or a voice command has one target with two behaviours. The
+ * refusal is in the type rather than only in a diagnostic, so a caller finds out
+ * where they are looking rather than in a console. **The alternative is named and
+ * it is the one to use: the caller's own link in the caption under the tile.** The
+ * caption is drawn outside the button, so a link in it is a control of its own with
+ * its own accessible name, its own focus position after the tile rather than
+ * inside it, and the words the caller chose on it. A gallery of case studies is
+ * nine tiles with nine captions and nine links, and it is better for it than nine
+ * tiles that were also nine links.
+ *
+ * **The tile's accessible name is composed from the two values the caller passed
+ * and never from a word Prism chose.** With no caption it is the `alt`. With a
+ * string caption it is the caption and then the `alt`, because the caption is what
+ * the reader can already see and the description is what they cannot get from a
+ * thumbnail. Prism adds a separator and nothing else. See `nameOf` for why, and
+ * for what happens when the caption is a node rather than a string.
+ *
+ * **The count is drawn whenever there is more than one image, and there is no prop
+ * for it.** A count of one names nothing and a count of zero is not on the page,
+ * so the only state in which a count says anything is the state in which it is
+ * drawn. It is a number, so it is in the mono face and it is `aria-hidden`: it is
+ * machine notation about the set rather than part of any tile's name, and a reader
+ * who needs the position of the image they are looking at gets it from the rail,
+ * which names every image by its own description. If a consumer needs a count they
+ * can hide, the honest answer is that the number is not information and the set's
+ * own title is where its size belongs.
+ *
+ * **`ratio` is a number handed to `AspectRatio`, not a Tailwind keyword.** Prism's
+ * stylesheet is built by scanning this package's own source, so `aspect-square`
+ * written here would be a utility that appears in no Prism file and is therefore a
+ * utility no consumer's stylesheet contains, and a portrait ratio is not a keyword
+ * at all. So the three shapes are numbers this Block holds and passes.
+ *
+ * **The images belong to the caller, so this is the one Block in this wave that
+ * needs `'use client'`.** It owns the open index and nothing else, which is the
+ * smallest possible reason: the state is one number, and the data is not fetched
+ * or held, so the client JavaScript a consumer pays for here is the dialog stack
+ * `Lightbox` already brings and no more.
+ */
+export function Gallery01({ eyebrow, title, description, items, columns = 3, ratio = 'landscape', labels, headingLevel = 'h2', className, }) {
+    // One number, and it is the only state this Block owns: which image is open, or
+    // `null` for the state in which none is. The images themselves are props, so a
+    // consumer that closes the dialog and re-renders with a different set has not
+    // lost anything this Block was holding.
+    const [openAt, setOpenAt] = useState(null);
+    for (const item of items) {
+        if (item.href !== undefined) {
+            throw new Error(`Gallery01: the item "${item.id}" passed an href, so its tile would be a lightbox trigger and a link in ` +
+                'one hit area, which is two controls where a reader expects one and a Tab stop whose behaviour they ' +
+                'cannot predict. Put the link in the caption under the tile instead, where the words on it are yours.');
+        }
+    }
+    if (items.length === 0)
+        return null;
+    const at = openAt ?? 0;
+    const current = items[at] ?? items[0];
+    // A count of one names nothing, so the only state in which the count says
+    // anything is the state in which it is drawn.
+    const counted = items.length > 1;
+    return (_jsxs(Section, { children: [title ? (_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-12" })) : null, _jsx("ul", { "data-slot": "gallery", "data-ratio": ratio, className: cn('grid gap-4', TRACKS[columns], className), children: items.map((item, index) => (_jsxs("li", { "data-slot": "gallery-tile", className: "flex flex-col gap-2", children: [_jsxs("button", { type: "button", "data-slot": "gallery-trigger", "data-index": index, "aria-label": nameOf(item), onClick: () => setOpenAt(index), 
+                            // The ring is `ring-ring` at full strength and 3px, for the reason
+                            // `button.tsx` states: half alpha composites to between 1.14:1 and
+                            // 2.74:1 against every surface in all six themes and clears 3:1 in
+                            // none of them, which fails WCAG 1.4.11 on the one indicator a
+                            // keyboard user has. A tile is the item most likely to be reached by
+                            // keyboard, because it is one of many and they are all the same.
+                            className: "ring-ring focus-visible:ring-[3px] hover:border-primary relative block w-full overflow-hidden rounded-lg border outline-none transition-colors duration-fast ease-out", children: [_jsx(AspectRatio, { ratio: RATIOS[ratio], children: _jsx("img", { "data-slot": "gallery-image", src: item.src, alt: "", className: "absolute inset-0 size-full object-cover" }) }), counted ? (_jsx("span", { "data-slot": "gallery-count", "aria-hidden": "true", className: "bg-background/90 text-foreground absolute right-2 bottom-2 rounded-md px-1.5 py-0.5 font-mono text-xs", children: items.length })) : null] }), item.caption ? (_jsx("div", { "data-slot": "gallery-caption", className: "text-muted-foreground text-pretty text-sm", children: item.caption })) : null] }, item.id))) }), _jsx(Lightbox, { open: openAt !== null, onOpenChange: (open) => {
+                    if (!open)
+                        setOpenAt(null);
+                }, src: current.src, alt: current.alt, caption: current.caption, 
+                // The rail is this set, in this order, named by each image's own
+                // description. The lightbox asks for an index rather than holding the
+                // images, so a consumer whose set is ordered differently at full size owns
+                // the index itself and this is the wrong Item for them.
+                thumbnails: items.map((item) => ({ src: item.src, alt: item.alt })), index: at, onIndexChange: setOpenAt, zoomLabel: labels.zoom, previousLabel: labels.previous, nextLabel: labels.next, closeLabel: labels.close })] }));
+}
+export default Gallery01;

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

@@ -0,0 +1,3 @@
+export { Gallery01, default } from './gallery.js';
+export type { Gallery01Props, Gallery01Item, Gallery01Labels, Gallery01Ratio, Gallery01Columns, } from './gallery.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/gallery-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAK9C,YAAY,EACV,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,EACd,gBAAgB,GACjB,MAAM,WAAW,CAAA"}

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

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