@atelic-action/ui 0.17.2 → 1.1.0

package/src/sections/ReviewCarousel.tsx

@@ -0,0 +1,223 @@
+import { ArrowUpRight, ChevronLeft, ChevronRight } from "lucide-react";
+import { type KeyboardEvent, type ReactNode, useState } from "react";
+import { Eyebrow } from "../primitives";
+import { StarRow } from "../primitives/StarRow";
+import type { ReviewItem } from "./ReviewWall";
+
+export type { ReviewItem };
+
+export interface ReviewStat {
+	value: string;
+	label: string;
+}
+
+export interface ReviewCarouselProps {
+	eyebrow?: string;
+	/** The aggregate figure as a string, so "5.0" keeps its zero. */
+	score: string;
+	/** The denominator beside the score; pass an empty string to drop it. */
+	outOf?: string;
+	/** Aggregate star row, 1 to 5. Omit when the source shows no stars. */
+	rating?: number;
+	/** Caption beside the stars, e.g. "from 100 verified Google reviews". */
+	caption?: string;
+	/**
+	 * Permalink to the business's live review profile; turns the caption
+	 * into a link out to it, the same idiom `ReviewWall` uses for a review's
+	 * dated source link. Without a `caption` there is nothing to link, so
+	 * the prop is inert. Prefer a count the profile can't outgrow ("100+"),
+	 * since the live number climbs and the caption doesn't.
+	 */
+	profileUrl?: string;
+	/** Short paragraph under the caption: where the reviews come from. */
+	lead?: ReactNode;
+	/** Optional value/label row (three reads well). Omit to hide entirely. */
+	stats?: ReviewStat[];
+	/** The reviews, shown one at a time. */
+	items: ReviewItem[];
+	/** Accessible name for the carousel region. */
+	ariaLabel?: string;
+	id?: string;
+	className?: string;
+}
+
+/**
+ * Real reviews run from a sentence to a paragraph, and every slide shares
+ * one card, so the quote's type size steps down as it gets longer: short
+ * quotes stay big and quotable, long ones stay inside a card the page can
+ * hold. Length, not layout, decides — the same quote always sets the same
+ * way, on the server and in the browser.
+ */
+function quoteSize(quote: string): string {
+	if (quote.length > 420) return "is-compact";
+	if (quote.length > 260) return "is-medium";
+	return "";
+}
+
+/**
+ * The social-proof split: the aggregate rating on the left (eyebrow, big
+ * score, star row and caption, a short provenance paragraph, an optional
+ * stat row) and a single large review card on the right, stepped through
+ * with dot pagination and round prev/next arrows.
+ *
+ * Every quote ships in the static HTML — inactive slides are hidden by
+ * CSS, never conditionally rendered — so crawlers and answer engines read
+ * all of them. Slides stack in one grid cell, so the card is as tall as
+ * the longest quote and stepping never shifts the page.
+ *
+ * Per-review stars are opt-in per item (`rating`), like `ReviewWall`:
+ * render them only when the source actually shows them.
+ *
+ * `profileUrl` turns the caption into a link out to the live review
+ * profile, carrying the wall's dated-source idiom (quiet text, trailing
+ * arrow, new tab) so a visitor can check the aggregate at the source.
+ */
+export function ReviewCarousel({
+	eyebrow,
+	score,
+	outOf = "5",
+	rating,
+	caption,
+	profileUrl,
+	lead,
+	stats,
+	items,
+	ariaLabel = "Customer reviews",
+	id,
+	className,
+}: ReviewCarouselProps) {
+	const [rawIndex, setIndex] = useState(0);
+	const count = items.length;
+	const index = Math.min(rawIndex, Math.max(count - 1, 0));
+
+	function go(next: number) {
+		if (count === 0) return;
+		setIndex(((next % count) + count) % count);
+	}
+
+	// Left/right step the carousel whenever focus sits on one of its
+	// controls, the keyboard convention for a paged region.
+	function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+		if (event.key === "ArrowLeft") {
+			event.preventDefault();
+			go(index - 1);
+		} else if (event.key === "ArrowRight") {
+			event.preventDefault();
+			go(index + 1);
+		}
+	}
+
+	return (
+		<section
+			className={["section", "review-carousel", className].filter(Boolean).join(" ")}
+			id={id}
+		>
+			<div className="wrap rc-grid">
+				<div className="rc-aggregate">
+					{eyebrow && <Eyebrow>{eyebrow}</Eyebrow>}
+					<p className="rc-score">
+						<span className="rc-score-num">{score}</span>
+						{outOf && <span className="rc-score-out">/ {outOf}</span>}
+					</p>
+					{(rating != null || caption) && (
+						<p className="rc-rating">
+							{rating != null && <StarRow rating={rating} size={19} />}
+							{caption &&
+								(profileUrl ? (
+									<a
+										className="rc-caption"
+										href={profileUrl}
+										target="_blank"
+										rel="noopener"
+										aria-label={`${caption}, opens the review profile in a new tab`}
+									>
+										{caption}
+										<ArrowUpRight size={14} strokeWidth={2} aria-hidden="true" />
+									</a>
+								) : (
+									<span className="rc-caption">{caption}</span>
+								))}
+						</p>
+					)}
+					{lead && <p className="rc-lead">{lead}</p>}
+					{stats && stats.length > 0 && (
+						<dl className="rc-stats">
+							{stats.map((stat) => (
+								<div className="rc-stat" key={stat.label}>
+									<dt className="rc-stat-value">{stat.value}</dt>
+									<dd className="rc-stat-label">{stat.label}</dd>
+								</div>
+							))}
+						</dl>
+					)}
+				</div>
+
+				{/* A named <section> is an ARIA region, the carousel pattern's
+				    wrapper — spelled semantically rather than role="group". */}
+				<section
+					className="rc-viewport"
+					aria-roledescription="carousel"
+					aria-label={ariaLabel}
+					onKeyDown={onKeyDown}
+				>
+					<div className="rc-stage" aria-live="polite">
+						{items.map((item, i) => (
+							<figure
+								className={["rc-slide", i === index && "is-active"].filter(Boolean).join(" ")}
+								key={item.by + item.quote.slice(0, 24)}
+								aria-hidden={i !== index}
+								aria-roledescription="slide"
+								aria-label={`Review ${i + 1} of ${count}`}
+							>
+								{item.rating != null && <StarRow rating={item.rating} size={17} />}
+								<blockquote
+									className={["rc-quote", quoteSize(item.quote)].filter(Boolean).join(" ")}
+								>
+									“{item.quote}”
+								</blockquote>
+								<figcaption className="rc-who">
+									<span className="rc-name">{item.by}</span>
+									{item.detail && <span className="rc-detail">{item.detail}</span>}
+								</figcaption>
+							</figure>
+						))}
+					</div>
+
+					<div className="rc-controls">
+						<div className="rc-dots">
+							{items.map((_, i) => (
+								<button
+									type="button"
+									className={["rc-dot", i === index && "is-active"].filter(Boolean).join(" ")}
+									// biome-ignore lint/suspicious/noArrayIndexKey: a dot is a position, not an identity; review text can repeat
+									key={`dot-${i}`}
+									aria-label={`Go to review ${i + 1}`}
+									aria-current={i === index}
+									onClick={() => setIndex(i)}
+								/>
+							))}
+						</div>
+						<div className="rc-arrows">
+							<button
+								type="button"
+								className="rc-arrow"
+								aria-label="Previous review"
+								onClick={() => go(index - 1)}
+							>
+								<ChevronLeft size={18} strokeWidth={2} aria-hidden="true" />
+							</button>
+							<button
+								type="button"
+								className="rc-arrow"
+								aria-label="Next review"
+								onClick={() => go(index + 1)}
+							>
+								<ChevronRight size={18} strokeWidth={2} aria-hidden="true" />
+							</button>
+						</div>
+					</div>
+				</section>
+			</div>
+		</section>
+	);
+}

