@atelic-action/ui 0.1.0

package/src/chrome/SiteMenu.tsx

@@ -0,0 +1,130 @@
+import { useEffect, useRef } from "react";
+import { newTabProps } from "../lib/newTabProps";
+import type { CallToAction, MenuContact, NavLink } from "../types";
+
+export interface SiteMenuProps {
+	/** Whether the menu is showing. The owner holds this state. */
+	open: boolean;
+	/**
+	 * Called once each time the menu closes on its own: Escape, a followed
+	 * link, or the close button. The owner sets its state to closed. A close
+	 * the owner asked for, by passing `open={false}`, is not reported back.
+	 */
+	onClose: () => void;
+	/** The entries in order: a site's nav, or a page's own stops as `#id` links. */
+	links: NavLink[];
+	/** The primary action, rendered as a standard button below the entries. */
+	primaryCTA?: CallToAction;
+	/** The phone, email, and address block at the foot. */
+	contact?: MenuContact;
+	id?: string;
+	/** The dialog's accessible name. Defaults to "Menu". */
+	label?: string;
+}
+
+/**
+ * The full screen overlay menu for small screens, on a native modal
+ * `<dialog>`: the platform supplies Escape, focus containment, and focus
+ * return to the burger. The dialog renders closed on the server and opens
+ * only in an effect, so the menu stays safe to prerender. Page scroll holds
+ * still through chrome.css while the dialog is open.
+ */
+export function SiteMenu({
+	open,
+	onClose,
+	links,
+	primaryCTA,
+	contact,
+	id,
+	label = "Menu",
+}: SiteMenuProps) {
+	const dialogRef = useRef<HTMLDialogElement>(null);
+	// Whether the owner already knows the menu is closed. Escape fires cancel
+	// and then close, and a followed link closes the dialog and notifies
+	// directly, so every path runs through reportClosed and reports once.
+	const closedRef = useRef(true);
+
+	useEffect(() => {
+		const dialog = dialogRef.current;
+		if (!dialog) return;
+		closedRef.current = !open;
+		if (open && !dialog.open) dialog.showModal();
+		if (!open && dialog.open) dialog.close();
+	}, [open]);
+
+	const reportClosed = () => {
+		if (closedRef.current) return;
+		closedRef.current = true;
+		onClose();
+	};
+
+	// A followed link closes the dialog before the browser navigates, so the
+	// scroll lock is already lifted when an in page jump lands. The owner
+	// hears about it now rather than when the close event's task runs.
+	const close = () => {
+		const dialog = dialogRef.current;
+		if (dialog?.open) dialog.close();
+		reportClosed();
+	};
+
+	return (
+		<dialog
+			ref={dialogRef}
+			id={id}
+			className="mobile-menu"
+			aria-label={label}
+			onCancel={reportClosed}
+			onClose={reportClosed}
+		>
+			<button type="button" className="mm-close" aria-label="Close menu" onClick={close}>
+				<span />
+				<span />
+			</button>
+			{links.map((link, i) => (
+				<a key={link.href} className="mm-link" href={link.href} onClick={close}>
+					<span>{link.label}</span>
+					<span className="idx">{String(i + 1).padStart(2, "0")}</span>
+				</a>
+			))}
+			{primaryCTA && (
+				<a
+					className="btn btn-primary btn-lg mm-cta"
+					href={primaryCTA.href}
+					onClick={close}
+					{...newTabProps(primaryCTA.href, primaryCTA.external)}
+				>
+					{primaryCTA.label}
+				</a>
+			)}
+			{contact && <ContactBlock contact={contact} />}
+		</dialog>
+	);
+}
+
+function ContactBlock({ contact: { phone, email, address } }: { contact: MenuContact }) {
+	return (
+		<div className="mm-contact">
+			{phone && (
+				<>
+					CALL / TEXT&nbsp;&nbsp;{phone.display}
+					<br />
+				</>
+			)}
+			{email && (
+				<>
+					{email}
+					<br />
+				</>
+			)}
+			{address && (
+				<>
+					{/* A business that publishes a service area but no storefront leaves
+					    street empty; without the guard the separator dangles. */}
+					{address.street && <>{address.street.toUpperCase()} · </>}
+					{address.locality.toUpperCase()}, {address.region}
+					{address.postalCode ? ` ${address.postalCode}` : ""}
+				</>
+			)}
+		</div>
+	);
+}

