@atelic-action/artifact 5.0.0 → 5.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/artifact",
-	"version": "5.0.0",
+	"version": "5.1.0",
 	"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.5.0",
 		"lucide-react": "^1.23.0",
 		"react": "^19.0.0"
 	},
 	"devDependencies": {
-		"@atelic-action/ui": "^3.4.0",
+		"@atelic-action/ui": "^3.5.0",
 		"@biomejs/biome": "^2.0.0",
 		"@playwright/test": "^1.60.0",
 		"@sentry/react": "^10.0.0",

package/src/documents/Topic.tsx

@@ -133,6 +133,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 +245,7 @@ export type ReadInnerBlock =
 	| ReadTable
 	| ReadBar
 	| ReadScale
+	| ReadSpeed
 	| ReadFindings
 	| ReadStats
 	| ReadColumns
@@ -292,6 +371,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 +516,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

@@ -1118,6 +1118,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";