@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/components/ui/lightbox.d.ts

@@ -0,0 +1,165 @@
+import { type ReactNode } from 'react';
+/** One image in the rail, and the words that describe it. */
+type LightboxThumbnail = {
+    /** The image, at the size a thumbnail is drawn. */
+    src: string;
+    /** The caller's description of it, and the button's accessible name. */
+    alt: string;
+};
+/** The props the Lightbox accepts. */
+export interface LightboxProps {
+    /** Whether the dialog is open. */
+    open: boolean;
+    /** Called when the reader closes the dialog, by any route. */
+    onOpenChange: (open: boolean) => void;
+    /** The image being shown, at the size it should be shown at. */
+    src: string;
+    /**
+     * The image's description, and required.
+     *
+     * Required because an enlarged image is the whole point of this Component and
+     * an unnamed one is not enlarged, it is merely bigger: a lightbox with no
+     * description is a picture a reader can see more of and still not read, and the
+     * reader has paid a modal, a focus trap and an Escape key for it. It is also
+     * the name the dialog falls back to when the caller passes a caption this
+     * Component cannot turn into a title, so it is load bearing twice.
+     */
+    alt: string;
+    /**
+     * The sentence under the image, in the caller's words.
+     *
+     * A string here becomes the dialog's visible name as well as its caption,
+     * because one sentence naming a figure is better than the same sentence twice
+     * in two places. A node is drawn under the image and the dialog is named by
+     * `alt` instead, which is the cost of a node: a node may be an image, a list
+     * or a piece of formatting, and a dialog's name has to be a string.
+     */
+    caption?: ReactNode;
+    /**
+     * The other images, in order, and the rail of buttons that reaches them.
+     *
+     * The rail is drawn only when this is given and holds more than one, because a
+     * rail of one is a picture of the picture you are already looking at. When it
+     * is given, `src` and `alt` are expected to be the entry at the current index,
+     * and moving the rail asks for a new index rather than moving the image: the
+     * caller owns the data and this Component owns the words a reader hears.
+     */
+    thumbnails?: readonly LightboxThumbnail[];
+    /**
+     * Which image is showing, zero based. Omit it for an uncontrolled lightbox
+     * that remembers where it was.
+     *
+     * A number and not a required prop, matching `Carousel`: a lightbox with one
+     * image has nothing to move between, and a caller who passes `thumbnails`
+     * should pass this too, which is the arrangement the type cannot enforce and
+     * the documentation has to.
+     */
+    index?: number;
+    /** Called with the image the reader asked for. */
+    onIndexChange?: (index: number) => void;
+    /**
+     * The accessible name of the zoom control. Required.
+     *
+     * A prop and not a word, because this package ships no string a consumer
+     * cannot localise, and a control is the clearest case of one: a button whose
+     * label reads "Zoom" in a product whose interface says something else is a
+     * control the consumer cannot fix without patching the library. The same
+     * reasoning as `check-block-copy`'s account of the dialog's close button, which
+     * is the finding that made this a rule rather than a preference.
+     *
+     * One name for a two state control, and the state is announced with
+     * `aria-pressed`, so a reader hears the name and then whether the image is
+     * currently at actual size. That has a consequence for the word: it should be
+     * a noun for the thing being changed, such as "Image size", rather than a verb
+     * for one of the two directions, because a verb is a claim about what the
+     * press will do and the press does whichever of the two the state is not. A
+     * caller who wants two distinct names has to own the state to get them, which
+     * the two index props already let them do.
+     */
+    zoomLabel: string;
+    /** The accessible name of the control that shows the previous image. Required, for the same reason. */
+    previousLabel: string;
+    /** The accessible name of the control that shows the next image. Required, for the same reason. */
+    nextLabel: string;
+    /** The accessible name of the control that closes the dialog. Required, for the same reason. */
+    closeLabel: string;
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+}
+/**
+ * An image at full size, in a dialog, with its own words and its own way out.
+ *
+ * **This Item exists because an image the reader cannot enlarge is an image the
+ * reader cannot read.** That is the whole argument, and it is not a small one,
+ * because an image carries text for a great many products: a chart exported as
+ * a picture, a screenshot of a console, a diagram, a photograph of a receipt, a
+ * logo lockup with a wordmark in it. At 320 pixels wide none of that is
+ * readable, and a reader who cannot read it has been shown a thumbnail and told
+ * it was the thing. Zooming in the browser is the alternative every consumer
+ * reaches for, and it is a poor one for a reader who is not using a mouse, one
+ * for a touch device where the gesture is not discoverable, and one that leaves
+ * the page's own focus, Escape key and scroll position behind, so the reader
+ * comes back to a different place than they left. A dialog is the whole of that
+ * and it comes free from a component library.
+ *
+ * **The dialog is `Dialog`, not a re-derivation of it.** The focus trap, the
+ * restore of focus to whatever opened it, the Escape key, the outside press, the
+ * scroll lock and the portal are all already solved and all of them are solved
+ * badly twice as often as they are solved well. An image overlay built on
+ * `<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 every
+ * one of those defects is invisible in review because the overlay works for the
+ * person writing it. So this Component composes `Dialog` and spends its own
+ * surface on the three things `Dialog` does not know about: the rail, the
+ * controls and the zoom.
+ *
+ * **The four labels are props because Prism does not ship the words.** That is
+ * `check-block-copy`'s finding about `Dialog`'s close button, and it is a
+ * finding about this Component too: a hardcoded label is copy 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. They
+ * are required rather than optional even though a lightbox with no rail draws
+ * no previous and no next control, and the reasoning is worth stating because it
+ * looks like friction. A required prop is a question asked at build time; an
+ * optional one is a question nobody asks, and the lightbox that grew a rail
+ * later would be the release where the two missing labels are discovered. It
+ * also keeps the prop set stable, so adding thumbnails is not a breaking change
+ * to the type.
+ *
+ * **The zoom is a state, not a gesture.** It toggles between fitted and actual
+ * size and the frame scrolls once the image is larger than it is, so the reader
+ * pans with the scroll keys and the arrow keys the way they pan anywhere else.
+ * There is no pinch, no drag to pan and no double tap, and the reason is that
+ * each of those is a bespoke pointer model that has to be discovered, whereas a
+ * scrollable frame is a thing every reader already knows. The transition on the
+ * image is a state change the reader caused, which is the first motion law's own
+ * case, and it carries no `motion-safe:` guard because it does not need one:
+ * `packages/ui/src/styles.css` ends with one unlayered `prefers-reduced-motion`
+ * rule that stops every transition, so a reader who has asked for less motion
+ * gets the new size immediately and loses only the travel between the two.
+ *
+ * **The rail is a list of real buttons and the current one is named, not
+ * coloured.** A rail of thumbnails is the one place a lightbox most often gets
+ * this wrong: the selected thumbnail gets a border and nothing else, so a
+ * screen reader user is read six identical buttons and a reader in greyscale is
+ * shown a difference of one pixel. Here each button is named by its own `alt`,
+ * which is a description of that image rather than of the position, and the
+ * current one carries `aria-current`. The inner image is marked decorative with
+ * an empty `alt`, so the button's name is the description and not a doubled
+ * reading of the same pixels.
+ *
+ * **The current image is the caller's.** `src` and `alt` are props, so this
+ * Component cannot move the image, and every control here asks for an index
+ * rather than setting one. That is a real constraint on a caller who wants the
+ * lightbox to own the sequence, and the reason for it is the same as everywhere
+ * else in this package: the images are application data, and a Component that
+ * held them would be a Component every consumer whose gallery is not this shape
+ * had to reimplement. A caller that wants an uncontrolled lightbox passes
+ * `index` and `onIndexChange` and keeps the state; one that wants the lightbox
+ * to remember where it was omits both and gets the local one.
+ *
+ * It is a client Component, and only because `Dialog` is one.
+ */
+declare function Lightbox({ open, onOpenChange, src, alt, caption, thumbnails, index, onIndexChange, zoomLabel, previousLabel, nextLabel, closeLabel, className, }: LightboxProps): import("react").JSX.Element;
+export { Lightbox };
+//# sourceMappingURL=lightbox.d.ts.map