package/src/chrome/SkipLink.tsx

@@ -0,0 +1,16 @@
+import type { ReactNode } from "react";
+
+export interface SkipLinkProps {
+	/** The main landmark's anchor. Defaults to "#main". */
+	href?: string;
+	children?: ReactNode;
+}
+
+/** The keyboard user's first stop: hidden until focused, then a jump past the chrome. */
+export function SkipLink({ href = "#main", children = "Skip to content" }: SkipLinkProps) {
+	return (
+		<a className="skip-link" href={href}>
+			{children}
+		</a>
+	);
+}

package/src/chrome/StickyCTABar.tsx

@@ -0,0 +1,50 @@
+import { Phone as PhoneIcon } from "lucide-react";
+import { useEffect, useState } from "react";
+import { newTabProps } from "../lib/newTabProps";
+import type { CallToAction, Phone } from "../types";
+
+export interface StickyCTABarProps {
+	/** The primary action, filling the bar. */
+	primaryCTA: CallToAction;
+	/** Adds a call shortcut beside the CTA. Omit for a business with no public phone. */
+	phone?: Phone;
+	/** Scroll depth in pixels before the bar slides in. Defaults to 520. */
+	threshold?: number;
+	/** The call shortcut's accessible name. Defaults to "Call us". */
+	callLabel?: string;
+}
+
+/** The phone only bottom bar: the primary CTA and a call shortcut, sliding in once scrolled. */
+export function StickyCTABar({
+	primaryCTA,
+	phone,
+	threshold = 520,
+	callLabel = "Call us",
+}: StickyCTABarProps) {
+	const [show, setShow] = useState(false);
+
+	useEffect(() => {
+		const onScroll = () => setShow(window.scrollY > threshold);
+		window.addEventListener("scroll", onScroll, { passive: true });
+		onScroll();
+		return () => window.removeEventListener("scroll", onScroll);
+	}, [threshold]);
+
+	return (
+		// Inert while offscreen, so its links take no keyboard focus before it slides in.
+		<div className={show ? "sticky-cta show" : "sticky-cta"} inert={!show}>
+			<a
+				className="btn btn-primary"
+				href={primaryCTA.href}
+				{...newTabProps(primaryCTA.href, primaryCTA.external)}
+			>
+				{primaryCTA.label}
+			</a>
+			{phone && (
+				<a className="btn btn-ghost btn-call" href={`tel:${phone.e164}`} aria-label={callLabel}>
+					<PhoneIcon size={18} aria-hidden="true" />
+				</a>
+			)}
+		</div>
+	);
+}

package/src/chrome/index.ts

@@ -0,0 +1,20 @@
+export type { PageStop } from "../hooks/useScrollSpy";
+export type {
+	Brand,
+	BrandLogo,
+	CallToAction,
+	HoursRow,
+	MenuContact,
+	NavLink,
+	Phone,
+	PostalAddress,
+	SiteLink,
+	SocialLink,
+} from "../types";
+export { BrandLockup, type BrandLockupProps } from "./BrandLockup";
+export { CreditBar } from "./CreditBar";
+export { Footer, type FooterProps } from "./Footer";
+export { SiteHeader, type SiteHeaderProps, type SiteHeaderVariant } from "./SiteHeader";
+export { SiteMenu, type SiteMenuProps } from "./SiteMenu";
+export { SkipLink, type SkipLinkProps } from "./SkipLink";
+export { StickyCTABar, type StickyCTABarProps } from "./StickyCTABar";

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export { type PageStop, useScrollSpy } from "./useScrollSpy";

package/src/hooks/useScrollSpy.ts

