@atelic-action/ui 0.17.2 → 1.0.0

package/src/sections/FAQBrowser.tsx

@@ -0,0 +1,283 @@
+import { Check, ChevronDown, Link2, Search, X } from "lucide-react";
+import { type ReactNode, useEffect, useMemo, useState } from "react";
+import { newTabProps } from "../lib/newTabProps";
+import { useOpenHeight } from "../lib/useOpenHeight";
+import { useWithBase } from "../routing/BasePathProvider";
+import { JumpRail } from "./JumpRail";
+import { PageHero } from "./PageHero";
+
+export interface FAQCta {
+	label: string;
+	href: string;
+	newTab?: boolean;
+}
+
+export interface FAQEntry {
+	/** Stable slug; doubles as the deep-link anchor, e.g. "do-you-take-insurance". */
+	id: string;
+	question: string;
+	answer: ReactNode;
+	/** Plain-text answer for search matching and FAQPage structured data. */
+	answerText: string;
+	/** Optional link rendered at the end of the open answer. */
+	cta?: FAQCta;
+}
+
+export interface FAQCategory {
+	/** Stable slug; doubles as the section anchor. */
+	id: string;
+	title: string;
+	/** Short label for the sticky tab bar; falls back to title. */
+	tabLabel?: string;
+	description?: string;
+	/** Optional link line rendered under the category's card group. */
+	cta?: FAQCta;
+	items: FAQEntry[];
+}
+
+export interface FAQBrowserProps {
+	hero: { eyebrow?: string; title: ReactNode; lead?: ReactNode };
+	categories: FAQCategory[];
+	searchPlaceholder?: string;
+	browseAllLabel?: string;
+	/** Where the no match line sends a reader to ask instead. Defaults to "/contact". */
+	contactHref?: string;
+}
+
+function matches(query: string, item: FAQEntry): boolean {
+	const q = query.trim().toLowerCase();
+	if (!q) return true;
+	return item.question.toLowerCase().includes(q) || item.answerText.toLowerCase().includes(q);
+}
+
+function CTALink({ cta, className }: { cta: FAQCta; className?: string }) {
+	const withBase = useWithBase();
+	return (
+		<a className={className} href={withBase(cta.href)} {...newTabProps(cta.href, cta.newTab)}>
+			{cta.label} <span className="arrow">→</span>
+		</a>
+	);
+}
+
+function FAQRow({
+	item,
+	open,
+	copied,
+	onToggle,
+	onCopy,
+}: {
+	item: FAQEntry;
+	open: boolean;
+	copied: boolean;
+	onToggle: () => void;
+	onCopy: () => void;
+}) {
+	const { ref, maxHeight } = useOpenHeight(open);
+
+	return (
+		<div className={["faq-row", open && "open"].filter(Boolean).join(" ")} id={item.id}>
+			<div className="faq-row-head">
+				<button type="button" className="faq-row-q" aria-expanded={open} onClick={onToggle}>
+					{item.question}
+				</button>
+				<div className="faq-row-icons">
+					<button
+						type="button"
+						className={["faq-icon-btn", "faq-link-btn", copied && "copied"]
+							.filter(Boolean)
+							.join(" ")}
+						aria-label={copied ? "Link copied" : "Copy link to this question"}
+						onClick={onCopy}
+					>
+						{copied ? (
+							<Check size={16} strokeWidth={2} aria-hidden="true" />
+						) : (
+							<Link2 size={16} strokeWidth={1.6} aria-hidden="true" />
+						)}
+					</button>
+					<button
+						type="button"
+						className="faq-icon-btn faq-chevron"
+						aria-label={open ? "Collapse answer" : "Expand answer"}
+						aria-expanded={open}
+						onClick={onToggle}
+					>
+						<ChevronDown size={16} strokeWidth={2} aria-hidden="true" />
+					</button>
+				</div>
+			</div>
+			{/* Closed, the answer stays in the HTML for crawlers but is inert, so
+			    its links are out of the tab order and out of a screen reader's
+			    reach while it is clipped to nothing. */}
+			<div className="faq-row-a" style={{ maxHeight }} inert={!open}>
+				<div className="faq-row-a-inner" ref={ref}>
+					{item.answer}
+					{item.cta && <CTALink cta={item.cta} className="faq-answer-cta" />}
+				</div>
+			</div>
+		</div>
+	);
+}
+
+/**
+ * The full FAQ page organism: centered help hero with live search, a sticky
+ * category tab bar with scroll spy, and per-category card groups with
+ * expand-all, back-to-top, and per-question deep links. Search hides
+ * non-matching questions and empty categories.
+ */
+export function FAQBrowser({
+	hero,
+	categories,
+	searchPlaceholder = "Search questions or keywords",
+	browseAllLabel = "Browse all questions ↓",
+	contactHref = "/contact",
+}: FAQBrowserProps) {
+	const withBase = useWithBase();
+	const [query, setQuery] = useState("");
+	const [openIds, setOpenIds] = useState<Set<string>>(new Set());
+	const [copiedId, setCopiedId] = useState<string | null>(null);
+
+	const filtered = useMemo(() => {
+		const withMatches = categories.map((cat) => ({
+			...cat,
+			items: cat.items.filter((item) => matches(query, item)),
+		}));
+		return query.trim() ? withMatches.filter((cat) => cat.items.length > 0) : withMatches;
+	}, [categories, query]);
+
+	// Deep link: #<item-id> opens and scrolls to that question on load.
+	useEffect(() => {
+		const id = window.location.hash.slice(1);
+		if (!id) return;
+		const target = categories.flatMap((c) => c.items).find((item) => item.id === id);
+		if (!target) return;
+		setOpenIds((prev) => new Set(prev).add(id));
+		requestAnimationFrame(() => {
+			document.getElementById(id)?.scrollIntoView({ block: "center" });
+		});
+	}, [categories]);
+
+	function toggle(id: string) {
+		setOpenIds((prev) => {
+			const next = new Set(prev);
+			if (next.has(id)) next.delete(id);
+			else next.add(id);
+			return next;
+		});
+	}
+
+	// Copy only — updating the URL here would trip the router's scroll handling.
+	function copyLink(id: string) {
+		const url = `${window.location.origin}${window.location.pathname}#${id}`;
+		navigator.clipboard?.writeText(url).catch(() => {});
+		setCopiedId(id);
+		window.setTimeout(() => setCopiedId((current) => (current === id ? null : current)), 1600);
+	}
+
+	function toggleAll(cat: FAQCategory) {
+		const allOpen = cat.items.every((item) => openIds.has(item.id));
+		setOpenIds((prev) => {
+			const next = new Set(prev);
+			for (const item of cat.items) {
+				if (allOpen) next.delete(item.id);
+				else next.add(item.id);
+			}
+			return next;
+		});
+	}
+
+	return (
+		<>
+			<PageHero eyebrow={hero.eyebrow} title={hero.title} lead={hero.lead}>
+				{/* The find block centers on its own reading width under the
+				    left-aligned page header: search pill, browse-all beneath it. */}
+				<div className="faq-find">
+					<div className="faq-search">
+						<Search size={18} strokeWidth={1.6} aria-hidden="true" />
+						<input
+							type="search"
+							value={query}
+							onChange={(event) => setQuery(event.target.value)}
+							placeholder={searchPlaceholder}
+							aria-label="Search questions"
+						/>
+						{query && (
+							<button
+								type="button"
+								className="faq-search-clear"
+								aria-label="Clear search"
+								onClick={() => setQuery("")}
+							>
+								<X size={16} strokeWidth={2} aria-hidden="true" />
+							</button>
+						)}
+					</div>
+					{/* The first category the page renders, which a search may have
+					    hidden the first one of; with nothing matching, no link. */}
+					{browseAllLabel && filtered[0] && (
+						<a className="faq-browse-all" href={`#cat-${filtered[0].id}`}>
+							{browseAllLabel}
+						</a>
+					)}
+				</div>
+			</PageHero>
+
+			<JumpRail
+				ariaLabel="Question categories"
+				items={filtered.map((cat) => ({
+					id: `cat-${cat.id}`,
+					label: cat.tabLabel ?? cat.title,
+				}))}
+			/>
+
+			<div className="faq-cats">
+				{filtered.map((cat) => {
+					const allOpen = cat.items.length > 0 && cat.items.every((item) => openIds.has(item.id));
+					return (
+						<section className="faq-cat" id={`cat-${cat.id}`} key={cat.id}>
+							<div className="wrap">
+								<h2>{cat.title}</h2>
+								<div className="faq-cat-head">
+									{cat.description && <p className="faq-cat-desc">{cat.description}</p>}
+									<div className="faq-utils">
+										<button type="button" className="faq-util" onClick={() => toggleAll(cat)}>
+											{allOpen ? "Collapse all" : "Expand all"}
+										</button>
+										<button
+											type="button"
+											className="faq-util"
+											onClick={() => window.scrollTo({ top: 0, behavior: "smooth" })}
+										>
+											Back to top ↑
+										</button>
+									</div>
+								</div>
+								<div className="faq-group">
+									{cat.items.map((item) => (
+										<FAQRow
+											key={item.id}
+											item={item}
+											open={openIds.has(item.id)}
+											copied={copiedId === item.id}
+											onToggle={() => toggle(item.id)}
+											onCopy={() => copyLink(item.id)}
+										/>
+									))}
+								</div>
+								{cat.cta && <CTALink cta={cat.cta} className="faq-cat-cta" />}
+							</div>
+						</section>
+					);
+				})}
+				{query.trim() && filtered.length === 0 && (
+					<div className="wrap faq-empty">
+						<p>
+							No questions match "{query.trim()}". Try another word, or{" "}
+							<a href={withBase(contactHref)}>reach out directly</a>. We're happy to help.
+						</p>
+					</div>
+				)}
+			</div>
+		</>
+	);
+}

