@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/blocks/process-flow-01/process-flow.js

@@ -0,0 +1,71 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The grid tracks each column count gets.
+ *
+ * Spelled out per length, so a flow has exactly as many tracks as it declared and
+ * not one empty at the end of a row. The `sm:` step is a narrowing rather than a
+ * widening: on a narrow screen a flow becomes one column per line, because a
+ * three-up row of stage names at phone width is three columns of two words each.
+ */
+const TRACKS = {
+    2: 'sm:grid-cols-2',
+    3: 'sm:grid-cols-2 lg:grid-cols-3',
+    4: 'sm:grid-cols-2 lg:grid-cols-4',
+};
+/**
+ * A pipeline drawn as a flow: the stages in order, wrapping across lines.
+ *
+ * **The rail's refusal of a fifth stage is left standing.** `ProcessRail01` holds
+ * two, three or four stages and a five-element array is a compile error, and that is
+ * the same decision this Block is built beside rather than against: a rail is a
+ * claim about a sequence on one line, and a rail that quietly dropped a stage to fit
+ * a width would be a diagram of a process that is not the process. A company site
+ * states six stages, and it was drawing them as a grid of short points, where the
+ * six ordinals and the terminal label were lost and a sequence read as a set. That
+ * gap is a gap in the roster, and the honest repair is a second shape rather than a
+ * wider tuple: raising the rail's ceiling to six would make the fourth column
+ * unrepresentable as a type error, which is the property that made the original
+ * decision good.
+ *
+ * **It is one `<ol>`, and that is the part the layout is built around.** A flow that
+ * wrapped into a row per group would be several lists, and a screen reader would
+ * announce it as three lists of two, which is precisely the set-where-a-sequence-was
+ * that this Block exists to avoid. So the stages are one ordered list and the
+ * wrapping is done by the grid, which means the Block never gets to know where a
+ * line broke, and therefore cannot draw something that is only right on the widest
+ * screen.
+ *
+ * **The ordinal is the continuity mechanism, and it is treated as one.** It runs
+ * `01` through to the last stage with no restart, in the mono face, at a size a
+ * reader can scan down a column rather than read one at a time. That is what makes a
+ * wrapped flow legible: a reader who lands on stage four sees `04` and knows it
+ * continues stage three, whatever the column count happens to be at the width they
+ * are using. Nothing else in this Block is load-bearing for the sequence, and
+ * anything that needed to know where the line broke would be.
+ *
+ * **The thread is a line through the stages, not a box around each one.** Each
+ * stage draws a top border and the grid separates them by a single pixel, so a run
+ * of stages on one line reads as one line broken by hairline gaps, and the gap
+ * between two lines is wider. That is the same technique the rail uses, and it is
+ * chosen here for a specific reason: it holds at any column count, including the
+ * one-column layout a phone gets, without the Block knowing anything about it. A
+ * connector drawn between a stage and its successor would need the column count to
+ * be right, and would be wrong at every width the type does not describe.
+ *
+ * A caption of more than about twelve words wraps under a stage and the line stops
+ * reading as a line, so the caption is a line and the detail belongs above the flow
+ * in `description`.
+ *
+ * It is a server Component: no hook, no state and no client code.
+ */
+export function ProcessFlow01({ eyebrow, title, description, finalLabel, stages, columns = 3, headingLevel = 'h2', className, }) {
+    if (stages.length < 2) {
+        throw new Error('ProcessFlow01: a flow of fewer than two stages is a label, not a sequence, and ' +
+            'the Block would be drawing a line through nothing. ComposeProcessRail01 for a ' +
+            'two-stage rail, or pass the stages the pipeline actually has.');
+    }
+    return (_jsxs(Section, { children: [title ? (_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-12" })) : null, _jsx("ol", { "data-slot": "process-flow", className: cn('grid gap-y-8 sm:gap-x-px sm:gap-y-10', TRACKS[columns], className), children: stages.map((stage, index) => (_jsxs("li", { "data-slot": "process-stage", "data-ordinal": String(index + 1).padStart(2, '0'), className: "border-border flex flex-col gap-2 border-t pt-4", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3", children: [_jsx("span", { className: "text-muted-foreground font-mono text-xs tabular-nums", children: String(index + 1).padStart(2, '0') }), finalLabel && index === stages.length - 1 ? (_jsx("span", { className: "text-muted-foreground font-mono text-xs", children: finalLabel })) : null] }), _jsx("span", { className: "text-sm font-semibold", children: stage.name }), _jsx("span", { className: "text-muted-foreground text-pretty text-sm", children: stage.description })] }, stage.name))) })] }));
+}
+export default ProcessFlow01;

