@atelic-action/ui 0.17.2 → 1.1.0

package/src/scripts/contact-canary.ts

@@ -0,0 +1,98 @@
+/**
+ * The contact relay canary: submits a token bearing test message to the live
+ * site's /api/contact and asserts the whole pipe worked. A pass means the
+ * function is deployed, its env is present, the Resend key is valid, the
+ * sending domain is verified, Resend accepted the message (200 plus an id),
+ * and the client destination the function is configured with is the one
+ * expected. The canary lands in CONTACT_CANARY_TO, never the client's inbox.
+ *
+ * Env: SITE_URL, CONTACT_EXPECTED_TO, CONTACT_CANARY_TOKEN.
+ * Usage: atelic-contact-canary   (a site's daily contact-canary workflow runs it)
+ * Exits 1 on any failure, naming the failed assertion.
+ *
+ * A SITE_URL on the reserved `.invalid` TLD (`https://canary.invalid`) is the
+ * explicit off switch, for a repo with no live site (a template): the run
+ * passes without submitting anything. An unset SITE_URL still fails, so a
+ * site that never configured the canary is caught, not silently skipped.
+ */
+
+/** The environment the canary reads: SITE_URL, CONTACT_EXPECTED_TO, and CONTACT_CANARY_TOKEN. */
+export type CanaryEnv = Record<string, string | undefined>;
+
+export interface CanaryResult {
+	verdict: "pass" | "skip" | "fail";
+	message: string;
+}
+
+const fail = (reason: string): CanaryResult => ({ verdict: "fail", message: `FAIL: ${reason}` });
+
+/**
+ * Runs the canary against the site the environment names. `fetcher` is the
+ * fetch to send with, so a test can stand in for the network.
+ */
+export async function runCanary(
+	env: CanaryEnv,
+	fetcher: typeof fetch = fetch,
+	now: Date = new Date(),
+): Promise<CanaryResult> {
+	const site = env.SITE_URL?.replace(/\/$/, "");
+	if (!site) return fail("SITE_URL is not set");
+	let host: string;
+	try {
+		host = new URL(site).hostname;
+	} catch {
+		return fail(`SITE_URL is not a URL: ${site}`);
+	}
+	if (host.endsWith(".invalid")) {
+		return { verdict: "skip", message: `skipped: SITE_URL is ${site}, the explicit off switch` };
+	}
+	const expectedTo = env.CONTACT_EXPECTED_TO;
+	const token = env.CONTACT_CANARY_TOKEN;
+	if (!expectedTo) return fail("CONTACT_EXPECTED_TO is not set");
+	if (!token) return fail("CONTACT_CANARY_TOKEN is not set");
+
+	const endpoint = `${site}/api/contact`;
+	let response: Response;
+	try {
+		response = await fetcher(endpoint, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			signal: AbortSignal.timeout(20000),
+			body: JSON.stringify({
+				name: "Contact canary",
+				email: "canary@atelic.me",
+				topic: "Canary",
+				message: `Automated contact relay check at ${now.toISOString()}. If you are reading this in the client inbox, CONTACT_CANARY_TO is misconfigured.`,
+				company: "",
+				canary: token,
+			}),
+		});
+	} catch (error) {
+		return fail(`request failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+
+	const body = (await response.json().catch(() => ({}))) as {
+		ok?: boolean;
+		id?: string | null;
+		to?: string;
+		error?: string;
+	};
+	if (response.status !== 200 || body.ok !== true) {
+		return fail(`relay returned ${response.status}${body.error ? `: ${body.error}` : ""}`);
+	}
+	if (!body.id) return fail("Resend accepted the message without an id (canary path not taken?)");
+	if (body.to !== expectedTo) {
+		return fail(`configured destination is ${body.to ?? "(none)"}, expected ${expectedTo}`);
+	}
+	return { verdict: "pass", message: `ok: Resend id ${body.id}, destination ${body.to}` };
+}
+
+/** The command: runs the canary the environment configures. */
+export async function main(): Promise<void> {
+	const result = await runCanary(process.env);
+	if (result.verdict === "fail") {
+		console.error(`[contact-canary] ${result.message}`);
+		process.exit(1);
+	}
+	console.log(`[contact-canary] ${result.message}`);
+}

package/src/scripts/serve-static.ts

@@ -5,10 +5,35 @@
  * never runs a server. The build it serves is the site's, found from the
  * working directory.
  *
+ * A marketing build served under a base path (its config's `basePath`, or the
+ * `VITE_BASE_PATH` rehearsal override) is served both ways it is served for
+ * real: under the prefix, as the cut's own Vercel host does through its two
+ * rewrites, and without it, as the host owner's proxy forwards each request
+ * with the prefix stripped (moved from template-marketing in 0.19.0).
+ *
  * Usage: atelic-serve-static   (PORT sets the port, 4173 unless given)
  */
 import { existsSync, statSync } from "node:fs";
 import { join, normalize } from "node:path";
+import { pathToFileURL } from "node:url";
+import { normalizeBasePath, stripBase } from "../routing/basePath";
+import { siteConfigPath } from "./site-config";
+
+/**
+ * The base path the build in `cwd` was made under: `VITE_BASE_PATH` when set,
+ * else the `basePath` its src/site.config.ts exports, else the root. A site
+ * with no config, or one whose config carries no base, is served at the root.
+ */
+export async function siteBasePath(
+	cwd: string,
+	env: Record<string, string | undefined> = process.env,
+): Promise<string> {
+	if (env.VITE_BASE_PATH !== undefined) return normalizeBasePath(env.VITE_BASE_PATH);
+	const path = siteConfigPath(cwd);
+	if (!existsSync(path)) return "";
+	const module = (await import(pathToFileURL(path).href)) as { site?: { basePath?: string } };
+	return normalizeBasePath(module.site?.basePath);
+}
 
 /** The file a request path names under `root`, by Vercel's clean URL rules; none on a miss. */
 export function resolveFile(root: string, pathname: string): string | undefined {
@@ -24,9 +49,10 @@ export function resolveFile(root: string, pathname: string): string | undefined
 }
 
 /** The command: serves dist/client of the working directory until stopped. */
-export function main(cwd: string = process.cwd()): void {
+export async function main(cwd: string = process.cwd()): Promise<void> {
 	const root = join(cwd, "dist", "client");
 	const port = Number(process.env.PORT ?? 4173);
+	const base = await siteBasePath(cwd);
 
 	Bun.serve({
 		// Loopback only: this serves the build to the local browser under test and
@@ -34,7 +60,7 @@ export function main(cwd: string = process.cwd()): void {
 		hostname: "127.0.0.1",
 		port,
 		fetch(request) {
-			const file = resolveFile(root, new URL(request.url).pathname);
+			const file = resolveFile(root, stripBase(base, new URL(request.url).pathname));
 			if (file) return new Response(Bun.file(file));
 			return new Response(Bun.file(join(root, "404.html")), {
 				status: 404,
@@ -43,5 +69,5 @@ export function main(cwd: string = process.cwd()): void {
 		},
 	});
 
-	console.log(`serving ${root} on http://127.0.0.1:${port}`);
+	console.log(`serving ${root} on http://127.0.0.1:${port}${base ? ` (and under ${base})` : ""}`);
 }

package/src/sections/BlogIndex.tsx

@@ -0,0 +1,57 @@
+import { ArrowUpRight } from "lucide-react";
+import { displayDate } from "../lib/displayDate";
+import { useWithBase } from "../routing/BasePathProvider";
+
+export interface BlogIndexItem {
+	slug: string;
+	title: string;
+	description?: string;
+	publishedAt: string;
+	/** Reading time in minutes, when the caller has computed one. */
+	readingMinutes?: number;
+}
+
+export interface BlogIndexProps {
+	items: BlogIndexItem[];
+	/** Base path the slugs hang from. Defaults to "/blog". */
+	basePath?: string;
+	id?: string;
+	className?: string;
+}
+
+/**
+ * The blog listing: every post, newest first, as a plain readable stack
+ * rather than a card grid. These are articles, not products, and a list
+ * that reads top to bottom suits a small archive better than a gallery
+ * that pads it out.
+ *
+ * Every entry is a real anchor to a prerendered page, which is what lets
+ * the build's link crawler discover the posts without an explicit page
+ * list in the vite config.
+ */
+export function BlogIndex({ items, basePath = "/blog", id, className }: BlogIndexProps) {
+	const withBase = useWithBase();
+	return (
+		<section className={["section", "blog-index", className].filter(Boolean).join(" ")} id={id}>
+			<div className="wrap">
+				<ol className="bi-list">
+					{items.map((item) => (
+						<li className="bi-item" key={item.slug}>
+							<a className="bi-link" href={withBase(`${basePath}/${item.slug}`)}>
+								<span className="bi-meta">
+									<time dateTime={item.publishedAt}>{displayDate(item.publishedAt)}</time>
+									{item.readingMinutes ? <span> · {item.readingMinutes} min read</span> : null}
+								</span>
+								<h2 className="bi-title">
+									{item.title}
+									<ArrowUpRight className="bi-arrow" size={20} strokeWidth={2} aria-hidden="true" />
+								</h2>
+								{item.description && <p className="bi-excerpt">{item.description}</p>}
+							</a>
+						</li>
+					))}
+				</ol>
+			</div>
+		</section>
+	);
+}

package/src/sections/BlogPost.tsx

@@ -0,0 +1,65 @@
+import { ArrowLeft } from "lucide-react";
+import { displayDate } from "../lib/displayDate";
+import { type ProseBlock, ProseBlocks } from "../primitives/ProseBlocks";
+import { useWithBase } from "../routing/BasePathProvider";
+
+export interface BlogPostDoc {
+	title: string;
+	description?: string;
+	publishedAt: string;
+	updatedAt?: string | null;
+	author?: string;
+	blocks: ProseBlock[];
+}
+
+export interface BlogPostProps {
+	doc: BlogPostDoc;
+	/** Where the "all posts" link goes. Defaults to "/blog". */
+	basePath?: string;
+	backLabel?: string;
+	id?: string;
+	className?: string;
+}
+
+/**
+ * A single post: byline, dateline, body, and a way back to the archive.
+ *
+ * The article's own `h1` lives here rather than in a PageHero, because a post
+ * title is the content rather than a page banner, and a hero would push 800
+ * words of the thing someone came to read below the fold.
+ *
+ * `dateModified` renders only when the source carries one. A "last updated"
+ * line invented at port time would be a freshness claim about writing nobody
+ * has touched.
+ */
+export function BlogPost({
+	doc,
+	basePath = "/blog",
+	backLabel = "All posts",
+	id,
+	className,
+}: BlogPostProps) {
+	const withBase = useWithBase();
+	return (
+		<article className={["section", "blog-post", className].filter(Boolean).join(" ")} id={id}>
+			<div className="wrap bp-wrap">
+				<a className="bp-back" href={withBase(basePath)}>
+					<ArrowLeft size={15} strokeWidth={2} aria-hidden="true" />
+					{backLabel}
+				</a>
+
+				<h1 className="bp-title">{doc.title}</h1>
+
+				<p className="bp-meta">
+					{doc.author && <span className="bp-author">{doc.author}</span>}
+					<time dateTime={doc.publishedAt}>{displayDate(doc.publishedAt)}</time>
+					{doc.updatedAt && doc.updatedAt !== doc.publishedAt && (
+						<span className="bp-updated">Updated {displayDate(doc.updatedAt)}</span>
+					)}
+				</p>
+
+				<ProseBlocks blocks={doc.blocks} className="bp-body" />
+			</div>
+		</article>
+	);
+}

package/src/sections/CTABanner.tsx

@@ -0,0 +1,93 @@
+import type { ReactNode } from "react";
+import { Eyebrow, Lead } from "../primitives";
+import { Button } from "../primitives/Button";
+import { useWithBase } from "../routing/BasePathProvider";
+
+export interface CTABannerCTA {
+	label: string;
+	href: string;
+	newTab?: boolean;
+}
+
+export interface CTABannerProps {
+	id?: string;
+	eyebrow?: string;
+	/** Headline; use <em className="serif"> spans for the script accent. */
+	title: ReactNode;
+	lead?: ReactNode;
+	/**
+	 * Full-bleed background image behind the content. Omit it and the banner
+	 * renders the token gradient fallback (the Hero treatment), so the section
+	 * works before photography exists.
+	 */
+	image?: { src: string; alt?: string };
+	primaryCta?: CTABannerCTA;
+	secondaryCta?: CTABannerCTA;
+	/**
+	 * Wash over the image so the copy pops: "dark" (light text over a dark
+	 * gradient, the hero treatment) or "light" (ink text over a surface wash,
+	 * for bright imagery). The wash fades toward the far side so the image
+	 * still reads.
+	 */
+	tone?: "dark" | "light";
+}
+
+/**
+ * Mid-page full-bleed CTA banner: the image spans the viewport as a backdrop
+ * with eyebrow, title, lead, and actions overlaid. The section-scale sibling
+ * of Hero — same treatment, banner height, usable anywhere in the page flow.
+ */
+export function CTABanner({
+	id,
+	eyebrow,
+	title,
+	lead,
+	image,
+	primaryCta,
+	secondaryCta,
+	tone = "dark",
+}: CTABannerProps) {
+	const withBase = useWithBase();
+	const onDark = tone === "dark";
+	return (
+		<section className={["cta-banner", tone].join(" ")} id={id}>
+			{image ? (
+				<img
+					className="cta-banner-media"
+					src={withBase(image.src)}
+					alt={image.alt ?? ""}
+					loading="lazy"
+				/>
+			) : (
+				<div className="cta-banner-media cta-banner-fallback" aria-hidden="true" />
+			)}
+			<div className="cta-banner-wash" aria-hidden="true" />
+			<div className="wrap">
+				<div className="cta-banner-content">
+					{eyebrow && <Eyebrow onDark={onDark}>{eyebrow}</Eyebrow>}
+					<h2>{title}</h2>
+					{lead && <Lead>{lead}</Lead>}
+					{(primaryCta || secondaryCta) && (
+						<div className="cta-banner-actions">
+							{primaryCta && (
+								<Button href={primaryCta.href} newTab={primaryCta.newTab} arrow>
+									{primaryCta.label}
+								</Button>
+							)}
+							{secondaryCta && (
+								<Button
+									variant="ghost"
+									onDark={onDark}
+									href={secondaryCta.href}
+									newTab={secondaryCta.newTab}
+								>
+									{secondaryCta.label}
+								</Button>
+							)}
+						</div>
+					)}
+				</div>
+			</div>
+		</section>
+	);
+}

package/src/sections/CTASection.tsx

@@ -0,0 +1,60 @@
+import type { ReactNode } from "react";
+import { Eyebrow, Lead } from "../primitives";
+import { Button } from "../primitives/Button";
+import type { SiteConfig } from "./siteConfig";
+
+export interface CTASectionProps {
+	/** The site's primary action, `site.cta`; a whole `SiteConfig` passes as it is. */
+	site: Pick<SiteConfig, "cta">;
+	eyebrow?: string;
+	title: ReactNode;
+	lead?: ReactNode;
+	/**
+	 * Overrides the primary action; by default the site's primary CTA
+	 * (site.cta) renders so every page closes with the same conversion
+	 * action in the same style.
+	 */
+	primary?: { label: string; href: string; newTab?: boolean };
+	/** Page-contextual secondary action; always a ghost button, always second. */
+	secondary?: { label: string; href: string; newTab?: boolean };
+	surface?: "default" | "alt";
+}
+
+/** The standard closing CTA: primary action from the site config, ghost secondary. */
+export function CTASection({
+	site,
+	eyebrow,
+	title,
+	lead,
+	primary,
+	secondary,
+	surface = "alt",
+}: CTASectionProps) {
+	const classes = ["section", "final-cta", surface === "alt" && "surface-alt"]
+		.filter(Boolean)
+		.join(" ");
+	const primaryAction = primary ?? {
+		label: site.cta.label,
+		href: site.cta.href,
+		newTab: site.cta.external,
+	};
+	return (
+		<section className={classes}>
+			<div className="wrap center">
+				{eyebrow && <Eyebrow center>{eyebrow}</Eyebrow>}
+				<h2>{title}</h2>
+				{lead && <Lead className="cta-lead">{lead}</Lead>}
+				<div className="cta-row center">
+					<Button href={primaryAction.href} newTab={primaryAction.newTab} size="lg" arrow>
+						{primaryAction.label}
+					</Button>
+					{secondary && (
+						<Button href={secondary.href} newTab={secondary.newTab} variant="ghost" size="lg">
+							{secondary.label}
+						</Button>
+					)}
+				</div>
+			</div>
+		</section>
+	);
+}

package/src/sections/ComparisonTable.tsx

@@ -0,0 +1,114 @@
+import type { ReactNode } from "react";
+
+/**
+ * A graded before and after: one row per graded item, each side carrying a grade and
+ * the points behind it. Built for case studies, where the reader's question is
+ * "what actually changed", and the answer has to survive being scanned.
+ *
+ * The grade sits beside its points rather than above them, and an "after"
+ * grade takes the primary color only when it differs from its "before", so
+ * running an eye down the last column finds every change without reading.
+ *
+ * Row labels, grades and copy all arrive as props: the component knows
+ * nothing about clients or scoring scales.
+ */
+
+export interface ComparisonState {
+	/**
+	 * A grade for this side. A single character renders as a large letter;
+	 * anything longer renders as a small mono note, which is how an ungraded
+	 * state ("not measured") says so without being handed a letter it did not
+	 * earn.
+	 */
+	grade: string;
+	/** What was true. One point renders as prose, several as a list. */
+	points: ReactNode[];
+}
+
+export interface ComparisonRow {
+	id: string;
+	/** The row label, e.g. the thing being graded. */
+	stage: string;
+	before: ComparisonState;
+	after: ComparisonState;
+}
+
+export interface ComparisonTableProps {
+	rows: ComparisonRow[];
+	/** Column headers. Defaults suit a before and after. */
+	columns?: { stage?: string; before?: string; after?: string };
+	/** Small print under the table, e.g. what the grades mean. */
+	footnote?: ReactNode;
+	className?: string;
+}
+
+function Cell({ state, highlight }: { state: ComparisonState; highlight: boolean }) {
+	const isLetter = state.grade.length === 1;
+	return (
+		<div className="cmp-cell">
+			<span
+				className={["cmp-grade", isLetter ? "is-letter" : "is-note", highlight ? "is-moved" : ""]
+					.filter(Boolean)
+					.join(" ")}
+			>
+				{state.grade}
+			</span>
+			<div className="cmp-points">
+				{state.points.length === 1 ? (
+					state.points[0]
+				) : (
+					<ul>
+						{state.points.map((point, i) => (
+							// biome-ignore lint/suspicious/noArrayIndexKey: a row's points are static and never reorder.
+							<li key={i}>{point}</li>
+						))}
+					</ul>
+				)}
+			</div>
+		</div>
+	);
+}
+
+export function ComparisonTable({ rows, columns, footnote, className }: ComparisonTableProps) {
+	const heads = {
+		stage: columns?.stage ?? "Area",
+		before: columns?.before ?? "Before",
+		after: columns?.after ?? "After",
+	};
+
+	return (
+		<div className={["comparison", className].filter(Boolean).join(" ")}>
+			<div className="cmp-scroll">
+				<table className="cmp-table">
+					<colgroup>
+						<col className="cmp-col-stage" />
+						<col className="cmp-col-half" />
+						<col className="cmp-col-half" />
+					</colgroup>
+					<thead>
+						<tr>
+							<th>{heads.stage}</th>
+							<th>{heads.before}</th>
+							<th>{heads.after}</th>
+						</tr>
+					</thead>
+					<tbody>
+						{rows.map((row) => (
+							<tr key={row.id}>
+								<th scope="row">{row.stage}</th>
+								<td>
+									<Cell state={row.before} highlight={false} />
+								</td>
+								<td className="is-after">
+									<Cell state={row.after} highlight={row.before.grade !== row.after.grade} />
+								</td>
+							</tr>
+						))}
+					</tbody>
+				</table>
+			</div>
+
+			{footnote && <p className="cmp-footnote">{footnote}</p>}
+		</div>
+	);
+}