@atelic-action/ui 0.17.1 → 1.0.0

package/src/sections/RevealSlider.tsx

@@ -0,0 +1,156 @@
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import {
+	type CSSProperties,
+	type KeyboardEvent,
+	type PointerEvent,
+	useCallback,
+	useRef,
+	useState,
+} from "react";
+import { useWithBase } from "../routing/BasePathProvider";
+
+export interface RevealSlide {
+	/** The image. Omit it and pass `placeholder` until the real shot exists. */
+	src?: string;
+	alt?: string;
+	/**
+	 * Shot brief rendered as a labeled block when there is no `src` yet, e.g.
+	 * "Screenshot: the old home page on a phone". The two sides render in
+	 * different tones, so dragging still moves something visible.
+	 */
+	placeholder?: string;
+	/** Corner label, e.g. "Today" or "The rebuild". */
+	label: string;
+}
+
+export interface RevealSliderProps {
+	/** The current-state image, revealed on the left. */
+	before: RevealSlide;
+	/** The rebuilt-state image, the base layer on the right. */
+	after: RevealSlide;
+	/** Starting divider position, 0-100. Default 50. */
+	startAt?: number;
+	/** Frame aspect ratio; both images should match it. Default "16/10". */
+	aspectRatio?: string;
+	/**
+	 * Accessible name for the drag handle. Defaults to a neutral before and
+	 * after, because what the two states are is the page's business rather
+	 * than the component's. Name them when the page can be specific.
+	 */
+	ariaLabel?: string;
+}
+
+/** One side of the frame: the photograph, or its shot brief until one exists. */
+function Layer({
+	slide,
+	side,
+	style,
+}: {
+	slide: RevealSlide;
+	side: "before" | "after";
+	style?: CSSProperties;
+}) {
+	const withBase = useWithBase();
+	const base = ["rslider-layer", side === "before" && "rslider-before"].filter(Boolean).join(" ");
+	if (!slide.src) {
+		return (
+			<div className={`${base} rslider-ph is-${side}`} style={style}>
+				<span>{slide.placeholder ?? slide.label}</span>
+			</div>
+		);
+	}
+	return (
+		<img
+			className={`${base} rslider-img`}
+			src={withBase(slide.src)}
+			alt={slide.alt ?? ""}
+			draggable={false}
+			style={style}
+		/>
+	);
+}
+
+/**
+ * Drag-to-compare before/after slider. The rebuilt image is the base layer;
+ * the current image is masked with clip-path so dragging never distorts either
+ * one. SSR-safe: prerenders at `startAt`, then hydrates the pointer + keyboard
+ * handles. Reusable across any before/after reveal.
+ *
+ * A side with no `src` renders its shot brief instead, so a case study or a
+ * project page can be composed before the photography exists.
+ */
+export function RevealSlider({
+	before,
+	after,
+	startAt = 50,
+	aspectRatio = "16/10",
+	ariaLabel = "Drag to compare before and after",
+}: RevealSliderProps) {
+	const [pos, setPos] = useState(startAt);
+	const frameRef = useRef<HTMLDivElement>(null);
+	const dragging = useRef(false);
+
+	const setFromClientX = useCallback((clientX: number) => {
+		const el = frameRef.current;
+		if (!el) return;
+		const rect = el.getBoundingClientRect();
+		const next = ((clientX - rect.left) / rect.width) * 100;
+		setPos(Math.max(0, Math.min(100, next)));
+	}, []);
+
+	const onPointerDown = (e: PointerEvent<HTMLButtonElement>) => {
+		dragging.current = true;
+		e.currentTarget.setPointerCapture?.(e.pointerId);
+		setFromClientX(e.clientX);
+	};
+	const onPointerMove = (e: PointerEvent<HTMLDivElement>) => {
+		if (dragging.current) setFromClientX(e.clientX);
+	};
+	const endDrag = () => {
+		dragging.current = false;
+	};
+	const onKeyDown = (e: KeyboardEvent<HTMLButtonElement>) => {
+		if (e.key === "ArrowLeft") {
+			setPos((p) => Math.max(0, p - 3));
+			e.preventDefault();
+		} else if (e.key === "ArrowRight") {
+			setPos((p) => Math.min(100, p + 3));
+			e.preventDefault();
+		}
+	};
+
+	return (
+		<div
+			className="rslider"
+			style={{ aspectRatio }}
+			ref={frameRef}
+			onPointerMove={onPointerMove}
+			onPointerUp={endDrag}
+			onPointerLeave={endDrag}
+			onPointerCancel={endDrag}
+		>
+			<Layer slide={after} side="after" />
+			<Layer slide={before} side="before" style={{ clipPath: `inset(0 ${100 - pos}% 0 0)` }} />
+			<span className="rslider-label rslider-label-before">{before.label}</span>
+			<span className="rslider-label rslider-label-after">{after.label}</span>
+			<div className="rslider-line" style={{ left: `${pos}%` }} aria-hidden />
+			<button
+				type="button"
+				className="rslider-handle"
+				style={{ left: `${pos}%` }}
+				role="slider"
+				aria-label={ariaLabel}
+				aria-valuemin={0}
+				aria-valuemax={100}
+				aria-valuenow={Math.round(pos)}
+				onPointerDown={onPointerDown}
+				onKeyDown={onKeyDown}
+			>
+				<span className="rslider-grip">
+					<ChevronLeft size={16} aria-hidden />
+					<ChevronRight size={16} aria-hidden />
+				</span>
+			</button>
+		</div>
+	);
+}

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