@atelic-action/artifact 5.0.0 → 5.1.1

package/README.md

@@ -26,7 +26,7 @@ Every export of the package, all from the one entry, `@atelic-action/artifact`.
 | `ReadAccess`, `ReadTier`, `ReadSection`, `ReadChange`, `ReadRecommendation`, `ReadMarkets`, `ReadMarketRow`, `ReadRented`, `ReadStep`, `ReadPlan`, `ReadClose`, `ReadPrint`, `ReadLink`, `ReadParagraph` | The shapes a read's content is written in. `ReadSection` is a `ReadTopic` plus `gist`, `before`, `changes`, and `recommend`; its `why`, a finding's `body`, a market row's `read`, and the rented `text` take a paragraph (a string, or runs of text and links) as well as a node, so a routine can write a read as JSON | none |
 | `Topic` | The section card on its own: the trade name linked to its definition, the one liner, the grade, the why line, the blocks, and the sources, with an `extra` slot after the blocks. The read renders every section through it | `/the-read` |
 | `ratingCell` | A star rating table cell for a `table` block, sorted by its figure | `/the-read` |
-| `ReadTopic`, `ReadBlock`, `ReadInnerBlock`, `ReadChecks`, `ReadTable`, `ReadBar`, `ReadScale`, `ReadStats`, `ReadColumns`, `ReadFindings`, `ReadShots`, `ReadMore`, `ReadBullet`, `ReadSource`, `ReadMark`, `ReadCell`, `ReadSorted`, `ReadTone` | The shapes a section card and its blocks are written in | none |
+| `ReadTopic`, `ReadBlock`, `ReadInnerBlock`, `ReadChecks`, `ReadTable`, `ReadBar`, `ReadScale`, `ReadStats`, `ReadColumns`, `ReadFindings`, `ReadShots`, `ReadMore`, `ReadBullet`, `ReadSource`, `ReadMark`, `ReadCell`, `ReadSorted`, `ReadTone` | The shapes a section card and its blocks are written in. In a `table` block, a cell past the first given as `null` is empty: it reaches ui's `DataTable` untouched, draws its short gray rule, reads the column's `emptyLabel` (or "None") to a screen reader, and sorts last either way, while a typed dash stays content, since it can mean unchanged. A `none` mark draws the same rule with its own `text` but sorts as a mark, lowest of the four, and the markets table's unread grade draws it too | none |
 | `WriteupGrade`, `WriteupPerson`, `WriteupShot` | The grade letter, the sign off person, and the owner's screen, shared by every document, all three re exported from ui under ui's names | none |
 | `Report`, `ReportProps` | The monthly page: the four questions, the seven grades now and before, the sign off, on one letter sheet | `/report` |
 | `ReportLead`, `ReportLeads`, `ReportGradeRow` | The shapes a monthly page's content is written in | none |
@@ -48,7 +48,7 @@ What a document is built from stays in `@atelic-action/ui`, and this package imp
 bun add @atelic-action/artifact @atelic-action/ui
 ```
 
-Peer dependencies: `@atelic-action/ui` at `^3.4.0`, `react` at `^19.0.0`, and `lucide-react` at `^1.23.0`. The package ships TSX and CSS as source, compiled inside the site's own Vite like ui's; a site whose `vite.config.ts` is one `artifactConfig` call from `@atelic-action/ui/vite` needs nothing more, for the build, the prerender, and the dev server alike. The default labels a document sets live in the document: the read's `readLabels` and the sealed document's gate copy are overridden through props, and the monthly page's four questions are fixed on purpose, since they are its contract with the Statement of Work.
+Peer dependencies: `@atelic-action/ui` at `^3.9.1`, `react` at `^19.0.0`, and `lucide-react` at `^1.23.0`. The package ships TSX and CSS as source, compiled inside the site's own Vite like ui's; a site whose `vite.config.ts` is one `artifactConfig` call from `@atelic-action/ui/vite` needs nothing more, for the build, the prerender, and the dev server alike. The default labels a document sets live in the document: the read's `readLabels` and the sealed document's gate copy are overridden through props, and the monthly page's four questions are fixed on purpose, since they are its contract with the Statement of Work.
 
 ```tsx
 import { TheRead } from "@atelic-action/artifact";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/artifact",