@@ -0,0 +1,44 @@
+import { useEffect, useState } from "react";
+
+/** One stop in a page's own navigation: an anchor already on the page. */
+export interface PageStop {
+	/** Anchor id of an element already on the page. */
+	id: string;
+	label: string;
+}
+
+/**
+ * Scroll spy over a list of anchor ids: returns the id whose section is in
+ * the reading band, or null before any section has entered it. The header's
+ * page stops and a page's own jump rail both highlight from it.
+ */
+export function useScrollSpy(ids: string[]): string | null {
+	const [activeId, setActiveId] = useState<string | null>(null);
+	// Key on the joined ids so callers can pass a freshly mapped array
+	// without tearing down the observer every render.
+	const key = ids.join("|");
+
+	useEffect(() => {
+		// A new id list never keeps an id it no longer contains.
+		setActiveId(null);
+		if (typeof IntersectionObserver === "undefined") return;
+		const sections = key
+			.split("|")
+			.filter(Boolean)
+			.map((id) => document.getElementById(id))
+			.filter((el): el is HTMLElement => el !== null);
+		if (sections.length === 0) return;
+		const observer = new IntersectionObserver(
+			(entries) => {
+				for (const entry of entries) {
+					if (entry.isIntersecting) setActiveId(entry.target.id);
+				}
+			},
+			{ rootMargin: "-30% 0px -60% 0px" },
+		);
+		for (const el of sections) observer.observe(el);
+		return () => observer.disconnect();
+	}, [key]);
+
+	return activeId;
+}

package/src/lib/newTabProps.ts

@@ -0,0 +1,14 @@
+/**
+ * The target="_blank" props for a link, suppressed on protocol links: a
+ * mailto: or tel: opened in a new tab leaves a dead blank tab on desktop and
+ * breaks the handler handoff on phones, so the new tab request is ignored for
+ * them no matter what the caller asks (learned on atelic.me's mailto CTA,
+ * 2026-08-28).
+ */
+export function newTabProps(
+	href: string,
+	newTab: boolean | undefined,
+): { target: "_blank"; rel: "noopener" } | Record<string, never> {
+	if (!newTab || /^(mailto|tel|sms):/i.test(href)) return {};
+	return { target: "_blank", rel: "noopener" };
+}

package/src/styles/base.css