package/src/sections/FeatureDetail.tsx

@@ -0,0 +1,60 @@
+import type { ReactNode } from "react";
+import { Eyebrow, Lead } from "../primitives";
+import { Chip } from "../primitives/Chip";
+import { ImageFrame } from "../primitives/ImageFrame";
+import { TickList } from "../primitives/TickList";
+
+export interface FeatureDetailProps {
+	/** Anchor id for jump links, e.g. "dry-needling". */
+	id?: string;
+	/** Optional mono index label, e.g. "01". Rendered above the eyebrow; omit for no number. */
+	num?: string;
+	eyebrow?: string;
+	title: ReactNode;
+	tags?: string[];
+	lead?: ReactNode;
+	ticks?: ReactNode[];
+	image?: { src: string; alt: string };
+	/** Placeholder label rendered in the media frame until a real image exists. */
+	placeholder?: string;
+	/** Media on the left on wide screens (alternating rows). */
+	flip?: boolean;
+}
+
+/** Alternating copy-and-media feature row (the services page pattern). */
+export function FeatureDetail({
+	id,
+	num,
+	eyebrow,
+	title,
+	tags,
+	lead,
+	ticks,
+	image,
+	placeholder,
+	flip = false,
+}: FeatureDetailProps) {
+	return (
+		<article className={["feature-detail", flip && "flip"].filter(Boolean).join(" ")} id={id}>
+			<div>
+				{num && <span className="feature-num">{num}</span>}
+				{eyebrow && <Eyebrow>{eyebrow}</Eyebrow>}
+				<h2>{title}</h2>
+				{tags && tags.length > 0 && (
+					<div className="chip-row tag-row">
+						{tags.map((tag) => (
+							<Chip key={tag} dot>
+								{tag}
+							</Chip>
+						))}
+					</div>
+				)}
+				{lead && <Lead>{lead}</Lead>}
+				{ticks && ticks.length > 0 && <TickList items={ticks} className="detail-ticks" />}
+			</div>
+			<div className="feature-detail-media">
+				<ImageFrame src={image?.src} alt={image?.alt} placeholder={placeholder} aspectRatio="4/3" />
+			</div>
+		</article>
+	);
+}

