@atelic-action/artifact 1.2.0 → 1.3.0

package/README.md

@@ -7,7 +7,7 @@ The documents the practice hands or sends a business, as a published package and
 
 Three layers, each a version the next depends on (ATE-671): `@atelic-action/ui` holds the pieces, this package holds the documents built from them, and each business's folder holds only its content, routes, and config. A document fix reaches a folder by bumping this package; a piece fix by bumping ui here, then this package in the folder.
 
-Five artifacts live in the template site: the **writeup** at `/writeup`, the graded document an owner gets, a web page first with its printed copy derived from it; the **read** at `/read`, what a customer gets at the end of an engagement's first week, the baseline's grades explained by cause with the plan in order; the **proposal** at `/proposal`, sealed into the page and opened by the reader's own email address; the **monthly page** at `/report`, what an Operate client gets each month on one letter sheet; and the **note** at `/notes`, the first touch for a business whose site publishes no email address, set as a short page. The bare host sends a reader to the writeup. Every artifact prerenders to static HTML, stays out of every index, and carries the practice's brand by default.
+Five artifacts live in the template site: the **writeup** at `/writeup`, the graded document an owner gets, a web page first with its printed copy derived from it; the **read** at `/the-read`, what a customer gets at the end of an engagement's first week, the baseline's grades explained by cause with the plan in order; the **proposal** at `/proposal`, sealed into the page and opened by the reader's own email address; the **monthly page** at `/report`, what an Operate client gets each month on one letter sheet; and the **note** at `/notes`, the first touch for a business whose site publishes no email address, set as a short page. The bare host sends a reader to the writeup. Every artifact prerenders to static HTML, stays out of every index, and carries the practice's brand by default.
 
 The method behind them (the seven sections, the four grades from A to D, the rented line, what moved, and when an artifact is private) is the practice repo's `FOOTPRINT.md`. This repo builds to it and never restates it.
 
@@ -25,8 +25,8 @@ Every export of the package, all from the one entry, `@atelic-action/artifact`.
 | `ratingCell` | A star rating table cell for a writeup table, sorted by its figure | `/writeup` |
 | `WriteupBlock`, `WriteupTopic`, `WriteupPart`, `WriteupSheet`, `WriteupSummary`, `WriteupSummaryRow`, `WriteupMarkets`, `WriteupRented`, `WriteupMark`, `WriteupCell`, `WriteupTone`, and the rest of the `Writeup*` types | The shapes a writeup's content is written in | none |
 | `WriteupGrade`, `WriteupPerson`, `WriteupShot` | The grade letter, the sign off person, and the owner's screen, shared by every document, all three re exported from ui | none |
-| `Read`, `ReadProps` | The baseline's grades explained by cause: the gist table; each section read top to bottom as where we looked (the tools, linked, at the top), what it showed (a short paragraph or two, a compact table of facts, lists of examples under their own headings, and any proof pictures), why (one sentence on a tinted panel), today and after (a two column table), and what we recommend (a checklist); then the plan in order. A beat with no data is left out, heading and all | `/read` |
-| `readLabels`, `ReadLabels` | The fixed words the read sets (Prepared for, the gist table's columns, Where We Looked, What It Showed, Why, Today, After, What We Recommend, the plan's heading), each overridable through `labels` | `/read` |
+| `Read`, `ReadProps` | The baseline's grades explained by cause: the gist table, with an optional `note` callout under it for what the read leaves out; each section under its trade name with the owner's question beneath it, read top to bottom as where we looked (the tools, linked, at the top), what it showed (a short paragraph or two, a compact table of facts, lists of examples under their own headings, and any proof pictures), why (one sentence on a tinted panel), today and after (a two column table), and what we recommend (a checklist); then the plan in order. A beat with no data is left out, heading and all | `/the-read` |
+| `readLabels`, `ReadLabels` | The fixed words the read sets (Prepared for, the gist table's columns, Where We Looked, What It Showed, Why, Today, After, What We Recommend, the plan's heading), each overridable through `labels` | `/the-read` |
 | `ReadTier`, `ReadSection`, `ReadTool`, `ReadFact`, `ReadExamples`, `ReadChange`, `ReadStep`, `ReadPlan`, `ReadClose`, `ReadLink`, `ReadParagraph` | The shapes a read's content is written in, all plain data so a routine can write a read as JSON. A section's `tools` were its `sources` in 1.0.0; `sources` is still read, and rendered at the top as tools, and `ReadSource` names the same shape as `ReadTool` | none |
 | `Report`, `ReportProps` | The monthly page: the four questions, the seven grades now and before, the sign off, on one letter sheet | `/report` |
 | `ReportLead`, `ReportLeads`, `ReportGradeRow` | The shapes a monthly page's content is written in | none |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/artifact",
