@nanisoft/prism-ui 0.13.0 → 0.16.0

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';

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

@@ -0,0 +1,301 @@
+import { type ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * The cells a project row can draw, and the four column names a caller names
+ * them with in the table form.
+ *
+ * A closed set, and the closure is the point: the cells are the Block's, so a
+ * table with a ninth column would be a table whose ninth column has nothing to
+ * put in it. The names are the caller's, which is the other half of the same
+ * thing. A projects index is a set of records whose vocabulary differs by
+ * product, and "State", "Status" and "Stage" are three names for one column and
+ * only the set's owner can say which is right. So `header` is a prop and `id` is
+ * not.
+ */
+export type ProjectListCell = 'name' | 'summary' | 'state' | 'owner' | 'progress' | 'updated' | 'tags' | 'href';
+/**
+ * One column of a projects table: which cell it draws, and the words above it.
+ *
+ * The `header` precedent is `ResourceListColumn`'s and the difference from
+ * `DataTableColumn` is the same one that file states: `DataTableColumn` takes a
+ * `cell` function because it has no idea what a row contains, and this Block knows
+ * the eight cells a project has, so a caller that could write a `cell` function
+ * could draw this table without this Block. What is left is the part that is
+ * genuinely the caller's: the name of the column, its order, and where it sits.
+ */
+export type ProjectListColumn = {
+    /** Which of the eight cells this column draws. */
+    id: ProjectListCell;
+    /** The column's name, in the product's own words. */
+    header: ReactNode;
+    /**
+     * Layout classes for the column, applied to the header cell and to every cell
+     * under it. Alignment and a fixed width are what this is for.
+     */
+    className?: string;
+};
+/**
+ * One project in a list: the same fields `Project01` takes, in the form a row can
+ * carry.
+ *
+ * The field names are the same and the shapes are the same, and that is the whole
+ * point of this Block existing beside that one. A consumer with a project model
+ * has one model, so the same `Project` type renders a detail header and a list row
+ * and the two Blocks cannot drift apart, because there is nothing to drift: a
+ * caller maps their project onto the fields once and both Blocks read the same
+ * names. The cost is stated rather than hidden: a list row has nowhere to put a
+ * stage list, a span of dates and an action slot, so the fields a row drops are
+ * dropped by this type rather than silently ignored, and a caller who needs a
+ * project's stages in a list is looking for `Project01` for that project.
+ */
+export type ProjectListProject = {
+    /** A stable key for the project, within this list. */
+    id: string;
+    /** The project's own name. The anchor of the row and of its cell in a table. */
+    name: string;
+    /** One sentence about what this project is. A node, and a node only. */
+    summary?: ReactNode;
+    /**
+     * Where the project stands, in the caller's own vocabulary.
+     *
+     * Required on every project, and a string rather than a union of five positions
+     * for the reason the tone table above states: a projects index gathers from more
+     * than one source in most products, and a Block that narrowed the state would be
+     * a Block that decided what a project may be in.
+     */
+    state: string;
+    /**
+     * The words for that state.
+     *
+     * Optional in the type and required in practice, and the run throws without it:
+     * every project carries a state, so every project owes words for it, and a dot
+     * with no sentence beside it is the one thing the copy gate and `Status` both
+     * exist to prevent. The `?` is here so a caller arriving from JavaScript gets
+     * this diagnostic rather than a crash inside a Component.
+     */
+    stateLabel?: string;
+    /** Who owns it, with the portrait where there is one. */
+    owner?: {
+        /** The person's own name. */
+        name: string;
+        /** The portrait, with the name the initials come from. */
+        avatar?: {
+            /** The photograph. Omit it, or pass a URL that fails, for the initials. */
+            src?: string;
+            /** The person's name, which is the initials' source. */
+            name: string;
+        };
+    };
+    /**
+     * How far along the project is, on `Progress`'s own scale of 0 to 100.
+     *
+     * Omit it for a project that is not measured, and the row draws no bar rather
+     * than a bar at zero, because a bar at zero is a claim that nothing has
+     * happened and a planning project is a thing that has not started.
+     */
+    progress?: number;
+    /**
+     * The sentence the bar announces, given the value and the project's name.
+     *
+     * Optional in the type and required in practice whenever any project carries a
+     * `progress`, and the run throws without it. The name is in the argument because
+     * a list of forty projects is a page where a reader has to be told which bar is
+     * which, and a bar at forty per cent means whatever the reader assumes.
+     */
+    progressLabel?: (value: number, name: string) => string;
+    /** When the project last moved, in whichever of the three forms the caller has. */
+    updated?: number | string;
+    /**
+     * The sentence for that moment, given the moment.
+     *
+     * Optional in the type and required in practice whenever any project carries an
+     * `updated`, and the run throws without it. A moment handed to `RelativeTime`
+     * with nothing beside it is a date in the reader's own locale and no claim about
+     * how old it is, which is the honest reading and is not the one a list of
+     * projects is for.
+     */
+    updatedLabel?: (value: number | string) => string;
+    /** The caller's own chips for this project, in the order they should be met. */
+    tags?: {
+        id: string;
+        label: ReactNode;
+    }[];
+    /** Where the row goes. Rendered as a native anchor, so the destination is real. */
+    href?: string;
+    /**
+     * The words on that link, and required whenever `href` is set.
+     *
+     * A link whose only words are a project's name tells a reader nothing about what
+     * activating it will do. The words are the caller's because the destination is
+     * theirs, and the trailing position rather than the whole row is deliberate: a
+     * row whose accessible name is its name, its summary, its state and its date is
+     * a name a reader cannot hear the end of.
+     */
+    hrefLabel?: string;
+};
+/**
+ * The props a ProjectList01 takes, and the one conditional pair among them.
+ *
+ * Every string and every number is a prop and the Block ships none: no project, no
+ * state, no owner, no progress figure, no date, no chip and not one column heading.
+ * A projects index that invented a set of them would be publishing somebody
+ * else's portfolio, and the absence of the empty sentence is the sharpest version
+ * of the rule: "no projects yet" is true of a new product and false of a filter
+ * that matched nothing, so `empty` is required.
+ */
+export type ProjectList01Props = {
+    /** 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 projects, in the order a reader should meet them.
+     *
+     * Order is the caller's, and this Block does not sort: a projects index is very
+     * often already ordered by a query that knows which project is live, which the
+     * team wants at the top and which the reader is waiting for, and a Block that
+     * sorted by name or by date would undo that decision without saying so.
+     */
+    projects: ProjectListProject[];
+    /**
+     * The controls that act on the whole list: a search field, a sort, a create
+     * button, a `DataToolbar` the caller composed.
+     *
+     * A slot rather than a set of named controls, because which controls a list has
+     * is the caller's fact, and because a slot keeps this Block a server Component:
+     * a caller whose toolbar needs state renders a client component into it, and the
+     * client boundary is theirs rather than this file's.
+     */
+    toolbar?: ReactNode;
+    /**
+     * The filter column, beside the list rather than above it.
+     *
+     * A `FilterPanel` is what this slot is for, and a panel is a column, so it is
+     * drawn in a narrow aside at the leading edge with the list beside it. A caller
+     * whose filters are a popover trigger or a set of chips passes them in
+     * `toolbar` and leaves this alone; a Block that drew the filters itself would be
+     * deciding that a projects index is faceted, which most are not.
+     */
+    filters?: ReactNode;
+    /**
+     * The band's slot under the list: pagination, a count, a load-more control.
+     *
+     * Under the list and not inside it, because it is the one part of the surface
+     * that has to stay put while a reader works down a long list.
+     */
+    footer?: ReactNode;
+    /**
+     * What the Block renders in place of the rows when there are none.
+     *
+     * Required, and a slot rather than a string, because the two empty states a
+     * projects index has are different claims: a product with no projects yet and a
+     * filter that matched nothing are opposite sentences, and a Block that wrote
+     * either one would be wrong in half the products that installed it.
+     */
+    empty: ReactNode;
+    /**
+     * Whether the list is a stack of rows or a real table.
+     *
+     * `rows` is for a short list where the summary is the point, and it is the
+     * default because a list a reader scans top to bottom does not need column
+     * semantics to be read. `table` is for a long one, where the reader is comparing
+     * a value in one row against the same value in another, which is the moment a
+     * row stops being a list and becomes a record set: it is the moment a screen
+     * reader needs a column header to know which of six values it has landed on, and
+     * it is the moment a caller starts wanting to sort.
+     */
+    variant?: 'rows' | 'table';
+    /**
+     * The caller's own columns, in the order the reader should meet them.
+     *
+     * Required in the table form and refused in the row form, and the union below is
+     * what says so. The `name` column has to be among them and the run fails without
+     * it, because it is the row header: a table whose rows have no row header is a
+     * table where a reader who lands on one cell is not told which project they are
+     * in. A column no project carries is a column of empty cells, which is a column
+     * every reader scans twice, and the run fails on that too.
+     */
+    columns?: ProjectListColumn[];
+    /**
+     * Heading level for the section title. See `HeadingLevel`.
+     */
+    headingLevel?: HeadingLevel;
+    /** Layout only, exactly as on every Block. */
+    className?: string;
+} & ({
+    /** A table declares its columns, because a header row is read out loud. */
+    variant: 'table';
+    columns: ProjectListColumn[];
+} | {
+    /** A row list has no header row, so there is nothing to declare. */
+    variant?: 'rows';
+    columns?: never;
+});
+/**
+ * A list of projects, as rows or as a real table, with a toolbar, a filter column
+ * and an empty state the caller writes.
+ *
+ * **This is the many-projects counterpart to `Project01`, and the two take the
+ * same field names on purpose.** A consumer with a project model has one model: a
+ * caller maps their project onto `name`, `state`, `owner`, `progress`, `updated`
+ * and `tags` once, and that mapping feeds a detail header and a list row without
+ * either Block knowing the other exists. The alternative, a list Block with its own
+ * field names, gives every consumer two models to keep in step, and the two drift
+ * within a release rather than across one, which is the failure mode this
+ * repository is organised against. The cost is stated rather than hidden: a row has
+ * nowhere to put a stage list, a span of dates and an action slot, so those fields
+ * are absent from the row type instead of being quietly ignored.
+ *
+ * **The two variants answer different questions, and `rows` is the one that is
+ * scanned while `table` is the one that is compared.** A short list where the
+ * summary is the point wants the rows form: each row is one project read top to
+ * bottom, its name and its sentence and its state, with no header row to announce
+ * and no columns to align, and the reader's job is to find the one they want. A
+ * long list wants the table form, and the moment that changes is the moment a
+ * reader starts comparing a value in one row against the same value in another:
+ * that is when the content is records with columns rather than a list of things,
+ * which is the exact boundary `ListPanel` draws in its own documentation. The
+ * three things a `<div>` grid gets wrong are the three a reader of forty projects
+ * needs: there is no `th` to navigate by, so a screen reader announces a bare run
+ * of values with no idea which is the state and which is the owner; there is no
+ * row header, so a reader who lands on one cell is not told which project they are
+ * in; and there is nothing for a browser's own table commands to act on.
+ *
+ * **The filter column is a slot, and it is a slot rather than a set of named
+ * controls because a projects index is not always faceted.** `FilterPanel` is the
+ * Component it is for, and the panel is a column, so the slot is drawn in a narrow
+ * aside at the leading edge with the list beside it. A caller whose filters are a
+ * popover trigger or a row of chips passes them in `toolbar` instead, and a Block
+ * that drew its own filters would be deciding that every projects index is a
+ * faceted browser, which most of them are not.
+ *
+ * **The order is the caller's and this Block does not sort.** The same argument
+ * `ResourceList01` gives and the same one `Leaderboard01` gives harder: a projects
+ * index is very often already ordered by a query that knows which project is live,
+ * and a Block that sorted by name or by date would undo a decision it cannot see.
+ * A `sort` prop would be 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.
+ *
+ * **The run fails on five ways a projects table can be wrong, and every one of
+ * them reaches a developer rather than a reader.** A `columns` array with no
+ * `name` in it is a header row with a cell fewer than every body row and a table
+ * whose rows have no identity. A `columns` array that names the same cell twice is
+ * a table with two columns reading the same value. A column no project carries is
+ * a column of empty cells. A project with a state and no words for it is a dot
+ * with nothing beside it. And a project with a progress and no sentence for it, or
+ * a moment and no sentence for it, or a link and no words on it, is a figure
+ * announcing a bare number, a date with no claim about how old it is, and a link
+ * announced by its address. Each message names the project rather than the index,
+ * because a caller with forty projects needs to know which one.
+ *
+ * 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 project
+ * that asks for a fill, and the portrait is `Avatar`, whose only client work is
+ * measuring whether an image has loaded.
+ */
+export declare function ProjectList01({ eyebrow, title, description, projects, toolbar, filters, footer, empty, variant, columns, headingLevel, className, }: ProjectList01Props): import("react").JSX.Element;
+export default ProjectList01;
+//# sourceMappingURL=project-list.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"project-list.d.ts","sourceRoot":"","sources":["../../../src/blocks/project-list-01/project-list.tsx"],"names":[],"mappings":"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"}