@nanisoft/prism-ui 0.10.2 → 0.15.0

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

@@ -0,0 +1,247 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Avatar, AvatarFallback, AvatarImage } from '../../components/ui/avatar.js';
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Metric } from '../../components/ui/metric.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 { Steps } from '../../components/ui/steps.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The tone each state is drawn in, from the semantic contract and no other.
+ *
+ * Two of the five share a role and the sharing is deliberate rather than lazy.
+ * `active` and `complete` are both `success`, because a project that is running
+ * and a project that finished are the two states a reader is glad to see, and the
+ * words beside the dot are what tell them apart, which is the arrangement the
+ * whole tier rests on: colour is never the only channel. `planning` is `info`,
+ * the contract's cool role that means not an alarm, because work being shaped is
+ * not a fault. `archived` is `neutral`, because a project nobody is working on is
+ * not in dispute and must not be drawn as though it were.
+ *
+ * `blocked` is `warning` and not `destructive`, for the reason `FieldMap01` gives
+ * for an unmapped field: an unmapped field is a thing to do rather than a
+ * breakage, and a table of thirty projects where four are amber is a table with
+ * four tasks in it, while the same four in red reads as four incidents and sends
+ * a reader looking for a failure that is not happening. The cost is named here
+ * because it is real: a blocked project is a genuine problem, and this tone says
+ * "attend to it" rather than "something is broken". A caller whose product treats
+ * a block as a failure has no seam here, and the answer is `summary`.
+ */
+const STATE_TONE = {
+    planning: 'info',
+    active: 'success',
+    blocked: 'warning',
+    complete: 'success',
+    archived: 'neutral',
+};
+/**
+ * The state a stage's mark is drawn from.
+ *
+ * Three entries for three positions. `done` becomes `complete` because that is
+ * the word `Steps` uses for a stage behind the reader, and the two vocabularies
+ * differ only there. A map rather than a lookup at the call site because the
+ * translation is a fact about the Component and not about the data, and a Block
+ * that spelled `complete` in five places would be five chances to spell it once
+ * wrong.
+ */
+const RAIL_STATE = {
+    done: 'complete',
+    current: 'current',
+    upcoming: 'upcoming',
+};
+/**
+ * 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` and `Team01` apply and it is
+ * repeated here for the reason `Team01` states in full: that helper is private to
+ * its module and exporting it would make a private derivation part of the
+ * published surface of a Component in order to save six lines in a Block. The cost
+ * of the repetition is named rather than hidden, because three modules now carry
+ * this rule and a change to it is a change in three. A caller who needs a case it
+ * does not cover passes their own node through the `avatar` slot's `name` and a
+ * monogram of their own choosing.
+ */
+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 stage the rail is on, and the reason this Block picks it rather than asking.
+ *
+ * `Steps` requires exactly one current step and throws without one, and a
+ * project's stage list is a place where that is genuinely absent: a project whose
+ * stages are all done has no current stage, and a project nobody has started has
+ * one that is not declared. So the rail's position is derived when the caller has
+ * not declared it: the first stage that has not been done, and the last stage
+ * when everything is done, which is the only position a finished rail can hold.
+ *
+ * The caller who has declared one gets it, and the caller who has declared two is
+ * a caller whose data contradicts itself, which the guard above refuses rather
+ * than a position this Block guesses at.
+ */
+function railCurrent(stages) {
+    const declared = stages.findIndex((stage) => stage.state === 'current');
+    if (declared !== -1)
+        return declared;
+    const firstOpen = stages.findIndex((stage) => stage.state === 'upcoming');
+    return firstOpen === -1 ? stages.length - 1 : firstOpen;
+}
+/**
+ * A project in full: its name, where it stands, who owns it, when it runs, how far
+ * along it is, what it reads, and the stages it is on.
+ *
+ * **The reader here is looking for one project, so everything in this Block is
+ * scannable and the two things a reader reaches for are a state and an owner.**
+ * That is the fact the whole arrangement is built on, and it is why the state and
+ * the owner sit on the first line under the name rather than in a field list at
+ * the bottom: a reader who has opened a project to find out whether it is stuck
+ * has two questions, and neither of them is a figure. Scanability and keyboard
+ * reach outrank expression at this tier, and a state nobody can find in a glance
+ * is a state this Block has failed to ship whatever else it got right.
+ *
+ * **The state is `Status` and the figures are `Metric`, and neither was redrawn.**
+ * `Status` is a dot in one of five tones beside the caller's own words, and it
+ * owns the arrangement that matters here: the dot is `aria-hidden` and the words
+ * carry the state, so a reader who cannot separate `warning` from `destructive`
+ * still reads which is which, and a state is never colour alone. A hand-drawn dot
+ * beside a word in this Block would be a second implementation of that Component
+ * and the second one is the one that gets the `aria-hidden` wrong. `Metric` owns
+ * the arrangement a headline figure is read in, which puts the figure first and
+ * the name under it, and it owns the fact that a string figure is set in the mono
+ * face while a composed one is not. The one thing it cannot do is print a delta it
+ * has no unit for, and the cost of that is stated on `Project01Figure`.
+ *
+ * **The fill is `Progress` with `valueText`, and the reason is the seam rather
+ * than 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. The
+ * second half is why the words travel as a string: this Block is a server
+ * Component and `Progress` is a client one, so a callback handed down from here is
+ * a build error rather than a warning, and `Progress` therefore publishes
+ * `valueText` for exactly this case. The cost of composing it is real and is named
+ * here: `Progress` is a client Component, so a project with a fill is a client
+ * island and a caller with forty projects on one page is paying for forty. The
+ * answer is to leave `progress` off the projects that are not measured.
+ *
+ * **The stage list is `Steps`, because the rail is a Component and the three
+ * marks are already right.** The alternative was a hand-drawn list of discs and
+ * rules, and it is a second implementation of three things `Steps` has already
+ * settled: that the states differ by shape before they differ by colour, so a
+ * reader who cannot separate a filled disc from a ring is not being told two
+ * different things about two different stages; that exactly one step carries
+ * `aria-current`, because two current steps is a rail with two answers to where
+ * the reader is; and that the rule between the steps carries how far along they
+ * are, rather than a bar per step restating "done" once per stage and leaving the
+ * arithmetic to the reader. The cost is stated rather than hidden, and it is the
+ * rail's own limitation rather than this Block's: `Steps`'s qualifier is a string,
+ * and a stage's moment is a node, so the rail cannot hold a date. The moments are
+ * drawn beneath it as the definition list they are, and a caller whose stages are
+ * mostly dates wants `MilestoneTimeline01`, which is the Block built for a dated
+ * sequence.
+ *
+ * **The dates are the caller's and the sentence is the caller's, and this is the
+ * same rule the rest of this roster keeps arriving at from three directions.** The
+ * moments are passed to `RelativeTime` untouched, so the absolute reading a reader
+ * sees is the platform's own in the language they have, and `dateLabel` supplies
+ * the sentence beside it, which is the one string in the pair that is English by
+ * nature: it has a plural, it changes shape past a day, and every language words
+ * it differently. A Block that formatted the moment instead would ship one
+ * locale's format into every consumer's project, and a Block that wrote the
+ * sentence would ship English. The honest cost is a small one and it is named
+ * here: `dateLabel` is given the moment and not the role, so it cannot say whether
+ * a reading is the start of the span or the end of it, and the order is what
+ * carries that. A caller whose product names its two ends differently composes the
+ * two readings themselves, which is the same amount of work and one more prop.
+ *
+ * **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 on the
+ * project that asks for a fill, and the portrait is `Avatar`, whose only client
+ * work is measuring whether an image has loaded.
+ */
+export function Project01({ name, summary, state, stateLabel, owner, startsAt, endsAt, dateLabel, figures, stages, actions, progress, progressLabel, layout = 'stacked', headingLevel = 'h2', className, }) {
+    /*
+     * The announced sentence for the bar, bound once after the guard below.
+     *
+     * The union above is what makes the pair complete, so by the time anything
+     * renders the function is there. The type cannot see that, because the check is
+     * on one arm of a union and the use is inside a ternary over `progress`, so a
+     * closure is bound here and the render reads one name. `labelProgress` never
+     * returns an empty string: the guard has already refused that case, and a second
+     * refusal inside the render would be the same diagnostic twice.
+     */
+    const labelProgress = (value) => {
+        if (progressLabel === undefined) {
+            throw new Error('Project01: reached the bar with no progressLabel, which the union above should have made ' +
+                'impossible. The two are separate so that the diagnostic names the prop rather than the render.');
+        }
+        return progressLabel(value, name);
+    };
+    if (owner !== undefined && owner.href !== undefined && !owner.hrefLabel) {
+        throw new Error(`Project01: the owner of "${name}" declares an href with no hrefLabel, so the link would be ` +
+            'announced by its destination alone. A person\'s name is a name, and the sentence saying that ' +
+            'following the link is a thing you can do belongs to the caller.');
+    }
+    const currents = stages?.filter((stage) => stage.state === 'current').length ?? 0;
+    if (currents > 1) {
+        throw new Error(`Project01: the stages of "${name}" declare ${currents} current stages, and a rail has one ` +
+            'position. Two current stages is a reader told they are in two places at once. Declare one, or ' +
+            'leave the state to the order.');
+    }
+    for (const stage of stages ?? []) {
+        if (!stage.stateLabel) {
+            throw new Error(`Project01: the stage "${stage.id}" declares a state and no stateLabel, so the mark beside it ` +
+                'would be a shape with no sentence, and a shape a reader can only see is a state nobody can act ' +
+                'on. Pass the words your readers use for that position.');
+        }
+    }
+    const rail = (stages ?? []).map((stage) => ({
+        label: stage.name,
+        description: stage.stateLabel,
+        // The states are the caller's rather than the rail's whenever the caller
+        // declared a position, because a project that reached a stage out of band is
+        // real and a rail derived from the order would draw a claim the data
+        // contradicts. With no declared position the rail derives every mark, which is
+        // the arrangement that cannot disagree with itself.
+        ...(currents === 1 ? { state: RAIL_STATE[stage.state] } : null),
+    }));
+    const dated = (stages ?? []).filter((stage) => stage.at !== undefined);
+    const hasSpan = startsAt !== undefined || endsAt !== undefined;
+    const aside = (_jsxs("div", { "data-slot": "project-01-aside", className: "flex min-w-0 flex-col gap-6", children: [_jsxs("div", { "data-slot": "project-01-facts", className: "flex flex-wrap items-center gap-x-6 gap-y-3", children: [_jsx(Status, { tone: STATE_TONE[state], label: stateLabel(state) }), owner === undefined ? null : (_jsxs("span", { "data-slot": "project-01-owner", className: "flex min-w-0 items-center gap-2", children: [owner.avatar === undefined ? null : (_jsxs(Avatar, { className: "size-6", children: [owner.avatar.src === undefined ? null : (_jsx(AvatarImage, { src: owner.avatar.src, alt: "" })), _jsx(AvatarFallback, { className: "text-mono", children: initialsOf(owner.avatar.name) })] })), owner.href === undefined || owner.hrefLabel === undefined ? (_jsx("span", { "data-slot": "project-01-owner-name", className: "text-sm", children: owner.name })) : (_jsx(CtaLink, { href: owner.href, size: "sm", variant: "ghost", children: owner.hrefLabel }))] })), hasSpan ? (
+                    /*
+                      The two ends of the span, in the order the span runs, with no separator
+                      between them. The gap is the separator and it is deliberate: a dash, a
+                      comma or a "to" would be a word or a piece of punctuation this Block
+                      chose, and the caller's `dateLabel` is the only thing on this line
+                      allowed to say anything. `data-slot` names each end so a test and a
+                      caller can find one of them, which is what a reader cannot do.
+                    */
+                    _jsxs("span", { "data-slot": "project-01-span", className: "text-muted-foreground flex flex-wrap items-baseline gap-x-3 text-sm", children: [startsAt === undefined ? null : (_jsx(RelativeTime, { "data-slot": "project-01-start", date: startsAt, relative: dateLabel?.(startsAt) })), endsAt === undefined ? null : (_jsx(RelativeTime, { "data-slot": "project-01-end", date: endsAt, relative: dateLabel?.(endsAt) }))] })) : null] }), actions === undefined ? null : (_jsx("div", { "data-slot": "project-01-actions", className: "flex flex-wrap items-center gap-2", children: actions }))] }));
+    const body = (_jsxs(_Fragment, { children: [progress === undefined ? null : (_jsx("div", { "data-slot": "project-01-progress", className: "flex flex-col gap-2", children: _jsx(Progress, { value: progress, valueText: labelProgress(progress) }) })), figures === undefined || figures.length === 0 ? null : (_jsx("div", { "data-slot": "project-01-figures", className: "grid gap-6 sm:grid-cols-2 lg:grid-cols-4", children: figures.map((figure) => (_jsx(Metric, { "data-slot": "project-01-figure", value: figure.value, label: figure.label, delta: figure.delta }, figure.label))) })), stages === undefined || stages.length === 0 ? null : (_jsxs("div", { "data-slot": "project-01-stages", className: "flex flex-col gap-6", children: [_jsx(Steps, { steps: rail, current: railCurrent(stages) }), dated.length === 0 ? null : (
+                    /*
+                      The moments, which the rail has no room for. See the JSDoc above: a
+                      `Step`'s qualifier is a string, and a date is a node, so the two ends
+                      of the same fact cannot both go in the rail. A definition list is the
+                      honest shape for a set of names and their moments, and it is drawn
+                      only when there is a moment to draw, because a list of nothing is a
+                      gap the reader looks through.
+                    */
+                    _jsx("dl", { "data-slot": "project-01-dates", className: "grid gap-x-8 gap-y-2 sm:grid-cols-2", children: dated.map((stage) => (_jsxs("div", { "data-slot": "project-01-date", className: "flex items-baseline gap-3", children: [_jsx("dt", { className: "text-sm font-medium", children: stage.name }), _jsx("dd", { className: "text-muted-foreground text-sm", children: _jsx(RelativeTime, { date: stage.at }) })] }, stage.id))) }))] }))] }));
+    return (_jsxs(Section, { "data-slot": "project-01", className: cn(className), children: [_jsx(SectionHeading, { as: headingLevel, align: "left", title: name, description: summary, className: "mb-10" }), _jsx("div", { "data-slot": "project-01-body", "data-layout": layout, className: cn(
+                // The two layouts get one display each rather than a base and an
+                // override, because `flex` and `grid` are the same property and which
+                // one wins is a question about the order of the generated stylesheet
+                // rather than about the order of the class names here.
+                layout === 'split'
+                    ? 'grid gap-10 lg:grid-cols-[minmax(0,3fr)_minmax(0,2fr)] lg:gap-14'
+                    : 'flex flex-col gap-10'), children: layout === 'split' ? (_jsxs(_Fragment, { children: [_jsx("div", { "data-slot": "project-01-main", className: "flex min-w-0 flex-col gap-10", children: body }), aside] })) : (_jsxs(_Fragment, { children: [aside, body] })) })] }));
+}
+export default Project01;

