@atelic-action/ui 0.17.2 → 1.0.0

package/src/scripts/check-base-path.ts

@@ -0,0 +1,130 @@
+/**
+ * Fails the build when dist/client or vercel.json disagrees with the base
+ * path. The last step of a marketing site's `bun run build`; the rules and
+ * their reasons live in src/lib/basePathAudit.ts, and the setting itself is
+ * `basePath` in the site's src/site.config.ts.
+ *
+ * A `VITE_BASE_PATH` override that differs from the config is a rehearsal
+ * build (CI proves a site under "/proto" that way): its HTML is held to the
+ * override, but vercel.json still describes the committed config, so a
+ * rewrite mismatch only warns, except on Vercel, where it would ship.
+ *
+ * Usage: atelic-check-base-path   (from the site's root)
+ * Exits 1 on any problem.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+	cssRefs,
+	htmlRefs,
+	type Rewrite,
+	rewriteProblems,
+	unbasedRefs,
+} from "../lib/basePathAudit";
+import { normalizeBasePath } from "../routing/basePath";
+import { SITE_CONFIG, siteConfigPath } from "./site-config";
+
+/** Where the build writes the pages, from the site's root. */
+export const BUILD_ROOT = "dist/client";
+
+export interface BasePathInput {
+	/** The `basePath` the site's config commits to. */
+	configured: string | undefined;
+	/** `VITE_BASE_PATH`, when the build was a rehearsal under another base. */
+	override: string | undefined;
+	/** Every built HTML and CSS file, by its path, with its text. */
+	files: Array<{ path: string; text: string }>;
+	/** The site's vercel.json, parsed. */
+	vercel: { rewrites?: Rewrite[] };
+	/** Whether the build runs on Vercel, where a rehearsal mismatch would ship. */
+	onVercel: boolean;
+}
+
+export interface BasePathReport {
+	base: string;
+	rehearsal: boolean;
+	checked: number;
+	problems: string[];
+	warnings: string[];
+}
+
+/** The audit, kept pure so it can be tested without a build. */
+export function auditBasePath(input: BasePathInput): BasePathReport {
+	const configured = normalizeBasePath(input.configured);
+	const base = normalizeBasePath(input.override ?? input.configured);
+	const rehearsal = input.override !== undefined && base !== configured;
+
+	const problems: string[] = [];
+	const warnings: string[] = [];
+	let checked = 0;
+	for (const file of input.files) {
+		const refs = file.path.endsWith(".html")
+			? htmlRefs(file.text)
+			: file.path.endsWith(".css")
+				? cssRefs(file.text)
+				: undefined;
+		if (!refs) continue;
+		checked++;
+		for (const ref of unbasedRefs(refs, base)) {
+			problems.push(`${file.path}: ${ref} lacks the base ${base}`);
+		}
+	}
+
+	const rewrites = rewriteProblems(input.vercel, base).map((problem) => `vercel.json: ${problem}`);
+	if (rehearsal && !input.onVercel) {
+		warnings.push(...rewrites.map((problem) => `rehearsal build, not deployable: ${problem}`));
+	} else {
+		problems.push(...rewrites);
+	}
+	return { base, rehearsal, checked, problems, warnings };
+}
+
+function builtFiles(dir: string, root: string): Array<{ path: string; text: string }> {
+	return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) return builtFiles(path, root);
+		if (!path.endsWith(".html") && !path.endsWith(".css")) return [];
+		return [
+			{ path: join(BUILD_ROOT, path.slice(root.length + 1)), text: readFileSync(path, "utf8") },
+		];
+	});
+}
+
+/** The command: audits the build of the site in `cwd`. */
+export async function main(cwd: string = process.cwd()): Promise<void> {
+	const configPath = siteConfigPath(cwd);
+	if (!existsSync(configPath)) {
+		console.error(`[base-path] no ${SITE_CONFIG} in ${cwd}. Run this from the root of a site.`);
+		process.exit(1);
+	}
+	const { site } = (await import(pathToFileURL(configPath).href)) as {
+		site?: { basePath?: string };
+	};
+	const root = resolve(cwd, BUILD_ROOT);
+	if (!existsSync(root)) {
+		console.error(`[base-path] no ${BUILD_ROOT} in ${cwd}. Build the site first.`);
+		process.exit(1);
+	}
+	const vercelPath = resolve(cwd, "vercel.json");
+	const report = auditBasePath({
+		configured: site?.basePath,
+		override: process.env.VITE_BASE_PATH,
+		files: builtFiles(root, root),
+		vercel: existsSync(vercelPath) ? JSON.parse(readFileSync(vercelPath, "utf8")) : {},
+		onVercel: Boolean(process.env.VERCEL),
+	});
+
+	for (const warning of report.warnings) console.warn(`[base-path] ${warning}`);
+	if (report.problems.length > 0) {
+		for (const problem of report.problems) console.error(`[base-path] ${problem}`);
+		const count = report.problems.length;
+		console.error(
+			`[base-path] ${count} problem${count === 1 ? "" : "s"}; see the @atelic-action/ui README, Sections, Serving Under a Base Path`,
+		);
+		process.exit(1);
+	}
+	console.log(
+		`[base-path] ${report.base || "root"}: ${report.checked} HTML and CSS files checked${report.rehearsal ? " (rehearsal)" : ""}`,
+	);
+}

package/src/scripts/clean-sitemap.ts

@@ -0,0 +1,27 @@
+/**
+ * Strips `#fragment` and trailing slash duplicates out of the built
+ * dist/client/sitemap.xml. A step of a marketing site's `bun run build`, after
+ * vite writes the sitemap; the logic and its reasoning live in
+ * src/lib/sitemap.ts. A site with a base path ships no sitemap
+ * (`marketingConfig` turns it off), so there is nothing to clean.
+ *
+ * Usage: atelic-clean-sitemap   (from the site's root)
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { dedupeSitemap } from "../lib/sitemap";
+
+/** Where the build writes the sitemap, from the site's root. */
+export const SITEMAP = "dist/client/sitemap.xml";
+
+/** The command: cleans the sitemap of the build in `cwd`, if it built one. */
+export function main(cwd: string = process.cwd()): void {
+	const path = resolve(cwd, SITEMAP);
+	if (!existsSync(path)) {
+		console.log(`[sitemap] ${SITEMAP} not built (base path set), nothing to clean`);
+		return;
+	}
+	const { xml, removed } = dedupeSitemap(readFileSync(path, "utf8"));
+	writeFileSync(path, xml);
+	console.log(`[sitemap] ${SITEMAP} (${removed} duplicate URL${removed === 1 ? "" : "s"} removed)`);
+}

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>
+	);
+}