package/src/sections/ReviewWall.tsx

@@ -0,0 +1,220 @@
+import { ArrowUpRight } from "lucide-react";
+import { type ReactNode, useMemo, useState } from "react";
+import { SectionHeading } from "../primitives";
+import { StarRow } from "../primitives/StarRow";
+
+export interface ReviewItem {
+	/** The review text, verbatim. Rendered inside typographic quote marks. */
+	quote: string;
+	/** Attribution, exactly as the source attributes it (e.g. "Greg T."). */
+	by: string;
+	/** Optional context line under the name: a source, a service, a city. */
+	detail?: string;
+	/**
+	 * Star count, 1 to 5. Render stars only when the source shows them —
+	 * never invent a rating the reviewer didn't give.
+	 */
+	rating?: number;
+	/**
+	 * Review date as the source gives it. An ISO date (`2026-04-24`) sorts
+	 * correctly and renders as-is; any other string renders but sorts
+	 * lexically, so prefer ISO.
+	 */
+	date?: string;
+	/** Permalink to the review at its source; turns the date into a link. */
+	sourceUrl?: string;
+	/** Short labels (service, program, location) that drive the filter. */
+	tags?: string[];
+}
+
+export interface ReviewWallProps {
+	items: ReviewItem[];
+	/** Optional header block above the grid. */
+	eyebrow?: string;
+	title?: ReactNode;
+	lead?: ReactNode;
+	/**
+	 * Tag filter dropdown. Defaults to on whenever the data carries tags —
+	 * pass `false` to suppress it; `true` is a no-op without tags.
+	 */
+	filterable?: boolean;
+	/**
+	 * Newest / oldest sort dropdown. Defaults to on whenever the data
+	 * carries dates.
+	 */
+	sortable?: boolean;
+	/** Label for the "no filter" option, e.g. "All services". */
+	allTagsLabel?: string;
+	/**
+	 * Character budget above which a quote visually clamps behind a
+	 * "Read more" toggle. The full text always ships in the static HTML
+	 * (the clamp is CSS-only), so crawlers read every word.
+	 */
+	clampAt?: number;
+	id?: string;
+	className?: string;
+}
+
+function initials(by: string): string {
+	return by
+		.split(/\s+/)
+		.slice(0, 2)
+		.map((word) => word[0] ?? "")
+		.join("")
+		.toUpperCase();
+}
+
+function ReviewCard({ item, clampAt }: { item: ReviewItem; clampAt: number }) {
+	const clampable = item.quote.length > clampAt;
+	const [expanded, setExpanded] = useState(false);
+	return (
+		<figure className="rw-card">
+			{(item.rating != null || item.date) && (
+				<div className="rw-top">
+					{item.rating != null && <StarRow rating={item.rating} />}
+					{item.date &&
+						(item.sourceUrl ? (
+							<a
+								className="rw-date"
+								href={item.sourceUrl}
+								target="_blank"
+								rel="noopener"
+								aria-label={`Read the ${item.date} review from ${item.by} at its source`}
+							>
+								{item.date}
+								<ArrowUpRight size={13} strokeWidth={2} aria-hidden="true" />
+							</a>
+						) : (
+							<span className="rw-date">{item.date}</span>
+						))}
+				</div>
+			)}
+			<blockquote
+				className={["rw-quote", clampable && !expanded && "clamped"].filter(Boolean).join(" ")}
+			>
+				“{item.quote}”
+			</blockquote>
+			{clampable && (
+				<button
+					type="button"
+					className="rw-more"
+					aria-expanded={expanded}
+					onClick={() => setExpanded((open) => !open)}
+				>
+					{expanded ? "Show less" : "Read more"}
+				</button>
+			)}
+			{item.tags && item.tags.length > 0 && (
+				<div className="rw-tags">
+					{item.tags.map((tag) => (
+						<span className="rw-tag" key={tag}>
+							{tag}
+						</span>
+					))}
+				</div>
+			)}
+			<figcaption className="rw-who">
+				<span className="rw-avatar" aria-hidden="true">
+					{initials(item.by)}
+				</span>
+				<span className="rw-name-block">
+					<span className="rw-name">{item.by}</span>
+					{item.detail && <span className="rw-detail">{item.detail}</span>}
+				</span>
+			</figcaption>
+		</figure>
+	);
+}
+
+/**
+ * The reviews-page organism: an optional header block, optional tag and
+ * sort controls, and a responsive grid of uniform review cards. Each card
+ * carries an optional star row, an optional date that links out to the
+ * review at its source, a CSS-clamped quote behind a per-card "Read more"
+ * toggle, optional tag chips, and an initials-avatar attribution line
+ * pinned to the card floor.
+ *
+ * Everything above the grid is optional, so the bare `<ReviewWall items />`
+ * form still renders a plain wall under a page's own SectionHeading. The
+ * controls appear only when the data can drive them (tags for the filter,
+ * dates for the sort), and the unfiltered state is what prerenders, so
+ * every quote ships in the static HTML.
+ */
+export function ReviewWall({
+	items,
+	eyebrow,
+	title,
+	lead,
+	filterable,
+	sortable,
+	allTagsLabel = "All tags",
+	clampAt = 220,
+	id,
+	className,
+}: ReviewWallProps) {
+	const tags = useMemo(() => {
+		const seen = new Set<string>();
+		for (const item of items) for (const tag of item.tags ?? []) seen.add(tag);
+		return [...seen].sort((a, b) => a.localeCompare(b));
+	}, [items]);
+	const hasDates = useMemo(() => items.some((item) => item.date), [items]);
+
+	const showFilter = (filterable ?? true) && tags.length > 0;
+	const showSort = (sortable ?? true) && hasDates;
+
+	const [tag, setTag] = useState("");
+	const [order, setOrder] = useState<"newest" | "oldest">("newest");
+
+	const shown = useMemo(() => {
+		const kept = tag ? items.filter((item) => item.tags?.includes(tag)) : [...items];
+		if (!showSort) return kept;
+		return kept.sort((a, b) => {
+			const left = a.date ?? "";
+			const right = b.date ?? "";
+			if (left === right) return 0;
+			return order === "newest" ? right.localeCompare(left) : left.localeCompare(right);
+		});
+	}, [items, tag, order, showSort]);
+
+	return (
+		<div className={["review-wall-block", className].filter(Boolean).join(" ")} id={id}>
+			{(eyebrow || title) && <SectionHeading eyebrow={eyebrow} title={title ?? ""} lead={lead} />}
+
+			{(showFilter || showSort) && (
+				<div className="rw-controls">
+					{showFilter && (
+						<label className="rw-select">
+							<span className="rw-select-label">Filter reviews by tag</span>
+							<select value={tag} onChange={(event) => setTag(event.target.value)}>
+								<option value="">{allTagsLabel}</option>
+								{tags.map((option) => (
+									<option key={option} value={option}>
+										{option}
+									</option>
+								))}
+							</select>
+						</label>
+					)}
+					{showSort && (
+						<label className="rw-select rw-select-end">
+							<span className="rw-select-label">Sort reviews by date</span>
+							<select
+								value={order}
+								onChange={(event) => setOrder(event.target.value as "newest" | "oldest")}
+							>
+								<option value="newest">Newest</option>
+								<option value="oldest">Oldest</option>
+							</select>
+						</label>
+					)}
+				</div>
+			)}
+
+			<div className="review-wall">
+				{shown.map((item) => (
+					<ReviewCard key={item.by + item.quote.slice(0, 24)} item={item} clampAt={clampAt} />
+				))}
+			</div>
+		</div>
+	);
+}