package/dist/components/ui/lightbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lightbox.d.ts","sourceRoot":"","sources":["../../../src/components/ui/lightbox.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAK3D,6DAA6D;AAC7D,KAAK,iBAAiB,GAAG;IACvB,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAA;IACX,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,IAAI,EAAE,OAAO,CAAA;IACb,8DAA8D;IAC9D,YAAY,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACrC,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;;;;OASG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;IACzC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kDAAkD;IAClD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,uGAAuG;IACvG,aAAa,EAAE,MAAM,CAAA;IACrB,mGAAmG;IACnG,SAAS,EAAE,MAAM,CAAA;IACjB,gGAAgG;IAChG,UAAU,EAAE,MAAM,CAAA;IAClB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA2BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,iBAAS,QAAQ,CAAC,EAChB,IAAI,EACJ,YAAY,EACZ,GAAG,EACH,GAAG,EACH,OAAO,EACP,UAAU,EACV,KAAK,EACL,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACT,UAAU,EACV,SAAS,GACV,EAAE,aAAa,+BA+Kf;AAED,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/ui/lightbox.js

@@ -0,0 +1,130 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronLeftIcon, ChevronRightIcon, XIcon, ZoomInIcon, ZoomOutIcon } from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { cn } from '../../lib/utils.js';
+import { Dialog, DialogClose, DialogContent, DialogTitle } from './dialog.js';
+/**
+ * The metrics every control in this Component draws, and the coarse-pointer floor.
+ *
+ * `pointer-coarse:size-11` is a step rather than a band. These are ghost icon
+ * controls in a centred bar inside the dialog, and the drawn size is not the point of
+ * any of them, which is the condition a band exists for and the reason the switch,
+ * thumb and corner-icon cases in `DESIGN.md` band instead. The bar is `gap-2`, so
+ * growing each control by four pixels on each side costs eight pixels of gap per
+ * neighbour and the bar is centred rather than flush, so nothing shifts off the edge.
+ *
+ * The close control here is a `DialogClose`, and `DialogClose` carries no size of its
+ * own: `dialog.tsx` puts its coarse-pointer floor on the close control it renders
+ * inside `DialogContent`, and this one is a separate `DialogClose` passed as a child,
+ * so this string is the only thing sizing it. See DESIGN.md, The coarse-pointer floor.
+ */
+const CONTROL = 'text-muted-foreground hover:text-foreground inline-flex size-9 items-center justify-center rounded-md outline-none transition-colors duration-fast ease-out disabled:pointer-events-none disabled:opacity-50 focus-visible:ring-ring focus-visible:ring-[3px]' +
+    ' pointer-coarse:size-11';
+/** An index held inside the set, which is what keeps a rail control from falling off it. */
+function clamp(value, total) {
+    if (total <= 0)
+        return 0;
+    return Math.min(Math.max(value, 0), total - 1);
+}
+/**
+ * An image at full size, in a dialog, with its own words and its own way out.
+ *
+ * **This Item exists because an image the reader cannot enlarge is an image the
+ * reader cannot read.** That is the whole argument, and it is not a small one,
+ * because an image carries text for a great many products: a chart exported as
+ * a picture, a screenshot of a console, a diagram, a photograph of a receipt, a
+ * logo lockup with a wordmark in it. At 320 pixels wide none of that is
+ * readable, and a reader who cannot read it has been shown a thumbnail and told
+ * it was the thing. Zooming in the browser is the alternative every consumer
+ * reaches for, and it is a poor one for a reader who is not using a mouse, one
+ * for a touch device where the gesture is not discoverable, and one that leaves
+ * the page's own focus, Escape key and scroll position behind, so the reader
+ * comes back to a different place than they left. A dialog is the whole of that
+ * and it comes free from a component library.
+ *
+ * **The dialog is `Dialog`, not a re-derivation of it.** The focus trap, the
+ * restore of focus to whatever opened it, the Escape key, the outside press, the
+ * scroll lock and the portal are all already solved and all of them are solved
+ * badly twice as often as they are solved well. An image overlay built on
+ * `<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 every
+ * one of those defects is invisible in review because the overlay works for the
+ * person writing it. So this Component composes `Dialog` and spends its own
+ * surface on the three things `Dialog` does not know about: the rail, the
+ * controls and the zoom.
+ *
+ * **The four labels are props because Prism does not ship the words.** That is
+ * `check-block-copy`'s finding about `Dialog`'s close button, and it is a
+ * finding about this Component too: a hardcoded label is copy 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. They
+ * are required rather than optional even though a lightbox with no rail draws
+ * no previous and no next control, and the reasoning is worth stating because it
+ * looks like friction. A required prop is a question asked at build time; an
+ * optional one is a question nobody asks, and the lightbox that grew a rail
+ * later would be the release where the two missing labels are discovered. It
+ * also keeps the prop set stable, so adding thumbnails is not a breaking change
+ * to the type.
+ *
+ * **The zoom is a state, not a gesture.** It toggles between fitted and actual
+ * size and the frame scrolls once the image is larger than it is, so the reader
+ * pans with the scroll keys and the arrow keys the way they pan anywhere else.
+ * There is no pinch, no drag to pan and no double tap, and the reason is that
+ * each of those is a bespoke pointer model that has to be discovered, whereas a
+ * scrollable frame is a thing every reader already knows. The transition on the
+ * image is a state change the reader caused, which is the first motion law's own
+ * case, and it carries no `motion-safe:` guard because it does not need one:
+ * `packages/ui/src/styles.css` ends with one unlayered `prefers-reduced-motion`
+ * rule that stops every transition, so a reader who has asked for less motion
+ * gets the new size immediately and loses only the travel between the two.
+ *
+ * **The rail is a list of real buttons and the current one is named, not
+ * coloured.** A rail of thumbnails is the one place a lightbox most often gets
+ * this wrong: the selected thumbnail gets a border and nothing else, so a
+ * screen reader user is read six identical buttons and a reader in greyscale is
+ * shown a difference of one pixel. Here each button is named by its own `alt`,
+ * which is a description of that image rather than of the position, and the
+ * current one carries `aria-current`. The inner image is marked decorative with
+ * an empty `alt`, so the button's name is the description and not a doubled
+ * reading of the same pixels.
+ *
+ * **The current image is the caller's.** `src` and `alt` are props, so this
+ * Component cannot move the image, and every control here asks for an index
+ * rather than setting one. That is a real constraint on a caller who wants the
+ * lightbox to own the sequence, and the reason for it is the same as everywhere
+ * else in this package: the images are application data, and a Component that
+ * held them would be a Component every consumer whose gallery is not this shape
+ * had to reimplement. A caller that wants an uncontrolled lightbox passes
+ * `index` and `onIndexChange` and keeps the state; one that wants the lightbox
+ * to remember where it was omits both and gets the local one.
+ *
+ * It is a client Component, and only because `Dialog` is one.
+ */
+function Lightbox({ open, onOpenChange, src, alt, caption, thumbnails, index, onIndexChange, zoomLabel, previousLabel, nextLabel, closeLabel, className, }) {
+    const total = thumbnails?.length ?? 0;
+    const [uncontrolled, setUncontrolled] = useState(0);
+    const at = clamp(index ?? uncontrolled, total);
+    const [zoomed, setZoomed] = useState(false);
+    // Zoom is a decision about this visit. Reopening on the zoomed image would
+    // mean a reader who closed a picture halfway through came back to a crop they
+    // had forgotten they had made, and the reset is the smaller surprise.
+    useEffect(() => {
+        if (!open)
+            setZoomed(false);
+    }, [open]);
+    const move = (next) => {
+        const at1 = clamp(next, total);
+        if (index === undefined)
+            setUncontrolled(at1);
+        onIndexChange?.(at1);
+    };
+    // A string caption is the dialog's name as well as its caption: one sentence
+    // naming a figure beats the same sentence twice. A node cannot be a name,
+    // because a name is a string and a node may be a list or a picture, so the
+    // dialog falls back to the image's own description.
+    const named = typeof caption === 'string' && caption.trim() !== '' ? caption : alt;
+    const titleVisible = named === caption;
+    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { "data-slot": "lightbox", showCloseButton: false, className: cn('max-w-overlay-media', className), children: [_jsx(DialogTitle, { "data-slot": "lightbox-title", className: titleVisible ? 'text-muted-foreground text-sm font-normal' : 'sr-only', children: named }), _jsx("div", { "data-slot": "lightbox-frame", "data-zoomed": zoomed || undefined, className: "overflow-auto", children: _jsx("img", { "data-slot": "lightbox-image", src: src, alt: alt, className: cn('mx-auto block transition-transform duration-base ease-out', zoomed ? 'max-w-none' : 'max-h-[70vh] max-w-full object-contain') }) }), caption !== undefined && !titleVisible ? (_jsx("div", { "data-slot": "lightbox-caption", className: "text-muted-foreground text-sm", children: caption })) : null, total > 1 ? (_jsx("ul", { "data-slot": "lightbox-rail", className: "flex flex-wrap items-center justify-center gap-2", children: thumbnails?.map((entry, at1) => (_jsx("li", { "data-slot": "lightbox-rail-item", children: _jsx("button", { type: "button", "data-slot": "lightbox-thumbnail", "data-current": at1 === at || undefined, "aria-label": entry.alt, "aria-current": at1 === at ? 'true' : undefined, onClick: () => move(at1), className: cn('block overflow-hidden rounded-md border-2 outline-none transition-colors duration-fast ease-out', at1 === at ? 'border-primary' : 'border-transparent hover:border-border', 'focus-visible:ring-ring focus-visible:ring-[3px]'), children: _jsx("img", { "data-slot": "lightbox-thumbnail-image", src: entry.src, alt: "", className: "h-12 w-16 object-cover" }) }) }, entry.src))) })) : null, _jsxs("div", { "data-slot": "lightbox-controls", className: "flex items-center justify-center gap-2", children: [total > 1 ? (_jsx("button", { type: "button", "data-slot": "lightbox-previous", "aria-label": previousLabel, disabled: at === 0, onClick: () => move(at - 1), className: CONTROL, children: _jsx(ChevronLeftIcon, { className: "size-4", "aria-hidden": "true" }) })) : null, _jsx("button", { type: "button", "data-slot": "lightbox-zoom", "aria-label": zoomLabel, "aria-pressed": zoomed, onClick: () => setZoomed((value) => !value), className: CONTROL, children: zoomed ? (_jsx(ZoomOutIcon, { className: "size-4", "aria-hidden": "true" })) : (_jsx(ZoomInIcon, { className: "size-4", "aria-hidden": "true" })) }), total > 1 ? (_jsx("button", { type: "button", "data-slot": "lightbox-next", "aria-label": nextLabel, disabled: at === total - 1, onClick: () => move(at + 1), className: CONTROL, children: _jsx(ChevronRightIcon, { className: "size-4", "aria-hidden": "true" }) })) : null, _jsx(DialogClose, { "data-slot": "lightbox-close", "aria-label": closeLabel, className: CONTROL, children: _jsx(XIcon, { className: "size-4", "aria-hidden": "true" }) })] })] }) }));
+}
+export { Lightbox };