-	"version": "5.0.0",
+	"version": "5.1.1",
 	"description": "The composed documents the Atelic practice hands or sends a business (the read, the monthly page, the note, the first call sheet, and the sealed document), built from the pieces in @atelic-action/ui",
 	"type": "module",
 	"license": "MIT",
@@ -37,12 +37,12 @@
 		"format": "biome format . --write"
 	},
 	"peerDependencies": {
-		"@atelic-action/ui": "^3.4.0",
+		"@atelic-action/ui": "^3.9.1",
 		"lucide-react": "^1.23.0",
 		"react": "^19.0.0"
 	},
 	"devDependencies": {
-		"@atelic-action/ui": "^3.4.0",
+		"@atelic-action/ui": "^3.9.1",
 		"@biomejs/biome": "^2.0.0",
 		"@playwright/test": "^1.60.0",
 		"@sentry/react": "^10.0.0",

package/src/documents/TheRead.tsx

@@ -454,8 +454,8 @@ function Markets({ markets }: { markets: ReadMarkets }) {
 											</>
 										) : (
 											<>
-												<span className="op-sr-only">{`${column}, not read`}</span>
-												<span className="op-dash" aria-hidden="true" />
+												<span className="data-table-empty" aria-hidden="true" />
+												<span className="data-table-empty-label">{`${column}, not read`}</span>
 											</>
 										)}
 									</td>

package/src/documents/Topic.tsx

@@ -82,7 +82,15 @@ export interface ReadSorted {
 	sort: number | string;
 }
 
