@atelic-action/artifact 0.0.0-stage → 1.1.0

package/src/documents/Read.tsx

@@ -0,0 +1,544 @@
+import {
+	GradeChip,
+	gradeLabel,
+	newTabProps,
+	SignOff,
+	type WriteupGrade,
+	type WriteupPerson,
+} from "@atelic-action/ui/artifact";
+import { ArrowUpRight, Check } from "lucide-react";
+import { type ArtifactLink, type ArtifactParagraph, isEmpty, Paragraph, Runs } from "./Paragraph";
+import { Shot, type WriteupShot } from "./Shot";
+
+/**
+ * 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); then the tiers; then the
+ * plan, in order; then one closing line and the sign off.
+ *
+ * Each section reads as an aggregator of the tools we looked through, top to
+ * bottom: where we looked (the tools, linked, each with an optional line);
+ * what it showed (a short paragraph or two, a compact table of facts, lists
+ * of examples, and any proof pictures); why, in one sentence on a tinted
+ * panel; today and after, a two column table of what a thing is and what it
+ * becomes; and what we recommend, as a checklist. A beat with nothing in it
+ * is left out, heading and all.
+ *
+ * It is the writeup's sibling, not a variant: it wears the writeup's column,
+ * head, grade chip and key, tier heading, section card, screen, 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, with no change to the props. Every prop
+ * is plain data, so a routine can write a read as JSON; the one exception is
+ * the sign off person's `role`, which takes a node and is equally happy with
+ * a string.
+ */
+
+/** A link inside running text: the words the reader clicks and where they go. */
+export type ReadLink = ArtifactLink;
+
+/** A paragraph: a plain string, or runs of text and links in order. */
+export type ReadParagraph = ArtifactParagraph;
+
+/** A tool we looked through: its name, where it opens (in a new tab), and a line on what we read there. */
+export interface ReadTool {
+	label: string;
+	href?: string;
+	/** One short line, e.g. "Page indexing, the last 90 days". */
+	note?: string;
+}
+
+/** The 1.0.0 name for a tool; the same shape. */
+export type ReadSource = ReadTool;
+
+/** One row of a section's facts: a short label and its value, e.g. "Pages on Google" and "9 of 9". */
+export interface ReadFact {
+	label: string;
+	value: ReadParagraph;
+}
+
+/** A list of examples under its own short heading; each item a paragraph that can carry links. */
+export interface ReadExamples {
+	title?: string;
+	items: ReadParagraph[];
+}
+
+/** One row of today and after: what a thing is now, and what it becomes. */
+export interface ReadChange {
+	now: ReadParagraph;
+	after: ReadParagraph;
+}
+
+/** One section of a tier: a question, read top to bottom in five beats. */
+export interface ReadSection {
+	/** The anchor the gist table links to, e.g. "technical-seo". */
+	id: string;
+	/** The section's trade name, e.g. "Technical SEO": the gist table's Section column, and the line over the question. */
+	name: string;
+	/** The question the section answers, in the owner's words, e.g. "Can Google read the site?". The section's heading. */
+	question: string;
+	/** The baseline's grade. Omit for a section not yet graded; the table shows a quiet dash. */
+	grade?: WriteupGrade;
+	/** The one line in the gist table. */
+	gist: ReadParagraph;
+	/** Where we looked: the tools the readings came from, linked, at the top of the section. */
+	tools?: ReadTool[];
+	/** The 1.0.0 name for `tools`, still read and rendered in the same place; `tools` wins when both are set. */
+	sources?: ReadTool[];
+	/** What it showed: one or two short paragraphs. */
+	found: ReadParagraph[];
+	/** What it showed, as a compact two column table of facts under the paragraphs. */
+	facts?: ReadFact[];
+	/** What it showed, as lists of examples, each under its own short heading. */
+	examples?: ReadExamples[];
+	/** Proof pictures, each over its caption, e.g. a search result capture per market. */
+	shots?: WriteupShot[];
+	/** Why, in one sentence, set apart. */
+	why: ReadParagraph;
+	/** Today and after: what each thing is, and what it becomes. */
+	changes?: ReadChange[];
+	/** What we recommend, as a checklist. */
+	recommend?: 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". */
+	id?: string;
+	/** The tier's name, e.g. "Health". */
+	title: string;
+	/** The question the tier answers, in the owner's words. */
+	lead?: string;
+	sections: ReadSection[];
+}
+
+/** One step of the plan: a bold title and a sentence or two. */
+export interface ReadStep {
+	title: string;
+	body?: ReadParagraph;
+	/** Whose step it is when it is not the practice's, e.g. "Yours" or a name; set beside the title. */
+	who?: string;
+}
+
+/** The plan: the steps in order, numbered. */
+export interface ReadPlan {
+	/** The anchor a header stop points at, e.g. "plan". */
+	id?: string;
+	/** The heading; defaults to the `plan` label. */
+	title?: string;
+	/** A line over the steps. */
+	lead?: ReadParagraph;
+	steps: ReadStep[];
+}
+
+/** The close: one line, then the sign off. */
+export interface ReadClose {
+	/** One sentence, e.g. what follows and when. */
+	line: ReadParagraph;
+	signOff?: string;
+	person?: WriteupPerson;
+}
+
+/** The fixed words the page sets, each overridable. */
+export interface ReadLabels {
+	/** The dateline's words before the business, e.g. "Prepared for". */
+	preparedFor: string;
+	/** The gist table's first column. */
+	section: string;
+	/** The gist table's second column. */
+	grade: string;
+	/** The gist table's third column. */
+	gist: string;
+	/** What a screen reader hears for a section with no grade. */
+	notGraded: string;
+	/** The beat at the top of a section: the tools we looked through. */
+	tools: string;
+	/** The beat that says what the tools showed. */
+	found: string;
+	/** The one sentence beat. */
+	why: string;
+	/** The today and after table's first column. */
+	now: string;
+	/** The today and after table's second column. */
+	after: string;
+	/** The checklist beat at the foot of a section. */
+	recommend: string;
+	/** The plan's heading when it names none. */
+	plan: string;
+}
+
+export const readLabels: ReadLabels = {
+	preparedFor: "Prepared for",
+	section: "Section",
+	grade: "Grade",
+	gist: "The Gist",
+	notGraded: "Not graded yet",
+	tools: "Where We Looked",
+	found: "What It Showed",
+	why: "Why",
+	now: "Today",
+	after: "After",
+	recommend: "What We Recommend",
+	plan: "The Plan",
+};
+
+export interface ReadProps {
+	title: string;
+	/** The business, set in the dateline. */
+	preparedFor: string;
+	/** The ISO date, e.g. "2026-10-16". */
+	date: string;
+	/** Two or three sentences under the title. */
+	lede: ReadParagraph;
+	/** The heading over the gist table, e.g. "At a Glance". */
+	gistTitle?: string;
+	/** 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. */
+	tiers: ReadTier[];
+	plan: ReadPlan;
+	close: ReadClose;
+	labels?: Partial<ReadLabels>;
+}
+
+/** A paragraph with something to read. Content may arrive as JSON, so a missing one counts as empty. */
+function filled(paragraph: ReadParagraph | undefined | null): paragraph is ReadParagraph {
+	return paragraph !== undefined && paragraph !== null && !isEmpty(paragraph);
+}
+
+function Tools({ tools, label }: { tools: ReadTool[]; label: string }) {
+	return (
+		<div className="rd-beat rd-tools">
+			<h4>{label}</h4>
+			<ul className="rd-tools-list">
+				{tools.map((tool, i) => (
+					// biome-ignore lint/suspicious/noArrayIndexKey: tools are static content in a fixed order, and a label may repeat
+					<li key={i}>
+						{tool.href ? (
+							<a href={tool.href} {...newTabProps(tool.href, true)}>
+								{tool.label}
+								<ArrowUpRight size={13} aria-hidden="true" />
+							</a>
+						) : (
+							<span className="rd-tool-name">{tool.label}</span>
+						)}
+						{tool.note && <span className="rd-tool-note">{tool.note}</span>}
+					</li>
+				))}
+			</ul>
+		</div>
+	);
+}
+
+function Facts({ facts }: { facts: ReadFact[] }) {
+	return (
+		<table className="rd-facts">
+			<tbody>
+				{facts.map((fact, i) => (
+					// biome-ignore lint/suspicious/noArrayIndexKey: facts are static content in a fixed order
+					<tr key={i}>
+						<th scope="row">{fact.label}</th>
+						<td>
+							<Runs paragraph={fact.value} />
+						</td>
+					</tr>
+				))}
+			</tbody>
+		</table>
+	);
+}
+
+function Changes({ changes, labels }: { changes: ReadChange[]; labels: ReadLabels }) {
+	return (
+		<div className="rd-beat rd-changes">
+			<table className="rd-changes-table">
+				<thead>
+					<tr>
+						<th scope="col" className="rd-now">
+							{labels.now}
+						</th>
+						<th scope="col" className="rd-after">
+							{labels.after}
+						</th>
+					</tr>
+				</thead>
+				<tbody>
+					{changes.map((change, i) => (
+						// biome-ignore lint/suspicious/noArrayIndexKey: rows are static content in a fixed order
+						<tr key={i}>
+							<td className="rd-now" data-label={labels.now}>
+								{filled(change.now) && <Runs paragraph={change.now} />}
+							</td>
+							<td className="rd-after" data-label={labels.after}>
+								{filled(change.after) && <Runs paragraph={change.after} />}
+							</td>
+						</tr>
+					))}
+				</tbody>
+			</table>
+		</div>
+	);
+}
+
+function Recommend({ items, label }: { items: ReadParagraph[]; label: string }) {
+	return (
+		<div className="rd-beat rd-recommend">
+			<h4>{label}</h4>
+			<ul className="rd-checks">
+				{items.map((item, i) => (
+					// biome-ignore lint/suspicious/noArrayIndexKey: recommendations are static content in a fixed order
+					<li key={i}>
+						<Check size={16} strokeWidth={2.5} aria-hidden="true" />
+						<span>
+							<Runs paragraph={item} />
+						</span>
+					</li>
+				))}
+			</ul>
+		</div>
+	);
+}
+
+function Gist({
+	tiers,
+	title,
+	gradeKey,
+	labels,
+}: {
+	tiers: ReadTier[];
+	title?: string;
+	gradeKey?: ReadProps["gradeKey"];
+	labels: ReadLabels;
+}) {
+	const key = gradeKey ?? [];
+	return (
+		<section className="rd-gist" aria-label={title ? undefined : labels.gist}>
+			{(title || key.length > 0) && (
+				<div className="op-ov-head">
+					{title && <h2 className="op-ov-title">{title}</h2>}
+					{key.length > 0 && (
+						<ul className="op-legend">
+							{key.map((entry) => (
+								<li key={entry.grade}>
+									<GradeChip grade={entry.grade} />
+									<span>{entry.label}</span>
+								</li>
+							))}
+						</ul>
+					)}
+				</div>
+			)}
+			<div className="rd-gist-card">
+				<table className="rd-gist-table">
+					<thead>
+						<tr>
+							<th scope="col" className="rd-gist-section">
+								{labels.section}
+							</th>
+							<th scope="col" className="rd-gist-grade">
+								{labels.grade}
+							</th>
+							<th scope="col" className="rd-gist-read">
+								{labels.gist}
+							</th>
+						</tr>
+					</thead>
+					{tiers.map((tier) => (
+						<tbody key={tier.title}>
+							<tr className="rd-gist-tier">
+								<th scope="rowgroup" colSpan={3}>
+									{tier.title}
+								</th>
+							</tr>
+							{tier.sections.map((section) => (
+								<tr key={section.id}>
+									<th scope="row" className="rd-gist-section">
+										<a href={`#${section.id}`}>{section.name}</a>
+									</th>
+									<td className="rd-gist-grade">
+										{section.grade ? (
+											<>
+												<span className="op-sr-only">{gradeLabel[section.grade]}</span>
+												<span aria-hidden="true">
+													<GradeChip grade={section.grade} />
+												</span>
+											</>
+										) : (
+											<>
+												<span className="op-sr-only">{labels.notGraded}</span>
+												<span className="op-dash" aria-hidden="true" />
+											</>
+										)}
+									</td>
+									<td className="rd-gist-read">
+										<Runs paragraph={section.gist} />
+									</td>
+								</tr>
+							))}
+						</tbody>
+					))}
+				</table>
+			</div>
+		</section>
+	);
+}
+
+function Section({ section, labels }: { section: ReadSection; labels: ReadLabels }) {
+	const tools = (section.tools ?? section.sources ?? []).filter((tool) => tool?.label?.trim());
+	const found = (section.found ?? []).filter(filled);
+	const facts = (section.facts ?? []).filter((fact) => filled(fact?.value));
+	const examples = (section.examples ?? [])
+		.map((list) => ({ title: list?.title, items: (list?.items ?? []).filter(filled) }))
+		.filter((list) => list.items.length > 0);
+	const shots = section.shots ?? [];
+	const changes = (section.changes ?? []).filter(
+		(change) => filled(change?.now) || filled(change?.after),
+	);
+	const recommend = (section.recommend ?? []).filter(filled);
+	const showed = found.length + facts.length + examples.length + shots.length > 0;
+	return (
+		<section className="op-topic rd-section" id={section.id}>
+			<header className="op-topic-head">
+				<div>
+					<p className="rd-name">{section.name}</p>
+					<h3>{section.question}</h3>
+				</div>
+				{section.grade && (
+					<>
+						<span className="op-sr-only">{`${labels.grade} ${gradeLabel[section.grade]}`}</span>
+						<span className="rd-grade" aria-hidden="true">
+							<GradeChip grade={section.grade} />
+						</span>
+					</>
+				)}
+			</header>
+			{tools.length > 0 && <Tools tools={tools} label={labels.tools} />}
+			{showed && (
+				<div className="rd-beat rd-found">
+					<h4>{labels.found}</h4>
+					{found.map((paragraph, i) => (
+						// biome-ignore lint/suspicious/noArrayIndexKey: paragraphs are static content in a fixed order
+						<Paragraph paragraph={paragraph} key={i} />
+					))}
+					{facts.length > 0 && <Facts facts={facts} />}
+					{examples.map((list, i) => (
+						// biome-ignore lint/suspicious/noArrayIndexKey: lists are static content in a fixed order, and a title may repeat
+						<div className="rd-examples-block" key={i}>
+							{list.title && <h5>{list.title}</h5>}
+							<ul className="rd-examples">
+								{list.items.map((example, j) => (
+									// biome-ignore lint/suspicious/noArrayIndexKey: examples are static content in a fixed order
+									<li key={j}>
+										<Runs paragraph={example} />
+									</li>
+								))}
+							</ul>
+						</div>
+					))}
+					{shots.length > 0 && (
+						<div className="rd-shots" data-count={Math.min(shots.length, 3)}>
+							{shots.map((shot) => (
+								<Shot shot={shot} key={shot.src} />
+							))}
+						</div>
+					)}
+				</div>
+			)}
+			{filled(section.why) && (
+				<div className="rd-beat rd-why">
+					<h4>{labels.why}</h4>
+					<Paragraph paragraph={section.why} />
+				</div>
+			)}
+			{changes.length > 0 && <Changes changes={changes} labels={labels} />}
+			{recommend.length > 0 && <Recommend items={recommend} label={labels.recommend} />}
+		</section>
+	);
+}
+
+function Plan({ plan, labels }: { plan: ReadPlan; labels: ReadLabels }) {
+	return (
+		<section className="rd-plan" id={plan.id}>
+			<h2>{plan.title ?? labels.plan}</h2>
+			{filled(plan.lead) && <Paragraph paragraph={plan.lead} className="rd-plan-lead" />}
+			<ol className="rd-steps">
+				{plan.steps.map((step) => (
+					<li className="rd-step" key={step.title}>
+						<p>
+							<b className="rd-step-title">{step.title}</b>
+							{step.who && (
+								<>
+									{" "}
+									<span className="rd-step-who">{step.who}</span>
+								</>
+							)}
+							{filled(step.body) && (
+								<>
+									{" "}
+									<Runs paragraph={step.body} />
+								</>
+							)}
+						</p>
+					</li>
+				))}
+			</ol>
+		</section>
+	);
+}
+
+export function Read({
+	title,
+	preparedFor,
+	date,
+	lede,
+	gistTitle,
+	gradeKey,
+	tiers,
+	plan,
+	close,
+	labels: overrides,
+}: ReadProps) {
+	const labels = { ...readLabels, ...overrides };
+	const shownTiers = tiers.filter((tier) => tier.sections.length > 0);
+	return (
+		<div className="op rd">
+			<article className="op-doc rd-doc">
+				<header className="op-head">
+					<p className="op-meta">
+						{labels.preparedFor} <b>{preparedFor}</b>
+						<span className="op-meta-sep" aria-hidden="true">
+							{" · "}
+						</span>
+						<span className="op-meta-date">{date}</span>
+					</p>
+					<h1>{title}</h1>
+					{filled(lede) && <Paragraph paragraph={lede} className="op-intro rd-lede" />}
+				</header>
+				{shownTiers.length > 0 && (
+					<Gist tiers={shownTiers} title={gistTitle} gradeKey={gradeKey} labels={labels} />
+				)}
+				{shownTiers.map((tier) => (
+					<div className="rd-tier" key={tier.title}>
+						<div className="op-part" id={tier.id}>
+							<h2>{tier.title}</h2>
+							{tier.lead && <p>{tier.lead}</p>}
+						</div>
+						{tier.sections.map((section) => (
+							<Section section={section} labels={labels} key={section.id} />
+						))}
+					</div>
+				))}
+				{plan.steps.length > 0 && <Plan plan={plan} labels={labels} />}
+				{filled(close.line) && <Paragraph paragraph={close.line} className="rd-closing" />}
+				{close.signOff && close.person && (
+					<footer className="op-close rd-close">
+						<SignOff signOff={close.signOff} person={close.person} />
+					</footer>
+				)}
+			</article>
+		</div>
+	);
+}