package/src/sections/FeatureGrid.tsx

@@ -0,0 +1,83 @@
+import type { CSSProperties, ReactNode } from "react";
+import { SectionHeading } from "../primitives";
+import { useWithBase } from "../routing/BasePathProvider";
+
+interface FeatureCardBase {
+	/** Small mono index label, e.g. "01". */
+	num?: string;
+	title: string;
+}
+
+/**
+ * A card is either a link or a card that contains one, never both. The linked
+ * variant wraps the whole card in an anchor, and an anchor inside an anchor is
+ * invalid markup that browsers silently unnest, so a linked card's description
+ * stays plain text. The unlinked variant takes a node, which is how a word
+ * inside a card links to its definition.
+ *
+ * That node is inline content only: the description renders inside the card's
+ * `<p>`, so a block element (`p`, `div`, `ul`) nested there is invalid markup.
+ * TypeScript has no phrasing content type to say so, which leaves it a rule
+ * rather than a constraint.
+ */
+export type FeatureCard =
+	| (FeatureCardBase & { description: ReactNode; href?: never; linkLabel?: never })
+	| (FeatureCardBase & { description: string; href: string; linkLabel?: string });
+
+export interface FeatureGridProps {
+	eyebrow?: string;
+	/** Deprecated no-op: the eyebrow's trailing fade is now its only rendering. */
+	eyebrowRun?: boolean;
+	title: ReactNode;
+	items: FeatureCard[];
+	/** Cards per row at desktop width (default 4). */
+	columns?: 2 | 3 | 4;
+	surface?: "default" | "alt";
+	id?: string;
+}
+
+/** Numbered feature/service card grid with hover lift. */
+export function FeatureGrid({
+	eyebrow,
+	title,
+	items,
+	columns = 4,
+	surface = "alt",
+	id,
+}: FeatureGridProps) {
+	const withBase = useWithBase();
+	const sectionClasses = ["section", surface === "alt" && "surface-alt"].filter(Boolean).join(" ");
+	const gridStyle = { "--fg-cols": columns } as CSSProperties;
+	return (
+		<section className={sectionClasses} id={id}>
+			<div className="wrap">
+				<SectionHeading eyebrow={eyebrow} title={title} />
+				<div className="feature-grid" style={gridStyle}>
+					{items.map((item) => {
+						const inner = (
+							<>
+								{item.num && <span className="feature-num">{item.num}</span>}
+								<h3>{item.title}</h3>
+								<p>{item.description}</p>
+								{item.href && item.linkLabel && (
+									<span className="feature-link">
+										{item.linkLabel} <span className="arrow">→</span>
+									</span>
+								)}
+							</>
+						);
+						return item.href ? (
+							<a key={item.title} className="feature-card" href={withBase(item.href)}>
+								{inner}
+							</a>
+						) : (
+							<div key={item.title} className="feature-card">
+								{inner}
+							</div>
+						);
+					})}
+				</div>
+			</div>
+		</section>
+	);
+}

