@nanisoft/prism-ui 0.13.0 → 0.16.0

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

@@ -0,0 +1,286 @@
+import { type ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * How a task is arranged, and the two questions the choice answers.
+ *
+ * `list` puts everything about a task under its title, so a task can carry a note
+ * and a reading and an owner and still read as one block. `checklist` puts the
+ * title on a line of its own and the owner, the moment and the mark at the
+ * trailing edge of it, so a reader scanning the left edge of a long list sees
+ * titles and a column of names without reading a paragraph to do it.
+ *
+ * The difference is arrangement and not content. Both draw the same fields and
+ * neither drops one, because a variant that hid a field would be a variant that
+ * decided which facts matter, and that is a claim about the caller's work rather
+  * than a shape. What a checklist costs is the note: it is the piece that goes
+  * second when the row runs out of width, so a list of tasks with long notes is a
+  * list, and a list of short ones is a checklist.
+  *
+  * **The type is `Todo01Form` and the prop is `variant`, and the two names
+  * differing is the surface gate working rather than a slip.**
+  * `check-surface.mjs` refuses to let a public entry export a name ending in
+  * `Variant`, because in this package that shape names a cva map: a recipe a
+  * consumer could read and compose with. This union is the two arrangements the
+  * Block can draw and it is named for the arrangement. The prop keeps the name
+  * `variant` because a Component is allowed to take one. `ChartForm` and
+  * `ContentGrid01Form` are named the same way for the same reason.
+  */
+export type Todo01Form = 'list' | 'checklist';
+/** One task in a list. */
+export type Todo01Task = {
+    /** The task's stable key within the list. */
+    id: string;
+    /**
+     * What the task is, in the words a reader would use about it in conversation.
+     *
+     * It is also the checkbox's own `<label>`, which is the whole of the keyboard
+     * story on this Block: see the Component JSDoc.
+     */
+    title: string;
+    /**
+     * One line about the task, under its title.
+     *
+     * A node because the honest second line of a task is not always a sentence: it
+     * is a link, a quoted line, a code reference, a warning. The Block draws it in
+     * the muted ink and never truncates it, because a truncated note on a task is a
+     * note the reader has to open the task to read, which is a worse queue than one
+     * that says less.
+     */
+    note?: ReactNode;
+    /** Who has it, in the product's own words. A person, a team, a role. */
+    owner?: string;
+    /**
+     * The owner's picture, when there is one.
+     *
+     * A `name` is required and the `src` is not, because the name is what the
+     * fallback initials are made from and a face with no name beside it identifies
+     * nobody. Both are the caller's: a task list that fetched a directory would be a
+     * task list that had a data client in it.
+     */
+    ownerAvatar?: {
+        src?: string;
+        name: string;
+    };
+    /**
+     * When the task is wanted, in whichever of the three forms the caller holds it.
+     *
+     * Drawn through `relative-time`, so a number arrives as a date in the reader's
+     * own locale and a string is handed to the platform untouched. The rejected
+     * alternative was drawing the value as passed, which puts a raw epoch on the
+     * page for every caller whose data layer holds milliseconds, and a due date
+     * printed as an integer is the one field on a task list nobody can act on.
+     */
+    due?: number | string | ReactNode;
+    /**
+     * The caller's own words for the moment, given the moment they passed.
+     *
+     * Optional, and used only when `due` is a value: it is the relative half, and
+     * the absolute half is the platform's, which is the split `relative-time`
+     * states at length. A caller who wants both halves in their own voice passes a
+     * node as `due` instead, and this is not called.
+     */
+    dueLabel?: (due: number | string) => string;
+    /** Whether the task is finished. */
+    done?: boolean;
+    /**
+     * Where the task goes. Its presence makes the title's row carry a link beside
+     * the title rather than the title itself, because a task's title is its checkbox
+     * label and a link cannot be a label without taking the control away from the
+     * reader.
+     */
+    href?: string;
+    /** The words on that link, and required whenever `href` is. */
+    hrefLabel?: string;
+    /**
+     * Whether the task is blocked, and the words for that.
+     *
+     * A mark and not a lock, and the reason is worth stating because the obvious
+     * arrangement is a disabled checkbox: a control that has stopped asking is a
+     * control the reader has stopped reading, and a task somebody unblocked two
+     * minutes ago would need the page to re-render before its checkbox came back.
+     * The Block marks the row and leaves the control live, and the caller's handler
+     * decides what a blocked task may become.
+     */
+    blocked?: boolean;
+    /** The words for a blocked task, in the product's own vocabulary. */
+    blockedLabel?: string;
+};
+/**
+ * The props a Todo01 takes.
+ *
+ * Every string is a prop and the Block ships none. There is no sample task, no
+ * owner, no due reading, no progress sentence and no wording for an empty list,
+ * and the absence of the first two is the sharpest version of the rule: a task
+ * list is a claim about what a team has agreed to do, and a Block that shipped
+ * three of them would be publishing somebody else's commitments.
+ *
+ * The last two members are a union rather than three independent optional props,
+ * for the reason the authoring contract gives: `progressLabel` is required in one
+ * shape and forbidden in the other, and an optional prop cannot say that. A
+ * caller who turns the bar off must not be left holding a function nothing reads,
+ * and a caller who leaves it on must not be able to forget the words.
+ */
+export type Todo01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /**
+     * The section title.
+     *
+     * Optional, because a task list is very often composed inside a page that
+     * already owns a heading for it, and a Block that insisted on a second one
+     * would put two `h2`s in the same place.
+     */
+    title?: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /**
+     * The tasks, in the order a reader should meet them.
+     *
+     * Order is the caller's and the Block does not sort. A task list is very often
+     * already ordered by the thing that produced it, and a Block that sorted by due
+     * date would put an undated task last for no reason the reader can see, which is
+     * the failure a hand-rolled list avoids by not sorting at all.
+     */
+    tasks: readonly Todo01Task[];
+    /**
+     * Called with a task's `id` and the state it is being changed to, when the
+     * reader ticks or unticks its checkbox.
+     *
+     * A callback and not state the Block holds, for the reason the whole package
+     * holds: a task list is the consumer's data and the consumer is the only one who
+     * can persist a change to it. The Block reports the change and re-renders from
+     * whatever the caller passes next, so a server-rendered list and a client store
+     * drive the same Block. Omit it and the checkboxes render read-only, which is
+     * the honest state for a list nobody can change.
+     */
+    onToggle?: (id: string, done: boolean) => void;
+    /**
+     * What the Block renders in place of the list when there are none.
+     *
+     * Required and a node, for the reason it is required on every Block in this
+     * package: an empty task list is a claim, and "nothing to do" is a different
+     * claim in a product where the week is quiet and in a product where the query
+     * failed.
+     */
+    empty: ReactNode;
+    /**
+     * How a task is arranged. @defaultValue 'list'
+     *
+     * See `Todo01Form` for what the two questions are and what each costs.
+     */
+    variant?: Todo01Form;
+    /** Heading level for the section title. @defaultValue 'h2' */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Block. Changing a Prism-owned visual property
+     * from here is prohibited.
+     */
+    className?: string;
+} & ({
+    /**
+     * Whether the aggregate bar is drawn. @defaultValue true
+     *
+     * On by default, and the default is the decision: a task list whose progress
+     * is not visible makes a reader count the ticked rows, and counting is the
+     * one thing this Block can do for them for free.
+     */
+    showProgress?: true;
+    /**
+     * The words for the aggregate, given how many are done and how many there
+     * * are.
+     *
+     * Required whenever the bar is drawn, and the reason is the seam rather than
+     * the sentence. This Block is a server Component until `onToggle` is passed
+     * and a client Component after it, because a handler is a function and a
+     * function is a piece of state. `Progress` is a client Component either way.
+     * A function prop cannot cross from a server Component into a client one,
+     * so `getAriaValueText` is not expressible from half of the callers this
+     * Block has, and `valueText` is: the caller composes the words, the Block
+     * counts the rows, and the bar announces a string across the boundary. That
+     * rule is `Progress`'s own, and it is worth restating in every Block that
+     * composes a client Component with a callback, because a caller who reaches
+     * for `getAriaValueText` first will not find it.
+     */
+    progressLabel: (done: number, total: number) => string;
+} | {
+    /** Turn the aggregate bar off, for a list short enough to read as a whole. */
+    showProgress: false;
+    /** Forbidden with the bar off, because a function nothing reads is a trap. */
+    progressLabel?: never;
+});
+/**
+ * A task list: a checkbox, a title, a note, an owner, a moment and a link per
+ * task, with an aggregate bar and no state of its own.
+ *
+ * **The checkbox is `checkbox.tsx` and a `div` with an `onClick` is not an
+ * alternative, for the reason the Component JSDoc gives and the reason a keyboard
+ * reader feels.** `Checkbox` owns its focus ring at full strength, it owns a hit
+ * target that grows to 44 pixels on a coarse pointer, and it renders a hidden
+ * native input beside itself so the whole thing submits and validates like a
+ * checkbox in a form. A `div` with an `onClick` has none of those: it is not in
+ * the tab order at all, it cannot be operated with Space, and a screen reader
+ * announces a group of text rather than a control that can be changed. On a task
+ * list that defect is not a nicety, because ticking a box is the only thing a
+ * reader does with a task list, and a list whose every control is unreachable is a
+ * list a keyboard user cannot use to do their job.
+ *
+ * **The title is the checkbox's `<label>`, and that is a decision about the hit
+ * target as much as the name.** A bare sixteen pixel control is a control a reader
+ * has to aim at, and a task list is a list of things people read on a phone
+ * while walking. Labelling the control with the whole title makes the target the
+ * width of the task, which is the single cheapest thing this Block does for a
+ * coarse pointer, and it makes the accessible name the same text the row shows, so
+ * the two cannot drift. The rejected arrangement is an `aria-label` per checkbox,
+ * which announces a sentence the reader cannot see on the page.
+ *
+ * **The aggregate bar is `Progress` with `valueText` and not with
+ * `getAriaValueText`, and the reason is the server boundary rather than taste.**
+ * This Block is a server Component until `onToggle` is passed and a client
+ * Component after it, because a handler is a function, a function is a piece of
+ * state, and state is a client module. `Progress` is a client Component either
+ * way. A function prop from a server Component into a client Component is a build
+ * error rather than a warning, so `getAriaValueText` is not expressible from half
+ * of the callers this Block has, and a Block that shipped it would be a Block
+ * half its callers cannot render. `valueText` is the form that crosses: the
+ * caller composes the words, the Block counts the rows it was given, and the bar
+ * announces a string. The rule is worth stating once per Block that composes a
+ * client Component with a callback, and this is the place it cost somebody a
+ * release.
+ *
+ * **The words travel as a string and are not drawn a second time.** `valueText`
+ * is what the bar announces, and printing the same sentence beside the bar means
+ * a screen reader reads it once as the bar's value and once as loose text on the
+ * page. A caller who wants the aggregate visible as well as announced passes their
+ * own node above the list, which is a sentence they can place, style and
+ * translate.
+ *
+ * **A finished task stays in the list, struck through and muted, and it is still
+ * reachable by keyboard.** Both halves of that are the decision. Hiding a finished
+ * task makes a list look shorter every time it works, which is a queue that
+ * rewards the reader for not checking it, and a completed task a reader cannot
+ * find is a task they will redo: the failure mode is not an aesthetic complaint
+ * about a strikethrough, it is duplicated work. So the row stays, the checkbox
+ * stays focusable and unticked-able, and the two utilities are the whole of the
+ * change. The cost is real and worth naming: a long list of finished tasks is a
+ * list a reader has to scan past, and the answer is the consumer's own filter,
+ * which is the only one who knows whether the reader wanted the history on the
+ * page.
+ *
+ * **Nothing here holds the state, and the checkboxes say so when nobody is
+ * listening.** With no `onToggle` the control renders `readOnly` rather than
+ * `disabled`, which is a real distinction: a disabled checkbox is skipped by the
+ * tab order and announced as unavailable, so a list of them tells a keyboard
+ * reader that the whole list is broken, while a read-only one is focusable and
+ * announces its state. A list nobody can change is a list someone is reading, and
+ * reading is a use.
+ *
+ * It is a client Component, and the reason is the callback rather than the state,
+ * as in every other Block in this wave. `onToggle` is a function, a function is a
+ * piece of state, and state is a client module: a server component cannot hand an
+ * event handler to a `<button>`, so a caller rendering this from a server
+ * component would get a list whose checkboxes do nothing. The rest of the
+ * rendering is a list and a bar, which is the price of that and a small one.
+ */
+export declare function Todo01({ eyebrow, title, description, tasks, onToggle, empty, variant, headingLevel, className, showProgress, progressLabel, }: Todo01Props): import("react").JSX.Element;
+export default Todo01;
+//# sourceMappingURL=todo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"todo.d.ts","sourceRoot":"","sources":["../../../src/blocks/todo-01/todo.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAO7C,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAIxF;;;;;;;;;;;;;;;;;;;;;;;;IAwBI;AACJ,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,WAAW,CAAA;AAE7C,0BAA0B;AAC1B,MAAM,MAAM,UAAU,GAAG;IACvB,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAA;IACV;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5C;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,KAAK,MAAM,CAAA;IAC3C,oCAAoC;IACpC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;OAOG;IACH,KAAK,EAAE,SAAS,UAAU,EAAE,CAAA;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IAC9C;;;;;;;OAOG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,UAAU,CAAA;IACpB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,CACA;IACE;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,IAAI,CAAA;IACnB;;;;;;;;;;;;;;;OAeG;IACH,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;CACvD,GACD;IACE,8EAA8E;IAC9E,YAAY,EAAE,KAAK,CAAA;IACnB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,KAAK,CAAA;CACtB,CACJ,CAAA;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,wBAAgB,MAAM,CAAC,EACrB,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,QAAQ,EACR,KAAK,EACL,OAAgB,EAChB,YAAmB,EACnB,SAAS,EACT,YAAmB,EACnB,aAAa,GACd,EAAE,WAAW,+BAgLb;AAED,eAAe,MAAM,CAAA"}

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