package/dist/components/ui/list-panel.d.ts

@@ -0,0 +1,288 @@
+import { type ComponentProps, type ReactNode } from 'react';
+/**
+ * The props a `ListPanelHeader` takes.
+ *
+ * A part rather than an Item, and it stays inside this module: DESIGN.md's
+ * authoring contract says compound parts ship from their parent module and do not
+ * form a second vocabulary, so `ListPanelHeader` is not a catalogue entry and gets
+ * no folder of its own.
+ */
+export interface ListPanelHeaderProps extends Omit<ComponentProps<'div'>, 'title'> {
+    /**
+     * The id the panel's `aria-labelledby` points at.
+     *
+     * Supplied by `ListPanel`, which generates it and puts it on the title element.
+     * It is not optional in the sense of being forgettable: a caller who renders a
+     * `ListPanelHeader` inside their own `section` passes their own id and sets
+     * `aria-labelledby` themselves, and the cost of that arrangement is the reason
+     * the `title` prop on `ListPanel` is the ordinary path.
+     */
+    titleId: string;
+    /** The one line that names the panel. */
+    title?: ReactNode;
+    /** The supporting line under the title. */
+    description?: ReactNode;
+    /**
+     * A count line, such as the caller's own "12 of 40".
+     *
+     * A node and not a number because the sentence around the number is the
+     * consumer's: an English reader wants "12 of 40", a locale that puts the total
+     * first wants it the other way round, and a panel that assembled the sentence
+     * would have assembled it in one of them.
+     */
+    count?: ReactNode;
+    /** The controls at the trailing edge of the header. */
+    actions?: ReactNode;
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * The props a `ListPanelBody` takes, as a union over whether the body scrolls.
+ *
+ * A union rather than two independent optionals, for the reason the whole module
+ * keeps repeating: a scroll region is a tab stop, so a scrolling body owes it a
+ * name, and a body that does not scroll is not a tab stop and owes nothing. One
+ * optional prop set cannot say that, and a `label` that is required in one shape
+ * and optional in another is a prop whose absence is sometimes a mistake and
+ * sometimes a decision.
+ */
+export type ListPanelBodyProps = Omit<ComponentProps<'div'>, 'children'> & {
+    /** The rows, or whatever the list actually is. */
+    children?: ReactNode;
+    /** Layout only. */
+    className?: string;
+} & ({
+    /**
+     * A body that scrolls, which is a tab stop and therefore has to be named.
+     *
+     * The rule `ScrollArea` states, restated here because the body is the part
+     * the caller touches, and a rule one step further on is a rule a caller reading
+     * this module never meets. `scroll` is optional in this arm rather than
+     * required, so a caller who is scrolling writes `<ListPanelBody label="...">`
+     * and reads no boolean at all.
+     */
+    scroll?: true;
+    label: string;
+} | {
+    /**
+     * A body that grows with its content, which is not a tab stop and needs no
+     * name.
+     */
+    scroll?: false;
+    label?: string;
+});
+/** The props a `ListPanelFooter` takes. */
+export interface ListPanelFooterProps extends ComponentProps<'div'> {
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * The props a `ListPanel` takes, as a union over whether the body scrolls.
+ *
+ * A union rather than one optional prop set, because `label` and `maxHeight` are
+ * required in one shape and meaningless in the other, and an optional prop cannot
+ * say that. A caller who turns scrolling on has named a tab stop and owes it a
+ * name; a caller who has turned it off has no tab stop and owes nothing.
+ */
+export type ListPanelProps = Omit<ComponentProps<'section'>, 'children' | 'title'> & {
+    /**
+     * The one line that names the panel, and the accessible name of the region.
+     *
+     * A `ReactNode` and not a `string`, because the panel's visible title is
+     * content: an emphasis inside it, a count styled as part of it, a node with a
+     * link in it. The accessible name is derived from this element by
+     * `aria-labelledby` rather than set as a string, so the two can never say
+     * different things.
+     */
+    title?: ReactNode;
+    /** The supporting line under the title, in the muted ink. */
+    description?: ReactNode;
+    /**
+     * A count line, such as the caller's own "12 of 40".
+     *
+     * Rendered under the description rather than beside the title because a count
+     * is read after the name and before the description, and putting it on the
+     * title's line would make the title itself wrap for a number.
+     */
+    count?: ReactNode;
+    /**
+     * The header's toolbar slot: the controls that act on the whole list rather
+     * than on one row.
+     *
+     * A slot and not a set of named controls, because which controls a list has is
+     * the consumer's fact. A panel that drew a search box and a sort would be a
+     * panel that assumed the list it holds is searchable and sortable.
+     */
+    actions?: ReactNode;
+    /**
+     * The footer's slot: the actions that belong to the whole list, such as load
+     * more, or the line saying how much of the set is shown.
+     *
+     * Distinct from `actions` because a header acts on the list and a footer ends
+     * it, and because the footer is the only part that stays put while the body
+     * scrolls. Merging them would put a control that has to stay reachable in a
+     * band that scrolls away.
+     */
+    footer?: ReactNode;
+    /** The list itself: the caller's own `ul`, `ol`, table or set of rows. */
+    children?: ReactNode;
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+} & ({
+    /**
+     * Whether the body scrolls inside the panel's `maxHeight`.
+     *
+     * On by default, and the default is the decision: the panel exists because
+     * the list is long, and a panel that grows to the length of its list is a
+     * frame around a page.
+     */
+    scroll?: true;
+    /**
+     * The height the panel stops at, in pixels, once the list is longer than
+     * that.
+     *
+     * A number and not a Tailwind class because the bound is data rather than
+     * layout: the same panel is a short one in a sidebar and a tall one on a
+     * full page, and a caller who could only say `max-h-80` would be picking
+     * one of those for the other.
+     */
+    maxHeight?: number;
+    /**
+     * The panel's accessible name, and the scroll region's.
+     *
+     * A `string` and not a `ReactNode`, because this one is written into
+     * `aria-label` and an accessible name is a string. A node here would
+     * render as nothing a reader hears.
+     */
+    label: string;
+} | {
+    /** Turn scrolling off for a panel whose list is known to be short. */
+    scroll: false;
+    /** A bound with no scrolling is a bound that hides rows, so it is refused. */
+    maxHeight?: never;
+    /**
+     * The panel's accessible name, used only when there is no `title` to take
+     * it from.
+     */
+    label?: string;
+});
+/**
+ * A titled panel whose body is a scrolling list, with slots above and below it.
+ *
+ * **This is the third thing, and the reason it exists is that the other two were
+ * already taken.** `item.tsx` is a row: media, a name, a description, a value
+ * and trailing controls, with no opinion at all about what encloses it. And
+ * `fact-list.tsx` is a definition list: a term beside its answer, scanned down a
+ * column, short enough that the whole set is meant to be read. Neither is a
+ * container, and a long list needs one. So this is the third thing: a titled,
+ * bounded, scrollable region that gives a long list a place to end. The three
+ * compose, and none of them can be derived from another: rows without a panel is
+ * a page that never ends, and a panel without rows is a frame.
+ *
+ * **A `ListPanel` is not a table, and the difference is the reader's job rather
+ * than the markup's.** A panel holds a list: each row is one thing, read top to
+ * bottom, and the reader is scanning for the one they want. The moment the reader
+ * needs to compare a value in one row against the same value in another, the
+ * content is records with columns, the answer is `table.tsx`, and putting rows in
+ * a panel instead is a table a reader has to read cell by cell because the
+ * semantics are not there. The reverse is equally wrong: a two-column table of
+ * one thing per row, where the second column is a status nobody compares against
+ * anything, is a list that paid for column semantics it does not use.
+ *
+ * **The region is a real `<section>` and it is named by its own title.** Not a
+ * `div`, because a panel of forty rows is a landmark a screen reader user walks
+ * past on the way to something else, and a landmark they cannot name is a
+ * landmark they walk past twice. The name comes from `aria-labelledby` pointing
+ * at the title element rather than from a string prop, so the name a reader hears
+ * and the name a sighted reader reads are the same text by construction and
+ * cannot drift.
+ *
+ * **With no title there is no invented one.** The panel renders a `section` with
+ * no name and says nothing, and `label` is the only way to name it. This is the
+ * one place in this package where a region is allowed to arrive anonymous, and it
+ * is the right answer rather than a gap: a panel named "Panel" is a claim that
+ * is wrong in every consumer's product, and a screen reader user hearing "Panel"
+ * learns less than hearing nothing, because a name is a promise that something
+ * follows it. An anonymous region is honestly absent from the landmark list and
+ * the reader moves on. A caller who wants a name passes one.
+ *
+ * **The scroll is `ScrollArea` and not `overflow: auto`, and that is the whole
+ * reason the body is not written inline.** The browser's scrollbar is the one
+ * control on a page that belongs to no design system: it is a rectangle the
+ * operating system drew, in a colour chosen for the OS's own background rather
+ * than for the card the content is on, and it is the only control that is resized
+ * by dragging and appears on a timer. Composing this panel around `overflow-auto`
+ * would give the reader a Prism surface beside an operating system scrollbar on
+ * every panel in every consumer. The scrolling itself is still the browser's, so
+ * the arrow keys, Page Up, Page Down, Home, End, the scroll position and
+ * scroll-into-view all keep working, and only the bar's appearance is taken over.
+ *
+ * **The bound is on the panel and the body absorbs it.** `maxHeight` is set on
+ * the `section`, which is a flex column, and the body is the flex item that
+ * shrinks, so a list shorter than the bound grows the panel to fit and a list
+ * longer than it scrolls inside what is left after the header and the footer. The
+ * alternative, a `max-height` on the scroll region alone, leaves the region's own
+ * height content-driven and clips the rows without giving the reader anything to
+ * scroll.
+ *
+ * **The title's id is generated, and `useId` is why this module needs no
+ * `'use client'`.** Pointing `aria-labelledby` at an element the Component drew
+ * itself needs an id, and the Component may not invent one by counting: two panels
+ * on a page would both reach for the same first id. `useId` is the one hook React
+ * runs during a server render as well as a client one, so the panel is an ordinary
+ * server Component with the `'use client'` line and the client runtime left off.
+ * What that costs is stated rather than implied: a panel whose body scrolls is in
+ * the client graph anyway, through `ScrollArea`, and a panel with `scroll={false}`
+ * and no caller state of its own ships no JavaScript from this file.
+ *
+ * The four exported parts are the panel's own pieces, and they are exported
+ * rather than kept private for the reason `Card`'s parts are: a caller who wants
+ * the header's geometry inside a `Card` they built, or a footer on a section of
+ * their own, should not have to re-derive `border-b px-4 py-3` to get it. The
+ * `title`, `description`, `count`, `actions` and `footer` props are the shorthand
+ * for the ordinary case, and the two are the same markup.
+ */
+declare function ListPanel({ title, description, count, actions, footer, children, scroll, maxHeight, label, className, style, ...props }: ListPanelProps): import("react").JSX.Element;
+/**
+ * The row above a panel's list: the title, its supporting lines, and a toolbar
+ * slot at the trailing edge.
+ *
+ * Rendered by `ListPanel` when any of its four slots is present, and not rendered
+ * at all when none is, because a bordered band with nothing in it is a gap the
+ * reader looks through. The title element is a `span` carrying the id the panel
+ * points `aria-labelledby` at, rather than a heading: a panel's title is not
+ * always the heading of the region it sits in, four panels in a grid are four
+ * titles under one section heading, and four `h3`s under one `h2` is right while
+ * four `h2`s is four sections. A caller who wants a heading there passes an
+ * element as `title` and keeps the name.
+ */
+declare function ListPanelHeader({ titleId, title, description, count, actions, className, ...props }: ListPanelHeaderProps): import("react").JSX.Element;
+/**
+ * A panel's body: the list, and the scroll region it scrolls in.
+ *
+ * **The scroll region is `ScrollArea` and the rows are the caller's own element.**
+ * The panel draws the frame and the scrollbar; the caller writes the `ul`, the
+ * `ol` or the table inside it, because the shape of the list is a fact about the
+ * data and a list of records in a `ul` is a different thing from the same records
+ * in a table. That is the same decision `Item` makes about the row, applied one
+ * level up, and it is why this Component takes `children` and no `items`.
+ *
+ * The vertical scrollbar only. A panel scrolls because it is tall, and a panel
+ * whose content is also wider than the panel is a caller who has put a table in
+ * the wrong place: `table.tsx` already owns a horizontal region for exactly that,
+ * and two nested scrollers is a reader with two axes to guess about.
+ */
+declare function ListPanelBody({ scroll, label, className, children, ...props }: ListPanelBodyProps): import("react").JSX.Element;
+/**
+ * The band under a panel's list, where the actions that belong to the whole list
+ * sit and where a count that is not the caller's headline number belongs.
+ *
+ * On the muted surface and above a rule rather than on the card, because it is the
+ * one band in the panel that does not scroll: a control the reader has to reach
+ * after scrolling to the end of a long list cannot be in the list. A footer that
+ * scrolls away with the rows is a footer that only exists for a reader who never
+ * needed it.
+ */
+declare function ListPanelFooter({ className, ...props }: ListPanelFooterProps): import("react").JSX.Element;
+export { ListPanel, ListPanelHeader, ListPanelBody, ListPanelFooter };
+//# sourceMappingURL=list-panel.d.ts.map

package/dist/components/ui/list-panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-panel.d.ts","sourceRoot":"","sources":["../../../src/components/ui/list-panel.tsx"],"names":[],"mappings":"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"}