@atelic-action/artifact 4.2.0 → 5.0.0

package/src/documents/{Read.tsx → TheRead.tsx}

@@ -1,6 +1,8 @@
 import {
 	type ArtifactLink,
 	type ArtifactParagraph,
+	GradeChip,
+	gradeLabel,
 	isEmpty,
 	newTabProps,
 	Paragraph,
@@ -12,36 +14,39 @@ import {
 import { IconList, ReportCard, type Tone } from "@atelic-action/ui/components";
 import { ArrowUpRight, Check } from "lucide-react";
 import type { ReactNode } from "react";
-import { Topic, type WriteupTopic } from "./Writeup";
+import { isRuns, type ReadTopic, Topic } from "./Topic";
 
 /**
- * The read: what a customer gets at the end of an engagement's first week,
- * before anything changes. Where the writeup says what letter each section
- * earned, the read says why, and what changes. Its shape is the practice's
- * FOOTPRINT.md, under What the Owner Gets: a title and a dated lede; the gist
- * table (every section, its grade, and one line), with a note under it for
- * what the read leaves out; then the tiers; then the plan, in order; then one
- * closing line and the sign off.
+ * The read: the graded document a business gets from the practice, built from
+ * one snapshot. Its shape is the practice's FOOTPRINT.md, under What the
+ * Owner Gets: a title and a dated lede; the scorecard (every section under
+ * its tier, its grade, and one line, with the earlier letter beside it on a
+ * later read), with a note over it for what the read leaves out; the plan in
+ * order; then the tiers, each section the card in Topic.tsx (the trade name
+ * linked to its definition, the one liner, the grade, the why line as the
+ * summary of what we saw, the blocks, and the sources at the foot) plus what
+ * is the read's own, today and after and what we recommend; a tier may open
+ * on a table of letters per market and close on the paid facts line, which
+ * is never graded; then one closing line and the sign off. A beat with
+ * nothing in it is left out.
  *
- * A section is the writeup's section card, the same `Topic`, so the two
- * documents read alike (Forni, 2026-10-16): the trade name linked to its
- * definition, the one liner, the grade, and the why line, which here is the
- * summary of what we saw in one or two sentences; then the writeup's blocks
- * (findings with the owner's screens beside them, the basics, a table, a
- * fold); then what is the read's own, today and after as a two column table
- * and what we recommend as a checklist; and the tools we looked through at
- * the foot, as the sources. A beat with nothing in it is left out.
+ * The same page at two depths, and `access` says which. A public read is
+ * built from public readings alone and may be hosted open; a private one
+ * adds what the owner's own consoles show and deploys only behind the wall.
+ * The component draws whatever beats the content carries, so the depth
+ * lives in the content and `access` is the declaration the host is checked
+ * against (the content test, and `access` in site.config.ts).
  *
- * It wears the writeup's column, head, grade chip and key, tier heading,
- * section card, and close (the `.op` classes), and adds only what is its own
- * (the `.rd` classes). The gist table is drawn from the tiers, so a tier
- * added later (Conversion, once the analytics access lands) is one more entry
- * in `tiers` and appears in the table and the body alike; until then `note`
- * says so under the table. Every prop but a finding's body and the sign off
- * person's `role` is plain data, and both are equally happy with a string, so
- * a routine can write a read as JSON.
+ * Every prop but a finding's body, a why line, and the sign off person's
+ * `role` is plain data, and all three are equally happy with a string, so a
+ * routine can write a read as JSON. `print` is the printed copy's own: the
+ * sender and recipient lockup where the header was, and the pointer to the
+ * hosted twin with its QR under the sign off.
  */
 
+/** Whether anything on the page came from the owner's own consoles. */
+export type ReadAccess = "public" | "private";
+
 /** A link inside running text: the words the reader clicks and where they go. */
 export type ReadLink = ArtifactLink;
 
@@ -55,13 +60,15 @@ export interface ReadChange {
 }
 
 /**
- * One section of a tier: the writeup's section card (its `title`, `href`,
- * `oneLiner`, `grade`, `why`, `blocks`, and `sources`), plus the read's own:
- * the gist table's line, today and after, and what we recommend.
+ * One section of a tier: the card (its `title`, `href`, `oneLiner`, `grade`,
+ * `why`, `blocks`, and `sources`), plus the scorecard's line, the earlier
+ * letter, today and after, and what we recommend.
  */
-export interface ReadSection extends Omit<WriteupTopic, "kind" | "why"> {
-	/** The one line in the gist table. */
+export interface ReadSection extends Omit<ReadTopic, "why"> {
+	/** The one line on the scorecard. */
 	gist: ReadParagraph;
+	/** The grade in the earlier snapshot, on a later read: what moved. */
+	before?: WriteupGrade;
 	/** The summary of what we saw, in one or two sentences: the why line. A paragraph, so a read written as JSON can carry links in it. */
 	why?: ReactNode | ReadParagraph;
 	/** Today and after: what each thing is, and what it becomes. Set after the blocks. */
@@ -80,6 +87,29 @@ export interface ReadRecommendation {
 	tone?: Tone;
 }
 
+export interface ReadMarketRow {
+	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 | ReadParagraph;
+}
+
+/** The markets table: one row per market or site, one letter per column, the read beside it. */
+export interface ReadMarkets {
+	title: string;
+	lead?: string;
+	columns: string[];
+	rows: ReadMarketRow[];
+}
+
+/** The paid facts line: what is rented, never graded (FOOTPRINT.md, Paid). */
+export interface ReadRented {
+	/** The word before the line; defaults to the `rented` label. */
+	label?: string;
+	text: ReactNode | ReadParagraph;
+}
+
 /** A tier, e.g. Health: its heading, the question it answers, and its sections in order. */
 export interface ReadTier {
 	/** The anchor a header stop points at, e.g. "health". */
@@ -90,7 +120,11 @@ export interface ReadTier {
 	href?: string;
 	/** The questions the tier answers, in the owner's words. */
 	lead?: string;
+	/** A table of letters per market or site, over the sections. */
+	markets?: ReadMarkets;
 	sections: ReadSection[];
+	/** The paid facts line, under the sections. Visibility's, by FOOTPRINT.md. */
+	rented?: ReadRented;
 }
 
 /** One step of the plan: a bold title and a sentence or two. */
@@ -117,21 +151,35 @@ export interface ReadPlan {
 /** The close: one line, then the sign off. */
 export interface ReadClose {
 	/** One sentence, e.g. what follows and when. */
-	line: ReadParagraph;
+	line?: ReadParagraph;
 	signOff?: string;
 	person?: WriteupPerson;
 }
 
+/** The printed copy's own: the lockup where the header was, and the pointer to the hosted twin. */
+export interface ReadPrint {
+	/** The sender's wordmark text, e.g. "atelic"; drawn with the orange run. */
+	sender: { name: string; href?: string };
+	/** The recipient's logo, lockup right of the sender. */
+	recipient: { logoSrc: string; logoAlt: string };
+	/** The pointer to the hosted page under the sign off, with its QR. */
+	twin?: { line: string; domain: string; qrSrc: string };
+}
+
 /** The fixed words the page sets, each overridable. */
 export interface ReadLabels {
 	/** The dateline's words before the business, e.g. "Prepared for". */
 	preparedFor: string;
-	/** What a screen reader calls the gist card when it has no title. */
+	/** What a screen reader calls the scorecard when it has no title. */
 	gist: string;
-	/** What a screen reader hears before a letter, on the gist card and each section's card. */
+	/** What a screen reader hears before a letter, on the scorecard and each section's card. */
 	grade: string;
 	/** What a screen reader hears for a section with no grade. */
 	notGraded: string;
+	/** What a screen reader calls the earlier letter on the scorecard, e.g. "Before" or "June 2026". */
+	before: string;
+	/** The word before the paid facts line when it names none. */
+	rented: string;
 	/** The today and after table's first column. */
 	now: string;
 	/** The today and after table's second column. */
@@ -144,6 +192,8 @@ export interface ReadLabels {
 	sources: string;
 	/** The plan's heading when it names none. */
 	plan: string;
+	/** The note over the scorecard on a public read that sets none: what the read leaves out. */
+	publicNote: string;
 }
 
 export const readLabels: ReadLabels = {
@@ -151,15 +201,21 @@ export const readLabels: ReadLabels = {
 	gist: "The Gist",
 	grade: "Grade",
 	notGraded: "Not graded yet",
+	before: "Before",
+	rented: "Rented",
 	now: "Today",
 	after: "After",
 	recommend: "Recommendations",
 	why: "Why",
 	sources: "See it yourself",
 	plan: "The Plan",
+	publicNote:
+		"This page is read from the outside, through what anyone can open. A customer's read adds what the owner's own consoles show.",
 };
 
-export interface ReadProps {
+export interface TheReadProps {
+	/** Whether anything on the page came from the owner's own consoles; a private read deploys only behind the wall. */
+	access: ReadAccess;
 	title: string;
 	/** The business, set in the dateline. */
 	preparedFor: string;
@@ -169,19 +225,21 @@ export interface ReadProps {
 	lede: ReadParagraph;
 	/** The heading over the scorecard, e.g. "The Scorecard". */
 	gistTitle?: string;
-	/** The line under the scorecard's heading, e.g. what it is. */
+	/** The line under the scorecard's heading, e.g. what it is. Set only with a `gistTitle`, since it reads as the heading's subtitle. */
 	gistLead?: string;
-	/** The anchor a header stop points at for the scorecard, e.g. "scorecard". */
+	/** The anchor a header stop points at for the scorecard, e.g. "scorecard": on the heading with a `gistTitle`, on the card itself without one. */
 	gistId?: string;
-	/** A callout over the scorecard, under its heading, e.g. what the read leaves out and when it follows. */
+	/** A callout over the scorecard, under its heading, e.g. what the read leaves out and when it follows. A public read that sets none gets the `publicNote` label. */
 	note?: ReadParagraph;
 	/** The key: what each letter means, in a few words each. */
 	gradeKey?: Array<{ grade: WriteupGrade; label: string }>;
-	/** The tiers in order. Each section appears in the gist table and in the body. */
+	/** The tiers in order. Each section appears on the scorecard and in the body. */
 	tiers: ReadTier[];
 	plan: ReadPlan;
 	close: ReadClose;
 	labels?: Partial<ReadLabels>;
+	/** The printed copy's lockup and twin; the page prints without them when left out. */
+	print?: ReadPrint;
 }
 
 /** A paragraph with something to read. Content may arrive as JSON, so a missing one counts as empty. */
@@ -189,19 +247,6 @@ function filled(paragraph: ReadParagraph | undefined | null): paragraph is ReadP
 	return paragraph !== undefined && paragraph !== null && !isEmpty(paragraph);
 }
 
-/** 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 ReadParagraph {
-	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),
-		)
-	);
-}
-
 /** Content as a node: runs are rendered, a blank is dropped, and a node passes through. */
 function asNode(value: ReactNode | ReadParagraph | undefined | null): ReactNode {
 	if (value === undefined || value === null) return undefined;
@@ -276,8 +321,8 @@ function Gist({
 	id?: string;
 	title?: string;
 	lead?: string;
-	note?: ReadProps["note"];
-	gradeKey?: ReadProps["gradeKey"];
+	note?: ReadParagraph;
+	gradeKey?: TheReadProps["gradeKey"];
 	labels: ReadLabels;
 }) {
 	return (
@@ -294,17 +339,19 @@ function Gist({
 				</div>
 			)}
 			<ReportCard
+				id={title ? undefined : id}
 				className="rd-gist"
 				label={title ?? labels.gist}
 				legend={gradeKey}
 				legendAt="foot"
-				labels={{ grade: labels.grade, notGraded: labels.notGraded }}
+				labels={{ grade: labels.grade, notGraded: labels.notGraded, before: labels.before }}
 				groups={tiers.map((tier) => ({
 					title: tier.title,
 					rows: tier.sections.map((section) => ({
 						name: section.title,
 						href: `#${section.id}`,
 						grade: section.grade,
+						before: section.before,
 						line: <Runs paragraph={section.gist} />,
 					})),
 				}))}
@@ -313,7 +360,7 @@ function Gist({
 	);
 }
 
-/** A section: the writeup's card, with today and after and the checklist handed in after its blocks. */
+/** A section: the card, with today and after and the checklist handed in after its blocks. */
 function Section({ section, labels }: { section: ReadSection; labels: ReadLabels }) {
 	const changes = (section.changes ?? []).filter(
 		(change) => filled(change?.now) || filled(change?.after),
@@ -333,16 +380,21 @@ function Section({ section, labels }: { section: ReadSection; labels: ReadLabels
 			: block,
 	);
 	const sources = (section.sources ?? []).filter((source) => source?.label?.trim());
-	const topic: WriteupTopic = {
-		kind: "topic",
-		...section,
+	const {
+		gist: _gist,
+		before: _before,
+		changes: _changes,
+		recommend: _recommend,
+		...card
+	} = section;
+	const topic: ReadTopic = {
+		...card,
 		why: asNode(section.why),
 		whyLabel: section.whyLabel ?? labels.why,
 		gradeWord: section.gradeWord ?? labels.grade,
 		blocks,
 		sources,
 		sourcesLabel: section.sourcesLabel ?? labels.sources,
-		noShot: section.noShot ?? true,
 	};
 	const extra =
 		changes.length + recommend.length > 0 ? (
@@ -354,6 +406,79 @@ function Section({ section, labels }: { section: ReadSection; labels: ReadLabels
 	return <Topic topic={topic} extra={extra} />;
 }
 
+function Markets({ markets }: { markets: ReadMarkets }) {
+	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">{asNode(row.read)}</td>
+						</tr>
+					))}
+				</tbody>
+			</table>
+		</section>
+	);
+}
+
+function Rented({ rented, label }: { rented: ReadRented; label: string }) {
+	return (
+		<p className="op-rented">
+			<span className="op-rented-label">{rented.label ?? label}</span>
+			<span className="op-rented-text">{asNode(rented.text)}</span>
+		</p>
+	);
+}
+
 function Plan({ plan, labels }: { plan: ReadPlan; labels: ReadLabels }) {
 	return (
 		<section className="rd-plan" id={plan.id}>
@@ -387,7 +512,37 @@ function Plan({ plan, labels }: { plan: ReadPlan; labels: ReadLabels }) {
 	);
 }
 
-export function Read({
+function Tier({ tier, labels }: { tier: ReadTier; labels: ReadLabels }) {
+	const rented =
+		tier.rented && (isRuns(tier.rented.text) ? filled(tier.rented.text) : tier.rented.text != null)
+			? tier.rented
+			: undefined;
+	return (
+		<div className="rd-tier">
+			<div className="op-part" id={tier.id}>
+				<h2>
+					{tier.href ? (
+						<a href={tier.href} {...newTabProps(tier.href, true)}>
+							{tier.title}
+							<ArrowUpRight size={14} aria-hidden="true" />
+						</a>
+					) : (
+						tier.title
+					)}
+				</h2>
+				{tier.lead && <p>{tier.lead}</p>}
+			</div>
+			{tier.markets && tier.markets.rows.length > 0 && <Markets markets={tier.markets} />}
+			{tier.sections.map((section) => (
+				<Section section={section} labels={labels} key={section.id} />
+			))}
+			{rented && <Rented rented={rented} label={labels.rented} />}
+		</div>
+	);
+}
+
+export function TheRead({
+	access,
 	title,
 	preparedFor,
 	date,
@@ -401,13 +556,36 @@ export function Read({
 	plan,
 	close,
 	labels: overrides,
-}: ReadProps) {
+	print,
+}: TheReadProps) {
 	const labels = { ...readLabels, ...overrides };
 	const shownTiers = tiers.filter((tier) => tier.sections.length > 0);
+	const shownNote = filled(note) ? note : access === "public" ? labels.publicNote : undefined;
+	const signOff = Boolean(close.signOff && close.person);
 	return (
-		<div className="op rd">
+		<div className="op rd" data-access={access}>
 			<article className="op-doc rd-doc">
 				<header className="op-head">
+					{print && (
+						<div className="op-top">
+							<span className="op-mark">
+								{print.sender.href ? (
+									<a href={print.sender.href}>{print.sender.name}</a>
+								) : (
+									print.sender.name
+								)}
+								<span className="op-run" aria-hidden="true" />
+							</span>
+							<span className="op-x" aria-hidden="true">
+								×
+							</span>
+							<img
+								className="op-recipient"
+								src={print.recipient.logoSrc}
+								alt={print.recipient.logoAlt}
+							/>
+						</div>
+					)}
 					<p className="op-meta">
 						{labels.preparedFor} <b>{preparedFor}</b>
 						<span className="op-meta-sep" aria-hidden="true">
@@ -424,36 +602,34 @@ export function Read({
 						id={gistId}
 						title={gistTitle}
 						lead={gistLead}
-						note={note}
+						note={shownNote}
 						gradeKey={gradeKey}
 						labels={labels}
 					/>
 				)}
 				{plan.steps.length > 0 && <Plan plan={plan} labels={labels} />}
 				{shownTiers.map((tier) => (
-					<div className="rd-tier" key={tier.title}>
-						<div className="op-part" id={tier.id}>
-							<h2>
-								{tier.href ? (
-									<a href={tier.href} {...newTabProps(tier.href, true)}>
-										{tier.title}
-										<ArrowUpRight size={14} aria-hidden="true" />
-									</a>
-								) : (
-									tier.title
-								)}
-							</h2>
-							{tier.lead && <p>{tier.lead}</p>}
-						</div>
-						{tier.sections.map((section) => (
-							<Section section={section} labels={labels} key={section.id} />
-						))}
-					</div>
+					<Tier tier={tier} labels={labels} key={tier.title} />
 				))}
 				{filled(close.line) && <Paragraph paragraph={close.line} className="rd-closing" />}
-				{close.signOff && close.person && (
+				{(signOff || print?.twin) && (
 					<footer className="op-close rd-close">
-						<SignOff signOff={close.signOff} person={close.person} />
+						{signOff && close.signOff && close.person && (
+							<SignOff signOff={close.signOff} person={close.person} />
+						)}
+						{print?.twin && (
+							<div className="op-twin">
+								<div className="op-twin-text">
+									{print.twin.line}
+									<b>{print.twin.domain}</b>
+								</div>
+								<img
+									className="op-qr"
+									src={print.twin.qrSrc}
+									alt={`QR code for ${print.twin.domain}`}
+								/>
+							</div>
+						)}
 					</footer>
 				)}
 			</article>