@atelic-action/ui 0.16.1 → 0.17.0

package/README.md

@@ -229,7 +229,7 @@ The two pieces a reader sees are ordinary components, in `@atelic-action/ui/comp
 
 `@atelic-action/ui/artifact` is everything the artifact template shared across its cuts, so a fix reaches every business's documents with one version bump:
 
-- **The documents:** `Writeup`, `Report`, and `Gate` (the sealed document, with its `GatePayload` type; a reader's address is the key, so a payload never lists it, and the component identifies a reader to HubSpot by the address they typed), plus the `GradeChip` and `SignOff` the first two share, and every content type they take (`WriteupProps`, `ReportProps`, `GateProps`, and the rest).
+- **The documents:** `Writeup`, `Report`, `Note`, and `Gate` (the sealed document, with its `GatePayload` type; a reader's address is the key, so a payload never lists it, and the component identifies a reader to HubSpot by the address they typed), plus the `GradeChip` and `SignOff` they share, and every content type they take (`WriteupProps`, `ReportProps`, `NoteProps`, `GateProps`, and the rest).
 - **The shell:** `ArtifactShell`, the `.mkt` scope with the skip link, the dark header, the credit band, and the watermark around a page.
 - **The contract and the head:** the `ArtifactConfig` types, and `buildPageHead` and `canonicalUrl` with their `PageMeta` type.
 - **Who opened it:** `mintToken`, `sealReader`, `openReader`, `readerId`, `readerLink`, and `whoIsReading`. The same six are also built and exported alone as `@atelic-action/ui/artifact/readers`, because a Playwright spec and a script run under Node, which compiles nothing inside `node_modules`.
@@ -248,6 +248,8 @@ export function ArtifactShell(props: Omit<ArtifactShellProps, "currentPath">) {
 }
 ```
 
+**The note** is the first touch for a business whose site publishes no email address, served at `/notes` and wrapped in `ArtifactShell` exactly as the writeup is. It is the writeup's sibling, not a variant: a title and a dateline, the opener, two lanes of findings (what the customer sees, what sits under the hood), the steps the work would start with, and the close over the shared `SignOff`. Every prop is plain data, so a routine can write a note as JSON; a paragraph is a string or an array of strings and `{ text, href }` links, and the sign off person's `role` is the one field that also takes a node. A finding is a `Callout` with its `WriteupShot` under it. It reads on a phone first, sets the two lanes side by side when wide and on paper, and prints to one letter sheet under the writeup's `@page`.
+
 The documents import no stylesheet of their own. A site imports `@atelic-action/ui/styles/artifact.css` in its base sheet after `gate.css` and before its `theme.css`, so every page carries the rules whichever route it is. The sheet holds two `@page` rules, the monthly page's and then the writeup's, and the later one wins for every page a site prints; the order inside the sheet is the order the template's build bundled them in and is load bearing.
 
 ### The Artifact Vite Config

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "0.16.1",
+	"version": "0.17.0",
 	"description": "Shared UI for the Atelic templates: site chrome, base styles, the component library, and the access gate they install",
 	"type": "module",
 	"license": "UNLICENSED",

package/src/artifact/Note.tsx