package/src/documents/Report.tsx

@@ -0,0 +1,135 @@
+import {
+	GradeChip,
+	SignOff,
+	type WriteupGrade,
+	type WriteupPerson,
+} from "@atelic-action/ui/artifact";
+import type { ReactNode } from "react";
+
+/**
+ * The monthly page: what an Operate client gets each month, as one printed
+ * letter sheet and its hosted twin. Its shape is the practice's
+ * FOOTPRINT.md, under What the Owner Gets: the title and the period, then
+ * the leads block answering the four questions the Statement of Work
+ * promises, in that order, each a figure and one plain sentence; then the
+ * seven grades with what moved since last month and since the baseline; then
+ * the sign off. It wears the writeup's grade chip and sign off, and the
+ * artifact shell's header on screen; print drops the header and the credit
+ * band, so the sheet is the document alone.
+ */
+
+export interface ReportLead {
+	/** The figure, e.g. "31 leads" or "$1,240". */
+	figure: ReactNode;
+	/** One plain sentence on what the figure means to the owner. */
+	sentence: ReactNode;
+}
+
+/** The four questions, answered in this order on every monthly page. */
+export interface ReportLeads {
+	cameIn: ReportLead;
+	fromWhere: ReportLead;
+	cost: ReportLead;
+	closed: ReportLead;
+}
+
+export interface ReportGradeRow {
+	/** The tier, e.g. "Health". */
+	tier: string;
+	/** The section's trade name, e.g. "Local SEO". */
+	section: string;
+	/** The grade this month: the one judgement, in full color. */
+	now: WriteupGrade;
+	/** The grade last month; omit on the first month. */
+	lastMonth?: WriteupGrade;
+	/** The grade in the baseline snapshot, the first taken on private sources. */
+	baseline?: WriteupGrade;
+	/** One line on what moved, in the owner's words. */
+	moved: string;
+}
+
+export interface ReportProps {
+	title: string;
+	/** The period as printed, e.g. "September 2026". */
+	period: string;
+	leads: ReportLeads;
+	/** The seven sections, in the footprint's order. */
+	grades: ReportGradeRow[];
+	/** The sign off, the same lockup the writeup closes on. */
+	close: { signOff: string; person: WriteupPerson };
+}
+
+/**
+ * The questions are the monthly page's contract with the Statement of Work,
+ * the same on every client's page, so they live here rather than in content.
+ */
+const QUESTIONS: { key: keyof ReportLeads; label: string }[] = [
+	{ key: "cameIn", label: "What Came In" },
+	{ key: "fromWhere", label: "From Where" },
+	{ key: "cost", label: "What It Cost" },
+	{ key: "closed", label: "What It Closed" },
+];
+
+function Earlier({ grade, label }: { grade?: WriteupGrade; label: string }) {
+	return (
+		<td className="rp-earlier" data-label={label}>
+			{grade && <GradeChip grade={grade} />}
+		</td>
+	);
+}
+
+export function Report({ title, period, leads, grades, close }: ReportProps) {
+	let lastTier = "";
+	return (
+		<div className="rp">
+			<article className="rp-sheet">
+				<header className="rp-head">
+					<div className="rp-period">{period}</div>
+					<h1>{title}</h1>
+				</header>
+				<div className="rp-leads">
+					{QUESTIONS.map(({ key, label }) => (
+						<section className="rp-lead" key={key}>
+							<h2 className="rp-q">{label}</h2>
+							<div className="rp-figure">{leads[key].figure}</div>
+							<p>{leads[key].sentence}</p>
+						</section>
+					))}
+				</div>
+				<table className="rp-grades">
+					<thead>
+						<tr>
+							<th scope="col">Tier</th>
+							<th scope="col">Section</th>
+							<th scope="col">Now</th>
+							<th scope="col">Last Month</th>
+							<th scope="col">Baseline</th>
+							<th scope="col">What Moved</th>
+						</tr>
+					</thead>
+					<tbody>
+						{grades.map((row) => {
+							const tier = row.tier === lastTier ? "" : row.tier;
+							lastTier = row.tier;
+							return (
+								<tr key={row.section} className={tier ? "is-tier-start" : undefined}>
+									<td className="rp-tier">{tier}</td>
+									<td className="rp-section">{row.section}</td>
+									<td className="rp-now" data-label="Now">
+										<GradeChip grade={row.now} />
+									</td>
+									<Earlier grade={row.lastMonth} label="Last Month" />
+									<Earlier grade={row.baseline} label="Baseline" />
+									<td className="rp-moved">{row.moved}</td>
+								</tr>
+							);
+						})}
+					</tbody>
+				</table>
+				<footer className="rp-close">
+					<SignOff signOff={close.signOff} person={close.person} />
+				</footer>
+			</article>
+		</div>
+	);
+}