@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/components/ui/combobox.js

@@ -35,7 +35,10 @@ import { cn } from '../../lib/utils.js';
  * open and explains that the query found nothing, because a combobox that closed
  * itself on a non-match tells the reader their keystroke broke the control. The
  * explanation is a prop, since the sentence is the caller's and the query is put
- * into it.
+ * into it. The message is a sibling of the listbox and not inside it, because a
+ * listbox owns `option` and `group` and nothing else, and the field's
+ * `aria-controls` points at the popup rather than at the listbox, because there is
+ * no listbox in that state and `aria-controls` is required on an expanded combobox.
  *
  * **The field keeps the caret for the whole interaction.** The arrows move a
  * highlight through the list and leave focus where it is, so a reader can keep
@@ -67,6 +70,10 @@ function Combobox({ label, items, value, defaultValue = null, onValueChange, emp
     const generated = useId();
     const inputId = id ?? generated;
     const listId = `${generated}-list`;
+    // The popup the field controls. Separate from the listbox id because the listbox is
+    // not rendered at all when nothing matched, and `aria-controls` is a required
+    // attribute on an expanded combobox.
+    const popupId = `${generated}-popup`;
     const chosen = value === undefined ? ownValue : value;
     /** The chosen option, resolved against the option set the caller passed. */
     const chosenItem = useMemo(() => items.find((item) => item.value === chosen) ?? null, [items, chosen]);
@@ -208,7 +215,7 @@ function Combobox({ label, items, value, defaultValue = null, onValueChange, emp
         list.querySelector('[data-active="true"]')?.scrollIntoView({ block: 'nearest' });
     }, [activeIndex, isOpen]);
     const activeRow = isOpen ? ranked[activeIndex] : undefined;
-    return (_jsxs("div", { "data-slot": "combobox", className: cn('relative w-full', className), children: [_jsx("input", { "data-slot": "combobox-input", id: inputId, type: "text", role: "combobox", autoComplete: "off", "aria-expanded": isOpen && ranked.length > 0, "aria-controls": listId, "aria-haspopup": "listbox", "aria-autocomplete": "list", "aria-label": label, "aria-required": required || undefined, "aria-activedescendant": activeRow === undefined ? undefined : `${listId}-option-${activeIndex}`, ...(describedBy === undefined ? null : { 'aria-describedby': describedBy }), ...(placeholder === undefined ? null : { placeholder }), value: query, disabled: disabled, onChange: (event) => {
+    return (_jsxs("div", { "data-slot": "combobox", className: cn('relative w-full', className), children: [_jsx("input", { "data-slot": "combobox-input", id: inputId, type: "text", role: "combobox", autoComplete: "off", "aria-expanded": isOpen, "aria-controls": isOpen ? popupId : undefined, "aria-haspopup": "listbox", "aria-autocomplete": "list", "aria-label": label, "aria-required": required || undefined, "aria-activedescendant": activeRow === undefined ? undefined : `${listId}-option-${activeIndex}`, ...(describedBy === undefined ? null : { 'aria-describedby': describedBy }), ...(placeholder === undefined ? null : { placeholder }), value: query, disabled: disabled, onChange: (event) => {
                     const next = event.target.value;
                     setQuery(next);
                     setActive(0);
@@ -227,7 +234,16 @@ function Combobox({ label, items, value, defaultValue = null, onValueChange, emp
                 }, onBlur: () => {
                     setOpen(false);
                     restore();
-                }, onKeyDown: onKeyDown, className: cn('border-input bg-background text-foreground placeholder:text-muted-foreground flex h-9 w-full min-w-0 rounded-md border px-3 py-1 text-base shadow-xs transition-[color,box-shadow] duration-fast ease-out outline-none md:text-sm', 'focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50') }), name === undefined ? null : (_jsx("input", { type: "hidden", name: name, ...(form === undefined ? null : { form }), value: chosen ?? '', readOnly: true })), isOpen ? (ranked.length === 0 ? (_jsx("div", { "data-slot": "combobox-popup", className: "bg-popover text-popover-foreground absolute z-50 mt-1 w-full min-w-(--anchor-width) rounded-md border p-1 shadow-md", children: _jsxs("p", { "data-slot": "combobox-empty", role: "status", className: "text-muted-foreground px-3 py-6 text-center text-sm", children: [empty.message(trimmed), empty.hint === undefined ? null : (_jsx("span", { className: "mt-1 block text-xs", children: empty.hint }))] }) })) : (_jsx("div", { "data-slot": "combobox-popup", className: "bg-popover text-popover-foreground absolute z-50 mt-1 w-full min-w-(--anchor-width) rounded-md border p-1 shadow-md", children: _jsx("div", { "data-slot": "combobox-list", id: listId, ref: listRef, role: "listbox", "aria-label": label, className: "max-h-72 overflow-y-auto", children: ranked.map((hit, index) => {
+                }, onKeyDown: onKeyDown, className: cn('border-input bg-background text-foreground placeholder:text-muted-foreground flex h-9 w-full min-w-0 rounded-md border px-3 py-1 text-base shadow-xs transition-[color,box-shadow] duration-fast ease-out outline-none md:text-sm', 'focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50') }), name === undefined ? null : (_jsx("input", { type: "hidden", name: name, ...(form === undefined ? null : { form }), value: chosen ?? '', readOnly: true })), isOpen ? (
+            /*
+             * One popup with two children rather than two popups, because the empty
+             * message is a sibling of the listbox and not inside it: a listbox owns
+             * `option` and `group` and nothing else, so a `<p>` in the empty branch was a
+             * phantom row the index counted and no reader could choose. The id on the
+             * panel is what the field's `aria-controls` points at, so that reference
+             * resolves whether or not there is a listbox to point at.
+             */
+            _jsx("div", { id: popupId, "data-slot": "combobox-popup", className: "bg-popover text-popover-foreground absolute z-50 mt-1 w-full min-w-(--anchor-width) rounded-md border p-1 shadow-md", children: ranked.length === 0 ? (_jsxs("p", { "data-slot": "combobox-empty", role: "status", className: "text-muted-foreground px-3 py-6 text-center text-sm", children: [empty.message(trimmed), empty.hint === undefined ? null : (_jsx("span", { className: "mt-1 block text-xs", children: empty.hint }))] })) : (_jsx("div", { "data-slot": "combobox-list", id: listId, ref: listRef, role: "listbox", "aria-label": label, className: "max-h-72 overflow-y-auto", children: ranked.map((hit, index) => {
                         const isActive = index === activeIndex;
                         return (_jsxs("div", { id: `${listId}-option-${index}`, "data-slot": "combobox-option", "data-active": isActive, role: "option", "aria-selected": hit.item.value === chosen, "aria-disabled": hit.item.disabled || undefined, onMouseEnter: () => {
                                 if (!hit.item.disabled)
@@ -238,6 +254,6 @@ function Combobox({ label, items, value, defaultValue = null, onValueChange, emp
                             // pointer choice is a blur, and the blur is the path that puts
                             // the old answer back into the field.
                             onMouseDown: (event) => event.preventDefault(), onClick: () => run(hit.item), className: cn('flex cursor-pointer items-baseline justify-between gap-3 rounded-sm px-3 py-2 text-sm outline-none', 'focus-visible:ring-ring focus-visible:ring-[3px]', hit.item.disabled && 'text-muted-foreground cursor-not-allowed opacity-50', !hit.item.disabled && isActive && 'bg-accent text-accent-foreground', !hit.item.disabled && !isActive && 'text-muted-foreground hover:text-foreground'), children: [_jsx("span", { className: "min-w-0 truncate", children: hit.range === undefined ? (hit.item.label) : (_jsxs(_Fragment, { children: [hit.item.label.slice(0, hit.range[0]), _jsx("strong", { className: "font-semibold", children: hit.item.label.slice(hit.range[0], hit.range[1]) }), hit.item.label.slice(hit.range[1])] })) }), hit.item.hint === undefined ? null : (_jsx("span", { className: "shrink-0 text-xs", children: hit.item.hint }))] }, hit.item.value));
-                    }) }) }))) : null] }));
+                    }) })) })) : null] }));
 }
 export { Combobox };

package/dist/components/ui/command-palette.d.ts

@@ -100,6 +100,17 @@ export interface CommandPaletteProps {
  * highlight through the list rather than moving focus into it, so a reader can keep
  * typing while they choose, and the highlighted row carries the state. That is the
  * combobox pattern and it is the reason the arrows do not steal the caret.
+ *
+ * **A query that matched nothing is a popup that is still open.** The panel stays,
+ * it says so in the caller's sentence, and the field announces itself expanded,
+ * because a palette that closed itself on a non-match tells the reader their
+ * keystroke broke it. The message is a sibling of the listbox rather than a child of
+ * it, because a listbox owns `option` and `group` and nothing else, and
+ * `aria-controls` points at the palette rather than at the listbox, because the
+ * listbox is not on the page in that state and `aria-controls` is required on an
+ * expanded combobox. `Combobox`, `MultiCombobox` and `CreatableCombobox` make the
+ * same choices, and they make them here rather than each answering the question
+ * again.
  */
 declare function CommandPalette({ open, onOpenChange, label, inputLabel, placeholder, groups, suggest, empty, className, }: CommandPaletteProps): import("react").JSX.Element;
 export { CommandPalette };

package/dist/components/ui/command-palette.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-palette.d.ts","sourceRoot":"","sources":["../../../src/components/ui/command-palette.tsx"],"names":[],"mappings":"AAQA;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,oBAAoB;IACpB,EAAE,EAAE,MAAM,CAAA;IACV,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,sCAAsC;IACtC,QAAQ,EAAE,MAAM,IAAI,CAAA;CACrB,CAAA;AAED,0DAA0D;AAC1D,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;CAC9B,CAAA;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,IAAI,EAAE,OAAO,CAAA;IACb,2CAA2C;IAC3C,YAAY,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACrC;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6BAA6B;IAC7B,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;IAC/B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;KAAE,CAAA;IAC1D;;;;;;OAMG;IACH,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5D,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,iBAAS,cAAc,CAAC,EACtB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,OAAO,EACP,KAAK,EACL,SAAS,GACV,EAAE,mBAAmB,+BAqPrB;AAED,OAAO,EAAE,cAAc,EAAE,CAAA"}
+{"version":3,"file":"command-palette.d.ts","sourceRoot":"","sources":["../../../src/components/ui/command-palette.tsx"],"names":[],"mappings":"AAQA;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,oBAAoB;IACpB,EAAE,EAAE,MAAM,CAAA;IACV,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,sCAAsC;IACtC,QAAQ,EAAE,MAAM,IAAI,CAAA;CACrB,CAAA;AAED,0DAA0D;AAC1D,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;CAC9B,CAAA;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,IAAI,EAAE,OAAO,CAAA;IACb,2CAA2C;IAC3C,YAAY,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACrC;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6BAA6B;IAC7B,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;IAC/B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;KAAE,CAAA;IAC1D;;;;;;OAMG;IACH,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5D,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,iBAAS,cAAc,CAAC,EACtB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,OAAO,EACP,KAAK,EACL,SAAS,GACV,EAAE,mBAAmB,+BAiUrB;AAED,OAAO,EAAE,cAAc,EAAE,CAAA"}

package/dist/components/ui/command-palette.js

@@ -32,12 +32,27 @@ import { cn } from '../../lib/utils.js';
  * highlight through the list rather than moving focus into it, so a reader can keep
  * typing while they choose, and the highlighted row carries the state. That is the
  * combobox pattern and it is the reason the arrows do not steal the caret.
+ *
+ * **A query that matched nothing is a popup that is still open.** The panel stays,
+ * it says so in the caller's sentence, and the field announces itself expanded,
+ * because a palette that closed itself on a non-match tells the reader their
+ * keystroke broke it. The message is a sibling of the listbox rather than a child of
+ * it, because a listbox owns `option` and `group` and nothing else, and
+ * `aria-controls` points at the palette rather than at the listbox, because the
+ * listbox is not on the page in that state and `aria-controls` is required on an
+ * expanded combobox. `Combobox`, `MultiCombobox` and `CreatableCombobox` make the
+ * same choices, and they make them here rather than each answering the question
+ * again.
  */
 function CommandPalette({ open, onOpenChange, label, inputLabel, placeholder, groups, suggest, empty, className, }) {
     const [query, setQuery] = useState('');
     const [active, setActive] = useState(0);
     const listRef = useRef(null);
     const titleId = useId();
+    // The surface the field controls, which is the palette itself. Separate from the
+    // listbox id because the listbox is not rendered at all when nothing matched, and
+    // `aria-controls` is a required attribute on an expanded combobox.
+    const popupId = `${titleId}-popup`;
     const trimmed = query.trim();
     /**
      * The ranked result: groups in their declared order, items within a group by
@@ -153,6 +168,10 @@ function CommandPalette({ open, onOpenChange, label, inputLabel, placeholder, gr
         // reader is already in. The DialogTitle is still rendered and still names
         // the dialog for assistive technology, which is the whole reason it
         // exists separately from anything visible.
+        //
+        // The id is the field's `aria-controls`. It is on the surface rather than on
+        // the listbox because the listbox is not rendered when nothing matched, and
+        // the field is expanded whenever the palette is open.
         , { 
             // The palette is a wide, top-anchored surface rather than a centred card,
             // and it carries no visible heading: the search field is what a reader
@@ -160,17 +179,44 @@ function CommandPalette({ open, onOpenChange, label, inputLabel, placeholder, gr
             // reader is already in. The DialogTitle is still rendered and still names
             // the dialog for assistive technology, which is the whole reason it
             // exists separately from anything visible.
-            side: "top", showCloseButton: false, className: cn('max-w-xl gap-0 p-0', className), children: [_jsx(DialogTitle, { className: "sr-only", children: label }), _jsx("div", { className: "border-border flex items-center border-b px-3", children: _jsx("input", { "data-slot": "command-palette-input", type: "text", role: "combobox", "aria-expanded": flat.length > 0, "aria-controls": `${titleId}-list`, "aria-activedescendant": flat[activeIndex] === undefined ? undefined : `${titleId}-item-${flat[activeIndex]?.id}`, "aria-label": inputLabel, ...(placeholder === undefined ? null : { placeholder }), value: query, onChange: (event) => {
+            //
+            // The id is the field's `aria-controls`. It is on the surface rather than on
+            // the listbox because the listbox is not rendered when nothing matched, and
+            // the field is expanded whenever the palette is open.
+            id: popupId, side: "top", showCloseButton: false, className: cn('max-w-overlay-palette gap-0 p-0', className), children: [_jsx(DialogTitle, { className: "sr-only", children: label }), _jsx("div", { className: "border-border flex items-center border-b px-3", children: _jsx("input", { "data-slot": "command-palette-input", type: "text", role: "combobox", "aria-expanded": open, "aria-controls": open ? popupId : undefined, "aria-activedescendant": flat[activeIndex] === undefined ? undefined : `${titleId}-item-${flat[activeIndex]?.id}`, "aria-label": inputLabel, ...(placeholder === undefined ? null : { placeholder }), value: query, onChange: (event) => {
                             setQuery(event.target.value);
                             setActive(0);
                         }, onKeyDown: onKeyDown, 
                         // The field is focused when the palette opens, so a reader can type
                         // immediately. Nothing else in the surface is focusable, which is what
                         // makes this a combobox rather than a list of buttons.
-                        autoFocus: true, className: "placeholder:text-muted-foreground h-12 w-full bg-transparent text-sm outline-none" }) }), _jsx("div", { "data-slot": "command-palette-list", id: `${titleId}-list`, ref: listRef, role: "listbox", "aria-label": label, className: "max-h-80 overflow-y-auto p-1", children: results.length === 0 ? (_jsxs("p", { "data-slot": "command-palette-empty", className: "text-muted-foreground px-3 py-6 text-center text-sm", children: [empty.message(trimmed), empty.hint === undefined ? null : (_jsx("span", { className: "mt-1 block text-xs", children: empty.hint }))] })) : (results.map((group) => (_jsxs("div", { "data-slot": "command-palette-group", className: "mb-1 last:mb-0", children: [_jsx("div", { "data-slot": "command-palette-group-label", className: "text-muted-foreground bg-popover text-xs font-medium tracking-wide uppercase sticky top-0 px-3 py-1.5", children: group.label }), group.hits.map((hit) => {
+                        autoFocus: true, 
+                        // The ring is at full strength, and it is drawn at all because this is
+                        // the control focus lands in and `outline-none` is what removed the
+                        // browser's indicator from it. A field with no visible focus is a field
+                        // a keyboard reader cannot say they are inside. The ring and not the
+                        // border, as `Command` draws it: this field has no border to colour.
+                        //
+                        // `text-base` then `md:text-sm`, which is the pair `Input`, `Textarea`,
+                        // `Combobox`, `Form` and `NumberField` all carry and which this field
+                        // was the one exception to. The reason is iOS Safari and not a visual
+                        // one: it zooms the viewport on a focused input under 16 pixels and does
+                        // not zoom back out, so a palette opened on a phone was a page the reader
+                        // could not get out of.
+                        className: "placeholder:text-muted-foreground h-12 w-full bg-transparent text-base outline-none focus-visible:ring-ring focus-visible:ring-[3px] md:text-sm" }) }), results.length === 0 ? (_jsx("div", { "data-slot": "command-palette-empty-state", className: "max-h-80 overflow-y-auto p-1", children: _jsxs("p", { "data-slot": "command-palette-empty", role: "status", className: "text-muted-foreground px-3 py-6 text-center text-sm", children: [empty.message(trimmed), empty.hint === undefined ? null : (_jsx("span", { className: "mt-1 block text-xs", children: empty.hint }))] }) })) : (_jsx("div", { "data-slot": "command-palette-list", id: `${titleId}-list`, ref: listRef, role: "listbox", "aria-label": label, className: "max-h-80 overflow-y-auto p-1", children: results.map((group) => (
+                    /*
+                     * `role="group"` and not a bare `<div>`. A listbox owns `option` and
+                     * `group` and nothing else, so a wrapper with no role puts its options
+                     * straight into the listbox and the heading beside them becomes an
+                     * unowned loose text node: a reader hears the heading as another row
+                     * and has no way to ask what the rows under it belong to. The name is
+                     * `aria-labelledby` on the heading that is already drawn rather than a
+                     * second copy of the words in an attribute that could drift from it.
+                     */
+                    _jsxs("div", { role: "group", "aria-labelledby": `${titleId}-group-${group.id}`, "data-slot": "command-palette-group", className: "mb-1 last:mb-0", children: [_jsx("div", { id: `${titleId}-group-${group.id}`, "data-slot": "command-palette-group-label", className: "text-muted-foreground bg-popover text-xs font-medium tracking-wide uppercase sticky top-0 px-3 py-1.5", children: group.label }), group.hits.map((hit) => {
                                 const index = flat.indexOf(hit.item);
                                 const isActive = index === activeIndex;
                                 return (_jsxs("div", { id: `${titleId}-item-${hit.item.id}`, "data-slot": "command-palette-item", "data-active": isActive, role: "option", "aria-selected": isActive, onMouseEnter: () => setActive(index), onClick: () => run(hit.item), className: cn('flex cursor-pointer items-baseline justify-between gap-3 rounded-sm px-3 py-2 text-sm', isActive && 'bg-accent text-accent-foreground', !isActive && 'text-muted-foreground hover:text-foreground'), children: [_jsx("span", { className: "min-w-0 truncate", children: hit.range === undefined ? (hit.item.label) : (_jsxs(_Fragment, { children: [hit.item.label.slice(0, hit.range[0]), _jsx("strong", { className: "text-foreground font-semibold", children: hit.item.label.slice(hit.range[0], hit.range[1]) }), hit.item.label.slice(hit.range[1])] })) }), hit.item.hint === undefined ? null : (_jsx("span", { className: "shrink-0 text-xs", children: hit.item.hint }))] }, hit.item.id));
-                            })] }, group.id)))) })] }) }));
+                            })] }, group.id))) }))] }) }));
 }
 export { CommandPalette };

