@atelic-action/artifact 1.3.0 → 3.0.0

package/src/documents/Writeup.tsx

@@ -1,7 +1,9 @@
 import {
+	type ArtifactParagraph,
 	GradeChip,
 	gradeLabel,
 	newTabProps,
+	Runs,
 	Shot,
 	SignOff,
 	type WriteupGrade,
@@ -16,6 +18,7 @@ import {
 	type ColumnChartGroup,
 	DataTable,
 	Disclosure,
+	ReportCard,
 	StackedBar,
 	type StackedBarSegment,
 	type StatItem,
@@ -25,7 +28,7 @@ import {
 	type ThresholdZone,
 	type Tone,
 } from "@atelic-action/ui/components";
-import { ArrowUpRight, ChevronRight, CircleAlert, CircleCheck, CircleX, Star } from "lucide-react";
+import { ArrowUpRight, CircleAlert, CircleCheck, CircleX, Star } from "lucide-react";
 import type { ReactNode } from "react";
 
 export type { WriteupGrade, WriteupPerson, WriteupShot } from "@atelic-action/ui/artifact";
@@ -52,8 +55,8 @@ export type WriteupTone = Tone;
 export interface WriteupBullet {
 	/** The point, in a full sentence. The icon sits beside it. */
 	lead: string;
-	/** The one explainer that says why it matters. */
-	body?: ReactNode;
+	/** The one explainer that says why it matters: a node, or a paragraph of runs when the content arrives as JSON. */
+	body?: ReactNode | ArtifactParagraph;
 	/** 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. */
@@ -113,6 +116,8 @@ export interface WriteupTable extends BlockBase {
 		sortable?: boolean;
 		/** The direction a first click sorts in. */
 		firstSort?: "asc" | "desc";
+		/** The column hugs its content, for a swatch or a mark. */
+		fit?: boolean;
 	}>;
 	rows: Array<{ cells: WriteupCell[]; tone?: WriteupTone }>;
 	/** The sort the table opens in. */
@@ -199,8 +204,12 @@ 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. */
+	/** Why it earned that letter: the rule it met, in a sentence. The read sets its summary here. */
 	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. */
@@ -388,21 +397,43 @@ 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 {
+	if (typeof value === "string") return true;
+	return (
+		Array.isArray(value) &&
+		value.every(
+			(run) =>
+				typeof run === "string" ||
+				(typeof run === "object" && run !== null && "text" in run && "href" in run),
+		)
+	);
+}
+
+/** A finding's body as a node, whichever way the content wrote it. */
+function bodyNode(body: ReactNode | ArtifactParagraph | undefined): ReactNode {
+	if (body === undefined || body === null) return undefined;
+	return isRuns(body) ? <Runs paragraph={body} /> : body;
+}
+
 function Findings({ block, brief }: { block: WriteupFindings; brief?: string }) {
 	const hasShots = Boolean(block.shot || brief);
 	return (
 		<div className={`op-block op-findings${hasShots ? " has-shots" : ""}`}>
 			<div className="op-findings-list">
-				{block.items.map((item) => (
-					<Callout
-						key={item.lead}
-						tone={item.tone ?? (item.win ? "good" : "warn")}
-						title={item.lead}
-						variant={item.box ? "box" : "plain"}
-					>
-						{item.body}
-					</Callout>
-				))}
+				{block.items.map((item, i) => {
+					const shape = {
+						tone: item.tone ?? (item.win ? "good" : "warn"),
+						title: item.lead,
+						variant: item.box ? ("box" as const) : ("plain" as const),
+					};
+					return (
+						// biome-ignore lint/suspicious/noArrayIndexKey: findings are static content in a fixed order, and a lead may repeat
+						<Callout key={i} {...shape}>
+							{bodyNode(item.body)}
+						</Callout>
+					);
+				})}
 			</div>
 			{hasShots && (
 				<div className="op-shots">
@@ -495,7 +526,14 @@ function TopicBlock({ block }: { block: WriteupTopicBlock }) {
 	}
 }
 
-function Topic({ topic }: { topic: WriteupTopic }) {
+/**
+ * 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.
+ */
+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;
@@ -519,13 +557,25 @@ function Topic({ topic }: { topic: WriteupTopic }) {
 						)}
 					</h3>
 					<p className="op-def">{topic.oneLiner}</p>
-					{topic.grade && topic.why && (
+					{topic.why && (
 						<p className="op-why">
-							<b>{`Why ${gradeLabel[topic.grade]}:`}</b> {topic.why}
+							<b>
+								{topic.grade
+									? `${topic.whyLabel ?? "Why"} ${gradeLabel[topic.grade]}:`
+									: `${topic.whyLabel ?? "Why"}:`}
+							</b>{" "}
+							{topic.why}
 						</p>
 					)}
 				</div>
-				{topic.grade && <GradeChip grade={topic.grade} />}
+				{topic.grade && (
+					<>
+						<span className="op-sr-only">{`${topic.gradeWord ?? "Grade"} ${gradeLabel[topic.grade]}`}</span>
+						<span aria-hidden="true">
+							<GradeChip grade={topic.grade} />
+						</span>
+					</>
+				)}
 			</header>
 			<div className="op-blocks">
 				{topic.blocks?.map((block, i) => (
@@ -533,13 +583,15 @@ function Topic({ topic }: { topic: WriteupTopic }) {
 					<TopicBlock block={block} key={i} />
 				))}
 				{legacy && <Findings block={legacy} brief={brief} />}
+				{extra}
 			</div>
 			{topic.sources && topic.sources.length > 0 && (
 				<footer className="op-sources">
 					<span className="op-sources-label">{topic.sourcesLabel ?? "Sources"}</span>
 					<ul>
-						{topic.sources.map((source) => (
-							<li key={source.label}>
+						{topic.sources.map((source, i) => (
+							// biome-ignore lint/suspicious/noArrayIndexKey: sources are static content in a fixed order, and a label may repeat
+							<li key={i}>
 								{source.href ? (
 									<a href={source.href} {...newTabProps(source.href, true)}>
 										{source.label}
@@ -558,61 +610,30 @@ function Topic({ topic }: { topic: WriteupTopic }) {
 }
 
 function Summary({ summary }: { summary: WriteupSummary }) {
-	const tiers: Array<{ tier: string; rows: WriteupSummaryRow[] }> = [];
+	const groups: Array<{ title: string; rows: WriteupSummaryRow[] }> = [];
 	for (const row of summary.rows) {
-		const last = tiers[tiers.length - 1];
-		if (last && last.tier === row.tier) last.rows.push(row);
-		else tiers.push({ tier: row.tier, rows: [row] });
+		const last = groups[groups.length - 1];
+		if (last && last.title === row.tier) last.rows.push(row);
+		else groups.push({ title: row.tier, rows: [row] });
 	}
-	const beforeLabel = summary.beforeLabel ?? "Before";
 	return (
-		<section className="op-ov" id={summary.id}>
-			<div className="op-ov-head">
-				{summary.title && <h2 className="op-ov-title">{summary.title}</h2>}
-				{summary.legend && (
-					<ul className="op-legend">
-						{summary.legend.map((entry) => (
-							<li key={entry.grade}>
-								<GradeChip grade={entry.grade} />
-								<span>{entry.label}</span>
-							</li>
-						))}
-					</ul>
-				)}
-			</div>
-			<div className="op-ov-card">
-				{tiers.map(({ tier, rows }) => (
-					<div className="op-ov-tier" key={tier}>
-						<div className="op-ov-tier-label">{tier}</div>
-						<ul>
-							{rows.map((row) => (
-								<li className="op-ov-row" key={row.section}>
-									<span className="op-ov-grade">
-										{row.before && (
-											<span className="op-ov-before">
-												<span className="op-sr-only">{`${beforeLabel}: ${gradeLabel[row.before]}. `}</span>
-												<span aria-hidden="true">
-													<GradeChip grade={row.before} />
-												</span>
-											</span>
-										)}
-										<span className="op-sr-only">{`Grade ${gradeLabel[row.grade]}: `}</span>
-										<span aria-hidden="true">
-											<GradeChip grade={row.grade} />
-										</span>
-									</span>
-									<b className="op-ov-name">
-										{row.href ? <a href={row.href}>{row.section}</a> : row.section}
-									</b>
-									<span className="op-ov-read">{row.read}</span>
-									{row.href && <ChevronRight className="op-ov-go" size={18} aria-hidden="true" />}
-								</li>
-							))}
-						</ul>
-					</div>
-				))}
-			</div>
-		</section>
+		<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,
+				})),
+			}))}
+		/>
 	);
 }