package/dist/blocks/project-dashboard-01/index.d.ts

@@ -0,0 +1,3 @@
+export { ProjectDashboard01, default } from './project-dashboard.js';
+export type { ProjectDashboard01Figure, ProjectDashboard01Span, ProjectDashboard01Panel, ProjectDashboard01Props, } from './project-dashboard.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/project-dashboard-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/project-dashboard-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIjE,YAAY,EACV,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,qBAAqB,CAAA"}

package/dist/blocks/project-dashboard-01/index.js

@@ -0,0 +1 @@
+export { ProjectDashboard01, default } from './project-dashboard.js';

package/dist/blocks/project-dashboard-01/project-dashboard.d.ts

@@ -0,0 +1,200 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One figure in the row across the top.
+ *
+ * The same three fields `Project01` takes for its figures, declared separately
+ * rather than imported for the reason `ProcessFlow01` gives on `ProcessStage`: a
+ * dashboard and a detail header are different claims, and a caller composing one has
+ * no reason to take the other's type, and sharing the declaration would invite a
+ * caller to widen a dashboard figure by reaching for a detail field. The field names
+ * are still the same on purpose, so a consumer with a project model has one model.
+ */
+export type ProjectDashboard01Figure = {
+    /** What the figure measures, read under it. */
+    label: string;
+    /** The figure itself, already formatted by the caller. */
+    value: ReactNode;
+    /**
+     * The change against the previous reading, as a number whose sign is the
+     * direction. See `MetricDelta` on the Component.
+     */
+    delta?: number;
+};
+/**
+ * How much of the grid one panel takes.
+ *
+ * Three, and the set is a fraction of the row rather than a width in pixels: a
+ * dashboard's panels are wide or narrow, and the honest question about a panel is
+ * how much of the row beside it it wants, which is a proportion of the page rather
+ * than a measurement of itself. `full` is a panel that wants the whole row, `half`
+ * is a panel that shares it with one other, and `third` is a panel in a row of
+ * three.
+ */
+export type ProjectDashboard01Span = 'full' | 'half' | 'third';
+/**
+ * One panel of the overview: what it is called, how much of the row it takes, the
+ * controls that act on it, and its content.
+ *
+ * `children` is the whole of the panel and it is required, because a panel is a
+ * frame around something the caller composed and an empty frame is a card with a
+ * title and a gap in it. The six named panels this Block does not draw are the six
+ * a project overview usually has: a chart, a run queue, a list of stages, the people
+ * on it, its open issues and its recent activity. What a caller wants in them is a
+ * fact about their product, and a pipeline wants the run queue wide and the
+ * approvals narrow while an estate wants capacity wide and the fleet list narrow, so
+ * a Block that chose which of the six it was would be a template wearing a
+ * component's name.
+ */
+export type ProjectDashboard01Panel = {
+    /** A stable key for the panel, so a test can name one of them. */
+    id: string;
+    /**
+     * What the panel is called, in the caller's own words.
+     *
+     * Omit it for a panel that is a chart or a list with nothing to say above it, and
+     * the card draws no heading rather than an empty one. When it is given it is a
+     * heading one level below the section, derived rather than written, so a
+     * dashboard embedded one level deeper than it was written for carries its panel
+     * titles with it.
+     */
+    title?: ReactNode;
+    /**
+     * How much of the row this panel takes. Defaults to `half`.
+     *
+     * A proportion of the row rather than a width, and the default is `half` because
+     * two panels beside each other is the arrangement that works for every number of
+     * panels: one panel is half a row with a gap beside it, three are a row and a
+     * half, and six are three rows of two.
+     */
+    span?: ProjectDashboard01Span;
+    /**
+     * The controls that act on this panel rather than on the project: a range
+     * selector, a view switcher, a sort, a link to the full list.
+     *
+     * A slot, and placed at the trailing edge of the panel's header beside its title
+     * rather than above it, because a control the reader has to find is a control the
+     * reader does not use, and the title is what the panel is for.
+     */
+    toolbar?: ReactNode;
+    /** The panel's content, which is the caller's own node. */
+    children: ReactNode;
+};
+/**
+ * The props a ProjectDashboard01 takes.
+ *
+ * Every string and every number is a prop and the Block ships none: no project, no
+ * state, no figure, no panel and not one panel title. The absence of the panels is
+ * the sharpest version of the rule, because a dashboard is the surface most likely
+ * to be shipped with somebody else's numbers in it: a set of figures invented to look
+ * like a working product is worse than no dashboard, which is the argument
+ * `Stats01` makes in full and the reason that Block's early version is a paragraph
+ * on its own JSDoc.
+ */
+export type ProjectDashboard01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /**
+     * The project's own name.
+     *
+     * Required, and it is the section heading rather than a field inside the
+     * dashboard, because a dashboard whose name is a line of body text has already
+     * lost the outline: a reader navigating by heading would meet the section and then
+     * nothing until the panels.
+     */
+    name: string;
+    /** One or two sentences about what this project is, under the name. */
+    summary?: ReactNode;
+    /**
+     * Where the project stands, in the product's own vocabulary.
+     *
+     * Optional, and paired with `stateLabel` rather than beside it: a state a reader
+     * can only see is a state nobody can act on, so the words are required wherever
+     * the dot is drawn, and the run refuses exactly one of the two rather than
+     * drawing a dot with no sentence.
+     */
+    state?: string;
+    /** The words for that state. Required whenever `state` is given. */
+    stateLabel?: string;
+    /** The figures, in the order a reader should meet them. */
+    figures?: ProjectDashboard01Figure[];
+    /**
+     * The panels, in the order a reader should meet them.
+     *
+     * Order is the caller's because it is a claim about what a reader looks at first
+     * on a page that is trying to tell them everything at once, and this Block does
+     * not reorder panels to put a chart first: a dashboard whose top panel is the one
+     * the product cares about is a claim the caller is better placed to make.
+     */
+    panels?: ProjectDashboard01Panel[];
+    /** Heading level for the section heading. See `HeadingLevel`. */
+    headingLevel?: HeadingLevel;
+    /** Layout only, exactly as on every Block. */
+    className?: string;
+};
+/**
+ * One project's overview: the figures across the top, and a grid of panels whose
+ * spans the caller declares.
+ *
+ * **Every panel is a slot, and the reason is that what a project overview shows is a
+ * fact about the project.** A pipeline wants the run queue wide and the approvals
+ * narrow. An estate wants capacity wide and the fleet list narrow. A research group
+ * wants the papers wide and the citations narrow. Three products, three entirely
+ * different answers to "what is the most important thing on this page", and a Block
+ * that chose one of them would be a template wearing a component's name: a consumer
+ * whose most important panel is the narrow one would have to put it in a slot that
+ * was not there, and the fix would be to fork the Block rather than compose it,
+ * which is the one thing this package does not offer. So this Block owns three
+ * things and nothing else: the grid, the spans, and the figures row. What goes in a
+ * panel, what it is called, and how much of the row it wants are the caller's, and
+ * the cost of that is named rather than hidden: a caller with a panel no Component
+ * in this package can draw composes the row themselves inside the slot, and a
+ * dashboard with no panels at all is a figures row, which is a real surface and a
+ * short one.
+ *
+ * **The spans are proportions of a six-track row, and the row is the Block's rather
+ * than the caller's.** A caller who could pass a width would be choosing between
+ * pixels and fractions, and would have to keep the six answers in step by hand; the
+ * alternative, a `span` of `1 | 2 | 3`, reads as a count of tracks and invites a
+ * caller to pass a four that the row cannot express. So there are three words, they
+ * are proportions, and the tracks behind them are in one table above. What that
+ * costs is real and is on `ProjectDashboard01Span`: a dashboard that wants a fifth
+ * of a row has no seam here, and the answer is two panels side by side, which is
+ * also the arrangement that reads better on a phone.
+ *
+ * **The figures are `Metric` and the state is `Status`, and both were redrawn here
+ * at first.** `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 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 figure is set in the mono face while a
+ * composed one is not. `Status` owns the dot and the arrangement that matters most on
+ * a dashboard: the dot is `aria-hidden` and the words carry the state, so a reader
+ * who cannot separate the tones still reads which is which, and a row of states
+ * never becomes a row of colours. The one thing `Metric` cannot do is print a delta
+ * it has no unit for, so a figure with a `delta` and no formatter prints the number
+ * itself, which is honest and usually not what was wanted; the caller's answer is to
+ * put the whole change in `value` as a node they formatted.
+ *
+ * **A panel's title is a heading one step below the section, derived rather than
+ * written, and a panel with no title draws no heading at all.** A dashboard is
+ * usually three to six titled cards under one heading, and hardcoding `h3` would be
+ * right exactly once, at the nesting depth it was written for; `childLevel` is the
+ * answer every Block in this package gives the same question, and a dashboard
+ * embedded one level deeper than it was written for carries its titles with it. A
+ * panel with no title is a chart with nothing to say above it, and an empty heading
+ * is a gap the reader looks through.
+ *
+ * **An empty set renders the name and nothing else, which is the honest state for a
+ * project with no data on it yet.** The alternative, an empty grid of empty cards,
+ * is a page of six frames with nothing in them, and a reader who sees it concludes
+ * the product is broken rather than that the data has not arrived.
+ *
+ * It is a server Component: no hook, no state, no client code of its own and no
+ * router. What a panel contains is the caller's node, so a dashboard full of charts
+ * costs a consumer nothing from this module.
+ */
+export declare function ProjectDashboard01({ eyebrow, name, summary, state, stateLabel, figures, panels, headingLevel, className, }: ProjectDashboard01Props): import("react").JSX.Element;
+export default ProjectDashboard01;
+//# sourceMappingURL=project-dashboard.d.ts.map