@@ -0,0 +1,188 @@
+import { Callout } from "../components";
+import { newTabProps } from "../lib/newTabProps";
+import { Shot, type WriteupShot } from "./Shot";
+import { SignOff, type WriteupPerson } from "./SignOff";
+
+/**
+ * The note: the first touch, for a business whose site publishes no email
+ * address, written as a short page and left at `<short>.atelic.me/notes`. It
+ * is the first touch email set as a document, so it carries no grades, no
+ * sections, and no tables: a title, the opener, what the customer sees and
+ * what sits under the hood, where the work would start, and the close. It
+ * reads on a phone first and prints to one letter sheet.
+ *
+ * It is the writeup's sibling, not a variant of it: a site wraps it in
+ * ArtifactShell exactly as it wraps the writeup, and it reuses the writeup's
+ * pieces where they fit (the Callout a finding is set in, the owner's screen,
+ * the sign off). Every prop is plain data, so a routine can write a note 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 interface NoteLink {
+	text: string;
+	href: string;
+}
+
+/** A paragraph: a plain string, or runs of text and links in order. */
+export type NoteParagraph = string | Array<string | NoteLink>;
+
+/** One defect and what it costs, with the owner's screen under it when there is one. */
+export interface NoteFinding {
+	/** The defect, in a full sentence. */
+	lead: string;
+	/** The consequence: what it costs the business. */
+	body: string;
+	/**
+	 * Where the defect can be seen for oneself. The lead links there: in a new
+	 * tab for an http(s) link, in place otherwise.
+	 */
+	href?: string;
+	/** The owner's own screen, rendered under the finding. */
+	shot?: WriteupShot;
+}
+
+/** One side of the read, e.g. "What your customer sees", with one or two findings. */
+export interface NoteLane {
+	heading: string;
+	findings: NoteFinding[];
+}
+
+/** One place the work would start. */
+export interface NoteStep {
+	/** The step, set in bold. */
+	lead: string;
+	/** What it does, after the lead. */
+	body?: string;
+}
+
+/** Where the work would start: the line that introduces it, then the steps. */
+export interface NoteStart {
+	/** The line over the steps, e.g. "I would start by:". */
+	lead: string;
+	items: NoteStep[];
+}
+
+/** The close: who is writing and the offer, then the sign off. */
+export interface NoteClose {
+	/** The sender paragraph, then the offer line with its scheduling link and the exit sentence. */
+	paragraphs: NoteParagraph[];
+	signOff: string;
+	person: WriteupPerson;
+}
+
+export interface NoteProps {
+	title: string;
+	/** The business, set in the dateline: "Prepared for <business>, <date>". */
+	preparedFor: string;
+	/** The ISO date, e.g. "2026-10-09". */
+	date: string;
+	/** The street sighting and a kudos, then the gap sentence. */
+	opener: NoteParagraph;
+	/** "What your customer sees" and "What I see under the hood", in that order. */
+	lanes: NoteLane[];
+	start: NoteStart;
+	close: NoteClose;
+}
+
+/** A link opens in a new tab when it leaves the page, and in place when it is an anchor or a mail link. */
+function NoteAnchor({ href, children }: { href: string; children: string }) {
+	return (
+		<a href={href} {...newTabProps(href, /^https?:/i.test(href))}>
+			{children}
+		</a>
+	);
+}
+
+/** A paragraph with nothing to read: a blank string, or runs that are all blank strings. A link always counts. */
+function isEmpty(paragraph: NoteParagraph): boolean {
+	const runs = typeof paragraph === "string" ? [paragraph] : paragraph;
+	return runs.every((run) => typeof run === "string" && run.trim() === "");
+}
+
+function Paragraph({ paragraph, className }: { paragraph: NoteParagraph; className?: string }) {
+	const runs = typeof paragraph === "string" ? [paragraph] : paragraph;
+	return (
+		<p className={className}>
+			{runs.map((run, i) =>
+				typeof run === "string" ? (
+					run
+				) : (
+					// biome-ignore lint/suspicious/noArrayIndexKey: runs are static content in a fixed order
+					<NoteAnchor href={run.href} key={i}>
+						{run.text}
+					</NoteAnchor>
+				),
+			)}
+		</p>
+	);
+}
+
+function Finding({ finding }: { finding: NoteFinding }) {
+	return (
+		<li className="nt-finding">
+			<Callout
+				tone="warn"
+				title={
+					finding.href ? <NoteAnchor href={finding.href}>{finding.lead}</NoteAnchor> : finding.lead
+				}
+			>
+				{finding.body}
+			</Callout>
+			{finding.shot && <Shot shot={finding.shot} />}
+		</li>
+	);
+}
+
+export function Note({ title, preparedFor, date, opener, lanes, start, close }: NoteProps) {
+	const shownLanes = lanes.filter((lane) => lane.findings.length > 0);
+	const paragraphs = close.paragraphs.filter((paragraph) => !isEmpty(paragraph));
+	return (
+		<div className="nt">
+			<article className="nt-doc">
+				<header className="nt-head">
+					<p className="nt-meta">
+						Prepared for <b>{preparedFor}</b>, <span className="nt-meta-date">{date}</span>
+					</p>
+					<h1>{title}</h1>
+				</header>
+				{!isEmpty(opener) && <Paragraph paragraph={opener} className="nt-opener" />}
+				{shownLanes.length > 0 && (
+					<div className="nt-lanes">
+						{shownLanes.map((lane) => (
+							<section className="nt-lane" key={lane.heading}>
+								<h2>{lane.heading}</h2>
+								<ul className="nt-findings">
+									{lane.findings.map((finding) => (
+										<Finding finding={finding} key={finding.lead} />
+									))}
+								</ul>
+							</section>
+						))}
+					</div>
+				)}
+				{start.items.length > 0 && (
+					<section className="nt-start">
+						<p className="nt-start-lead">{start.lead}</p>
+						<ul>
+							{start.items.map((step) => (
+								<li key={step.lead}>
+									<b>{step.lead}</b>
+									{step.body && <> {step.body}</>}
+								</li>
+							))}
+						</ul>
+					</section>
+				)}
+				<footer className="nt-close">
+					{paragraphs.map((paragraph, i) => (
+						// biome-ignore lint/suspicious/noArrayIndexKey: paragraphs are static content in a fixed order
+						<Paragraph paragraph={paragraph} key={i} />
+					))}
+					<SignOff signOff={close.signOff} person={close.person} />
+				</footer>
+			</article>
+		</div>
+	);
+}