package/src/sections/Gallery.tsx

@@ -0,0 +1,84 @@
+import type { ReactNode } from "react";
+import { Eyebrow, Lead } from "../primitives";
+import { useWithBase } from "../routing/BasePathProvider";
+
+export interface GalleryPhoto {
+	src?: string;
+	/** Alt text: describe the work in the frame, never the brand. */
+	alt?: string;
+	/** Placeholder shot brief rendered when no src exists yet. */
+	placeholder?: string;
+	/** Short caption rendered under the photo. Keep it to one honest line. */
+	caption?: string;
+}
+
+export interface GalleryProps {
+	id?: string;
+	eyebrow?: string;
+	title: ReactNode;
+	lead?: ReactNode;
+	photos: GalleryPhoto[];
+	/** Tiles per row at desktop width (default 3). */
+	columns?: 2 | 3;
+	surface?: "default" | "alt";
+	/** Small note under the grid, e.g. photo provenance. */
+	footnote?: ReactNode;
+}
+
+/**
+ * A captioned photo grid for a business's own work. Built for trade and
+ * service clients whose proof is the job itself: every tile is a real
+ * photograph with a caption that says what it is, never a stock frame.
+ *
+ * Tiles crop to a fixed aspect so a mixed bag of phone photos still reads
+ * as one wall. Photos without a `src` render their shot brief as a labeled
+ * placeholder, so the wall can be composed before the photography exists.
+ */
+export function Gallery({
+	id,
+	eyebrow,
+	title,
+	lead,
+	photos,
+	columns = 3,
+	surface = "default",
+	footnote,
+}: GalleryProps) {
+	const withBase = useWithBase();
+	return (
+		<section
+			id={id}
+			className={["section gallery-section", surface === "alt" && "surface-alt"]
+				.filter(Boolean)
+				.join(" ")}
+		>
+			<div className="wrap">
+				{eyebrow && <Eyebrow>{eyebrow}</Eyebrow>}
+				<h2>{title}</h2>
+				{lead && <Lead style={{ maxWidth: "60ch" }}>{lead}</Lead>}
+				<ul className={`gallery-grid cols-${columns}`}>
+					{photos.map((photo) => (
+						<li className="gallery-item" key={photo.src ?? photo.placeholder ?? photo.caption}>
+							<figure>
+								{photo.src ? (
+									<div className="gallery-frame">
+										<img
+											src={withBase(photo.src)}
+											alt={photo.alt ?? ""}
+											loading="lazy"
+											decoding="async"
+										/>
+									</div>
+								) : (
+									<div className="gallery-frame ph">{photo.placeholder ?? "Photo"}</div>
+								)}
+								{photo.caption && <figcaption>{photo.caption}</figcaption>}
+							</figure>
+						</li>
+					))}
+				</ul>
+				{footnote && <p className="muted gallery-footnote">{footnote}</p>}
+			</div>
+		</section>
+	);
+}

