@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/blocks/member-list-01/member-list.d.ts

@@ -0,0 +1,192 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * What a member is doing right now, as far as the caller knows.
+ *
+ * The caller knows, not this Block. Presence arrives from a socket or a poll the
+ * consumer owns, and a Block that read it would be a Block that fetches.
+ */
+export type MemberPresence = 'online' | 'away' | 'offline';
+/**
+ * One member, as a members list shows them: who they are, what they do, whether
+ * they are around, and when they were last here.
+ */
+export type MemberList01Member = {
+    /**
+     * A stable key for the row, passed back to `onSelect` and `actions`, and
+     * carried on the markup as `data-member` so a test can name one row rather than
+     * the first one.
+     */
+    id: string;
+    /** The member's own name, and the accessible name of the row's control. */
+    name: string;
+    /** What they do. Omit it rather than passing an empty string. */
+    role?: string;
+    /** Where they are, as far as the consumer knows. See `MemberPresence`. */
+    presence?: MemberPresence;
+    /**
+     * The words for the presence, in the consumer's own vocabulary.
+     *
+     * Required whenever `presence` is given and not defaulted, for the reason
+     * `StatusLedger01`'s `statusLabel` states in full: the tone is a colour and the
+     * words are the information, and three products that call the same state "free",
+     * "available" and "online" cannot be given one word by a design system. A
+     * missing one throws, because a presence dot with no words beside it is a
+     * claim about a colleague that nothing in the document backs up.
+     */
+    presenceLabel?: string;
+    /**
+     * When the member was last here, already written as it should be read.
+     *
+     * A string rather than a `Date` and rather than a number of minutes, because a
+     * Block ships no formatting: see the Block's JSDoc for what the honest reading
+     * of a last-seen is and why Prism does not print it.
+     */
+    lastSeen?: string;
+    /**
+     * The portrait, with the name the initials come from.
+     *
+     * Omit it for a member the consumer has no photograph of. The initials rule
+     * is the one `AvatarGroup` applies and it is repeated rather than imported; see
+     * that Component for why the helper is not exported.
+     */
+    avatar?: {
+        /** The photograph. Omit it, or pass a URL that fails, for the initials. */
+        src?: string;
+        /** The member's name, which is the initials' source. */
+        name: string;
+    };
+    /**
+     * Where the member's own record goes.
+     *
+     * Rendered as a real anchor on the identity part of the row, so the destination
+     * shows in the status bar and can be opened in a new context. Mutually
+     * exclusive with a Block-level `onSelect`: see the Block's JSDoc.
+     */
+    href?: string;
+};
+/**
+ * The props a MemberList01 takes.
+ *
+ * Every string is a prop and the Block ships none. There is no member list, no
+ * default presence vocabulary and not one default presence label, because a
+ * presence label is a claim about a colleague and a design system is not the party
+ * that makes it.
+ */
+export type MemberList01Props = {
+    /**
+     * The list's own accessible name, rendered as the list's name and as no visible
+     * text.
+     *
+     * A string rather than a node because `aria-label` is a string in the platform:
+     * a node label would need an `aria-labelledby` hop to an element the
+     * surrounding panel owns, which is the caller's decision and not this Block's.
+     */
+    label?: string;
+    /** The section title. Omit it for a list composed inside a panel that has one. */
+    title?: ReactNode;
+    /** The members, in the order the caller wants them. The Block does not sort. */
+    members: readonly MemberList01Member[];
+    /**
+     * Makes each row a control.
+     *
+     * Pass it and every row is a real button whose accessible name is the member's
+     * own name, and this is the one Block in this wave that ships client code: a
+     * surface that attaches a handler is a client Component, and the directive is
+     * here rather than in a leaf so a consumer composing a server page gets the
+     * boundary in one place.
+     */
+    onSelect?: (id: string) => void;
+    /**
+     * The controls at the trailing edge of one row.
+     *
+     * A function of the member id rather than a node, so a caller with one row
+     * action set draws it once for a list of any length. These are in addition to
+     * whatever `href` or `onSelect` reaches and never instead of it, which is the
+     * rule `Item` states and the reason a members list never has a row whose only
+     * destination is a kebab menu.
+     */
+    actions?: (id: string) => ReactNode;
+    /**
+     * What the list shows when there are no members.
+     *
+     * A slot rather than a sentence, for the reason `EmptyState01` exists: an empty
+     * list has more than one reason behind it and the words differ. With nothing
+     * passed and no members, this Block renders nothing at all.
+     */
+    empty?: ReactNode;
+    /** Heading level for the section title. See `HeadingLevel`. */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Component. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A dense list of people for an application surface: a name, a role, a presence,
+ * a last-seen column and a slot for the caller's own row actions.
+ *
+ * **This is a Block and not `Item` and not `ListPanel`, and the two facts that
+ * make it a member list are the presence dot and the last-seen column.** `Item`
+ * is a row, and it is the right row for most lists: media, a title, a
+ * description, one value and trailing controls. What it cannot be is a row that
+ * knows a colleague is online. Its `meta` is one value, so presence and last-seen
+ * would have to be packed into one field and read as a single sentence by a
+ * screen reader, which is exactly the defect `Item`'s own JSDoc argues against
+ * when it says a row should not have to guess. `ListPanel` is the other half: a
+ * titled, bounded, scrollable region with header and footer slots, which knows
+ * about a region and not about its rows. Composing a member list from those two
+ * would leave every consumer writing the same two columns again, and writing them
+ * slightly differently each time, which is the drift this package exists to end.
+ *
+ * **The presence tones are mapped here and the words are the caller's, because a
+ * wrong mapping is a claim about a colleague.** `online` is `success`. `away` is
+ * `warning`, the one tone that reads as not available rather than as broken. And
+ * `offline` is `neutral` rather than `destructive`, because most people on a
+ * members list are offline and a page of red dots says a page of faults, which
+ * nobody believes and everybody has to look at. The words beside the dot come
+ * from `presenceLabel`, because three products that call the same state "free",
+ * "available" and "online" cannot be given one word by a design system, and a dot
+ * with no words is a claim with nothing in the document to check it against.
+ *
+ * **`lastSeen` is a string and Prism prints it exactly as passed.** The honest
+ * reading of when somebody was last around is a localised one, which is what
+ * `relative-time` exists for, so the caller composes that Component in its own
+ * code and passes the reading it produced, or draws the Component beside this
+ * list. A Block that formatted the moment itself would be choosing a locale, a
+ * calendar and a granularity on a colleague's behalf, and would put `Intl` in
+ * every consumer's bundle for a rendering Prism has no stake in. The cost is
+ * stated rather than hidden: a caller who passes a raw timestamp gets a raw
+ * timestamp, which is honest and rarely what was wanted.
+ *
+ * **A row with `onSelect` is a real button whose accessible name is the member's
+ * name and nothing else.** The name is set as the accessible name explicitly so
+ * that the role, the presence words and the last-seen reading inside the row do
+ * not get appended to it, which would make the button's name a sentence a
+ * speaker has to read twice. The visible name is inside that accessible name, so
+ * the WCAG rule that a visible label must be contained in the accessible name
+ * holds; the alternative, letting the row's own text name the button, is the
+ * arrangement this sentence exists to prevent. The button wraps the identity part
+ * of the row only, with the presence, the reading and the caller's actions
+ * outside it, so one row is one control and the actions are the second thing a
+ * reader meets rather than the first.
+ *
+ * **`href` and `onSelect` are exclusive per member, and the type cannot say so,
+ * so a check does.** A row that is a link and a button at once is not a control
+ * any keyboard model can express, and passing both is a mistake rather than a
+ * request, so it throws in a consumer's console rather than rendering one of the
+ * two. The alternative was a union on the member type keyed on a Block-level
+ * prop, which would have made every caller narrow their own data for a decision
+ * this Block can make once.
+ *
+ * It is the one client Block in this wave and the directive is the reason rather
+ * than an accident: `onSelect` attaches a handler, and a surface that attaches a
+ * handler owns the JavaScript that carries it. With `onSelect` omitted the
+ * rendered output is entirely static and there is no state to hydrate, because
+ * `Avatar` is the only client leaf and its client work is measuring whether an
+ * image has loaded.
+ */
+export declare function MemberList01({ label, title, members, onSelect, actions, empty, headingLevel, className, }: MemberList01Props): import("react").JSX.Element;
+export default MemberList01;
+//# sourceMappingURL=member-list.d.ts.map

package/dist/blocks/member-list-01/member-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"member-list.d.ts","sourceRoot":"","sources":["../../../src/blocks/member-list-01/member-list.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AA4BxF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAA;AAE1D;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAA;IACZ,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE;QACP,2EAA2E;QAC3E,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,wDAAwD;QACxD,IAAI,EAAE,MAAM,CAAA;KACb,CAAA;IACD;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kFAAkF;IAClF,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,gFAAgF;IAChF,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACtC;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,SAAS,CAAA;IACnC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAgDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,KAAK,EACL,OAAO,EACP,QAAQ,EACR,OAAO,EACP,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,iBAAiB,+BA+GnB;AAED,eAAe,YAAY,CAAA"}

package/dist/blocks/member-list-01/member-list.js

@@ -0,0 +1,142 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Avatar, AvatarFallback, AvatarImage } from '../../components/ui/avatar.js';
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { Status } from '../../components/ui/status.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The three presences a member can be in, and the tone each one is drawn in.
+ *
+ * The mapping is stated here rather than left in the caller's hands, and the
+ * reason is that a presence is a statement about a colleague. `online` is
+ * `success`, because it is the state the reader is looking for and it is the one
+ * a green dot has always meant. `away` is `warning`, because a colleague who is
+ * away has said they are not available and amber is the one tone in the contract
+ * that reads as not available rather than as broken. `offline` is `neutral`,
+ * because most people on a member list are offline and a row of red dots is a
+ * page of alarms that means nothing.
+ *
+ * `offline` is deliberately not `destructive`. Somebody who closed their laptop
+ * has not broken anything, and a tone that says they have is a claim about a
+ * colleague drawn from a row of data. The cost is stated rather than hidden: a
+ * reader who cannot separate `neutral` from `success` on a small dot still reads
+ * the words beside it, which is the same trade `Status` makes everywhere.
+ */
+const PRESENCE_TONE = {
+    online: 'success',
+    away: 'warning',
+    offline: 'neutral',
+};
+/**
+ * The initials a name produces, and the rule that produces them.
+ *
+ * Two letters from the first and last words, and the first two characters of a
+ * single word. It is the same rule `AvatarGroup` applies, repeated rather than
+ * imported, and the boundary is the reason: that helper is private to its module
+ * and exporting it would make a private derivation part of a published surface
+ * to save six lines in a Block. The cost is stated rather than hidden: two
+ * modules carry the rule, so a change to it is a change in both.
+ */
+function initialsOf(name) {
+    const words = name.trim().split(/\s+/).filter(Boolean);
+    const first = words[0];
+    if (first === undefined)
+        return '';
+    if (words.length === 1)
+        return first.slice(0, 2).toUpperCase();
+    return `${first.charAt(0)}${words[words.length - 1].charAt(0)}`.toUpperCase();
+}
+/**
+ * The three refusals, so that a member list never renders something it cannot
+ * justify.
+ *
+ * A presence with no words is a coloured dot, which is unreadable to a screen
+ * reader and invisible to a reader who cannot separate the tones. A member with
+ * both a destination and a selection is two controls in one row, which no
+ * keyboard model can express. The rest is composition the caller owns.
+ */
+function assertMembers(members, selectable) {
+    for (const member of members) {
+        if (member.presence !== undefined && (member.presenceLabel === undefined || member.presenceLabel.trim() === '')) {
+            throw new Error('MemberList01: a member declares a presence and no presenceLabel, so the dot would be a colour with ' +
+                'nothing to read beside it, which is a claim about a colleague no document backs up. Pass the words ' +
+                'this product uses for that state.');
+        }
+        if (selectable && member.href !== undefined) {
+            throw new Error('MemberList01: a member declares an href while the list is selectable, so the row would be a link and a ' +
+                'button at once. Pick one for the row: either the member has a destination, or the row selects.');
+        }
+    }
+}
+/**
+ * A dense list of people for an application surface: a name, a role, a presence,
+ * a last-seen column and a slot for the caller's own row actions.
+ *
+ * **This is a Block and not `Item` and not `ListPanel`, and the two facts that
+ * make it a member list are the presence dot and the last-seen column.** `Item`
+ * is a row, and it is the right row for most lists: media, a title, a
+ * description, one value and trailing controls. What it cannot be is a row that
+ * knows a colleague is online. Its `meta` is one value, so presence and last-seen
+ * would have to be packed into one field and read as a single sentence by a
+ * screen reader, which is exactly the defect `Item`'s own JSDoc argues against
+ * when it says a row should not have to guess. `ListPanel` is the other half: a
+ * titled, bounded, scrollable region with header and footer slots, which knows
+ * about a region and not about its rows. Composing a member list from those two
+ * would leave every consumer writing the same two columns again, and writing them
+ * slightly differently each time, which is the drift this package exists to end.
+ *
+ * **The presence tones are mapped here and the words are the caller's, because a
+ * wrong mapping is a claim about a colleague.** `online` is `success`. `away` is
+ * `warning`, the one tone that reads as not available rather than as broken. And
+ * `offline` is `neutral` rather than `destructive`, because most people on a
+ * members list are offline and a page of red dots says a page of faults, which
+ * nobody believes and everybody has to look at. The words beside the dot come
+ * from `presenceLabel`, because three products that call the same state "free",
+ * "available" and "online" cannot be given one word by a design system, and a dot
+ * with no words is a claim with nothing in the document to check it against.
+ *
+ * **`lastSeen` is a string and Prism prints it exactly as passed.** The honest
+ * reading of when somebody was last around is a localised one, which is what
+ * `relative-time` exists for, so the caller composes that Component in its own
+ * code and passes the reading it produced, or draws the Component beside this
+ * list. A Block that formatted the moment itself would be choosing a locale, a
+ * calendar and a granularity on a colleague's behalf, and would put `Intl` in
+ * every consumer's bundle for a rendering Prism has no stake in. The cost is
+ * stated rather than hidden: a caller who passes a raw timestamp gets a raw
+ * timestamp, which is honest and rarely what was wanted.
+ *
+ * **A row with `onSelect` is a real button whose accessible name is the member's
+ * name and nothing else.** The name is set as the accessible name explicitly so
+ * that the role, the presence words and the last-seen reading inside the row do
+ * not get appended to it, which would make the button's name a sentence a
+ * speaker has to read twice. The visible name is inside that accessible name, so
+ * the WCAG rule that a visible label must be contained in the accessible name
+ * holds; the alternative, letting the row's own text name the button, is the
+ * arrangement this sentence exists to prevent. The button wraps the identity part
+ * of the row only, with the presence, the reading and the caller's actions
+ * outside it, so one row is one control and the actions are the second thing a
+ * reader meets rather than the first.
+ *
+ * **`href` and `onSelect` are exclusive per member, and the type cannot say so,
+ * so a check does.** A row that is a link and a button at once is not a control
+ * any keyboard model can express, and passing both is a mistake rather than a
+ * request, so it throws in a consumer's console rather than rendering one of the
+ * two. The alternative was a union on the member type keyed on a Block-level
+ * prop, which would have made every caller narrow their own data for a decision
+ * this Block can make once.
+ *
+ * It is the one client Block in this wave and the directive is the reason rather
+ * than an accident: `onSelect` attaches a handler, and a surface that attaches a
+ * handler owns the JavaScript that carries it. With `onSelect` omitted the
+ * rendered output is entirely static and there is no state to hydrate, because
+ * `Avatar` is the only client leaf and its client work is measuring whether an
+ * image has loaded.
+ */
+export function MemberList01({ label, title, members, onSelect, actions, empty, headingLevel = 'h2', className, }) {
+    assertMembers(members, onSelect !== undefined);
+    return (_jsxs(Section, { className: cn('py-6', className), children: [title ? (_jsx(SectionHeading, { as: headingLevel, align: "left", title: title, className: "mb-6" })) : null, members.length === 0 ? (empty === undefined ? null : (_jsx("div", { "data-slot": "member-list-empty", className: "text-muted-foreground text-pretty text-sm", children: empty }))) : (_jsx("ul", { "data-slot": "member-list", "aria-label": label, className: "border-border flex flex-col border-t", children: members.map((member) => {
+                    const identity = (_jsxs(_Fragment, { children: [member.name, member.role === undefined ? null : (_jsx("span", { className: "text-muted-foreground block text-xs", children: member.role }))] }));
+                    return (_jsxs("li", { "data-slot": "member-list-row", "data-member": member.id, "data-presence": member.presence, className: "border-border flex items-center gap-3 border-b px-3 py-2", children: [member.avatar === undefined ? null : (_jsxs(Avatar, { className: "size-8", children: [member.avatar.src === undefined ? null : (_jsx(AvatarImage, { src: member.avatar.src, alt: "" })), _jsx(AvatarFallback, { className: "text-mono", children: initialsOf(member.avatar.name) })] })), onSelect === undefined ? (member.href === undefined ? (_jsx("span", { "data-slot": "member-list-identity", className: "min-w-0 flex-1 text-sm font-medium", children: identity })) : (_jsx("a", { "data-slot": "member-list-identity", href: member.href, className: "focus-visible:ring-ring min-w-0 flex-1 rounded-sm text-sm font-medium transition-colors duration-fast ease-out hover:underline focus-visible:ring-[3px] focus-visible:outline-none", children: identity }))) : (_jsx("button", { "data-slot": "member-list-identity", type: "button", "aria-label": member.name, onClick: () => onSelect(member.id), className: "focus-visible:ring-ring min-w-0 flex-1 rounded-sm text-left text-sm font-medium transition-colors duration-fast ease-out hover:underline focus-visible:ring-[3px] focus-visible:outline-none", children: identity })), member.presence === undefined ? null : (_jsx(Status, { size: "sm", tone: PRESENCE_TONE[member.presence], label: member.presenceLabel, className: "shrink-0" })), member.lastSeen === undefined ? null : (_jsx("span", { "data-slot": "member-list-last-seen", className: "text-muted-foreground shrink-0 text-xs tabular-nums sm:w-40 sm:text-right", children: member.lastSeen })), actions === undefined ? null : (_jsx("span", { "data-slot": "member-list-actions", className: "flex shrink-0 items-center gap-1", children: actions(member.id) }))] }, member.id));
+                }) }))] }));
+}
+export default MemberList01;