package/src/sections/SocialStrip.tsx

@@ -0,0 +1,83 @@
+import { AtSign } from "lucide-react";
+import type { ReactNode } from "react";
+import { SectionHeading } from "../primitives";
+import { Button } from "../primitives/Button";
+import { useWithBase } from "../routing/BasePathProvider";
+
+export interface SocialPhoto {
+	src?: string;
+	alt?: string;
+	/** Placeholder shot brief rendered when no src exists yet. */
+	placeholder?: string;
+}
+
+export interface SocialStripProps {
+	eyebrow?: string;
+	/** Deprecated no-op: the eyebrow's trailing fade is now its only rendering. */
+	eyebrowRun?: boolean;
+	title: ReactNode;
+	lead?: string;
+	/** Display handle, e.g. "@platformstrength". */
+	handle: string;
+	/** The profile the strip links out to. */
+	profileUrl: string;
+	photos: SocialPhoto[];
+	/** Follow button label; defaults to "Follow {handle}". */
+	followLabel?: string;
+	surface?: "default" | "alt";
+	id?: string;
+}
+
+/**
+ * A static strip of the business's own social photos with a follow link out.
+ * Deliberately not a live embed: third-party embed scripts are heavy,
+ * render-blocking, and break silently on static exports. Photos ship as local
+ * assets; the platform link carries the relationship.
+ */
+export function SocialStrip({
+	eyebrow,
+	title,
+	lead,
+	handle,
+	profileUrl,
+	photos,
+	followLabel,
+	surface = "default",
+	id,
+}: SocialStripProps) {
+	const withBase = useWithBase();
+	const sectionClasses = ["section", surface === "alt" && "surface-alt"].filter(Boolean).join(" ");
+	return (
+		<section className={sectionClasses} id={id}>
+			<div className="wrap">
+				<SectionHeading eyebrow={eyebrow} title={title} lead={lead} />
+				<div className="social-strip">
+					{photos.map((photo) =>
+						photo.src ? (
+							<a
+								key={photo.src}
+								className="social-tile"
+								href={profileUrl}
+								target="_blank"
+								rel="noopener"
+								aria-label={photo.alt ? `${photo.alt} (opens ${handle})` : `Opens ${handle}`}
+							>
+								<img src={withBase(photo.src)} alt={photo.alt ?? ""} loading="lazy" />
+							</a>
+						) : (
+							<div key={photo.placeholder} className="social-tile ph">
+								{photo.placeholder ?? "Photo"}
+							</div>
+						),
+					)}
+				</div>
+				<div className="social-follow">
+					<Button href={profileUrl} newTab variant="dark">
+						<AtSign size={17} aria-hidden />
+						{followLabel ?? `Follow ${handle}`}
+					</Button>
+				</div>
+			</div>
+		</section>
+	);
+}