package/src/sections/Hero.tsx

@@ -0,0 +1,110 @@
+import type { ReactNode } from "react";
+import { Eyebrow } from "../primitives";
+import { Button, type ButtonProps } from "../primitives/Button";
+import { useWithBase } from "../routing/BasePathProvider";
+
+export interface HeroCTA {
+	label: string;
+	href: string;
+	newTab?: boolean;
+}
+
+export interface HeroTrustItem {
+	value: string;
+	label: string;
+}
+
+export interface HeroProps {
+	eyebrow?: string;
+	/** Headline; use <em className="serif"> spans for the serif accent. */
+	title: ReactNode;
+	subtitle?: ReactNode;
+	/** Full-bleed hero image; omit to render the token-gradient fallback. */
+	image?: {
+		src: string;
+		alt: string;
+		/**
+		 * CSS object-position anchoring the photo's subject, e.g. "27% 35%".
+		 * Narrow viewports crop the sides of a cover-fit hero; without an
+		 * anchor the default center crop can push the subject out of frame.
+		 */
+		position?: string;
+	};
+	primaryCta?: HeroCTA;
+	secondaryCta?: HeroCTA;
+	/** Trust indicators rendered under the CTAs. */
+	trust?: HeroTrustItem[];
+	/** Anchor target for the scroll-down affordance, e.g. "#pain". */
+	scrollTarget?: string;
+}
+
+/** Full-bleed image hero with scrim, headline, CTA pair, and trust stats. */
+export function Hero({
+	eyebrow,
+	title,
+	subtitle,
+	image,
+	primaryCta,
+	secondaryCta,
+	trust,
+	scrollTarget,
+}: HeroProps) {
+	const withBase = useWithBase();
+	const ctaProps = (cta: HeroCTA, extra: Partial<ButtonProps>) => ({
+		href: cta.href,
+		newTab: cta.newTab,
+		...extra,
+	});
+
+	return (
+		<section className="hero">
+			<div className="hero-media">
+				{image ? (
+					<img
+						src={withBase(image.src)}
+						alt={image.alt}
+						fetchPriority="high"
+						{...(image.position ? { style: { objectPosition: image.position } } : {})}
+					/>
+				) : (
+					<div className="hero-media-fallback" />
+				)}
+				<div className="hero-scrim" />
+			</div>
+			<div className="wrap hero-content">
+				{eyebrow && <Eyebrow onDark>{eyebrow}</Eyebrow>}
+				<h1>{title}</h1>
+				{subtitle && <p className="hero-sub">{subtitle}</p>}
+				{(primaryCta || secondaryCta) && (
+					<div className="cta-row">
+						{primaryCta && (
+							<Button {...ctaProps(primaryCta, { size: "lg", arrow: true })}>
+								{primaryCta.label}
+							</Button>
+						)}
+						{secondaryCta && (
+							<Button {...ctaProps(secondaryCta, { variant: "ghost", size: "lg", onDark: true })}>
+								{secondaryCta.label}
+							</Button>
+						)}
+					</div>
+				)}
+				{trust && trust.length > 0 && (
+					<ul className="hero-trust">
+						{trust.map((item) => (
+							<li key={item.label}>
+								<strong>{item.value}</strong>
+								<span>{item.label}</span>
+							</li>
+						))}
+					</ul>
+				)}
+			</div>
+			{scrollTarget && (
+				<a className="hero-scroll" href={withBase(scrollTarget)} aria-label="Scroll down">
+					↓
+				</a>
+			)}
+		</section>
+	);
+}

