@nanisoft/prism-ui 0.13.0 → 0.15.0

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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"}

package/dist/components/ui/list-panel.js

@@ -0,0 +1,139 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { ScrollArea } from './scroll-area.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * 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.
+ */
+function ListPanel({ title, description, count, actions, footer, children, scroll, maxHeight, label, className, style, ...props }) {
+    const titleId = useId();
+    const named = title !== undefined;
+    const hasHeader = named || description !== undefined || count !== undefined || actions !== undefined;
+    const hasFooter = footer !== undefined && footer !== null && footer !== false;
+    return (_jsxs("section", { "data-slot": "list-panel", "aria-labelledby": named ? titleId : undefined, "aria-label": named ? undefined : label, style: maxHeight === undefined ? style : { maxHeight, ...style }, className: cn('bg-card text-card-foreground flex min-h-0 flex-col overflow-hidden rounded-lg border', className), ...props, children: [hasHeader ? (_jsx(ListPanelHeader, { titleId: titleId, title: title, description: description, count: count, actions: actions })) : null, scroll === false ? (_jsx(ListPanelBody, { label: label, children: children })) : (_jsx(ListPanelBody, { scroll: true, label: label, children: children })), hasFooter ? _jsx(ListPanelFooter, { children: footer }) : null] }));
+}
+/**
+ * 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.
+ */
+function ListPanelHeader({ titleId, title, description, count, actions, className, ...props }) {
+    return (_jsxs("div", { "data-slot": "list-panel-header", className: cn('flex items-start justify-between gap-4 border-b px-4 py-3', className), ...props, children: [_jsxs("div", { className: "flex min-w-0 flex-col gap-0.5", children: [title === undefined ? null : (_jsx("span", { id: titleId, "data-slot": "list-panel-title", className: "text-sm font-medium", children: title })), description === undefined ? null : (_jsx("span", { "data-slot": "list-panel-description", className: "text-muted-foreground text-sm", children: description })), count === undefined ? null : (_jsx("span", { "data-slot": "list-panel-count", className: "text-muted-foreground text-xs tabular-nums", children: count }))] }), actions === undefined ? null : (_jsx("div", { "data-slot": "list-panel-actions", className: "flex shrink-0 items-center gap-2", children: actions }))] }));
+}
+/**
+ * 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.
+ */
+function ListPanelBody({ scroll, label, className, children, ...props }) {
+    return (_jsx("div", { "data-slot": "list-panel-body", className: cn('min-w-0 flex-1', 
+        // The two states differ in more than a wrapper. A bounded body clips and
+        // hands the overflow to the scroll region; an unbounded one is allowed to
+        // grow, because the caller has said the list is short.
+        scroll === true ? 'min-h-0 overflow-hidden' : '', className), ...props, children: scroll === true ? (_jsx(ScrollArea, { label: label, orientation: "vertical", className: "h-full", children: children })) : (children) }));
+}
+/**
+ * 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.
+ */
+function ListPanelFooter({ className, ...props }) {
+    return (_jsx("div", { "data-slot": "list-panel-footer", className: cn('bg-muted/50 flex items-center gap-3 border-t px-4 py-3 text-sm', className), ...props }));
+}
+export { ListPanel, ListPanelHeader, ListPanelBody, ListPanelFooter };