package/src/sections/SplitSection.tsx

@@ -0,0 +1,56 @@
+import type { ReactNode } from "react";
+
+export interface SplitSectionProps {
+	left: ReactNode;
+	right: ReactNode;
+	/**
+	 * Column proportions: "even" (1/1), or "narrow-first" (0.9/1.1,
+	 * the media-plus-copy pattern).
+	 */
+	ratio?: "even" | "narrow-first";
+	align?: "start" | "center";
+	/** Section background band. */
+	surface?: "default" | "alt";
+	/** Compact top padding for sections directly under a page hero. */
+	tightTop?: boolean;
+	/**
+	 * Compact bottom padding for when the next section continues this
+	 * one's thought (e.g. a list that belongs to this section's copy).
+	 * Pair with `tight-top` on the follower to close the gap.
+	 */
+	tightBottom?: boolean;
+	id?: string;
+	className?: string;
+}
+
+/** The recurring two-column section: copy plus copy, or media plus copy. */
+export function SplitSection({
+	left,
+	right,
+	ratio = "even",
+	align = "start",
+	surface = "default",
+	tightTop = false,
+	tightBottom = false,
+	id,
+	className,
+}: SplitSectionProps) {
+	const sectionClasses = [
+		"section",
+		surface === "alt" && "surface-alt",
+		tightTop && "tight-top",
+		tightBottom && "tight-bottom",
+		className,
+	]
+		.filter(Boolean)
+		.join(" ");
+	const gridClasses = ["split", `ratio-${ratio}`, `align-${align}`].join(" ");
+	return (
+		<section className={sectionClasses} id={id}>
+			<div className={`wrap ${gridClasses}`}>
+				<div>{left}</div>
+				<div>{right}</div>
+			</div>
+		</section>
+	);
+}