package/dist/blocks/project-dashboard-01/project-dashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-dashboard.d.ts","sourceRoot":"","sources":["../../../src/blocks/project-dashboard-01/project-dashboard.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAqCpG;;;;;;;;;GASG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,KAAK,EAAE,SAAS,CAAA;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAiB9D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,sBAAsB,CAAA;IAC7B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,2DAA2D;IAC3D,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,uEAAuE;IACvE,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,wBAAwB,EAAE,CAAA;IACpC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,uBAAuB,EAAE,CAAA;IAClC,iEAAiE;IACjE,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,OAAO,EACP,IAAI,EACJ,OAAO,EACP,KAAK,EACL,UAAU,EACV,OAAO,EACP,MAAM,EACN,YAAmB,EACnB,SAAS,GACV,EAAE,uBAAuB,+BAkGzB;AAED,eAAe,kBAAkB,CAAA"}

package/dist/blocks/project-dashboard-01/project-dashboard.js

@@ -0,0 +1,124 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Card, CardContent, CardHeader, CardTitle } from '../../components/ui/card.js';
+import { Metric } from '../../components/ui/metric.js';
+import { Section, SectionHeading, childLevel } from '../../components/ui/section.js';
+import { Status } from '../../components/ui/status.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The tone a project's state is drawn in, from the semantic contract and no other.
+ *
+ * Keyed by the caller's own words rather than by a union, and the two states that
+ * share a role are the same two that share it in `Project01`: `active` and
+ * `complete` are both `success`, because a project that is running and a project
+ * that finished are the two states a reader is glad to see, and the words beside the
+ * dot are what tell them apart. `blocked` is `warning` and not `destructive` for the
+ * reason `FieldMap01` gives for an unmapped field: a blocked project is a thing to
+ * unblock rather than a breakage, and four amber rows is a dashboard with four tasks
+ * in it while four red rows is a dashboard sending a reader looking for an incident
+ * that is not happening.
+ */
+const STATE_TONE = {
+    planning: 'info',
+    active: 'success',
+    blocked: 'warning',
+    complete: 'success',
+    archived: 'neutral',
+};
+/**
+ * The tone a state is drawn in, falling back to the supporting ink.
+ *
+ * `neutral` for a state this table does not name, and the reason is that an
+ * unrecognised state is not an emergency: it is a vocabulary this Block has not been
+ * taught, and drawing it in the alarm colour would turn a naming mismatch into a page
+ * of red panels.
+ */
+function toneOf(state) {
+    return STATE_TONE[state] ?? 'neutral';
+}
+/**
+ * The tracks each span takes, out of the six the grid is built from.
+ *
+ * Spelled out per span so the arithmetic is in one table rather than in three
+ * places: six tracks, a half is three of them and a third is two. A map rather than
+ * a lookup at the call site because the translation is a fact about this Block's
+ * grid rather than about the caller's data, and a Block that computed it three times
+ * in three places would be three chances to compute it once differently.
+ */
+const SPAN = {
+    full: 'lg:col-span-6',
+    half: 'lg:col-span-3',
+    third: 'lg:col-span-2',
+};
+/**
+ * One project's overview: the figures across the top, and a grid of panels whose
+ * spans the caller declares.
+ *
+ * **Every panel is a slot, and the reason is that what a project overview shows is a
+ * fact about the project.** A pipeline wants the run queue wide and the approvals
+ * narrow. An estate wants capacity wide and the fleet list narrow. A research group
+ * wants the papers wide and the citations narrow. Three products, three entirely
+ * different answers to "what is the most important thing on this page", and a Block
+ * that chose one of them would be a template wearing a component's name: a consumer
+ * whose most important panel is the narrow one would have to put it in a slot that
+ * was not there, and the fix would be to fork the Block rather than compose it,
+ * which is the one thing this package does not offer. So this Block owns three
+ * things and nothing else: the grid, the spans, and the figures row. What goes in a
+ * panel, what it is called, and how much of the row it wants are the caller's, and
+ * the cost of that is named rather than hidden: a caller with a panel no Component
+ * in this package can draw composes the row themselves inside the slot, and a
+ * dashboard with no panels at all is a figures row, which is a real surface and a
+ * short one.
+ *
+ * **The spans are proportions of a six-track row, and the row is the Block's rather
+ * than the caller's.** A caller who could pass a width would be choosing between
+ * pixels and fractions, and would have to keep the six answers in step by hand; the
+ * alternative, a `span` of `1 | 2 | 3`, reads as a count of tracks and invites a
+ * caller to pass a four that the row cannot express. So there are three words, they
+ * are proportions, and the tracks behind them are in one table above. What that
+ * costs is real and is on `ProjectDashboard01Span`: a dashboard that wants a fifth
+ * of a row has no seam here, and the answer is two panels side by side, which is
+ * also the arrangement that reads better on a phone.
+ *
+ * **The figures are `Metric` and the state is `Status`, and both were redrawn here
+ * at first.** `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 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 figure is set in the mono face while a
+ * composed one is not. `Status` owns the dot and the arrangement that matters most on
+ * a dashboard: the dot is `aria-hidden` and the words carry the state, so a reader
+ * who cannot separate the tones still reads which is which, and a row of states
+ * never becomes a row of colours. The one thing `Metric` cannot do is print a delta
+ * it has no unit for, so a figure with a `delta` and no formatter prints the number
+ * itself, which is honest and usually not what was wanted; the caller's answer is to
+ * put the whole change in `value` as a node they formatted.
+ *
+ * **A panel's title is a heading one step below the section, derived rather than
+ * written, and a panel with no title draws no heading at all.** A dashboard is
+ * usually three to six titled cards under one heading, and hardcoding `h3` would be
+ * right exactly once, at the nesting depth it was written for; `childLevel` is the
+ * answer every Block in this package gives the same question, and a dashboard
+ * embedded one level deeper than it was written for carries its titles with it. A
+ * panel with no title is a chart with nothing to say above it, and an empty heading
+ * is a gap the reader looks through.
+ *
+ * **An empty set renders the name and nothing else, which is the honest state for a
+ * project with no data on it yet.** The alternative, an empty grid of empty cards,
+ * is a page of six frames with nothing in them, and a reader who sees it concludes
+ * the product is broken rather than that the data has not arrived.
+ *
+ * It is a server Component: no hook, no state, no client code of its own and no
+ * router. What a panel contains is the caller's node, so a dashboard full of charts
+ * costs a consumer nothing from this module.
+ */
+export function ProjectDashboard01({ eyebrow, name, summary, state, stateLabel, figures, panels, headingLevel = 'h2', className, }) {
+    if ((state === undefined) !== (stateLabel === undefined)) {
+        throw new Error(`ProjectDashboard01: "${name}" passes ${state === undefined ? 'a stateLabel with no state' : 'a state with no stateLabel'}, ` +
+            'so the dashboard would draw a dot with no sentence beside it or a sentence about a state that is ' +
+            'not there. A state a reader can only see is a state nobody can act on, so pass both or neither.');
+    }
+    const Title = childLevel(headingLevel);
+    return (_jsxs(Section, { "data-slot": "project-dashboard-01", className: cn(className), children: [_jsxs("div", { "data-slot": "project-dashboard-head", className: "flex flex-col gap-6", children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: name, description: summary }), state === undefined ? null : (_jsx("div", { "data-slot": "project-dashboard-state", children: _jsx(Status, { tone: toneOf(state), label: stateLabel }) }))] }), figures === undefined || figures.length === 0 ? null : (_jsx("div", { "data-slot": "project-dashboard-figures", className: "mt-10 grid gap-6 sm:grid-cols-2 lg:grid-cols-4", children: figures.map((figure) => (_jsx(Metric, { "data-slot": "project-dashboard-figure", value: figure.value, label: figure.label, delta: figure.delta }, figure.label))) })), panels === undefined || panels.length === 0 ? null : (_jsx("div", { "data-slot": "project-dashboard-panels", className: "mt-10 grid items-start gap-6 sm:grid-cols-2 lg:grid-cols-6", children: panels.map((panel) => (_jsxs(Card, { "data-slot": "project-dashboard-panel", "data-panel": panel.id, "data-span": panel.span ?? 'half', className: SPAN[panel.span ?? 'half'], children: [panel.title === undefined && panel.toolbar === undefined ? null : (_jsxs(CardHeader, { className: "flex items-center justify-between gap-4", children: [panel.title === undefined ? null : (_jsx(CardTitle, { as: Title, className: "min-w-0", children: panel.title })), panel.toolbar === undefined ? null : (_jsx("div", { "data-slot": "project-dashboard-panel-toolbar", className: "flex shrink-0 items-center gap-2", children: panel.toolbar }))] })), _jsx(CardContent, { className: "min-w-0", children: panel.children })] }, panel.id))) }))] }));
+}
+export default ProjectDashboard01;

package/dist/blocks/project-list-01/index.d.ts

@@ -0,0 +1,3 @@
+export { ProjectList01, default } from './project-list.js';
+export type { ProjectListCell, ProjectListColumn, ProjectListProject, ProjectList01Props } from './project-list.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/project-list-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/project-list-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAKvD,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/blocks/project-list-01/index.js

@@ -0,0 +1 @@
+export { ProjectList01, default } from './project-list.js';