package/dist/components/ui/contribution-graph.d.ts

@@ -0,0 +1,156 @@
+import type { ComponentProps } from 'react';
+/**
+ * The five steps of the intensity scale, from an absent day to a full one.
+ *
+ * A five-step scale and not a continuous ramp, and the reason is that a reader
+ * has to compare two squares at a glance. A continuous scale is smoother and
+ * unreadable: the difference between a Tuesday and the Wednesday beside it is a
+ * few percent of opacity, which is nothing to see, while the difference between
+ * step two and step three is a band the eye can sort without being told what the
+ * bands mean. Five is also the number the eye can rank in a column without
+ * counting, and a heat grid is read by scanning columns.
+ */
+export type ContributionLevel = 0 | 1 | 2 | 3 | 4;
+/** The props the ContributionGraph accepts. */
+export interface ContributionGraphProps extends Omit<ComponentProps<'div'>, 'children'> {
+    /**
+     * One entry per day, keyed by its own date.
+     *
+     * `date` is a `YYYY-MM-DD` key because that is the key a collector stores and
+     * the one a database index is on, so the caller passes what it already has
+     * rather than a second shape this Component would have to convert. The array
+     * is in any order: each day is placed by its own key, so a collector that
+     * returns newest first draws the same grid as one that returns oldest first.
+     *
+     * A day with a count of zero is a day the caller looked and found nothing. A
+     * day that is not in the array at all is a day nobody reported, and the two are
+     * drawn the same way and must be, because there is no third state to draw.
+     */
+    days: readonly {
+        date: string;
+        count: number;
+    }[];
+    /**
+     * The name of the figure, read before the grid and captioned on the table.
+     *
+     * Required rather than defaulted, for the two reasons `ChartFrame` states: two
+     * heat grids on a page are two figures a reader cannot tell apart, and a
+     * picture with no name is neither announced nor linkable. A figure named
+     * "Chart" is a Component shipping a sentence about a product it knows nothing
+     * about.
+     */
+    label: string;
+    /**
+     * The accessible name of one day's square, given the day.
+     *
+     * Required, and it is the one prop here that is a function rather than data,
+     * because it is the one thing Prism cannot compose. "4 contributions on 1
+     * March 2026" is a sentence in a language and a calendar, and a design system
+     * that wrote it would put English and a Gregorian month name into every
+     * consumer's product, in a figure that is otherwise entirely the caller's. The
+     * day is passed whole so the caller can say as much or as little as its own
+     * words need, and can reach for a translated month or a relative phrase.
+     *
+     * A day the caller did not report is never named, because there is nothing to
+     * name: an absence is not a zero and not a row.
+     */
+    dayLabel: (day: {
+        date: string;
+        count: number;
+    }) => string;
+    /**
+     * How many week columns to draw. @defaultValue 26
+     *
+     * Half a year, which is the range a contribution graph is read at when the
+     * question is "do I keep going" rather than "what did last Tuesday look like".
+     * The window is the most recent `weeks` weeks ending with the latest day given,
+     * so a day older than the window is not drawn rather than pushing everything
+     * else out of view. A grid whose window slid to fit every day would move under
+     * the reader every time a collector caught up.
+     */
+    weeks?: number;
+    /**
+     * Which day each row starts on. @defaultValue 1
+     *
+     * Zero for Sunday and one for Monday, and it is a prop because the caller's
+     * week is not the design system's: a grid that started on Monday when the
+     * product's week starts on Sunday puts a Saturday in the row above a Monday
+     * and the reader has to work that out before they can read anything. The
+     * default is Monday because that is the first day ISO 8601 names, and it is
+     * overridable for exactly the reason it is right most of the time.
+     */
+    weekStartsOn?: 0 | 1;
+    /**
+     * How a count becomes a level, given the count and the largest count drawn.
+     *
+     * The default is quartiles of the maximum, and the reason is stated in full on
+     * the helper above: a caller that pre-normalises has two chances to get the
+     * scale wrong. A caller with a real reason to bucket differently, a log
+     * distribution where the top day is a hundred times the median, a set where
+     * zero means something other than nothing, passes one function and gets a
+     * scale nobody else has to explain.
+     */
+    levelFor?: (count: number, max: number) => ContributionLevel;
+}
+/**
+ * A calendar of days, one square each, filled by how much happened on it.
+ *
+ * **The scale is the caller's counts and this Component's arithmetic.** The
+ * caller passes counts and the Component works out the largest count in the
+ * window and buckets against it, because a caller that pre-normalises has two
+ * chances to get the scale wrong and a mislabelled scale is a lie with a
+ * typeface on it. That is the reasoning `PulseSeries` states for its columns and
+ * the reason this Item is not a prop called `max` the caller had to divide by.
+ * The cost is named rather than hidden: quartiles of the maximum put most squares
+ * at level one or two when one day is an outlier, because that is what quartiles
+ * of an outlier are. A caller with a distribution like that passes `levelFor` and
+ * the cost goes away.
+ *
+ * **The maximum is taken from the days that are drawn, not from every day given.**
+ * A day that falls outside the window is neither drawn nor tabulated, and letting
+ * one into the maximum would stretch the scale around a square that is not in the
+ * picture, which is the quietest way a chart can be wrong. That is the rule
+ * `ChartFrame` states for a value past the end of its categories.
+ *
+ * **The four filled levels are one token at four strengths, never five
+ * colours.** `primary` at a quarter, a half, three quarters and full, over a
+ * `muted` empty cell. A ramp of five authored colour tokens would have been a
+ * second set of colour roles for a scale the alpha modifier already expresses, and
+ * it would not have moved with a scoped pack boundary the way an alpha step on one
+ * semantic role does. The cost is that the five steps are the same hue, so the
+ * grid reads as intensity rather than as categories, which is what a calendar of
+ * activity should read as.
+ *
+ * **A day the caller did not report is an absence, not a zero, and the two look
+ * the same on purpose.** Both are the empty cell, because there is no third
+ * drawing available: a hole in the grid would imply something happened, and a
+ * zero-filled cell for an unreported day would claim a measurement nobody made.
+ * The difference survives where it matters, in the table, where an unreported day
+ * has no row at all and a reported zero has a row reading zero. A short `days`
+ * array therefore leaves the leading weeks of the window empty rather than
+ * compressing the days it has, because a compressed grid is a grid whose cells no
+ * longer mean days.
+ *
+ * **Each square is named by the caller and the numbers are also in a table.** The
+ * squares carry `dayLabel` rather than a name this Component composed, because a
+ * composed name is a sentence in English and a Gregorian month. The counts are
+ * additionally rendered as a visually hidden table from the same array, so a
+ * screen reader's table navigation can reach a number directly and a crawler
+ * indexing the page finds the figures. The table has one row per reported day, its
+ * row head is the caller's own date key and its caption is the caller's own label;
+ * it has no column heading, because this Item has no word for "count" that is true
+ * in the caller's domain and inventing one would be a claim.
+ *
+ * The cost of naming every square is that a screen reader meets one stop per day
+ * before it reaches the table, which is a lot of stops for a hundred and eighty-two
+ * squares. That is the trade this design makes, and it is the same trade
+ * `ContributionGraph`'s table makes in the other direction: the grid answers "which
+ * days", the table answers "how many".
+ *
+ * It is a server Component. The window is arithmetic over props, there is no
+ * clock to read and no state to hold, so a contribution graph on a static page
+ * costs no client code.
+ */
+declare function ContributionGraph({ className, days, label, dayLabel, weeks, weekStartsOn, levelFor, ...props }: ContributionGraphProps): import("react").JSX.Element;
+export { ContributionGraph };
+//# sourceMappingURL=contribution-graph.d.ts.map