@@ -0,0 +1,221 @@
+/* =================================================================
+   @atelic-action/ui BASE: the few unscoped resets, then the canvas,
+   typography, and layout helpers, scoped to .mkt.
+   Tokens are read here and never defined: each site's theme.css owns
+   them. Everything sits in the atelic-ui layer, so any rule a site
+   writes outside a layer wins without a specificity fight.
+   ================================================================= */
+@layer atelic-ui {
+	/* ---- Resets ---- */
+	*,
+	*::before,
+	*::after {
+		box-sizing: border-box;
+	}
+	html,
+	body {
+		margin: 0;
+		padding: 0;
+	}
+	html {
+		-webkit-text-size-adjust: 100%;
+		scroll-behavior: smooth;
+	}
+	@media (prefers-reduced-motion: reduce) {
+		html {
+			scroll-behavior: auto;
+		}
+	}
+
+	/* ---- Page canvas ---- */
+	/* Horizontal overflow is clipped at the body (where it still propagates to
+	   the viewport) rather than on .mkt itself: an overflow-x on .mkt would
+	   silently break position: sticky for every descendant. */
+	body:has(.mkt) {
+		overflow-x: hidden;
+	}
+	.mkt {
+		font-family: var(--font-sans);
+		background: var(--surface);
+		color: var(--ink);
+		line-height: 1.55;
+		font-size: 17px;
+		-webkit-font-smoothing: antialiased;
+		text-rendering: optimizeLegibility;
+	}
+	.mkt a {
+		color: inherit;
+		text-decoration: none;
+	}
+	.mkt button {
+		font: inherit;
+		cursor: pointer;
+		border: none;
+		background: none;
+		color: inherit;
+	}
+	.mkt ul {
+		list-style: none;
+		padding: 0;
+		margin: 0;
+	}
+	.mkt img,
+	.mkt picture,
+	.mkt svg,
+	.mkt video {
+		display: block;
+		max-width: 100%;
+	}
+
+	/* ---- Typography ---- */
+	.mkt h1,
+	.mkt h2,
+	.mkt h3,
+	.mkt h4 {
+		/* Sites pairing a display face with a body face set --font-heading in
+		   their theme; without it, headings share the body family. */
+		font-family: var(--font-heading, var(--font-sans));
+		line-height: 1.04;
+		font-weight: 800;
+		letter-spacing: -0.02em;
+		text-wrap: balance;
+		margin: 0;
+	}
+	.mkt h1 {
+		font-size: clamp(2.6rem, 8vw, 5rem);
+	}
+	.mkt h2 {
+		font-size: clamp(2rem, 5.5vw, 3.4rem);
+	}
+	.mkt h3 {
+		font-size: clamp(1.35rem, 3vw, 1.85rem);
+		letter-spacing: -0.015em;
+	}
+	.mkt h4 {
+		font-size: 1.15rem;
+		font-weight: 700;
+		letter-spacing: -0.01em;
+	}
+	.mkt p {
+		text-wrap: pretty;
+		margin: 0;
+	}
+	.mkt em.serif,
+	.mkt .serif-em {
+		font-family: var(--font-serif);
+		font-style: italic;
+		font-weight: 400;
+		letter-spacing: -0.01em;
+		color: var(--primary);
+	}
+	/* Serif accent words in headings carry the brand accent color (the
+	   wordmark's signature), so the italic word reads as the highlight it is.
+	   A page on a dark surface lifts its own to the bright primary. */
+	.mkt h1 .serif,
+	.mkt h2 .serif {
+		color: var(--primary);
+	}
+
+	/* ---- Layout helpers ---- */
+	.mkt .wrap {
+		width: 100%;
+		max-width: var(--max-width);
+		margin-inline: auto;
+		padding-inline: var(--gutter);
+	}
+	.mkt .section {
+		padding-block: clamp(56px, 9vw, 120px);
+	}
+	/* A middle step, for a page whose alternating bands do the separating and
+	   whose default rhythm reads too airy as a result. */
+	.mkt .section-md {
+		padding-block: clamp(44px, 6.5vw, 84px);
+	}
+	.mkt .section-sm {
+		padding-block: clamp(40px, 6vw, 72px);
+	}
+	/* Section band modifiers, global because routes across chunks use them. */
+	.mkt .section.surface-alt {
+		background: var(--surface-alt);
+	}
+	.mkt .section.tight-top {
+		padding-top: clamp(20px, 3vw, 40px);
+	}
+	.mkt .section.tight-bottom {
+		padding-bottom: clamp(20px, 3vw, 40px);
+	}
+	.mkt .stack-sm > * + * {
+		margin-top: 0.75rem;
+	}
+	.mkt .stack > * + * {
+		margin-top: 1.25rem;
+	}
+	.mkt .center {
+		text-align: center;
+	}
+	.mkt .muted {
+		color: var(--neutral-600);
+	}
+	.mkt .nowrap {
+		white-space: nowrap;
+	}
+
+	/* ---- CTA row (pairs of buttons under headlines) ---- */
+	.mkt .cta-row {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 14px;
+		margin-top: 32px;
+	}
+	.mkt .cta-row.center {
+		justify-content: center;
+	}
+
+	/* ---- Chip row ---- */
+	.mkt .chip-row {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 10px;
+	}
+
+	/* ---- Prose (long form copy) ---- */
+	.mkt .prose {
+		max-width: 68ch;
+	}
+	.mkt .prose p {
+		margin-bottom: 1.1rem;
+		color: var(--ink-soft);
+		font-size: 1.08rem;
+		line-height: 1.7;
+	}
+	.mkt .prose h3 {
+		margin: 2.2rem 0 0.8rem;
+	}
+	.mkt .prose strong {
+		color: var(--ink);
+	}
+
+	/* Anchored sections sit under the fixed header; give every id an offset
+	   so jump links do not land beneath it. */
+	.mkt [id] {
+		scroll-margin-top: calc(var(--nav-height) + 16px);
+	}
+
+	/* ---- Prose links (long form body copy) ----
+	   The base anchor rule leaves links undecorated, and inside running text they
+	   inherit the paragraph color, so a link in a letter or a long note is
+	   invisible: the descriptive words read as prose and nobody clicks them.
+	   Underline them wherever prose runs. Learned on a reveal letter, where the
+	   whole ask was a link nobody could see. Scoped to paragraph links so a button
+	   dropped into a prose block is untouched, and placed last so it reads after
+	   the lighter anchor rules above. */
+	.mkt .prose p a:not(.btn) {
+		color: var(--ink);
+		border-bottom: 1px solid var(--neutral-300);
+		padding-bottom: 1px;
+	}
+	.mkt .prose p a:not(.btn):hover {
+		color: var(--primary);
+		border-color: var(--primary);
+	}
+}