package/dist/blocks/milestone-timeline-01/index.d.ts

@@ -0,0 +1,3 @@
+export { MilestoneTimeline01, default } from './milestone-timeline.js';
+export type { Milestone, MilestoneState, MilestoneTimeline01Props } from './milestone-timeline.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/milestone-timeline-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/milestone-timeline-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAMnE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/blocks/milestone-timeline-01/index.js

@@ -0,0 +1 @@
+export { MilestoneTimeline01, default } from './milestone-timeline.js';

package/dist/blocks/milestone-timeline-01/milestone-timeline.d.ts

@@ -0,0 +1,217 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * The three states a milestone can be in.
+ *
+ * Three, and the set is the sequence's rather than the Block's: a milestone
+ * either happened, is where the system is, or has not happened yet, and a fourth
+ * such as `delayed` or `at-risk` is a claim about a plan rather than a position
+ * in a sequence, which is what the three words are. A caller whose roadmap has a
+ * fourth state states it in the `body`, where a reader reads a sentence about one
+ * milestone, rather than here, where a fourth mark would be a colour the reader
+ * has to learn and a maintainer has to keep true.
+ */
+export type MilestoneState = 'complete' | 'current' | 'upcoming';
+/**
+ * One thing a system reached, when it reached it, and how far along it was.
+ */
+export type Milestone = {
+    /** A stable key for the milestone. */
+    id: string;
+    /**
+     * When it was reached, already written the way the reader should see it.
+     *
+     * A string and not a `Date`, for the reason this repository has already written
+     * down for the sibling that takes the same field: a `Date` carries a timezone
+     * and a calendar and renders as `Wed Mar 04 2026 00:00:00 GMT+0000` unless
+     * something formats it, so a `Date` prop would push the formatting decision
+     * onto every consumer and make the wrong answer the easy one. As a string the
+     * Block prints what it was given, which is honest whether that is `2024`,
+     * `Q3 2024` or `Winter 2024`. A caller who needs a localised absolute reading
+     * composes `RelativeTime` themselves, which hands back the platform's own
+     * formatting for the moment and the caller's own words for the distance from
+     * now, and a caller who wants a fixed date uses the platform's
+     * `Intl.DateTimeFormat` directly. Neither is available to this Block, which
+     * knows no locale and would ship English month names into every consumer's
+     * product.
+     */
+    at: string;
+    /** What the milestone is called, in the caller's own words. */
+    title: string;
+    /** What the milestone changed, for a reader who has arrived at it. */
+    body?: ReactNode;
+    /**
+     * How far along this milestone was, as a percentage, or nothing.
+     *
+     * Omit it for a milestone that is a moment rather than a piece of work, and the
+     * row draws no bar at all rather than a bar at zero, because a bar at zero is a
+     * claim that nothing happened and a milestone is by definition something that
+     * did.
+     */
+    progress?: number;
+    /**
+     * Where the milestone stands. Omit it and the row draws a bare tick on the
+     * rail rather than one of the three state marks, because the alternative is
+     * this Block drawing a state the caller did not say.
+     */
+    state?: MilestoneState;
+    /** Where the milestone goes. Rendered as a native anchor. */
+    href?: string;
+    /** The words on that link. Required whenever `href` is set. */
+    hrefLabel?: string;
+};
+/**
+ * The props a MilestoneTimeline01 takes.
+ *
+ * Every string and every number is a prop and the Block ships none. There is no
+ * default sequence, no default date, no default state and no default wording for
+ * the current milestone, and the absence of the sequence is the sharpest version
+ * of the rule: what a system has reached is a claim about a system, and a Block
+ * that shipped one would be publishing a roadmap on every consumer's behalf.
+ */
+export type MilestoneTimeline01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /** The section title. Required, because a sequence with no heading is a fragment. */
+    title: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /**
+     * The milestones, in the order they were reached. Order is the caller's,
+     * because it is a claim about what came first.
+     */
+    milestones: readonly Milestone[];
+    /**
+     * The words for the milestone that is current, and the only state on the rail
+     * that carries any. Required whenever a milestone is `current`.
+     */
+    nowLabel?: string;
+    /**
+     * The words for a milestone's progress, given the number.
+     *
+     * Required whenever any milestone carries `progress`. See the Component JSDoc
+     * for why the bar's own value is not enough to announce.
+     */
+    progressLabel?: (value: number) => string;
+    /**
+     * 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 dated sequence of what a system reached: when, what, and how far along it
+ * was, on a rail with a rule down one side and a fill per milestone.
+ *
+ * **What this is not, and it has to be sharp because two sibling items exist and
+ * a reader will meet all three.** The three differ by tense and by whether the
+ * sequence is still running, and nothing else, so the differences are worth
+ * stating as exactly that. `timeline.tsx` is a Component, not a Block, and it
+ * shows where a **run** has got to **as it happens**: it is fed events, it has
+ * four run states of its own (`pending`, `running`, `done`, `failed`), it scales
+ * each step's duration against the longest step in the run, and one of its states
+ * moves. It is a `live` concern, and a reader who met one of those on a page
+ * would be told something about the product is running right now. `story-01` is
+ * a Block, and it arranges a company's **past** in the **past tense**: a history,
+ * dated, in the order it happened, with a figure beside some of the entries and
+ * no state on any of them, because a history has nothing to be current about.
+ * This Block is a Block too, and it shows a system's **reached and not yet** state
+ * with a **fill per milestone**, and that is the middle case: it has a future, so
+ * it has an `upcoming`, and it has a position, so exactly one of its milestones
+ * may be `current` and that one is named. A consumer who has a run wants
+ * `Timeline`, a consumer who has a company wants `story-01`, and a consumer who
+ * has a system that has got to where it is now, and has not got to the rest of
+ * it, wants this.
+ *
+ * **The fill is `Progress`, and a filled bar drawn here would be a second
+ * implementation of a Component whose accessibility was already worked out.**
+ * Three states in a row is what `steps.tsx` already owns, and a Block that
+ * re-drew the rule would be a second implementation of a Component whose
+ * accessibility was already worked out. The same argument settles the bar: a
+ * hand-drawn filled bar is a div with a width on it, and a div with a width is a
+ * picture of a value that no screen reader, no crawler and no print stylesheet can
+ * read, which is the exact failure `Progress` exists to close, because it exposes
+ * the value, the minimum and the maximum through ARIA and takes the words for it
+ * through `valueText`. The cost of composing it rather than drawing is real
+ * and is named here: `Progress` is a client Component over Base UI, so a
+ * milestone that carries a `progress` is a client island, and a consumer with
+ * eight milestones all carrying one is paying for eight. The answer is to leave
+ * `progress` off the milestones that are moments, which is what the prop's own
+ * documentation says.
+ *
+ * **The words travel as a string and not as a function, and that is the server
+ * boundary rather than a preference.** This Block is a server Component and
+ * `Progress` is a client one, so a callback prop handed down from here is a build
+ * error: the two halves do not share a runtime, and a function cannot be
+ * serialised across the seam. It called `getAriaValueText={(v) => progressLabel(v)}`
+ * first, and the whole roster failed to prerender on the first milestone that
+ * carried a bar. `Progress` therefore publishes `valueText` for exactly this case
+ * and throws when a caller gives it both forms, so the ambiguity is reported
+ * rather than resolved by whichever prop the framework happened to read last.
+ *
+ * **`progressLabel` is required whenever a milestone carries a `progress`, and
+ * the reason is that the number is not a sentence and does not know its unit.**
+ * A milestone's bar is a percentage of something this Block cannot see, and
+ * sixty per cent of a migration is not the same fact as sixty per cent of a
+ * rollout of a policy, so the bar alone announces a bare figure that means
+ * whatever the reader assumes. The label is the caller's because the thing being
+ * measured is the caller's, and the same argument as `RelativeTime` applies to the
+ * rest of this surface: a sentence about a caller's own quantity cannot be
+ * authored here, because Prism does not know the unit, the period, or what the
+ * bar is a bar of.
+ *
+ * **`nowLabel` is required whenever a milestone is `current`, and the reason is
+ * the one this package keeps arriving at from three directions.** A mark is a
+ * shape, and a reader who cannot separate the emphasis ink from the border colour
+ * has learned nothing from it; a `current` milestone is the one row a reader may
+ * act on, and an unnamed current row is a row a reader has to guess the
+ * importance of. `StatusLedger01` requires its words for the same reason,
+ * `InstrumentPanel01` throws on a state with no label beside it, and the copy gate
+ * holds the close button of a dialog for it. The Block throws rather than
+ * shipping a state a reader can only see.
+ *
+ * **A milestone with no state draws a tick and not one of the three marks.**
+ * That is a small decision with a large one behind it. The three state marks all
+ * say something: this one is reached, this one is where the system is, this one
+ * has not happened. A caller who passes no `state` has said none of those, and the
+ * Block cannot pick one on their behalf, because the two available guesses are
+ * both wrong in a way a reader would act on. Drawing it as `complete` claims the
+ * system got there, and a milestone the team is still working on would then read
+ * as done. Drawing it as `upcoming` claims it has not, and a milestone that
+ * finished last year would then read as pending. So the row draws a bare hairline
+ * on the rail, which reads as a mark that has nothing to say, and the sequence is
+ * still complete and legible without it.
+ *
+ * **`at` is a string rather than a `Date`, so the caller keeps its own locale.**
+ * See the field's own documentation above. A `Date` prop would carry a timezone
+ * and a calendar into a Block that formats nothing, and the honest way to render
+ * a moment in a caller's language is the caller's to compose: `RelativeTime` for
+ * a localised absolute reading with the relative words handed back, or the
+ * platform's `Intl.DateTimeFormat` for a fixed one.
+ *
+ * **One `<ol>`, and the rail is not a second list.** A sequence drawn as a row
+ * per group would be several lists, and a screen reader would announce it as
+ * several. The milestones are one ordered list, the spine is a decorative span
+ * inside each entry and is `aria-hidden`, so the sequence is read from the
+ * entries and not from a rule. The spine runs from the mark to the bottom of its
+ * own entry and the last entry draws none, which is the detail that separates a
+ * rail from a border.
+ *
+ * A milestone title is a heading one step below the section, derived rather than
+ * written, so a Block embedded one level deeper carries its headings with it. A
+ * body of more than about four lines stops being a milestone body, and the detail
+ * belongs above the rail in `description` or in the caller's own figure.
+ *
+ * It is a server Component: no hook, no state, no client code of its own and no
+ * router. The only client code it can pull in is one `Progress` island per
+ * milestone that asks for a fill.
+ */
+export declare function MilestoneTimeline01({ eyebrow, title, description, milestones, nowLabel, progressLabel, headingLevel, className, }: MilestoneTimeline01Props): import("react").JSX.Element | null;
+export default MilestoneTimeline01;
+//# sourceMappingURL=milestone-timeline.d.ts.map

package/dist/blocks/milestone-timeline-01/milestone-timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"milestone-timeline.d.ts","sourceRoot":"","sources":["../../../src/blocks/milestone-timeline-01/milestone-timeline.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAIpG;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAA;AAkBhE;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;;;;;;;;;;;OAgBG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAA;IACb,sEAAsE;IACtE,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qFAAqF;IACrF,KAAK,EAAE,SAAS,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;OAGG;IACH,UAAU,EAAE,SAAS,SAAS,EAAE,CAAA;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACzC;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0GG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,OAAO,EACP,KAAK,EACL,WAAW,EACX,UAAU,EACV,QAAQ,EACR,aAAa,EACb,YAAmB,EACnB,SAAS,GACV,EAAE,wBAAwB,sCAsI1B;AAED,eAAe,mBAAmB,CAAA"}