package/dist/blocks/process-rail-01/index.d.ts

@@ -1,3 +1,3 @@
-export { ProcessRail01, default } from './process-rail';
-export type { ProcessRail01Props, ProcessRail01Steps, ProcessStep } from './process-rail';
+export { ProcessRail01, default } from './process-rail.js';
+export type { ProcessRail01Props, ProcessRail01Steps, ProcessStep } from './process-rail.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/blocks/process-rail-01/index.js

@@ -1 +1 @@
-export { ProcessRail01, default } from './process-rail';
+export { ProcessRail01, default } from './process-rail.js';

package/dist/blocks/process-rail-01/process-rail.d.ts

@@ -1,4 +1,4 @@
-import { type HeadingLevel } from '../../components/ui/section';
+import { type HeadingLevel } from '../../components/ui/section.js';
 /**
  * One step of a process, as the rail draws it.
  *

package/dist/blocks/process-rail-01/process-rail.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Section, SectionHeading } from '../../components/ui/section';
-import { cn } from '../../lib/utils';
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
 /**
  * The grid tracks each admissible length gets, keyed on the tuple's own length.
  *

package/dist/blocks/product-grid-01/index.d.ts

@@ -1,3 +1,3 @@
-export { ProductGrid01, default } from './product-grid';
-export type { ProductGrid01Props, ProductGrid01Product } from './product-grid';
+export { ProductGrid01, default } from './product-grid.js';
+export type { ProductGrid01Props, ProductGrid01Product } from './product-grid.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/blocks/product-grid-01/index.js

@@ -1 +1 @@
-export { ProductGrid01, default } from './product-grid';
+export { ProductGrid01, default } from './product-grid.js';

package/dist/blocks/product-grid-01/product-grid.d.ts

@@ -1,5 +1,5 @@
-import { type ProductMarkProps } from '../../components/ui/product-mark';
-import { type HeadingLevel } from '../../components/ui/section';
+import { type ProductMarkProps } from '../../components/ui/product-mark.js';
+import { type HeadingLevel } from '../../components/ui/section.js';
 /**
  * One product in the grid, as the row draws it.
  *
@@ -27,6 +27,24 @@ export type ProductGrid01Product = {
     pack?: ProductMarkProps['pack'];
     /** One line about what the product is. */
     tagline: string;
