@atelic-action/artifact 4.2.0 → 5.0.0

package/src/documents/{Writeup.tsx → Topic.tsx}

@@ -5,9 +5,7 @@ import {
 	newTabProps,
 	Runs,
 	Shot,
-	SignOff,
 	type WriteupGrade,
-	type WriteupPerson,
 	type WriteupShot,
 } from "@atelic-action/ui/artifact";
 import {
@@ -18,7 +16,6 @@ import {
 	type ColumnChartGroup,
 	DataTable,
 	Disclosure,
-	ReportCard,
 	StackedBar,
 	type StackedBarSegment,
 	type StatItem,
@@ -31,28 +28,25 @@ import {
 import { ArrowUpRight, CircleAlert, CircleCheck, CircleX, Star } from "lucide-react";
 import type { ReactNode } from "react";
 
-export type { WriteupGrade, WriteupPerson, WriteupShot } from "@atelic-action/ui/artifact";
-
 /**
- * The writeup: the graded document an owner gets. It is a web page first: an
- * overview that links into every section, then the three tiers, each section
- * a card of small blocks and a line of sources that open the tools the
- * reading came from. Print is the same page with the chrome dropped and the
- * type brought down, flowing across letter pages; nothing is clipped.
+ * The section card: the trade name linked to its definition, the one liner,
+ * the grade, the why line, the blocks, and the sources at the foot. The read
+ * renders every section through it, handing what the card itself does not
+ * know (today and after, what we recommend) as `extra`, set after the blocks
+ * and before the sources.
  *
  * Every block is a component from @atelic-action/ui (the checklist, the
  * sortable table, the charts, the stat row, the callout, the disclosure);
- * this file owns only the document: the overview, the tiers, the section
- * card, the markets table, and the close. Its skeleton is the practice's
- * FOOTPRINT.md, and what it says follows the pitch surface rules
+ * this file owns only the card around them and the shapes a block's content
+ * is written in. What it says follows the pitch surface rules
  * (Brand/voice.md): the trade's term linked to its definition, or plain
  * words, and no term an owner would have to look up.
  */
 
 /** How a mark, a bar segment, or a zone reads; the shared package's tones. */
-export type WriteupTone = Tone;
+export type ReadTone = Tone;
 
-export interface WriteupBullet {
+export interface ReadBullet {
 	/** The point, in a full sentence. The icon sits beside it. */
 	lead: string;
 	/** The one explainer that says why it matters: a node, or a paragraph of runs when the content arrives as JSON. */
@@ -60,19 +54,19 @@ export interface WriteupBullet {
 	/** A win the owner already has: marked good. Everything else reads as needing work. */
 	win?: boolean;
 	/** Overrides the tone, e.g. "info" for something not yet read. */
-	tone?: WriteupTone;
+	tone?: ReadTone;
 	/** Sets the finding apart on a tinted ground, for something missing or owed. */
 	box?: boolean;
 }
 
 /** A place a reading came from: the tool, opened in a new tab when it has an address. */
-export interface WriteupSource {
+export interface ReadSource {
 	label: string;
 	href?: string;
 }
 
 /** A yes or no cell: the icon alone, with the text read to a screen reader. A figure a reader needs (a rank, a count) is a column of its own. */
-export interface WriteupMark {
+export interface ReadMark {
 	mark: "good" | "warn" | "bad" | "none";
 	/** What the mark means, e.g. "Loads" or "Page Not Found"; always read to a screen reader. */
 	text: string;
@@ -83,14 +77,14 @@ export interface WriteupMark {
 }
 
 /** A cell whose display is not what it sorts by, e.g. "4.8" beside a star. */
-export interface WriteupSorted {
+export interface ReadSorted {
 	display: ReactNode;
 	sort: number | string;
 }
 
-export type WriteupCell = ReactNode | WriteupMark | WriteupSorted;
+export type ReadCell = ReactNode | ReadMark | ReadSorted;
 
-function isMark(cell: WriteupCell): cell is WriteupMark {
+function isMark(cell: ReadCell): cell is ReadMark {
 	return typeof cell === "object" && cell !== null && "mark" in cell;
 }
 
@@ -101,13 +95,13 @@ interface BlockBase {
 }
 
 /** A short list of pass or fail checks, the basics a section rests on. */
-export interface WriteupChecks extends BlockBase {
+export interface ReadChecks extends BlockBase {
 	kind: "checks";
 	items: ChecklistItem[];
 }
 
 /** A table: the first column names the row, the rest are short facts or marks. */
-export interface WriteupTable extends BlockBase {
+export interface ReadTable extends BlockBase {
 	kind: "table";
 	columns: Array<{
 		label: string;
@@ -119,19 +113,19 @@ export interface WriteupTable extends BlockBase {
 		/** The column hugs its content, for a swatch or a mark. */
 		fit?: boolean;
 	}>;
-	rows: Array<{ cells: WriteupCell[]; tone?: WriteupTone }>;
+	rows: Array<{ cells: ReadCell[]; tone?: ReadTone }>;
 	/** The sort the table opens in. */
 	sort?: { column: number; direction: "asc" | "desc" };
 }
 
 /** One stacked bar: the parts of a whole, with a key. */
-export interface WriteupBar extends BlockBase {
+export interface ReadBar extends BlockBase {
 	kind: "bar";
 	segments: StackedBarSegment[];
 }
 
 /** A scale with zones and one line per reading. */
-export interface WriteupScale extends BlockBase {
+export interface ReadScale extends BlockBase {
 	kind: "scale";
 	max: number;
 	zones: ThresholdZone[];
@@ -140,59 +134,59 @@ export interface WriteupScale extends BlockBase {
 }
 
 /** A few numbers worth reading first, each with its period and its comparisons. */
-export interface WriteupStats extends BlockBase {
+export interface ReadStats extends BlockBase {
 	kind: "stats";
 	items: StatItem[];
 }
 
 /** A column chart: a bar a period, the periods in labeled groups. */
-export interface WriteupColumns extends BlockBase {
+export interface ReadColumns extends BlockBase {
 	kind: "columns";
 	groups: ColumnChartGroup[];
-	legend?: Array<{ label: string; tone: WriteupTone }>;
+	legend?: Array<{ label: string; tone: ReadTone }>;
 }
 
 /** Findings, each an icon beside its point with the explainer under it, and the owner's screen beside them. */
-export interface WriteupFindings {
+export interface ReadFindings {
 	kind: "findings";
-	items: WriteupBullet[];
+	items: ReadBullet[];
 	shot?: WriteupShot;
 	shot2?: WriteupShot;
 }
 
 /** The owner's own screens, side by side at one size. */
-export interface WriteupShots {
+export interface ReadShots {
 	kind: "shots";
 	title?: string;
 	shots: WriteupShot[];
 }
 
 /** Blocks that can sit inside a fold (a `more` block). */
-export type WriteupInnerBlock =
-	| WriteupChecks
-	| WriteupTable
-	| WriteupBar
-	| WriteupScale
-	| WriteupFindings
-	| WriteupStats
-	| WriteupColumns
-	| WriteupShots;
+export type ReadInnerBlock =
+	| ReadChecks
+	| ReadTable
+	| ReadBar
+	| ReadScale
+	| ReadFindings
+	| ReadStats
+	| ReadColumns
+	| ReadShots;
 
 /**
  * A fold, the native Disclosure: the label says what is inside and the
  * summary says what it shows, so the detail needs no explaining once open.
  */
-export interface WriteupMore {
+export interface ReadMore {
 	kind: "more";
 	label: string;
 	summary?: ReactNode;
-	blocks: WriteupInnerBlock[];
+	blocks: ReadInnerBlock[];
 }
 
-export type WriteupTopicBlock = WriteupInnerBlock | WriteupMore;
+export type ReadBlock = ReadInnerBlock | ReadMore;
 
-export interface WriteupTopic {
-	kind: "topic";
+/** The section card's own content: what the card knows how to draw on its own. */
+export interface ReadTopic {
 	id: string;
 	/** The discipline's trade name, e.g. "Local SEO" or "Core Web Vitals". */
 	title: string;
@@ -204,126 +198,27 @@ export interface WriteupTopic {
 	oneLiner: string;
 	/** The section's grade, beside the heading. */
 	grade?: WriteupGrade;
-	/** Why it earned that letter: the rule it met, in a sentence. The read sets its summary here. */
+	/** Why it earned that letter: the summary of what we saw, in a sentence or two. */
 	why?: ReactNode;
 	/** The word before the grade on the why line; defaults to "Why". */
 	whyLabel?: string;
 	/** What a screen reader hears before the grade's letter; defaults to "Grade". */
 	gradeWord?: string;
 	/** The section's blocks, in order. */
-	blocks?: WriteupTopicBlock[];
-	/** Findings without blocks: rendered as one findings block with the shots beside it. */
-	bullets?: WriteupBullet[];
-	shot?: WriteupShot;
-	shot2?: WriteupShot;
-	shotBrief?: string;
-	/** The topic carries no picture by design. */
-	noShot?: boolean;
+	blocks?: ReadBlock[];
 	/** The tools the readings came from, linked. */
-	sources?: WriteupSource[];
-	/** The label over the sources, e.g. "Where this comes from". */
+	sources?: ReadSource[];
+	/** The label over the sources, e.g. "See it yourself". */
 	sourcesLabel?: string;
 }
 
-export interface WriteupPart {
-	kind: "part";
-	/** The anchor a header stop points at, e.g. "health". */
-	id?: string;
-	/** The tier's name, e.g. "Health". */
-	title: string;
-	/** The question the tier answers, in the owner's words. */
-	lead: string;
-}
-
-export interface WriteupSummaryRow {
-	/** The tier, e.g. "Health". */
-	tier: string;
-	/** The section's trade name, matching a topic title. */
-	section: string;
-	/** The topic's anchor, e.g. "#technical-seo"; the row links to it. */
-	href?: string;
-	grade: WriteupGrade;
-	/** The grade in the earlier snapshot, on a later writeup: what moved. */
-	before?: WriteupGrade;
-	/** The read behind the grade, in the owner's words. */
-	read: ReactNode;
-}
-
-/** The overview the writeup opens on: every section, its grade, and one plain read. */
-export interface WriteupSummary {
-	kind: "summary";
-	id?: string;
-	title?: string;
-	rows: WriteupSummaryRow[];
-	/** What each letter means, in a few words each. */
-	legend?: Array<{ grade: WriteupGrade; label: string }>;
-	/** What a screen reader calls the earlier letter, e.g. "June 2026"; defaults to "Before". */
-	beforeLabel?: string;
-}
-
-/** The paid facts line: what is rented, never graded (FOOTPRINT.md, Paid). */
-export interface WriteupRented {
-	kind: "rented";
-	label?: string;
-	text: ReactNode;
-}
-
-export interface WriteupMarketRow {
-	market: string;
-	place?: string;
-	/** One grade per column, in column order; null draws a quiet dash for a column not read. */
-	grades: Array<WriteupGrade | null>;
-	read: ReactNode;
-}
-
-/** The markets table: one row per market, one letter per column, the read beside it. */
-export interface WriteupMarkets {
-	kind: "markets";
-	title: string;
-	lead?: string;
-	columns: string[];
-	rows: WriteupMarketRow[];
-}
-
-export type WriteupBlock =
-	| WriteupPart
-	| WriteupTopic
-	| WriteupSummary
-	| WriteupRented
-	| WriteupMarkets;
-
-export interface WriteupSheet {
-	id: string;
-	blocks: WriteupBlock[];
-}
-
-export interface WriteupProps {
-	/** The sender's wordmark text, e.g. "atelic"; drawn with the orange run. Print only. */
-	sender: { name: string; href?: string };
-	/** The recipient's logo, lockup right of the sender. Print only. */
-	recipient: { logoSrc: string; logoAlt: string };
-	preparedFor: string;
-	date: string;
-	title: string;
-	/** One or two sentences under the title: what this is and where it was read from. */
-	intro?: ReactNode;
-	/** Groups of blocks. They run together on screen and in print. */
-	sheets: WriteupSheet[];
-	close: {
-		signOff: string;
-		person: WriteupPerson;
-		/** The pointer to the hosted page, on the printed copy only. */
-		twin?: { line: string; domain: string; qrSrc: string };
-	};
-}
-
 const toneIcon = {
 	good: CircleCheck,
 	bad: CircleX,
 	warn: CircleAlert,
 } as const;
 
-function Mark({ cell }: { cell: WriteupMark }) {
+function Mark({ cell }: { cell: ReadMark }) {
 	if (cell.mark === "none") {
 		return (
 			<span className="op-mark-cell" data-tone="muted">
@@ -343,7 +238,7 @@ function Mark({ cell }: { cell: WriteupMark }) {
 }
 
 /** A star rating as a table cell: the figure beside a star, sorted by the figure. */
-export function ratingCell(rating: number, tone?: WriteupTone): WriteupSorted {
+export function ratingCell(rating: number, tone?: ReadTone): ReadSorted {
 	return {
 		sort: rating,
 		display: (
@@ -381,7 +276,7 @@ function Block({
 	);
 }
 
-function Table({ block }: { block: WriteupTable }) {
+function Table({ block }: { block: ReadTable }) {
 	const rows = block.rows.map((row) => ({
 		tone: row.tone,
 		cells: row.cells.map((cell) =>
@@ -398,7 +293,7 @@ function Table({ block }: { block: WriteupTable }) {
 }
 
 /** A string or runs of text and links, the shape JSON content arrives in; a node of elements is anything else. */
-function isRuns(value: unknown): value is ArtifactParagraph {
+export function isRuns(value: unknown): value is ArtifactParagraph {
 	if (typeof value === "string") return true;
 	return (
 		Array.isArray(value) &&
@@ -416,8 +311,8 @@ function bodyNode(body: ReactNode | ArtifactParagraph | undefined): ReactNode {
 	return isRuns(body) ? <Runs paragraph={body} /> : body;
 }
 
-function Findings({ block, brief }: { block: WriteupFindings; brief?: string }) {
-	const hasShots = Boolean(block.shot || brief);
+function Findings({ block }: { block: ReadFindings }) {
+	const hasShots = Boolean(block.shot);
 	return (
 		<div className={`op-block op-findings${hasShots ? " has-shots" : ""}`}>
 			<div className="op-findings-list">
@@ -435,25 +330,17 @@ function Findings({ block, brief }: { block: WriteupFindings; brief?: string })
 					);
 				})}
 			</div>
-			{hasShots && (
+			{block.shot && (
 				<div className="op-shots">
-					{block.shot ? (
-						<>
-							<Shot shot={block.shot} />
-							{block.shot2 && <Shot shot={block.shot2} />}
-						</>
-					) : (
-						<figure className="op-shot">
-							<span className="op-shot-brief">{brief}</span>
-						</figure>
-					)}
+					<Shot shot={block.shot} />
+					{block.shot2 && <Shot shot={block.shot2} />}
 				</div>
 			)}
 		</div>
 	);
 }
 
-function Shots({ block }: { block: WriteupShots }) {
+function Shots({ block }: { block: ReadShots }) {
 	return (
 		<Block className="op-shots-block" block={block}>
 			<div className="op-shots-row" data-count={Math.min(block.shots.length, 3)}>
@@ -465,7 +352,7 @@ function Shots({ block }: { block: WriteupShots }) {
 	);
 }
 
-function More({ block }: { block: WriteupMore }) {
+function More({ block }: { block: ReadMore }) {
 	return (
 		<Disclosure className="op-block op-more" label={block.label} summary={block.summary}>
 			<div className="op-more-body">
@@ -478,7 +365,7 @@ function More({ block }: { block: WriteupMore }) {
 	);
 }
 
-function TopicBlock({ block }: { block: WriteupTopicBlock }) {
+function TopicBlock({ block }: { block: ReadBlock }) {
 	switch (block.kind) {
 		case "checks":
 			return (
@@ -527,17 +414,10 @@ function TopicBlock({ block }: { block: WriteupTopicBlock }) {
 }
 
 /**
- * The section card: the trade name linked to its definition, the one liner,
- * the why line, the grade, the blocks, and the sources at the foot. The read
- * renders its sections through it too, handing anything of its own (today and
- * after, what we recommend) as `extra`, set after the blocks and before the
- * sources, so the two documents share one layout.
+ * The section card. `extra` is set after the blocks and before the sources,
+ * so a document's own beats sit inside the card with the rest.
  */
-export function Topic({ topic, extra }: { topic: WriteupTopic; extra?: ReactNode }) {
-	const legacy: WriteupFindings | null = topic.bullets
-		? { kind: "findings", items: topic.bullets, shot: topic.shot, shot2: topic.shot2 }
-		: null;
-	const brief = topic.noShot || topic.shot ? undefined : (topic.shotBrief ?? "Screenshot");
+export function Topic({ topic, extra }: { topic: ReadTopic; extra?: ReactNode }) {
 	return (
 		<section className="op-topic" id={topic.id}>
 			<header className="op-topic-head">
@@ -582,7 +462,6 @@ export function Topic({ topic, extra }: { topic: WriteupTopic; extra?: ReactNode
 					// biome-ignore lint/suspicious/noArrayIndexKey: blocks are static content in a fixed order
 					<TopicBlock block={block} key={i} />
 				))}
-				{legacy && <Findings block={legacy} brief={brief} />}
 				{extra}
 			</div>
 			{topic.sources && topic.sources.length > 0 && (
@@ -608,185 +487,3 @@ export function Topic({ topic, extra }: { topic: WriteupTopic; extra?: ReactNode
 		</section>
 	);
 }
-
-function Summary({ summary }: { summary: WriteupSummary }) {
-	const groups: Array<{ title: string; rows: WriteupSummaryRow[] }> = [];
-	for (const row of summary.rows) {
-		const last = groups[groups.length - 1];
-		if (last && last.title === row.tier) last.rows.push(row);
-		else groups.push({ title: row.tier, rows: [row] });
-	}
-	return (
-		<ReportCard
-			className="op-ov"
-			id={summary.id}
-			title={summary.title}
-			legend={summary.legend}
-			labels={{ before: summary.beforeLabel }}
-			groups={groups.map((group) => ({
-				title: group.title,
-				rows: group.rows.map((row) => ({
-					name: row.section,
-					href: row.href,
-					grade: row.grade,
-					before: row.before,
-					line: row.read,
-				})),
-			}))}
-		/>
-	);
-}
-
-function Markets({ markets }: { markets: WriteupMarkets }) {
-	return (
-		<section className="op-topic op-markets">
-			<header className="op-topic-head">
-				<div>
-					<h3>{markets.title}</h3>
-					{markets.lead && <p className="op-def">{markets.lead}</p>}
-				</div>
-			</header>
-			<table className="op-markets-table">
-				<thead>
-					<tr>
-						<th scope="col" className="op-markets-market">
-							<span className="op-sr-only">Market</span>
-						</th>
-						{markets.columns.map((column) => (
-							<th scope="col" className="op-markets-col" key={column}>
-								{column}
-							</th>
-						))}
-						<th scope="col" className="op-markets-read">
-							<span className="op-sr-only">Read</span>
-						</th>
-					</tr>
-				</thead>
-				<tbody>
-					{markets.rows.map((row) => (
-						<tr key={row.market}>
-							<th scope="row" className="op-markets-market">
-								{row.market}
-								{row.place && <span className="op-markets-place">{row.place}</span>}
-							</th>
-							{markets.columns.map((column, i) => {
-								const grade = row.grades[i] ?? null;
-								return (
-									<td className="op-markets-grade" key={column}>
-										<span className="op-markets-label" aria-hidden="true">
-											{column}
-										</span>
-										{grade ? (
-											<>
-												<span className="op-sr-only">{`${column}, grade ${gradeLabel[grade]}`}</span>
-												<span aria-hidden="true">
-													<GradeChip grade={grade} />
-												</span>
-											</>
-										) : (
-											<>
-												<span className="op-sr-only">{`${column}, not read`}</span>
-												<span className="op-dash" aria-hidden="true" />
-											</>
-										)}
-									</td>
-								);
-							})}
-							<td className="op-markets-read">{row.read}</td>
-						</tr>
-					))}
-				</tbody>
-			</table>
-		</section>
-	);
-}
-
-function Rented({ rented }: { rented: WriteupRented }) {
-	return (
-		<p className="op-rented">
-			<span className="op-rented-label">{rented.label ?? "Rented"}</span>
-			<span className="op-rented-text">{rented.text}</span>
-		</p>
-	);
-}
-
-function Part({ part }: { part: WriteupPart }) {
-	return (
-		<div className="op-part" id={part.id}>
-			<h2>{part.title}</h2>
-			<p>{part.lead}</p>
-		</div>
-	);
-}
-
-export function Writeup({
-	sender,
-	recipient,
-	preparedFor,
-	date,
-	title,
-	intro,
-	sheets,
-	close,
-}: WriteupProps) {
-	return (
-		<div className="op">
-			<div className="op-doc">
-				<header className="op-head">
-					<div className="op-top">
-						<span className="op-mark">
-							{sender.href ? <a href={sender.href}>{sender.name}</a> : sender.name}
-							<span className="op-run" aria-hidden="true" />
-						</span>
-						<span className="op-x" aria-hidden="true">
-							×
-						</span>
-						<img className="op-recipient" src={recipient.logoSrc} alt={recipient.logoAlt} />
-					</div>
-					<p className="op-meta">
-						Prepared for <b>{preparedFor}</b>
-						<span className="op-meta-sep" aria-hidden="true">
-							{" · "}
-						</span>
-						<span className="op-meta-date">{date}</span>
-					</p>
-					<h1>{title}</h1>
-					{intro && <p className="op-intro">{intro}</p>}
-				</header>
-				{sheets.map((sheet) => (
-					<div className="op-sheet" id={sheet.id} key={sheet.id}>
-						{sheet.blocks.map((block) =>
-							block.kind === "part" ? (
-								<Part key={block.title} part={block} />
-							) : block.kind === "summary" ? (
-								<Summary key="summary" summary={block} />
-							) : block.kind === "rented" ? (
-								<Rented key="rented" rented={block} />
-							) : block.kind === "markets" ? (
-								<Markets key={`markets-${block.title}`} markets={block} />
-							) : (
-								<Topic key={block.id} topic={block} />
-							),
-						)}
-					</div>
-				))}
-				<footer className="op-close">
-					<SignOff signOff={close.signOff} person={close.person} />
-					{close.twin && (
-						<div className="op-twin">
-							<div className="op-twin-text">
-								{close.twin.line}
-								<b>{close.twin.domain}</b>
-							</div>
-							<img
-								className="op-qr"
-								src={close.twin.qrSrc}
-								alt={`QR code for ${close.twin.domain}`}
-							/>
-						</div>
-					)}
-				</footer>
-			</div>
-		</div>
-	);
-}