@atelic-action/ui 0.17.2 → 1.1.0

package/src/lib/trackEvent.ts

@@ -0,0 +1,26 @@
+/**
+ * Sends one GA4 event through the Google tag a site loads, and nothing else:
+ * the tag itself, and the delegated listener for the click events, stay in
+ * the site. A silent no op when the tag is absent (no tag id configured, the
+ * script blocked, prerender with no window), and it never throws, since
+ * analytics must never break the page. Beacon transport, so an event fired on
+ * the way out of the page survives the navigation.
+ *
+ * Params are closed vocabularies: never a name, a phone number, an email
+ * address, or a message.
+ */
+
+type Gtag = (...args: unknown[]) => void;
+
+export type EventParams = Record<string, string | number | boolean>;
+
+export function trackEvent(name: string, params: EventParams = {}): void {
+	if (typeof window === "undefined") return;
+	try {
+		const gtag = (window as Window & { gtag?: Gtag }).gtag;
+		if (typeof gtag !== "function") return;
+		gtag("event", name, { ...params, transport_type: "beacon" });
+	} catch {
+		// Analytics must never break the page.
+	}
+}

package/src/lib/useOpenHeight.ts

@@ -0,0 +1,28 @@
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+
+const useIsoLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+/**
+ * The max height an expanding body animates to. Put `ref` on the content
+ * inside the clipped box: the height is measured before paint when the row
+ * opens (so a row that mounts already open is never clipped to nothing) and
+ * re-measured whenever the content resizes (rotation, font swap, late image).
+ * The layout effect runs before paint, so the 0 it starts from is never seen
+ * clipped, and the first open animates like every later one.
+ */
+export function useOpenHeight(open: boolean) {
+	const ref = useRef<HTMLDivElement>(null);
+	const [height, setHeight] = useState<number | null>(null);
+
+	useIsoLayoutEffect(() => {
+		const el = ref.current;
+		if (!open || !el) return;
+		setHeight(el.scrollHeight);
+		if (typeof ResizeObserver === "undefined") return;
+		const observer = new ResizeObserver(() => setHeight(el.scrollHeight));
+		observer.observe(el);
+		return () => observer.disconnect();
+	}, [open]);
+
+	return { ref, maxHeight: open ? (height ?? 0) : 0 } as const;
+}

package/src/primitives/Button.tsx

@@ -1,5 +1,6 @@
 import type { CSSProperties, ReactNode } from "react";
 import { newTabProps } from "../lib/newTabProps";