-	"version": "1.2.0",
+	"version": "1.3.0",
 	"description": "The composed documents the Atelic practice hands or sends a business (the writeup, the read, the monthly page, the note, and the sealed document), built from the pieces in @atelic-action/ui",
 	"type": "module",
 	"license": "MIT",

package/src/documents/Read.tsx

@@ -24,7 +24,8 @@ import { ArrowUpRight, Check } from "lucide-react";
  * 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);
+ * bottom, under its trade name with the owner's question beneath it: 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
@@ -36,7 +37,8 @@ import { ArrowUpRight, Check } from "lucide-react";
  * (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
+ * in the table and the body alike, with no change to the props; until then
+ * `note` says so in a callout under the table. 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.
@@ -81,9 +83,9 @@ export interface ReadChange {
 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. */
+	/** The section's trade name, e.g. "Technical SEO": the section's heading, and the gist table's Section column. */
 	name: string;
-	/** The question the section answers, in the owner's words, e.g. "Can Google read the site?". The section's heading. */
+	/** The question the section answers, in the owner's words, e.g. "Can Google read the site?", set under the heading. */
 	question: string;
 	/** The baseline's grade. Omit for a section not yet graded; the table shows a quiet dash. */
 	grade?: WriteupGrade;
@@ -200,6 +202,8 @@ export interface ReadProps {
 	lede: ReadParagraph;
 	/** The heading over the gist table, e.g. "At a Glance". */
 	gistTitle?: string;
+	/** A callout under the gist table, e.g. what the read leaves out and when it follows. */
+	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. */
@@ -408,8 +412,8 @@ function Section({ section, labels }: { section: ReadSection; labels: ReadLabels
 		<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>
+					<h3>{section.name}</h3>
+					<p className="rd-question">{section.question}</p>
 				</div>
 				{section.grade && (
 					<>
@@ -500,6 +504,7 @@ export function Read({
 	date,
 	lede,
 	gistTitle,
+	note,
 	gradeKey,
 	tiers,
 	plan,
@@ -523,7 +528,14 @@ export function Read({
 					{filled(lede) && <Paragraph paragraph={lede} className="op-intro rd-lede" />}
 				</header>
 				{shownTiers.length > 0 && (
-					<Gist tiers={shownTiers} title={gistTitle} gradeKey={gradeKey} labels={labels} />
+					<>
+						<Gist tiers={shownTiers} title={gistTitle} gradeKey={gradeKey} labels={labels} />
+						{filled(note) && (
+							<div className="rd-note" role="note">
+								<Paragraph paragraph={note} />
+							</div>
+						)}
+					</>
 				)}
 				{shownTiers.map((tier) => (
 					<div className="rd-tier" key={tier.title}>

package/src/documents/documents.css

@@ -2171,6 +2171,7 @@
 
 	/* Prose links read as links here, where the writeup's are quiet. */
 	.atelic-ui .rd-lede a,
+	.atelic-ui .rd-note a,
 	.atelic-ui .rd-beat a,
 	.atelic-ui .rd-gist-read a,
 	.atelic-ui .rd-plan a,
@@ -2251,13 +2252,13 @@
 	}
 
 	/* ---- a section: the trade name over the question, then its beats ---- */
-	.atelic-ui .rd-name {
-		margin: 0 0 4px;
-		font-family: var(--font-mono);
-		font-size: 11.5px;
-		letter-spacing: 0.1em;
-		text-transform: uppercase;
-		color: var(--op-ink-faint);
+	/* The owner's question sits under the section's name. */
+	.atelic-ui .rd-question {
+		margin: 4px 0 0;
+		font-size: 15.5px;
+		line-height: 1.4;
+		color: var(--op-ink-soft);
+		text-wrap: pretty;
 	}
 	.atelic-ui .rd-grade .op-grade {
 		width: 42px;
@@ -2383,6 +2384,20 @@
 	.atelic-ui .rd-examples li + li {
 		margin-top: 4px;
 	}
+	/* The note under the gist table: what the read leaves out, on the why panel's tint. */
+	.atelic-ui .rd-note {
+		margin-top: 18px;
+		padding: 12px 14px;
+		border-left: 3px solid var(--op-accent);
+		border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
+		background: var(--surface-alt);
+	}
+	.atelic-ui .rd-note p {
+		font-size: 15.5px;
+		line-height: 1.5;
+		color: var(--op-ink);
+		text-wrap: pretty;
+	}
 	/* Why is one sentence, set apart: a tinted panel with the accent's rule. */
 	.atelic-ui .rd-why {
 		padding: 12px 14px;
@@ -2668,6 +2683,7 @@
 		.atelic-ui .rd-tools,
 		.atelic-ui .rd-checks li,
 		.atelic-ui .rd-closing,
+		.atelic-ui .rd-note,
 		.atelic-ui .rd-why,
 		.atelic-ui .rd-step,
 		.atelic-ui .rd-close,