package/dist/components/ui/contribution-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contribution-graph.d.ts","sourceRoot":"","sources":["../../../src/components/ui/contribution-graph.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAK3C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAyEjD,+CAA+C;AAC/C,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IACrF;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAChD;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;;;OAaG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAA;IAC1D;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,CAAA;IACpB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,iBAAiB,CAAA;CAC7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,iBAAS,iBAAiB,CAAC,EACzB,SAAS,EACT,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,KAAU,EACV,YAAgB,EAChB,QAAoB,EACpB,GAAG,KAAK,EACT,EAAE,sBAAsB,+BAkGxB;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAA"}

package/dist/components/ui/contribution-graph.js

@@ -0,0 +1,170 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Table, TableBody, TableCaption, TableCell, TableHead, TableRow } from './table.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The fill each level is drawn in.
+ *
+ * Level zero is the empty cell, and it is the `muted` surface rather than a pale
+ * primary, so "nothing here" is visibly a different thing from "a little here".
+ * The other four are the same `primary` role at four alpha steps, so the scale
+ * is one token at four strengths and moves as a unit when the pack does. The
+ * alternative was a ramp of five authored colours, and that would have been a
+ * second set of colour tokens for a scale the alpha modifier already expresses.
+ */
+const LEVEL_FILL = {
+    0: 'bg-muted',
+    1: 'bg-primary/25',
+    2: 'bg-primary/50',
+    3: 'bg-primary/75',
+    4: 'bg-primary',
+};
+/** Milliseconds in a day, which is the unit a calendar is counted in. */
+const DAY = 86_400_000;
+/** The shape of a caller's day key, checked rather than assumed. */
+const DAY_KEY = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+ * The default bucketing: quartiles of the largest count in the window.
+ *
+ * A caller that pre-normalises has two chances to get the scale wrong, and a
+ * mislabelled axis is a lie with a typeface on it, which is the reason
+ * `PulseSeries` gives for taking raw magnitudes and scaling them against the
+ * tallest column. So this takes a count and the maximum the Component worked out
+ * from the days it drew, and the caller never divides anything. A count of zero
+ * or less is level zero whatever the maximum is, because a negative count is not
+ * a quiet day, it is data that is wrong, and this Component has no level to put
+ * that in.
+ */
+function quartiles(count, max) {
+    if (!(count > 0))
+        return 0;
+    if (!(max > 0))
+        return 4;
+    const share = count / max;
+    if (share <= 0.25)
+        return 1;
+    if (share <= 0.5)
+        return 2;
+    if (share <= 0.75)
+        return 3;
+    return 4;
+}
+/**
+ * A caller's day key as a count of days from the epoch, or `null` for a key the
+ * calendar does not have.
+ *
+ * The round trip is checked rather than trusted, because `Date.UTC` accepts a
+ * 31st of February and hands back the 3rd of March, so a key that names a day
+ * that does not exist would be drawn on the wrong cell and the graph would be
+ * quietly wrong in a way no reader could see. Returning `null` lets the caller
+ * refuse the whole set rather than move one square onto a day it was not
+ * reported for.
+ */
+function epochDayOf(key) {
+    const parts = DAY_KEY.exec(key);
+    if (parts === null)
+        return null;
+    const at = Date.UTC(Number(parts[1]), Number(parts[2]) - 1, Number(parts[3]));
+    return new Date(at).toISOString().slice(0, 10) === key ? Math.floor(at / DAY) : null;
+}
+/** Which day of the week a day count names, with Sunday as zero. */
+function weekdayOf(day) {
+    // The epoch was a Thursday, which is four days past Sunday, so adding four and
+    // taking the remainder counts from Sunday without a lookup table.
+    return (((day + 4) % 7) + 7) % 7;
+}
+/**
+ * A calendar of days, one square each, filled by how much happened on it.
+ *
+ * **The scale is the caller's counts and this Component's arithmetic.** The
+ * caller passes counts and the Component works out the largest count in the
+ * window and buckets against it, because a caller that pre-normalises has two
+ * chances to get the scale wrong and a mislabelled scale is a lie with a
+ * typeface on it. That is the reasoning `PulseSeries` states for its columns and
+ * the reason this Item is not a prop called `max` the caller had to divide by.
+ * The cost is named rather than hidden: quartiles of the maximum put most squares
+ * at level one or two when one day is an outlier, because that is what quartiles
+ * of an outlier are. A caller with a distribution like that passes `levelFor` and
+ * the cost goes away.
+ *
+ * **The maximum is taken from the days that are drawn, not from every day given.**
+ * A day that falls outside the window is neither drawn nor tabulated, and letting
+ * one into the maximum would stretch the scale around a square that is not in the
+ * picture, which is the quietest way a chart can be wrong. That is the rule
+ * `ChartFrame` states for a value past the end of its categories.
+ *
+ * **The four filled levels are one token at four strengths, never five
+ * colours.** `primary` at a quarter, a half, three quarters and full, over a
+ * `muted` empty cell. A ramp of five authored colour tokens would have been a
+ * second set of colour roles for a scale the alpha modifier already expresses, and
+ * it would not have moved with a scoped pack boundary the way an alpha step on one
+ * semantic role does. The cost is that the five steps are the same hue, so the
+ * grid reads as intensity rather than as categories, which is what a calendar of
+ * activity should read as.
+ *
+ * **A day the caller did not report is an absence, not a zero, and the two look
+ * the same on purpose.** Both are the empty cell, because there is no third
+ * drawing available: a hole in the grid would imply something happened, and a
+ * zero-filled cell for an unreported day would claim a measurement nobody made.
+ * The difference survives where it matters, in the table, where an unreported day
+ * has no row at all and a reported zero has a row reading zero. A short `days`
+ * array therefore leaves the leading weeks of the window empty rather than
+ * compressing the days it has, because a compressed grid is a grid whose cells no
+ * longer mean days.
+ *
+ * **Each square is named by the caller and the numbers are also in a table.** The
+ * squares carry `dayLabel` rather than a name this Component composed, because a
+ * composed name is a sentence in English and a Gregorian month. The counts are
+ * additionally rendered as a visually hidden table from the same array, so a
+ * screen reader's table navigation can reach a number directly and a crawler
+ * indexing the page finds the figures. The table has one row per reported day, its
+ * row head is the caller's own date key and its caption is the caller's own label;
+ * it has no column heading, because this Item has no word for "count" that is true
+ * in the caller's domain and inventing one would be a claim.
+ *
+ * The cost of naming every square is that a screen reader meets one stop per day
+ * before it reaches the table, which is a lot of stops for a hundred and eighty-two
+ * squares. That is the trade this design makes, and it is the same trade
+ * `ContributionGraph`'s table makes in the other direction: the grid answers "which
+ * days", the table answers "how many".
+ *
+ * It is a server Component. The window is arithmetic over props, there is no
+ * clock to read and no state to hold, so a contribution graph on a static page
+ * costs no client code.
+ */
+function ContributionGraph({ className, days, label, dayLabel, weeks = 26, weekStartsOn = 1, levelFor = quartiles, ...props }) {
+    const given = days.map((day) => {
+        const at = epochDayOf(day.date);
+        if (at === null) {
+            throw new Error(`ContributionGraph: a day is keyed '${day.date}', which is not a YYYY-MM-DD date the ` +
+                'calendar has, so there is no cell to draw it in. Pass the key your collector stores, and ' +
+                'a day the calendar does not have is a bug in the collector rather than a square to move.');
+        }
+        return { day, at };
+    });
+    // A nonsense `weeks` gets a floor of one rather than an empty grid, because an
+    // empty grid is a figure with nothing in it and this Component already refuses
+    // to draw one of those on the Sparkline.
+    const columns = Math.max(1, Math.floor(weeks));
+    // The window is the most recent `columns` weeks ending with the latest day
+    // given, so the caller's data fills the right-hand edge rather than the left.
+    // With no days at all the anchor is the epoch, which draws `columns` empty weeks
+    // rather than a special case, because an empty window and a window with nothing
+    // in it are the same picture.
+    const latest = given.length === 0 ? 0 : Math.max(...given.map((entry) => entry.at));
+    const first = latest - (((weekdayOf(latest) - weekStartsOn + 7) % 7) + (columns - 1) * 7);
+    const byDay = new Map(given.map((entry) => [entry.at, entry.day]));
+    const drawn = given.filter((entry) => entry.at >= first);
+    const max = drawn.length === 0 ? 0 : Math.max(...drawn.map((entry) => entry.day.count));
+    const cells = Array.from({ length: columns * 7 }, (_, index) => {
+        const at = first + index;
+        const day = byDay.get(at);
+        return { at, day, level: day === undefined ? 0 : levelFor(day.count, max) };
+    });
+    return (_jsxs("div", { "data-slot": "contribution-graph", role: "group", "aria-label": label, className: cn('flex w-full flex-col gap-2', className), ...props, children: [_jsx("div", { "data-slot": "contribution-weeks", className: "w-full overflow-x-auto pb-1", children: _jsx("div", { "data-slot": "contribution-grid", className: "flex gap-1", children: Array.from({ length: columns }, (_, column) => (_jsx("div", { "data-slot": "contribution-week", className: "flex flex-col gap-1", children: cells.slice(column * 7, column * 7 + 7).map((cell) => (_jsx("span", { "data-slot": "contribution-day", "data-date": cell.day?.date, "data-level": cell.level, 
+                            // A square is a picture of a day rather than text, so it takes
+                            // the image role and the caller's own name for that day. An
+                            // unreported day is hidden instead, because there is nothing
+                            // to name and an absence has no row in the table either.
+                            role: "img", "aria-label": cell.day === undefined ? undefined : dayLabel(cell.day), "aria-hidden": cell.day === undefined ? true : undefined, className: cn('size-3 shrink-0 rounded-sm', LEVEL_FILL[cell.level]) }, cell.at))) }, column))) }) }), _jsx("div", { "data-slot": "contribution-table", className: "sr-only", children: _jsxs(Table, { children: [_jsx(TableCaption, { children: label }), _jsx(TableBody, { children: drawn.map((entry) => (_jsxs(TableRow, { children: [_jsx(TableHead, { scope: "row", className: "font-mono font-normal", children: entry.day.date }), _jsx(TableCell, { className: "tabular-nums", children: entry.day.count })] }, entry.day.date))) })] }) })] }));
+}
+export { ContributionGraph };