+import { useWithBase } from "../routing/BasePathProvider";
 
 export interface ButtonProps {
 	variant?: "primary" | "dark" | "ghost";
@@ -39,6 +40,7 @@ export function Button({
 	style,
 	children,
 }: ButtonProps) {
+	const withBase = useWithBase();
 	const classes = [
 		"btn",
 		`btn-${variant}`,
@@ -63,7 +65,7 @@ export function Button({
 	if (href) {
 		return (
 			<a
-				href={href}
+				href={withBase(href)}
 				className={classes}
 				style={style}
 				aria-label={ariaLabel}

package/src/primitives/Chip.tsx

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import { useWithBase } from "../routing/BasePathProvider";
 
 export interface ChipProps {
 	/** Shows the small brand-colored dot before the label. */
@@ -12,6 +13,7 @@ export interface ChipProps {
 
 /** Small mono tag/badge, used for credentials, tags, and service areas. */
 export function Chip({ dot = false, onDark = false, href, children }: ChipProps) {
+	const withBase = useWithBase();
 	const classes = ["chip", onDark && "on-dark"].filter(Boolean).join(" ");
 	const content = (
 		<>
@@ -21,7 +23,7 @@ export function Chip({ dot = false, onDark = false, href, children }: ChipProps)
 	);
 	if (href) {
 		return (
-			<a className={classes} href={href}>
+			<a className={classes} href={withBase(href)}>
 				{content}
 			</a>
 		);

package/src/primitives/ImageFrame.tsx

@@ -0,0 +1,48 @@
+import type { CSSProperties } from "react";
+import { useWithBase } from "../routing/BasePathProvider";
+
+export interface ImageFrameProps {
+	src?: string;
+	alt?: string;
+	/** CSS aspect-ratio for the frame, e.g. "4/5". */
+	aspectRatio?: string;
+	maxWidth?: string;
+	/** Placeholder label rendered when no src is provided yet. */
+	placeholder?: string;
+	/** Set on above-the-fold imagery; defaults to lazy loading. */
+	priority?: boolean;
+	className?: string;
+	style?: CSSProperties;
+}
+
+/** Rounded, shadowed media frame; renders a labeled placeholder block until an image exists. */
+export function ImageFrame({
+	src,
+	alt = "",
+	aspectRatio,
+	maxWidth,
+	placeholder,
+	priority = false,
+	className,
+	style,
+}: ImageFrameProps) {
+	const withBase = useWithBase();
+	const frameStyle: CSSProperties = { aspectRatio, maxWidth, ...style };
+	if (!src) {
+		return (
+			<div className={["ph", className].filter(Boolean).join(" ")} style={frameStyle}>
+				{placeholder ?? "Image"}
+			</div>
+		);
+	}
+	return (
+		<div className={["imgframe", className].filter(Boolean).join(" ")} style={frameStyle}>
+			<img
+				src={withBase(src)}
+				alt={alt}
+				loading={priority ? undefined : "lazy"}
+				fetchPriority={priority ? "high" : undefined}
+			/>
+		</div>
+	);
+}

package/src/primitives/ProseBlocks.tsx

@@ -0,0 +1,67 @@
+/**
+ * One block of ported prose. A deliberately tiny vocabulary — headings,
+ * paragraphs, lists — because that is what survives extraction from a CMS
+ * intact, and because anything richer invites rewriting content that was
+ * meant to be carried across verbatim.
+ */
+export interface ProseBlock {
+	type: "h" | "p" | "ul";
+	/** Present for "h" and "p". */
+	text?: string;
+	/** Present for "ul". */
+	items?: string[];
+}
+
+export interface ProseBlocksProps {
+	blocks: ProseBlock[];
+	/**
+	 * Heading level for "h" blocks. Defaults to h2, since the page's h1
+	 * belongs to whatever hero sits above this.
+	 */
+	headingLevel?: "h2" | "h3";
+	className?: string;
+}
+
+/**
+ * Renders a document body from data rather than markup: legal pages, ported
+ * blog posts, anything whose words came from somewhere else and must not be
+ * quietly edited on the way in.
+ *
+ * Keys are derived from content plus position. Repeated text is common in
+ * ported prose ("Contact us" appears in three legal documents), so neither
+ * alone is stable.
+ */
+export function ProseBlocks({ blocks, headingLevel = "h2", className }: ProseBlocksProps) {
+	const Heading = headingLevel;
+	return (
+		<div className={["prose-blocks", className].filter(Boolean).join(" ")}>
+			{blocks.map((block, i) => {
+				if (block.type === "h") {
+					return (
+						// biome-ignore lint/suspicious/noArrayIndexKey: static ported prose; position plus content is the stable key (see above)
+						<Heading className="pb-heading" key={`h-${i}-${block.text?.slice(0, 24)}`}>
+							{block.text}
+						</Heading>
+					);
+				}
+				if (block.type === "ul") {
+					return (
+						// biome-ignore lint/suspicious/noArrayIndexKey: static ported prose; position plus content is the stable key (see above)
+						<ul className="pb-list" key={`ul-${i}-${(block.items ?? [])[0]?.slice(0, 24)}`}>
+							{(block.items ?? []).map((item, j) => (
+								// biome-ignore lint/suspicious/noArrayIndexKey: static ported prose; position plus content is the stable key (see above)
+								<li key={`${j}-${item.slice(0, 40)}`}>{item}</li>
+							))}
+						</ul>
+					);
+				}
+				return (
+					// biome-ignore lint/suspicious/noArrayIndexKey: static ported prose; position plus content is the stable key (see above)
+					<p className="pb-body" key={`p-${i}-${block.text?.slice(0, 24)}`}>
+						{block.text}
+					</p>
+				);
+			})}
+		</div>
+	);
+}

package/src/primitives/QuoteCard.tsx

@@ -0,0 +1,20 @@
+import type { ReactNode } from "react";
+
+export interface QuoteCardProps {
+	quote: ReactNode;
+	/** Attribution line, e.g. "Dr. Alex Rivers, PT, DPT". */
+	by: string;
+	center?: boolean;
+	className?: string;
+}
+
+/** Testimonial / pull-quote card with serif italic type. */
+export function QuoteCard({ quote, by, center = false, className }: QuoteCardProps) {
+	const classes = ["quote-card", center && "center", className].filter(Boolean).join(" ");
+	return (
+		<figure className={classes}>
+			<blockquote>{quote}</blockquote>
+			<figcaption className="by">{by}</figcaption>
+		</figure>
+	);
+}

package/src/primitives/StarRow.tsx

@@ -0,0 +1,37 @@
+import { Star } from "lucide-react";
+
+export interface StarRowProps {
+	/** Star count, 1 to 5. Rounded and clamped into range. */
+	rating: number;
+	/** Glyph size in px. */
+	size?: number;
+	className?: string;
+}
+
+/**
+ * A row of filled stars, rendered as a single labeled image so screen
+ * readers announce "4 out of 5 stars" instead of four decorative glyphs.
+ * Shared by the review components; render one only when the source
+ * actually shows a rating — never invent one.
+ */
+export function StarRow({ rating, size = 15, className }: StarRowProps) {
+	const count = Math.max(1, Math.min(5, Math.round(rating)));
+	return (
+		<span
+			className={["star-row", className].filter(Boolean).join(" ")}
+			role="img"
+			aria-label={`${count} out of 5 stars`}
+		>
+			{Array.from({ length: count }, (_, i) => (
+				<Star
+					// biome-ignore lint/suspicious/noArrayIndexKey: static decorative row
+					key={i}
+					size={size}
+					strokeWidth={1.5}
+					fill="currentColor"
+					aria-hidden="true"
+				/>
+			))}
+		</span>
+	);
+}

package/src/primitives/TickList.tsx

@@ -0,0 +1,24 @@
+import { Check } from "lucide-react";
+import type { ReactNode } from "react";
+
+export interface TickListProps {
+	items: ReactNode[];
+	className?: string;
+}
+
+/** Checkmark bullet list used in feature details and pricing cards. */
+export function TickList({ items, className }: TickListProps) {
+	return (
+		<ul className={["ticks", className].filter(Boolean).join(" ")}>
+			{items.map((item, i) => (
+				// biome-ignore lint/suspicious/noArrayIndexKey: static content lists never reorder
+				<li key={i}>
+					<span className="tick" aria-hidden="true">
+						<Check size={12} strokeWidth={3} />
+					</span>
+					{item}
+				</li>
+			))}
+		</ul>
+	);
+}

package/src/primitives/index.ts

@@ -1,5 +1,10 @@
 export { Button, type ButtonProps } from "./Button";
 export { Chip, type ChipProps } from "./Chip";
 export { Eyebrow, type EyebrowProps } from "./Eyebrow";
+export { ImageFrame, type ImageFrameProps } from "./ImageFrame";
 export { Lead, type LeadProps } from "./Lead";
+export { type ProseBlock, ProseBlocks, type ProseBlocksProps } from "./ProseBlocks";
+export { QuoteCard, type QuoteCardProps } from "./QuoteCard";
 export { SectionHeading, type SectionHeadingProps } from "./SectionHeading";
+export { StarRow, type StarRowProps } from "./StarRow";
+export { TickList, type TickListProps } from "./TickList";

package/src/routing/BasePathProvider.tsx

@@ -0,0 +1,47 @@
+import { createContext, type ReactNode, useCallback, useContext } from "react";
+import { joinBase, normalizeBasePath } from "./basePath";
+
+/**
+ * The base path every link the package renders carries. The package imports
+ * no router and reads no build setting, so a site says its base once, here,
+ * and `Button`, `Chip`, and every section that builds a link or an image
+ * source read it through `useBasePath`. `SiteShell` mounts the provider from
+ * its `basePath` prop, so a site that renders its pages inside the shell
+ * never mounts it by hand.
+ *
+ * With no provider above it the base is "", the root, and every path renders
+ * as given.
+ */
+const BasePathContext = createContext("");
+
+export interface BasePathProviderProps {
+	/** The prefix the site is served under: "", "/", "proto", and "/proto/" are all read as written. */
+	base?: string;
+	children: ReactNode;
+}
+
+export function BasePathProvider({ base, children }: BasePathProviderProps) {
+	return (
+		<BasePathContext.Provider value={normalizeBasePath(base)}>{children}</BasePathContext.Provider>
+	);
+}
+
+/** The base path in force: "" at the root, otherwise "/proto" in normalized form. */
+export function useBasePath(): string {
+	return useContext(BasePathContext);
+}
+
+/**
+ * A function that puts the base in force on a root absolute path. External
+ * URLs, protocol links, fragments, and paths that already carry the base pass
+ * through unchanged, and so does `undefined`, so an optional prop can be
+ * handed over as it is.
+ */
+export function useWithBase(): <T extends string | undefined>(path: T) => T {
+	const base = useBasePath();
+	return useCallback(
+		<T extends string | undefined>(path: T): T =>
+			(path === undefined ? path : joinBase(base, path)) as T,
+		[base],
+	);
+}

package/src/routing/basePath.ts

@@ -0,0 +1,57 @@
+/**
+ * The base path: the prefix a site is served under when it does not own the
+ * root of its host (a website build previewed at `/proto` on the business's
+ * artifact host). A site sets it once; `BasePathProvider` hands it to every
+ * component below, and `marketingConfig` turns it into Vite's `base` and the
+ * router's `basepath`.
+ *
+ * Normalized form: "" for the root, otherwise a leading slash and no trailing
+ * slash ("/proto"). These helpers are pure and take the base explicitly, so
+ * the Vite config, the build commands, and the tests use them as they are.
+ * Plain TypeScript with no imports, since the built Vite entry imports it.
+ */
+
+const SEGMENT = /^(\/[A-Za-z0-9._~-]+)+$/;
+
+/** Turns a configured value ("", "/", "proto", "/proto/") into "" or "/proto". Throws on anything else. */
+export function normalizeBasePath(raw: string | undefined): string {
+	const trimmed = (raw ?? "").trim();
+	if (trimmed === "" || trimmed === "/") return "";
+	const base = `/${trimmed.replace(/^\/+|\/+$/g, "")}`;
+	if (!SEGMENT.test(base)) {
+		throw new Error(
+			`basePath must be a path such as "/proto" (letters, digits, dot, dash, underscore, tilde): got ${JSON.stringify(raw)}`,
+		);
+	}
+	return base;
+}
+
+/** True for a path the base applies to: root absolute, not protocol relative. */
+function isRootAbsolute(path: string): boolean {
+	return path.startsWith("/") && !path.startsWith("//");
+}
+
+/** True when the path already carries the base (so applying it again is a no op). */
+export function hasBase(base: string, path: string): boolean {
+	if (!base) return true;
+	if (!path.startsWith(base)) return false;
+	const next = path.charAt(base.length);
+	return next === "" || next === "/" || next === "?" || next === "#";
+}
+
+/**
+ * Prefixes a root absolute path with the base. External URLs, protocol links
+ * (mailto:, tel:), fragments, relative paths, and paths that already carry the
+ * base come back unchanged, so it is safe on any href and idempotent.
+ */
+export function joinBase(base: string, path: string): string {
+	if (!base || !isRootAbsolute(path) || hasBase(base, path)) return path;
+	return `${base}${path}`;
+}
+
+/** Removes the base from a path that carries it ("/proto/faqs" to "/faqs", "/proto" to "/"). */
+export function stripBase(base: string, path: string): string {
+	if (!base || !isRootAbsolute(path) || !path.startsWith(base) || !hasBase(base, path)) return path;
+	const rest = path.slice(base.length);
+	return rest === "" || !rest.startsWith("/") ? `/${rest}` : rest;
+}

package/src/routing/index.ts

@@ -29,3 +29,11 @@ export function staticNotFoundRouting<Page>(page: Page) {
 		defaultPendingComponent: page,
 	};
 }
+
+export {
+	BasePathProvider,
+	type BasePathProviderProps,
+	useBasePath,
+	useWithBase,
+} from "./BasePathProvider";
+export { hasBase, joinBase, normalizeBasePath, stripBase } from "./basePath";

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