+    /**
+     * A second line, about **this product** rather than about the set.
+     *
+     * `tagline` and this are different claims and only one of them belongs on the
+     * row. A tagline is the shortest true thing about a member, and it reads the
+     * same in every row of a set. This is a sentence that is true of *this* product
+     * and would be false or vacuous beside its neighbours, which is the test for
+     * whether it belongs here. The company site's five products each carried one
+     * ("Autonomous software creation, supervised by you."), and folding them into the
+     * tagline would have been a copy edit rather than a fix, so they were dropped and
+     * reported instead.
+     *
+     * Rendered only when passed, so a row without one draws exactly what it drew
+     * before the field existed. See `ProductGrid01`'s JSDoc for which of the two
+     * levels a sentence belongs at, because the answer is a fact about the sentence
+     * and not a preference.
+     */
+    detail?: string;
     /**
      * Where the row goes. Rendered as a native anchor's `href`, so the row is a
      * link with the browser's own affordances rather than a click handler.
@@ -101,9 +119,23 @@ export type ProductGrid01Props = {
  * it, and middle-click opens it in a new tab. The mark is `aria-hidden` inside
  * it, so the link is announced once, by name, rather than as a shape and a word.
  *
- * A row carries one line of tagline. A second line is a second paragraph and
- * belongs above the grid in `description`, where it applies to the set rather
- * than to one member of it.
+ * **Which level a sentence belongs at is a fact about the sentence, and this
+ * settles it.** There are two levels and both are right, for different claims:
+ *
+ * - `description` is about **the set**. "Five products, one platform." or "Every
+ *   one of these runs on the same runtime." A sentence that would be equally true
+ *   if you deleted any one row belongs here, and nowhere else.
+ * - `Product.detail` is about **this member**. "Quantitative trading research for
+ *   the Indian market, the factory's newest build." A sentence that is false, or
+ *   vacuous, beside its neighbours belongs on the row.
+ *
+ * The test is whether the sentence survives its neighbours. A tagline reads the
+ * same in every row, so it is a tagline; the company site's five products each
+ * carried a sentence true of one and not of the four beside it, and the earlier
+ * version of this note told a caller to fold those into `description`, where they
+ * would have claimed to be about all five at once. That advice lost three
+ * published sentences in a migration rather than stating the choice, so both levels
+ * exist and the question above is the one to ask.
  *
  * It is a server Component: no hook, no state, no client code and no mode. The
  * mark resolves its colour through the cascade, so a page that renders this in a

package/dist/blocks/product-grid-01/product-grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"product-grid.d.ts","sourceRoot":"","sources":["../../../src/blocks/product-grid-01/product-grid.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,gBAAgB,EAAE,MAAM,kCAAkC,CAAA;AACrF,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAExF;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAA;IAC/B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAA;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,aAAa,CAAC,EAC5B,OAAO,EACP,KAAK,EACL,WAAW,EACX,QAAQ,EACR,OAAO,EACP,YAAmB,GACpB,EAAE,kBAAkB,sCAqCpB;AAED,eAAe,aAAa,CAAA"}
+{"version":3,"file":"product-grid.d.ts","sourceRoot":"","sources":["../../../src/blocks/product-grid-01/product-grid.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,gBAAgB,EAAE,MAAM,kCAAkC,CAAA;AACrF,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAExF;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAA;IAC/B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAA;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,aAAa,CAAC,EAC5B,OAAO,EACP,KAAK,EACL,WAAW,EACX,QAAQ,EACR,OAAO,EACP,YAAmB,GACpB,EAAE,kBAAkB,sCA8CpB;AAED,eAAe,aAAa,CAAA"}

package/dist/blocks/product-grid-01/product-grid.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { ProductMark } from '../../components/ui/product-mark';
-import { Section, SectionHeading } from '../../components/ui/section';
+import { ProductMark } from '../../components/ui/product-mark.js';
+import { Section, SectionHeading } from '../../components/ui/section.js';
 /**
  * A set of products as a stack of hairline rows: a two-part mark, a name, one
  * tagline and a destination per row.
@@ -35,9 +35,23 @@ import { Section, SectionHeading } from '../../components/ui/section';
  * it, and middle-click opens it in a new tab. The mark is `aria-hidden` inside
  * it, so the link is announced once, by name, rather than as a shape and a word.
  *
- * A row carries one line of tagline. A second line is a second paragraph and
- * belongs above the grid in `description`, where it applies to the set rather
- * than to one member of it.
+ * **Which level a sentence belongs at is a fact about the sentence, and this
+ * settles it.** There are two levels and both are right, for different claims:
+ *
+ * - `description` is about **the set**. "Five products, one platform." or "Every
+ *   one of these runs on the same runtime." A sentence that would be equally true
+ *   if you deleted any one row belongs here, and nowhere else.
+ * - `Product.detail` is about **this member**. "Quantitative trading research for
+ *   the Indian market, the factory's newest build." A sentence that is false, or
+ *   vacuous, beside its neighbours belongs on the row.
+ *
+ * The test is whether the sentence survives its neighbours. A tagline reads the
+ * same in every row, so it is a tagline; the company site's five products each
+ * carried a sentence true of one and not of the four beside it, and the earlier
+ * version of this note told a caller to fold those into `description`, where they
+ * would have claimed to be about all five at once. That advice lost three
+ * published sentences in a migration rather than stating the choice, so both levels
+ * exist and the question above is the one to ask.
  *
  * It is a server Component: no hook, no state, no client code and no mode. The
  * mark resolves its colour through the cascade, so a page that renders this in a
@@ -46,6 +60,6 @@ import { Section, SectionHeading } from '../../components/ui/section';
 export function ProductGrid01({ eyebrow, title, description, products, caption, headingLevel = 'h2', }) {
     if (products.length === 0)
         return null;
-    return (_jsxs(Section, { children: [title ? (_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-12" })) : null, _jsx("ul", { "data-slot": "product-grid", className: "flex flex-col", children: products.map((product) => (_jsx("li", { "data-slot": "product-grid-row", className: "border-b first:border-t", children: _jsxs("a", { href: product.href, rel: product.newTab ? 'noopener noreferrer' : undefined, target: product.newTab ? '_blank' : undefined, className: "hover:bg-accent/50 focus-visible:ring-ring flex flex-col gap-1 px-2 py-4 transition-colors duration-fast ease-out sm:flex-row sm:items-baseline sm:gap-6 focus-visible:ring-[3px] focus-visible:outline-none", children: [_jsx("span", { className: "flex shrink-0 items-center sm:w-64", children: _jsx(ProductMark, { id: product.id, name: product.name, pack: product.pack, size: "md" }) }), _jsx("span", { className: "text-muted-foreground text-pretty text-sm", children: product.tagline })] }) }, product.id))) }), caption ? _jsx("p", { className: "text-muted-foreground mt-6 text-pretty text-sm", children: caption }) : null] }));
+    return (_jsxs(Section, { children: [title ? (_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-12" })) : null, _jsx("ul", { "data-slot": "product-grid", className: "flex flex-col", children: products.map((product) => (_jsx("li", { "data-slot": "product-grid-row", className: "border-b first:border-t", children: _jsxs("a", { href: product.href, rel: product.newTab ? 'noopener noreferrer' : undefined, target: product.newTab ? '_blank' : undefined, className: "hover:bg-accent/50 focus-visible:ring-ring flex flex-col gap-1 px-2 py-4 transition-colors duration-fast ease-out sm:flex-row sm:items-baseline sm:gap-6 focus-visible:ring-[3px] focus-visible:outline-none", children: [_jsx("span", { className: "flex shrink-0 items-center sm:w-64", children: _jsx(ProductMark, { id: product.id, name: product.name, pack: product.pack, size: "md" }) }), _jsxs("span", { className: "flex min-w-0 flex-col gap-0.5", children: [_jsx("span", { className: "text-muted-foreground text-pretty text-sm", children: product.tagline }), product.detail ? (_jsx("span", { className: "text-pretty text-sm", children: product.detail })) : null] })] }) }, product.id))) }), caption ? _jsx("p", { className: "text-muted-foreground mt-6 text-pretty text-sm", children: caption }) : null] }));
 }
 export default ProductGrid01;

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

@@ -0,0 +1,3 @@
+export { Project01, default } from './project.js';
+export type { ProjectState, Project01Owner, Project01Figure, Project01Stage, Project01Props, } from './project.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/project-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAK9C,YAAY,EACV,YAAY,EACZ,cAAc,EACd,eAAe,EACf,cAAc,EACd,cAAc,GACf,MAAM,WAAW,CAAA"}

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

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

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

@@ -0,0 +1,323 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * The five states a project can be in.
+ *
+ * Five, and the words for them are the caller's rather than the type's, so this
+ * list is a set of positions rather than a vocabulary. That is the whole reason
+ * `stateLabel` exists and why it is required: four NaniSoft products each track
+ * this differently, and between them they use eleven words for these five
+ * positions, where "In progress" and "Active" and "Running" are one position and
+ * "Shipped" and "Done" and "Delivered" are another.
+ *
+ * A sixth state would be the one that splits a position that does not need
+ * splitting: `at-risk` over `blocked`, or a `live` that is not `complete`. Each
+ * one is a colour a reader has to learn and a word a maintainer has to keep true,
+ * and a ladder with more rungs than positions is how a status column stops being
+ * readable. What the caller wants to say about a project is `summary` and the
+ * caller's own `stateLabel`; the five below are the positions a project is in.
+ */
+export type ProjectState = 'planning' | 'active' | 'blocked' | 'complete' | 'archived';
+/**
+ * One person: the name, the portrait where there is one, and a destination where
+ * the consumer publishes one.
+ *
+ * The same shape `Team01` takes for a person, repeated rather than imported for
+ * the reason that file gives: a Block that is not a card grid is not a place a
+ * person's identity belongs, and a caller drawing a person in a project header and
+ * the same person on a team page is better served by one field name than by a type
+ * exported from whichever Block they found first.
+ */
+export type Project01Owner = {
+    /** The person's own name, as they publish it. */
+    name: string;
+    /**
+     * The portrait, with the name the initials come from.
+     *
+     * A name rather than a string, because an `Avatar` with no fallback is an empty
+     * circle for exactly as long as the image takes to arrive and forever if it
+     * never does.
+     */
+    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;
+    };
+    /** Where the person 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 person's name tells a reader nothing about what
+     * activating it will do, which is the same defect `Contact01` refuses. The
+     * sentence saying that following the link is a thing you can do belongs to the
+     * caller, because the destination is theirs.
+     */
+    hrefLabel?: string;
+};
+/**
+ * One figure about the project: what it measures, what it reads, and the change
+ * against the last reading.
+ *
+ * `value` is a node and not a number, for the reason `MetricProps.value` gives: a
+ * caller's figure is very often a value it formatted itself, with its own grouped
+ * thousands, its own currency and its own unit, and a `number` here would push
+ * that formatting onto every call site twice.
+ */
+export type Project01Figure = {
+    /** 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;
+};
+/**
+ * One stage of the project: what it is called, when it happened or is due, and
+ * where it stands.
+ *
+ * `name` is the anchor and it is what the rail is scanned for, so it is kept to
+ * the words a reader would use in conversation. The moment and the state are
+ * separate fields because they are separate facts, and a stage that has a date and
+ * no state is a real one.
+ */
+export type Project01Stage = {
+    /** A stable key for the stage. */
+    id: string;
+    /** What the stage is called, in the caller's own words. */
+    name: string;
+    /**
+     * When the stage happened, or is due.
+     *
+     * Epoch milliseconds, a `Date`, or a string the platform parses, and Prism
+     * hands it to `RelativeTime` untouched, so the reading a reader sees is the
+     * platform's in their own locale. See the Block JSDoc for why this Block
+     * formats nothing and takes the sentence from the caller instead.
+     */
+    at?: number | string;
+    /**
+     * Where the stage stands.
+     *
+     * `done` is behind the reader, `current` is where they are, and `upcoming` is
+     * ahead. A stage's state is a position in a sequence rather than a judgement
+     * about the project, which is why this list is three and `ProjectState` is five:
+     * a project can be blocked, and a stage in a sequence cannot, because a blocked
+     * stage is a fact about the project and belongs in its state.
+     */
+    state: 'done' | 'current' | 'upcoming';
+    /**
+     * The words for that state, in the product's own vocabulary.
+     *
+     * Required whenever a stage carries a state, and every stage does, so the run
+     * throws without it. The mark `Steps` draws is a shape, and a shape is not a
+     * sentence a reader can act on: "Shipped", "In review", "Signed off" and
+     * "Delivered" are the same position in four products' words.
+     */
+    stateLabel?: string;
+};
+/**
+ * The props a Project01 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 stage, no figure, no date and not one word of the sentence that says
+ * where a project is. The absence of the project itself is the sharpest version
+ * of the rule, because a project header drawn with a name in it is the single
+ * easiest thing in this package to write by accident and the single most likely
+ * to be somebody else's project.
+ *
+ * `progress` and `progressLabel` are a union rather than two optionals, and the
+ * reason is the one the authoring contract states: a prop that is required in one
+ * shape and forbidden in another cannot be an optional. The bar's own value is a
+ * number and a number is not a sentence, so the words beside it are the caller's,
+ * and a caller who has a fill and no words for it has a bar that announces a bare
+ * figure meaning whatever the reader assumes it is a percentage of.
+ */
+export type Project01Props = {
+    /**
+     * The project's own name.
+     *
+     * Required, and it is the section heading rather than a field inside the
+     * surface, because a project detail 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 fields.
+     */
+    name: string;
+    /** One or two sentences about what this project is, under the name. */
+    summary?: ReactNode;
+    /** Where the project stands. See `ProjectState`. */
+    state: ProjectState;
+    /**
+     * The words for that state, in the product's own vocabulary.
+     *
+     * Required and not derived from `state`, for the reason `ProjectState` gives:
+     * the state is a colour and the words are a claim, and four products use eleven
+     * words for five positions between them.
+     */
+    stateLabel: (state: ProjectState) => string;
+    /** Who owns it. Omit it for a project nobody owns, which is a real state. */
+    owner?: Project01Owner;
+    /** When the project opened. Handed to `RelativeTime` untouched. */
+    startsAt?: number | string;
+    /** When it is due to close. Handed to `RelativeTime` untouched. */
+    endsAt?: number | string;
+    /**
+     * The sentence for a moment in the span, given the moment.
+     *
+     * Optional, and its absence is a legitimate state rather than a gap: a project
+     * with a start and no end is an open project, and a project whose reader wants
+     * no relative words at all is a printed report. When it is given, it is the
+     * caller's words beside the platform's absolute reading, which is the one
+     * arrangement in this package where a date is neither formatted nor left bare.
+     */
+    dateLabel?: (value: number | string) => string;
+    /** The figures, in the order a reader should meet them. */
+    figures?: Project01Figure[];
+    /**
+     * The stages, in the order the project runs them.
+     *
+     * Order is the caller's because it is a claim about a sequence, and the rail
+     * this Block composes says "steps" to every reader and to every crawler, so a
+     * list in an order the project does not have is a wrong diagram rather than a
+     * layout problem.
+     */
+    stages?: Project01Stage[];
+    /**
+     * The controls that act on the project as a whole: pause, archive, cancel, open
+     * it somewhere.
+     *
+     * A slot and not a set of named buttons, because which controls a project has is
+     * the caller's fact: an estate that can archive a project and a pipeline that
+     * can cancel one share a header and nothing else. A Block that drew a pause
+     * control would hand every consumer a permission its product may not grant.
+     */
+    actions?: ReactNode;
+    /**
+     * Whether the facts sit in an aside beside the body or above it.
+     *
+     * `stacked` is the default because a project detail is read top to bottom, and
+     * the facts above the fold are the two a reader checks first. `split` puts the
+     * state, the owner, the span and the controls in a narrow column at the leading
+     * edge and gives the figures and the stages the width, which is right on a wide
+     * page where the reader is comparing this project against another one in the same
+     * session, and wrong on a phone where the main column would be at half the
+     * reading measure.
+     *
+     * The two facts and the controls are in one place in both arrangements, so a
+     * caller who switches `layout` does not move a single control: what changes is
+     * the column they sit in and nothing else.
+     *
+     * There is no third arrangement that changes Prism's drawing rather than this
+     * Block's spacing, because `className` is layout only.
+     */
+    layout?: 'stacked' | 'split';
+    /** Heading level for the section heading. See `HeadingLevel`. */
+    headingLevel?: HeadingLevel;
+    /** Layout only, exactly as on every Block. Changing a Prism-owned visual
+     * property from here is prohibited. */
+    className?: 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 Block 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.
+     *
+     * Required, and a function rather than a template for the reason
+     * `RelativeTime` gives in full: a bar is a percentage of something this
+     * Block cannot see, and forty per cent of a migration is not the same fact
+     * as forty per cent of a rollout. The name is in the argument because a
+     * project with two bars on one page is a page a reader has to be told which
+     * bar is which, and this is the cheap half of the answer: the caller has
+     * both names and this one has been passed.
+     */
+    progressLabel: (value: number, project: string) => string;
+} | {
+    /** No fill, so no sentence is owed and none is accepted. */
+    progress?: never;
+    progressLabel?: never;
+});
+/**
+ * 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 declare function Project01({ name, summary, state, stateLabel, owner, startsAt, endsAt, dateLabel, figures, stages, actions, progress, progressLabel, layout, headingLevel, className, }: Project01Props): import("react").JSX.Element;
+export default Project01;
+//# sourceMappingURL=project.d.ts.map

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

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