package/src/artifact/Shot.tsx

@@ -0,0 +1,32 @@
+import { newTabProps } from "../lib/newTabProps";
+
+export interface WriteupShot {
+	/** The crop shown on the page. */
+	src: string;
+	alt: string;
+	/** The full screenshot the crop opens in a new tab; omit to render the crop alone. */
+	href?: string;
+	caption: string;
+}
+
+/**
+ * The owner's own screen: the crop, opening the full screenshot in a new tab
+ * when it has one, over its caption. The writeup and the note both wear it;
+ * its styles (.op-shot) are the writeup's, and the note only sizes it.
+ */
+export function Shot({ shot }: { shot: WriteupShot }) {
+	return (
+		<figure className="op-shot">
+			{shot.href ? (
+				<a href={shot.href} {...newTabProps(shot.href, true)}>
+					<img src={shot.src} alt={shot.alt} loading="lazy" />
+				</a>
+			) : (
+				<span className="op-shot-frame">
+					<img src={shot.src} alt={shot.alt} loading="lazy" />
+				</span>
+			)}
+			<figcaption>{shot.caption}</figcaption>
+		</figure>
+	);
+}

package/src/artifact/Writeup.tsx

@@ -19,9 +19,11 @@ import {
 } from "../components";
 import { newTabProps } from "../lib/newTabProps";
 import { GradeChip, gradeLabel, type WriteupGrade } from "./GradeChip";
+import { Shot, type WriteupShot } from "./Shot";
 import { SignOff, type WriteupPerson } from "./SignOff";
 
 export type { WriteupGrade } from "./GradeChip";
+export type { WriteupShot } from "./Shot";
 export type { WriteupPerson } from "./SignOff";
 
 /**
@@ -43,15 +45,6 @@ export type { WriteupPerson } from "./SignOff";
 /** How a mark, a bar segment, or a zone reads; the shared package's tones. */
 export type WriteupTone = Tone;
 
-export interface WriteupShot {
-	/** The crop shown on the page. */
-	src: string;
-	alt: string;
-	/** The full screenshot the crop opens in a new tab; omit to render the crop alone. */
-	href?: string;
-	caption: string;
-}
-
 export interface WriteupBullet {
 	/** The point, in a full sentence. The icon sits beside it. */
 	lead: string;
@@ -391,23 +384,6 @@ function Table({ block }: { block: WriteupTable }) {
 	);
 }
 