package/src/sections/index.ts

@@ -0,0 +1,76 @@
+/**
+ * `@atelic-action/ui/sections`: the page scale sections a marketing site
+ * composes, moved here from template-marketing in 0.19.0 (ATE-643), with the
+ * `SiteConfig` contract they and `SiteShell` read. Their styles are
+ * `@atelic-action/ui/styles/sections.css`; a section imports no stylesheet of
+ * its own.
+ */
+export { isHoneypotFilled } from "../lib/honeypot";
+export { formatClock, formatHoursRange, isClosed } from "../lib/hours";
+export { type EventParams, trackEvent } from "../lib/trackEvent";
+export { BlogIndex, type BlogIndexItem, type BlogIndexProps } from "./BlogIndex";
+export { BlogPost, type BlogPostDoc, type BlogPostProps } from "./BlogPost";
+export {
+	type ComparisonRow,
+	type ComparisonState,
+	ComparisonTable,
+	type ComparisonTableProps,
+} from "./ComparisonTable";
+export { ContactForm, type ContactFormProps } from "./ContactForm";
+export {
+	ContactInfoCard,
+	type ContactInfoCardProps,
+	type ContactInfoCardSite,
+	type ContactPhone,
+} from "./ContactInfoCard";
+export { type Credential, CredentialList, type CredentialListProps } from "./CredentialList";
+export { CTABanner, type CTABannerCTA, type CTABannerProps } from "./CTABanner";
+export { CTASection, type CTASectionProps } from "./CTASection";
+export { type DeviceImage, DeviceShowcase, type DeviceShowcaseProps } from "./DeviceShowcase";
+export { ExpandList, type ExpandListItem, type ExpandListProps } from "./ExpandList";
+export {
+	FAQBrowser,
+	type FAQBrowserProps,
+	type FAQCategory,
+	type FAQCta,
+	type FAQEntry,
+} from "./FAQBrowser";
+export { FeatureDetail, type FeatureDetailProps } from "./FeatureDetail";
+export { type FeatureCard, FeatureGrid, type FeatureGridProps } from "./FeatureGrid";
+export { Gallery, type GalleryPhoto, type GalleryProps } from "./Gallery";
+export { Hero, type HeroCTA, type HeroProps, type HeroTrustItem } from "./Hero";
+export { HoursTable, type HoursTableProps } from "./HoursTable";
+export { JumpRail, type JumpRailItem, type JumpRailProps } from "./JumpRail";
+export { type LegalBlock, type LegalDoc, LegalPage, type LegalPageProps } from "./LegalPage";
+export {
+	LocationSection,
+	type LocationSectionProps,
+	type LocationSectionSite,
+} from "./LocationSection";
+export { type LocationEntry, Locations, type LocationsProps } from "./Locations";
+export { LogoMarquee, type LogoMarqueeProps } from "./LogoMarquee";
+export { MapEmbed, type MapEmbedProps, type MapEmbedSite } from "./MapEmbed";
+export { MediaBand, type MediaBandProps } from "./MediaBand";
+export { MenuList, type MenuListItem, type MenuListProps } from "./MenuList";
+export { PageHero, type PageHeroProps } from "./PageHero";
+export { type PressItem, PressQuotes, type PressQuotesProps, sortPress } from "./PressQuotes";
+export { PricingBand, type PricingBandProps } from "./PricingBand";
+export { PricingCard, type PricingCardProps } from "./PricingCard";
+export { type ProcessStep, ProcessSteps, type ProcessStepsProps } from "./ProcessSteps";
+export { ProfileCards, type ProfileCardsProps, type ProfileItem } from "./ProfileCards";
+export { type RevealSlide, RevealSlider, type RevealSliderProps } from "./RevealSlider";
+export { ReviewCarousel, type ReviewCarouselProps, type ReviewStat } from "./ReviewCarousel";
+export { type ReviewItem, ReviewWall, type ReviewWallProps } from "./ReviewWall";
+export { type SocialPhoto, SocialStrip, type SocialStripProps } from "./SocialStrip";
+export { SplitSection, type SplitSectionProps } from "./SplitSection";
+export type {
+	Address,
+	CTA,
+	Founder,
+	GateConfig,
+	NavItem,
+	OpeningHours,
+	SiteConfig,
+	SiteLink,
+	SocialLink,
+} from "./siteConfig";