-export type ReadCell = ReactNode | ReadMark | ReadSorted;
+/**
+ * A table cell: a node, a mark, or a sorted pair. `null` past the first
+ * column (which names the row, so is never empty) is an empty cell,
+ * passed to the shared table untouched: it draws the table's short gray rule,
+ * reads its column's `emptyLabel` to a screen reader, and sorts last either
+ * way. A typed dash is a string and stays content, since a dash can mean
+ * "unchanged".
+ */
+export type ReadCell = ReactNode | ReadMark | ReadSorted | null;
 
 function isMark(cell: ReadCell): cell is ReadMark {
 	return typeof cell === "object" && cell !== null && "mark" in cell;
@@ -112,6 +120,8 @@ export interface ReadTable extends BlockBase {
 		firstSort?: "asc" | "desc";
 		/** The column hugs its content, for a swatch or a mark. */
 		fit?: boolean;
+		/** What a screen reader hears for an empty cell in this column; defaults to "None". */
+		emptyLabel?: string;
 	}>;
 	rows: Array<{ cells: ReadCell[]; tone?: ReadTone }>;
 	/** The sort the table opens in. */
@@ -133,6 +143,84 @@ export interface ReadScale extends BlockBase {
 	readings: ThresholdReading[];
 }
 
+/** One run of Google's phone test: the five figures its report leads with, as the API returns them. */
+export interface ReadSpeedRun {
+	/** The performance score, 0 to 100. */
+	score: number;
+	/** First Contentful Paint, in milliseconds. */
+	fcpMs: number;
+	/** Largest Contentful Paint, in milliseconds. */
+	lcpMs: number;
+	/** Total Blocking Time, in milliseconds. */
+	tbtMs: number;
+	/** Cumulative Layout Shift, unitless. */
+	cls: number;
+}
+
+/** A column of the speed table: its heading and the explainer behind its info icon. */
+export interface ReadSpeedColumn {
+	label: string;
+	hint: string;
+}
+
+/** The words the speed block uses, for a document in another register. */
+export interface ReadSpeedLabels {
+	/** What a screen reader hears before a run's grade letter. */
+	gradeWord: string;
+	score: ReadSpeedColumn;
+	firstPaint: ReadSpeedColumn;
+	mainContent: ReadSpeedColumn;
+	frozen: ReadSpeedColumn;
+	shift: ReadSpeedColumn;
+	/** The small callout over the table: why there are three runs. */
+	whyThreeTitle: string;
+	whyThree: string;
+	/** The words before the date the runs were made, e.g. "These ran on". */
+	ranOn: string;
+}
+
+export const readSpeedLabels: ReadSpeedLabels = {
+	gradeWord: "Grade",
+	score: {
+		label: "Score",
+		hint: "Google’s own mark for the page, out of 100, from the four measures beside it. We grade it the way a school grades: 90 is an A, 80 a B, 60 a C, and under 60 a D.",
+	},
+	firstPaint: {
+		label: "First paint",
+		hint: "The first moment anything appears on the screen. Google calls it First Contentful Paint and draws its line for good at 1.8 s.",
+	},
+	mainContent: {
+		label: "Main content",
+		hint: "When the biggest thing on the screen, usually the headline or the photo behind it, has arrived. Google calls it Largest Contentful Paint and draws its line at 2.5 s.",
+	},
+	frozen: {
+		label: "Frozen for",
+		hint: "How long the page ignores a tap or a scroll while its scripts run. Google calls it Total Blocking Time and draws its line at 0.2 s.",
+	},
+	shift: {
+		label: "Layout shift",
+		hint: "How much the page jumps around while it loads, so a button moves as a thumb reaches for it. Google calls it Cumulative Layout Shift and draws its line at 0.1.",
+	},
+	whyThreeTitle: "Why three runs.",
+	whyThree:
+		"A single run swings with Google’s own servers and the moment it ran, so we run the test three times a minute apart. The middle score is the reading; the best and the worst are the range.",
+	ranOn: "These ran on",
+};
+
+/**
+ * Google's phone test: three runs, the five figures each, listed best score
+ * first; a small callout over the table says the middle one is the reading. The letter
+ * beside each score and the row's tone follow the score, graded the way a
+ * school grades (FOOTPRINT.md). The figures are the snapshot's, never typed.
+ */
+export interface ReadSpeed extends BlockBase {
+	kind: "speed";
+	runs: ReadSpeedRun[];
+	/** The day the runs were made, ISO, for the callout under the table. */
+	ran?: string;
+	labels?: Partial<ReadSpeedLabels>;
+}
+
 /** A few numbers worth reading first, each with its period and its comparisons. */
 export interface ReadStats extends BlockBase {
 	kind: "stats";
@@ -167,6 +255,7 @@ export type ReadInnerBlock =
 	| ReadTable
 	| ReadBar
 	| ReadScale
+	| ReadSpeed
 	| ReadFindings
 	| ReadStats
 	| ReadColumns
@@ -222,8 +311,8 @@ function Mark({ cell }: { cell: ReadMark }) {
 	if (cell.mark === "none") {
 		return (
 			<span className="op-mark-cell" data-tone="muted">
-				<span className="op-dash" aria-hidden="true" />
-				<span className="op-sr-only">{cell.text}</span>
+				<span className="data-table-empty" aria-hidden="true" />
+				<span className="data-table-empty-label">{cell.text}</span>
 			</span>
 		);
 	}
@@ -292,6 +381,68 @@ function Table({ block }: { block: ReadTable }) {
 	);
 }
 
+/** The letter for a score on a 100 point scale, graded the way a school grades. */
+function scoreGrade(score: number): WriteupGrade {
+	if (score >= 90) return "a";
+	if (score >= 80) return "b";
+	if (score >= 60) return "c";
+	return "d";
+}
+
+const gradeTone: Record<WriteupGrade, ReadTone> = { a: "good", b: "info", c: "warn", d: "bad" };
+
+const seconds = (ms: number) => `${(ms / 1000).toFixed(1)} s`;
+const shift = (cls: number) => (cls < 0.005 ? "0" : cls.toFixed(2));
+
+function Speed({ block }: { block: ReadSpeed }) {
+	const labels = { ...readSpeedLabels, ...block.labels };
+	const sorted = [...block.runs].sort((a, b) => b.score - a.score);
+	const rows = sorted.map((run) => {
+		const grade = scoreGrade(run.score);
+		return {
+			tone: gradeTone[grade],
+			cells: [
+				<span className="op-speed-score" key="score">
+					<span className="op-sr-only">{`${labels.gradeWord} ${gradeLabel[grade]}`}</span>
+					<span aria-hidden="true">
+						<GradeChip grade={grade} />
+					</span>
+					{run.score}
+				</span>,
+				seconds(run.fcpMs),
+				seconds(run.lcpMs),
+				seconds(run.tbtMs),
+				shift(run.cls),
+			],
+		};
+	});
+	const column = (c: ReadSpeedColumn) => ({
+		label: c.label,
+		hint: c.hint,
+		align: "right" as const,
+	});
+	return (
+		<>
+			<Callout tone="muted" title={labels.whyThreeTitle} className="op-speed-why">
+				{labels.whyThree}
+				{block.ran && ` ${labels.ranOn} ${block.ran}.`}
+			</Callout>
+			<Block className="op-table op-speed" block={block}>
+				<DataTable
+					columns={[
+						column(labels.score),
+						column(labels.firstPaint),
+						column(labels.mainContent),
+						column(labels.frozen),
+						column(labels.shift),
+					]}
+					rows={rows}
+				/>
+			</Block>
+		</>
+	);
+}
+
 /** A string or runs of text and links, the shape JSON content arrives in; a node of elements is anything else. */
 export function isRuns(value: unknown): value is ArtifactParagraph {
 	if (typeof value === "string") return true;
@@ -375,6 +526,8 @@ function TopicBlock({ block }: { block: ReadBlock }) {
 			);
 		case "table":
 			return <Table block={block} />;
+		case "speed":
+			return <Speed block={block} />;
 		case "bar":
 			return (
 				<Block className="op-bar" block={block}>

package/src/documents/documents.css

@@ -1069,13 +1069,6 @@
 		color: var(--op-ink);
 		font-weight: 600;
 	}
-	.atelic-ui .op-dash {
-		display: inline-block;
-		width: 14px;
-		height: 1.5px;
-		vertical-align: 0.3em;
-		background: var(--neutral-300);
-	}
 
 	/* The blocks are the shared package's components. These are the read's
 	   sizes for them. */
@@ -1118,6 +1111,58 @@
 	.atelic-ui .op-table td:has(.op-wrap) {
 		white-space: normal;
 	}
+	/* the phone test: a small grade chip before each run's score, at the
+	   column's left edge on a wide screen */
+	.atelic-ui .op-speed .op-grade {
+		display: inline-grid;
+		place-items: center;
+		width: 22px;
+		height: 22px;
+		margin: 0 8px 0 0;
+		padding: 0;
+		font-size: 12px;
+	}
+	.atelic-ui .op-speed-score {
+		display: inline-flex;
+		align-items: center;
+		font-variant-numeric: tabular-nums;
+	}
+	.atelic-ui .op-speed tbody th {
+		white-space: nowrap;
+		font-weight: 600;
+	}
+	@media print, (min-width: 721px) {
+		.atelic-ui .op-speed-score {
+			display: flex;
+			justify-content: space-between;
+			width: 100%;
+		}
+	}
+	/* the why over the table: one small line, the title run into the body */
+	.atelic-ui .op-speed-why {
+		margin-top: 12px;
+		font-size: 13px;
+		line-height: 1.45;
+		color: var(--op-ink-soft);
+	}
+	.atelic-ui .op-speed-why .callout-icon {
+		width: 14px;
+		height: 14px;
+		margin-top: 2px;
+	}
+	.atelic-ui .op-speed-why .callout-title,
+	.atelic-ui .op-speed-why .callout-body {
+		display: inline;
+		font-size: inherit;
+		line-height: inherit;
+	}
+	.atelic-ui .op-speed-why .callout-title {
+		font-weight: 600;
+		color: var(--op-ink);
+	}
+	.atelic-ui .op-speed-why .callout-title::after {
+		content: " ";
+	}
 	.atelic-ui .op-mark-cell {
 		display: inline-flex;
 		align-items: center;

package/src/documents/index.ts

@@ -25,10 +25,14 @@ export {
 	type ReadShots,
 	type ReadSorted,
 	type ReadSource,
+	type ReadSpeed,
+	type ReadSpeedLabels,
+	type ReadSpeedRun,
 	type ReadStats,
 	type ReadTable,
 	type ReadTone,
 	type ReadTopic,
 	ratingCell,
+	readSpeedLabels,
 	Topic,
 } from "./Topic";