-function Shot({ shot }: { shot: WriteupShot }) {
-	return (
-		<figure className="op-shot">
-			{shot.href ? (
-				<a href={shot.href} {...newTabProps(shot.href, true)}>
-					<img src={shot.src} alt={shot.alt} loading="lazy" />
-				</a>
-			) : (
-				<span className="op-shot-frame">
-					<img src={shot.src} alt={shot.alt} loading="lazy" />
-				</span>
-			)}
-			<figcaption>{shot.caption}</figcaption>
-		</figure>
-	);
-}
-
 function Findings({ block, brief }: { block: WriteupFindings; brief?: string }) {
 	const hasShots = Boolean(block.shot || brief);
 	return (

package/src/artifact/index.ts

@@ -11,6 +11,7 @@ export type {
 export { ErrorFallback } from "./ErrorFallback";
 export { Gate, type GatePayload, type GatePerson, type GateProps, normalizeEmail } from "./Gate";
 export { GradeChip, gradeLabel } from "./GradeChip";
+export * from "./Note";
 export { buildPageHead, canonicalUrl, type PageMeta } from "./pageHead";
 export * from "./Report";
 export {

package/src/styles/artifact.css

@@ -3,7 +3,8 @@
    share. Moved whole from the artifact template, in the order its build
    bundled them (the shared classes, the stage, the monthly page, the
    writeup), which the two @page rules depend on: the later one wins, and
-   the writeup's is the later one. They sit in the package's layer like
+   the writeup's is the later one. The note follows the writeup and sets
+   no @page, so the writeup's stays the one that wins. They sit in the package's layer like
    every sheet here, so any rule a site writes outside a layer still wins
    over them whatever its specificity. */
 @layer atelic-ui {
@@ -1859,4 +1860,250 @@
 			display: block;
 		}
 	}
+
+	/* =================================================================
+	   THE NOTE: the first touch set as a page (Note.tsx). A letter, not a
+	   report: one narrow column of running text, read on a phone first.
+
+	   - Phone first: the base rules are the phone's. The two lanes stack,
+	     each finding a Callout with the owner's screen under it.
+	   - Wide (721px and up) and print: the two lanes sit side by side.
+	   - Print: one letter sheet. The chrome steps aside (the writeup's print
+	     rules already hide the header and the credit band on any artifact
+	     page), the type comes down, and the screens shrink. The note sets
+	     no @page of its own: the writeup's, the later one in this sheet,
+	     sets letter paper for every artifact page.
+
+	   Tokens only. The finding is the shared Callout (styles/components.css),
+	   the screen the writeup's .op-shot, the sign off the shared .op-who;
+	   this sheet sets the letter around them and their sizes here.
+	   ================================================================= */
+	/* The borrowed .op-shot reads the writeup's own two tokens, mapped here as
+	   the writeup's .op root maps them. */
+	:is(.mkt, .atelic-ui) .nt {
+		--op-card: var(--card);
+		--op-ink-faint: var(--neutral-500);
+		font-family: var(--font-sans);
+		color: var(--ink);
+		background: var(--surface);
+	}
+	:is(.mkt, .atelic-ui) .nt-doc {
+		max-width: 760px;
+		margin: 0 auto;
+		padding: calc(var(--nav-height) + 22px) 18px 48px;
+		font-size: 17px;
+		line-height: 1.6;
+		print-color-adjust: exact;
+		-webkit-print-color-adjust: exact;
+	}
+	:is(.mkt, .atelic-ui) .nt a {
+		color: var(--primary);
+		text-decoration: underline;
+		text-underline-offset: 2px;
+		text-decoration-thickness: 1px;
+		overflow-wrap: anywhere;
+	}
+	:is(.mkt, .atelic-ui) .nt a:hover {
+		text-decoration-thickness: 2px;
+	}
+
+	/* ---- the head: who it is for, then the title ---- */
+	:is(.mkt, .atelic-ui) .nt-meta {
+		margin: 0 0 10px;
+		font-family: var(--font-mono);
+		font-size: 12.5px;
+		letter-spacing: 0.04em;
+		color: var(--neutral-500);
+	}
+	:is(.mkt, .atelic-ui) .nt-meta b {
+		font-weight: 500;
+		color: var(--ink-soft);
+	}
+	:is(.mkt, .atelic-ui) .nt-meta-date {
+		white-space: nowrap;
+	}
+	:is(.mkt, .atelic-ui) .nt h1 {
+		font-size: clamp(30px, 6vw, 40px);
+		font-weight: 650;
+		letter-spacing: -0.03em;
+		line-height: 1.1;
+		margin: 0;
+		text-wrap: balance;
+		color: var(--ink);
+	}
+
+	/* ---- the opener: the letter's first paragraph ---- */
+	:is(.mkt, .atelic-ui) .nt-opener {
+		margin: 18px 0 0;
+		font-size: 18px;
+		line-height: 1.6;
+		color: var(--ink);
+		text-wrap: pretty;
+	}
+
+	/* ---- the two lanes, each a heading and its findings ---- */
+	:is(.mkt, .atelic-ui) .nt-lanes {
+		display: grid;
+		grid-template-columns: minmax(0, 1fr);
+		gap: 26px;
+		margin-top: 30px;
+		padding-top: 24px;
+		border-top: 1px solid var(--neutral-100);
+	}
+	:is(.mkt, .atelic-ui) .nt-lane {
+		min-width: 0;
+	}
+	:is(.mkt, .atelic-ui) .nt-lane h2 {
+		margin: 0 0 14px;
+		font-size: 19px;
+		font-weight: 650;
+		letter-spacing: -0.015em;
+		line-height: 1.25;
+		color: var(--ink);
+	}
+	:is(.mkt, .atelic-ui) .nt-findings {
+		list-style: none;
+		margin: 0;
+		padding: 0;
+		display: flex;
+		flex-direction: column;
+		gap: 18px;
+	}
+	:is(.mkt, .atelic-ui) .nt-finding .callout {
+		font-size: 16px;
+		line-height: 1.5;
+	}
+	/* The screen sits under its finding, set in from the icon so it lines up
+	   with the words. It keeps its own shape, never wider than the lane and
+	   never so tall it carries the page. */
+	:is(.mkt, .atelic-ui) .nt-finding .op-shot {
+		margin: 10px 0 0 28px;
+	}
+	:is(.mkt, .atelic-ui) .nt-finding .op-shot a,
+	:is(.mkt, .atelic-ui) .nt-finding .op-shot-frame {
+		width: fit-content;
+		max-width: 100%;
+	}
+	:is(.mkt, .atelic-ui) .nt-finding .op-shot img {
+		width: auto;
+		max-width: 100%;
+		max-height: 340px;
+	}
+	:is(.mkt, .atelic-ui) .nt-finding .op-shot figcaption {
+		font-size: 12.5px;
+		line-height: 1.45;
+		color: var(--neutral-500);
+	}
+
+	/* ---- where the work would start ---- */
+	:is(.mkt, .atelic-ui) .nt-start {
+		margin-top: 30px;
+		padding-top: 24px;
+		border-top: 1px solid var(--neutral-100);
+	}
+	:is(.mkt, .atelic-ui) .nt-start-lead {
+		margin: 0 0 10px;
+		font-weight: 650;
+		color: var(--ink);
+	}
+	/* The site base strips list markers; the steps want theirs back. */
+	:is(.mkt, .atelic-ui) .nt-start ul {
+		margin: 0;
+		padding-left: 1.2em;
+		list-style: disc;
+		display: grid;
+		gap: 8px;
+		color: var(--ink-soft);
+	}
+	:is(.mkt, .atelic-ui) .nt-start li {
+		padding-left: 2px;
+	}
+	:is(.mkt, .atelic-ui) .nt-start li::marker {
+		color: var(--primary);
+	}
+	:is(.mkt, .atelic-ui) .nt-start b {
+		font-weight: 600;
+		color: var(--ink);
+	}
+
+	/* ---- the close: who is writing, the offer, then the sign off ---- */
+	:is(.mkt, .atelic-ui) .nt-close {
+		margin-top: 30px;
+		padding-top: 24px;
+		border-top: 1px solid var(--neutral-100);
+	}
+	:is(.mkt, .atelic-ui) .nt-close p {
+		margin: 0 0 14px;
+		text-wrap: pretty;
+	}
+	:is(.mkt, .atelic-ui) .nt-close .op-who {
+		margin-top: 22px;
+		gap: 14px;
+		font-size: 14px;
+		line-height: 1.6;
+		color: var(--neutral-500);
+	}
+	:is(.mkt, .atelic-ui) .nt-close .op-who img {
+		width: 56px;
+		height: 56px;
+	}
+	:is(.mkt, .atelic-ui) .nt-close .op-sign {
+		font-size: 24px;
+		margin-bottom: 8px;
+	}
+	/* The sign off's own links read as the writeup's do: quiet, in the text color. */
+	:is(.mkt, .atelic-ui) .nt-close .op-who a {
+		color: inherit;
+		text-decoration: none;
+	}
+
+	/* ---- wide, and on paper: the two lanes side by side ---- */
+	@media print, (min-width: 721px) {
+		:is(.mkt, .atelic-ui) .nt-doc {
+			padding: calc(var(--nav-height) + 36px) 24px 64px;
+		}
+		:is(.mkt, .atelic-ui) .nt-lanes {
+			grid-template-columns: repeat(2, minmax(0, 1fr));
+			gap: 32px;
+		}
+	}
+
+	/* ---- print: one letter sheet ---- */
+	@media print {
+		html:has(:is(.mkt, .atelic-ui) .nt-doc) {
+			zoom: 0.8;
+		}
+		:is(.mkt, .atelic-ui) .nt {
+			background: none;
+		}
+		:is(.mkt, .atelic-ui) .nt-doc {
+			max-width: none;
+			padding: 0;
+			font-size: 15px;
+			line-height: 1.5;
+		}
+		:is(.mkt, .atelic-ui) .nt-opener {
+			font-size: 16px;
+		}
+		:is(.mkt, .atelic-ui) .nt-lanes,
+		:is(.mkt, .atelic-ui) .nt-start,
+		:is(.mkt, .atelic-ui) .nt-close {
+			margin-top: 20px;
+			padding-top: 16px;
+		}
+		:is(.mkt, .atelic-ui) .nt-finding .callout {
+			font-size: 14.5px;
+		}
+		:is(.mkt, .atelic-ui) .nt-finding .op-shot img {
+			max-height: 1.9in;
+		}
+		:is(.mkt, .atelic-ui) .nt-finding .op-shot a {
+			cursor: auto;
+		}
+		:is(.mkt, .atelic-ui) .nt-finding,
+		:is(.mkt, .atelic-ui) .nt-start,
+		:is(.mkt, .atelic-ui) .nt-close {
+			break-inside: avoid;
+		}
+	}
 }