package/src/sections/HoursTable.tsx

@@ -0,0 +1,23 @@
+import { formatHoursRange, isClosed } from "../lib/hours";
+import type { OpeningHours } from "./siteConfig";
+
+export interface HoursTableProps {
+	hours: OpeningHours[];
+}
+
+/** Day-by-day hours rows with dashed rules and mono times. */
+export function HoursTable({ hours }: HoursTableProps) {
+	return (
+		<div>
+			{hours.map((row) => (
+				<div
+					key={row.label}
+					className={["hours-row", isClosed(row) && "closed"].filter(Boolean).join(" ")}
+				>
+					<span className="day">{row.label}</span>
+					<span className="time">{formatHoursRange(row)}</span>
+				</div>
+			))}
+		</div>
+	);
+}

package/src/sections/JumpRail.tsx

@@ -0,0 +1,35 @@
+import { type PageStop, useScrollSpy } from "../hooks";
+
+/** One tab on the rail: an anchor already on the page. */
+export type JumpRailItem = PageStop;
+
+export interface JumpRailProps {
+	items: JumpRailItem[];
+	ariaLabel?: string;
+}
+
+/**
+ * Sticky in page navigation: a pill tab per section anchor, highlighted by
+ * scroll spy as its section enters the reading band. Extracted from the FAQ
+ * browser's category tabs so any long page can share it. The scroll spy
+ * comes from @atelic-action/ui, the same hook the header's page stops use.
+ */
+export function JumpRail({ items, ariaLabel = "Page sections" }: JumpRailProps) {
+	const activeId = useScrollSpy(items.map((item) => item.id));
+
+	return (
+		<nav className="jump-rail" aria-label={ariaLabel}>
+			<div className="wrap jump-rail-inner">
+				{items.map((item) => (
+					<a
+						key={item.id}
+						href={`#${item.id}`}
+						className={activeId === item.id ? "active" : undefined}
+					>
+						{item.label}
+					</a>
+				))}
+			</div>
+		</nav>
+	);
+}