@@ -0,0 +1,149 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { Avatar, AvatarFallback, AvatarImage } from '../../components/ui/avatar.js';
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Checkbox } from '../../components/ui/checkbox.js';
+import { Progress } from '../../components/ui/progress.js';
+import { RelativeTime } from '../../components/ui/relative-time.js';
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { Status } from '../../components/ui/status.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The classes the two arrangements give the row, and the classes a finished task
+ * gives its own text.
+ *
+ * A finished task is muted and struck through, and nothing else about it changes.
+ * The two utilities are here rather than written on the elements because they are
+ * one decision about one state, and three places that each decide it is three
+ * places that can disagree about what a finished task looks like.
+ */
+const ROW = {
+    list: 'flex flex-col gap-1.5 py-4',
+    checklist: 'flex flex-wrap items-baseline gap-x-3 gap-y-1 py-2.5',
+};
+/** The moment half of a row, which is a value, a node, or nothing at all. */
+function dueOf(task) {
+    if (task.due === undefined)
+        return null;
+    if (typeof task.due !== 'string' && typeof task.due !== 'number')
+        return task.due;
+    return _jsx(RelativeTime, { date: task.due, relative: task.dueLabel?.(task.due) });
+}
+/**
+ * The two-letter mark a face falls back to, from a name the caller already holds.
+ *
+ * Two letters and not three, because the circle this sits in is sixteen pixels
+ * across and a third letter is a mark narrower than the gap between two of them.
+ * The name is a caller's data, so this reads it and invents nothing: a name with
+ * one word gives that word's first letter, because that is the only letter there
+ * is.
+ */
+function initialsOf(name) {
+    const parts = name.trim().split(/\s+/).filter(Boolean);
+    const letters = parts.slice(0, 2).map((part) => part.charAt(0));
+    return letters.join('').toUpperCase();
+}
+/**
+ * A task list: a checkbox, a title, a note, an owner, a moment and a link per
+ * task, with an aggregate bar and no state of its own.
+ *
+ * **The checkbox is `checkbox.tsx` and a `div` with an `onClick` is not an
+ * alternative, for the reason the Component JSDoc gives and the reason a keyboard
+ * reader feels.** `Checkbox` owns its focus ring at full strength, it owns a hit
+ * target that grows to 44 pixels on a coarse pointer, and it renders a hidden
+ * native input beside itself so the whole thing submits and validates like a
+ * checkbox in a form. A `div` with an `onClick` has none of those: it is not in
+ * the tab order at all, it cannot be operated with Space, and a screen reader
+ * announces a group of text rather than a control that can be changed. On a task
+ * list that defect is not a nicety, because ticking a box is the only thing a
+ * reader does with a task list, and a list whose every control is unreachable is a
+ * list a keyboard user cannot use to do their job.
+ *
+ * **The title is the checkbox's `<label>`, and that is a decision about the hit
+ * target as much as the name.** A bare sixteen pixel control is a control a reader
+ * has to aim at, and a task list is a list of things people read on a phone
+ * while walking. Labelling the control with the whole title makes the target the
+ * width of the task, which is the single cheapest thing this Block does for a
+ * coarse pointer, and it makes the accessible name the same text the row shows, so
+ * the two cannot drift. The rejected arrangement is an `aria-label` per checkbox,
+ * which announces a sentence the reader cannot see on the page.
+ *
+ * **The aggregate bar is `Progress` with `valueText` and not with
+ * `getAriaValueText`, and the reason is the server boundary rather than taste.**
+ * This Block is a server Component until `onToggle` is passed and a client
+ * Component after it, because a handler is a function, a function is a piece of
+ * state, and state is a client module. `Progress` is a client Component either
+ * way. A function prop from a server Component into a client Component is a build
+ * error rather than a warning, so `getAriaValueText` is not expressible from half
+ * of the callers this Block has, and a Block that shipped it would be a Block
+ * half its callers cannot render. `valueText` is the form that crosses: the
+ * caller composes the words, the Block counts the rows it was given, and the bar
+ * announces a string. The rule is worth stating once per Block that composes a
+ * client Component with a callback, and this is the place it cost somebody a
+ * release.
+ *
+ * **The words travel as a string and are not drawn a second time.** `valueText`
+ * is what the bar announces, and printing the same sentence beside the bar means
+ * a screen reader reads it once as the bar's value and once as loose text on the
+ * page. A caller who wants the aggregate visible as well as announced passes their
+ * own node above the list, which is a sentence they can place, style and
+ * translate.
+ *
+ * **A finished task stays in the list, struck through and muted, and it is still
+ * reachable by keyboard.** Both halves of that are the decision. Hiding a finished
+ * task makes a list look shorter every time it works, which is a queue that
+ * rewards the reader for not checking it, and a completed task a reader cannot
+ * find is a task they will redo: the failure mode is not an aesthetic complaint
+ * about a strikethrough, it is duplicated work. So the row stays, the checkbox
+ * stays focusable and unticked-able, and the two utilities are the whole of the
+ * change. The cost is real and worth naming: a long list of finished tasks is a
+ * list a reader has to scan past, and the answer is the consumer's own filter,
+ * which is the only one who knows whether the reader wanted the history on the
+ * page.
+ *
+ * **Nothing here holds the state, and the checkboxes say so when nobody is
+ * listening.** With no `onToggle` the control renders `readOnly` rather than
+ * `disabled`, which is a real distinction: a disabled checkbox is skipped by the
+ * tab order and announced as unavailable, so a list of them tells a keyboard
+ * reader that the whole list is broken, while a read-only one is focusable and
+ * announces its state. A list nobody can change is a list someone is reading, and
+ * reading is a use.
+ *
+ * It is a client Component, and the reason is the callback rather than the state,
+ * as in every other Block in this wave. `onToggle` is a function, a function is a
+ * piece of state, and state is a client module: a server component cannot hand an
+ * event handler to a `<button>`, so a caller rendering this from a server
+ * component would get a list whose checkboxes do nothing. The rest of the
+ * rendering is a list and a bar, which is the price of that and a small one.
+ */
+export function Todo01({ eyebrow, title, description, tasks, onToggle, empty, variant = 'list', headingLevel = 'h2', className, showProgress = true, progressLabel, }) {
+    const uid = useId();
+    for (const task of tasks) {
+        if (task.href !== undefined && task.hrefLabel === undefined) {
+            throw new Error(`Todo01: the task "${task.title}" declares an href with no hrefLabel, so the row would carry a ` +
+                'link with no words of its own and a reader would not know what activating it does. Pass the ' +
+                'words that say what it does, or omit the href.');
+        }
+        if (task.blocked === true && task.blockedLabel === undefined) {
+            throw new Error(`Todo01: the task "${task.title}" is blocked and no blockedLabel, so the mark beside it would be ` +
+                'a coloured dot with no sentence beside it. Pass the words for the state, or drop the flag.');
+        }
+    }
+    // Counted from the array that is about to be rendered rather than from a second
+    // pass, so a caller whose label disagrees with the page has a bug in their own
+    // function rather than a Block that passed one number and drew another.
+    const total = tasks.length;
+    const done = tasks.reduce((count, task) => count + (task.done === true ? 1 : 0), 0);
+    if (total === 0) {
+        return (_jsxs(Section, { "data-slot": "todo-01", className: cn(className), children: [title === undefined ? null : (_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-8" })), _jsx("p", { "data-slot": "todo-01-empty", className: "text-muted-foreground text-pretty", children: empty })] }));
+    }
+    return (_jsxs(Section, { "data-slot": "todo-01", className: cn(className), children: [title === undefined ? null : (_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-8" })), showProgress ? (_jsx(Progress, { "data-slot": "todo-01-progress", className: "mb-6", value: done, max: total, valueText: progressLabel?.(done, total) })) : null, _jsx("ul", { "data-slot": "todo-01-list", "data-variant": variant, className: "flex flex-col", children: tasks.map((task, index) => {
+                    const inputId = `${uid}-${index}`;
+                    const finished = task.done === true;
+                    const titleNode = (_jsx("label", { htmlFor: inputId, className: cn('text-sm font-medium', finished ? 'text-muted-foreground line-through' : null), children: task.title }));
+                    const meta = (_jsxs("div", { "data-slot": "todo-01-meta", className: "flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1 text-xs", children: [task.ownerAvatar === undefined && task.owner === undefined ? null : (_jsxs("span", { "data-slot": "todo-01-owner", className: "text-muted-foreground inline-flex min-w-0 items-center gap-1.5", children: [task.ownerAvatar === undefined ? null : (_jsxs(Avatar, { className: "size-5", children: [task.ownerAvatar.src === undefined ? null : (_jsx(AvatarImage, { src: task.ownerAvatar.src, alt: "" })), _jsx(AvatarFallback, { children: initialsOf(task.ownerAvatar.name) })] })), task.owner ?? task.ownerAvatar?.name] })), task.due === undefined ? null : (_jsx("span", { "data-slot": "todo-01-due", className: "text-muted-foreground", children: dueOf(task) })), task.blocked === true && task.blockedLabel !== undefined ? (_jsx(Status, { size: "sm", tone: "warning", label: task.blockedLabel })) : null, task.href === undefined || task.hrefLabel === undefined ? null : (_jsx(CtaLink, { href: task.href, variant: "ghost", size: "sm", children: task.hrefLabel }))] }));
+                    return (_jsxs("li", { "data-slot": "todo-01-task", "data-done": finished ? 'true' : undefined, "data-blocked": task.blocked === true ? 'true' : undefined, className: cn('border-border flex items-start gap-3 border-b first:border-t', ROW[variant]), children: [_jsx(Checkbox, { id: inputId, checked: finished, readOnly: onToggle === undefined, onCheckedChange: onToggle === undefined ? undefined : (checked) => onToggle(task.id, checked), className: "mt-0.5" }), _jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-1", children: [titleNode, variant === 'checklist' ? meta : null, task.note === undefined ? null : (_jsx("span", { className: "text-muted-foreground text-pretty text-sm", children: task.note })), variant === 'list' ? meta : null] })] }, task.id));
+                }) })] }));
+}
+export default Todo01;

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

@@ -0,0 +1,3 @@
+export { Trend01, default } from './trend.js';
+export type { Trend01Props, Trend01Item } from './trend.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/trend-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAI1C,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA"}

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

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

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

@@ -0,0 +1,184 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One row of a trend list: a name, what it is at now, how it moved, and a shape
+ * beside it.
+ *
+ * Every field except `id` and `label` is optional because a trend list is
+ * heterogeneous by nature. Some of the things a list tracks have a series behind
+ * them and some have only a reading, some moved and some did not, and a shape
+ * that made every field required would be a list where two thirds of every row is
+ * an empty cell drawn as a placeholder.
+ */
+export type Trend01Item = {
+    /** A stable key for the row. */
+    id: string;
+    /**
+     * The name of the thing being tracked, as a reader would name it in
+     * conversation. It is the label the metric carries, and it is the last thing
+     * read on the row because the figure and the direction come first.
+     */
+    label: string;
+    /**
+     * The current reading, already formatted by the caller.
+     *
+     * A `ReactNode` and not a `number`, for the reason `MetricProps.value` gives:
+     * a caller's figure is often a value it formatted itself, with its own grouped
+     * thousands, its own currency and its own unit, and a `number` here would push
+     * that formatting onto every call site twice. Prism takes the node and formats
+     * nothing.
+     */
+    value: ReactNode;
+    /**
+     * The change against the previous reading, as a number whose sign is the
+     * direction. See `MetricDelta` on the Component.
+     */
+    delta?: number;
+    /**
+     * The words for that change, given the number. Required whenever `delta` is
+     * set, and the Block throws without it. See the Component JSDoc for the full
+     * argument.
+     */
+    deltaLabel?: (delta: number) => string;
+    /**
+     * The readings behind the current one, oldest first, in the caller's own units.
+     *
+     * Raw magnitudes rather than percentages of a maximum, which is the contract
+     * `Sparkline` states: a caller that pre-normalises has two chances to get the
+     * shape wrong, and a series drawn against an axis nobody can see is a picture
+     * of somebody's arithmetic.
+     */
+    series?: number[];
+    /**
+     * The name of that series, and the only thing a screen reader reads from the
+     * shape. Required whenever `series` is set, and the Block throws without it.
+     */
+    seriesLabel?: string;
+    /** Where the row goes. Rendered as a native anchor, so the destination is real. */
+    href?: string;
+    /** The words on that link. Required whenever `href` is set. */
+    hrefLabel?: string;
+};
+/**
+ * The props a Trend01 takes.
+ *
+ * Every string and every number is a prop and the Block ships none. There is no
+ * sample list, no default metric, no default series and no default direction, and
+ * the reason is the one the whole Block rests on: the list a page shows is that
+ * page's own claim about what is rising, and a Block that invented one would be
+ * publishing a trend nobody collected.
+ */
+export type Trend01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /** The section title. Required, because a list with no heading is a fragment. */
+    title: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /**
+     * The rows, in the order a reader should meet them. See the Component JSDoc
+     * for why the Block does not sort them.
+     */
+    items: readonly Trend01Item[];
+    /**
+     * How many rows to render. Defaults to the whole set.
+     *
+     * A cap and not a page. A trend list that runs long is a long list of the same
+     * kind of row, and a reader who wants the rest of it wants the top of it, so
+     * the useful control is where to stop rather than which page they are on. A
+     * paged list of trends is a table with a `DataTable01` in it, and this Block is
+     * not that.
+     */
+    limit?: number;
+    /**
+     * What the Block renders in place of the rows when there are none.
+     *
+     * A slot rather than a string, and required at the call site in the sense that
+     * a Block cannot write the sentence: "nothing is rising" is a claim, and it is
+     * a different claim in a product where the answer is honest and a product where
+     * the pipeline is down. Omit it and a list with no rows renders nothing at all,
+     * which is the honest state for a section that has nothing to say.
+     */
+    empty?: ReactNode;
+    /**
+     * Heading level for the section title. @defaultValue 'h2'
+     *
+     * See `HeadingLevel`.
+     */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Block. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A ranked list of rising values: a name, a current reading, the change against
+ * the previous one, and a small series beside it.
+ *
+ * **A trend row is a metric with a shape beside it, so the Block composes
+ * `Metric` and `Sparkline` rather than drawing either of them.** Both halves of
+ * that sentence are load-bearing. `Metric` owns the arrangement a headline figure
+ * is read in, which puts the figure first and the name under it, and it owns the
+ * three things a hand-rolled version of that gets wrong: that the direction is
+ * derived from the sign of the number rather than declared beside it, that the
+ * rising mark is a glyph so assistive technology names it in the reader's own
+ * language rather than through an English `aria-label`, and that a string value
+ * is set in the mono face while a composed one is not. `Sparkline` owns the shape
+ * and, more importantly, owns the fact that the numbers behind the shape are in
+ * the document: a ninety-six pixel line with no axis is a picture a reader cannot
+ * query, so the Component renders the same array as a table a screen reader can
+ * walk and a crawler can index. A Block that hand-rolled either would be a second
+ * implementation of a Component that already owns it, and the second
+ * implementation would be the one without the table, because the table is the part
+ * nobody draws by hand and it is the part that matters.
+ *
+ * **`deltaLabel` is required whenever any row carries a `delta`, and the reason
+ * is that the Block cannot know which of three sentences the caller means.**
+ * "up 12 percent", "+12%" and "12 higher than last week" are three sentences
+ * about one number, and they are not formats of one another: the first is a
+ * phrase with a unit, the second is a signed figure for a reader who is already
+ * looking at a number, and the third is a comparison against a named period that
+ * a reader who cannot see the period will misread as a comparison against
+ * whatever they assumed. Worse, the fallback a Block would reach for is the worst
+ * of the three, because a bare "+12" printed beside a figure is a number with an
+ * arithmetic symbol on it, and a screen reader reads that as a formula rather
+ * than as a change. So the prop is required and the Block throws without it
+ * rather than printing the sign itself, and the cost of the throw is that a
+ * caller who genuinely has no unit has to write the formatter that says so.
+ *
+ * **`seriesLabel` is required whenever any row carries a `series`, for the reason
+ * the `Sparkline` JSDoc gives in full: a figure with no name is not announced
+ * and not linkable.** A trend list is a column of small pictures, and a column of
+ * unnamed pictures is a column of shapes a reader has to guess the meaning of from
+ * the number beside them, which is the guess the whole figure exists to remove.
+ * Two rows whose series are both "the last thirty days" and one row whose series
+ * is the same thirty days as a percentage are three pictures that look identical
+ * and mean three things, and only a name tells them apart.
+ *
+ * **The order is the caller's, and there is deliberately no `sort`.** A trend list
+ * is ranked, and the rank is the Block's premise, but the Block cannot see what
+ * it is ranking by: the caller may have ranked by the delta, by the current value,
+ * by a measure of their own that is not in the data at all, or by nothing at all
+ * because the list is a hand-picked set of five. A `sort` prop would have to name
+ * a key, and any key it named would be wrong for at least one of those four
+ * callers, and the failure would be silent: a list sorted by the wrong column
+ * still looks ranked. The other answer, deriving the order from the data, is
+ * worse, because it makes this Block a second derivation the caller then has to
+ * keep in step with their own data, and two orderings of one list that disagree is
+ * a list whose order nobody can fix without changing code in two places. So the
+ * rank is the position in the array, the ordinal is drawn from it, and the caller
+ * holds the one claim that ordering a ranked list makes.
+ *
+ * **The rows are one `<ol>`.** A list that was split by a cap, or by a variant,
+ * or by whether a row had a series, would be several lists and a screen reader
+ * would announce it as several. The cap shortens the list rather than dividing it,
+ * and a row with no series is a shorter row, not a different kind of row.
+ *
+ * It is a server Component: no hook, no state, no client code and no router. The
+ * two Components it composes are both server Components, so a trend list costs a
+ * consumer nothing in client JavaScript.
+ */
+export declare function Trend01({ eyebrow, title, description, items, limit, empty, headingLevel, className, }: Trend01Props): import("react").JSX.Element | null;
+export default Trend01;
+//# sourceMappingURL=trend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trend.d.ts","sourceRoot":"","sources":["../../../src/blocks/trend-01/trend.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAIxF;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,KAAK,EAAE,SAAS,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;OAGG;IACH,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;IAC7B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,wBAAgB,OAAO,CAAC,EACtB,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,KAAK,EACL,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,YAAY,sCA6Gd;AAED,eAAe,OAAO,CAAA"}