@atelic-action/ui 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @atelic-action/ui
+
+Shared UI for the Atelic templates: the site chrome (header, menu, footer, sticky CTA bar, and credit band), the scroll spy hook, and the one base stylesheet. The marketing and artifact templates install it instead of carrying their own copies, so a chrome fix lands once and every site picks it up with `bun update`.
+
+The package ships source, not a build. Its TSX and CSS arrive as written and compile inside each site's own Vite.
+
+## Install
+
+```bash
+bun add @atelic-action/ui
+```
+
+Peer dependencies: `react` and `react-dom` at `^19.0.0`, and `lucide-react` at `^1.23.0`.
+
+## Vite Config
+
+Prerendering and server rendering have to compile the package too, so keep it out of Vite's SSR externals. That is the one line a consumer adds:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+	ssr: { noExternal: ["@atelic-action/ui"] },
+});
+```
+
+## CSS Import Order
+
+Import the stylesheets in this order, from the root route or the site's base sheet:
+
+1. The site's fonts (`fonts.css`)
+2. `@atelic-action/ui/styles/base.css`
+3. `@atelic-action/ui/styles/chrome.css`
+4. The site's own CSS
+5. The site's `theme.css`, last
+
+Both package sheets sit inside `@layer atelic-ui`, so any rule a site writes outside a layer wins over them whatever its specificity. The package reads the theme tokens (`--ink`, `--surface`, `--primary`, `--nav-height`, and the rest) and defines none, so `theme.css` stays the one file a site edits to rebrand. The chrome's buttons wear the site's own `.btn` classes.
+
+## What Is Inside
+
+| Import | Exports |
+|---|---|
+| `@atelic-action/ui/chrome` | `SiteHeader`, `SiteMenu`, `Footer`, `CreditBar`, `StickyCTABar`, `BrandLockup`, `SkipLink`, and their prop types |
+| `@atelic-action/ui/hooks` | `useScrollSpy` and its `PageStop` type |
+| `@atelic-action/ui/styles/base.css` | Resets, the `.mkt` canvas, typography, and layout helpers |
+| `@atelic-action/ui/styles/chrome.css` | Styles for everything under `chrome` |
+
+Every component renders from props alone. None reads a config file or a router, so a site maps its own config onto the props in its shell:
+
+```tsx
+import { Footer, SiteHeader, SkipLink, StickyCTABar } from "@atelic-action/ui/chrome";
+
+<div className="mkt">
+	<SkipLink />
+	<SiteHeader
+		brand={{ name: site.name, logo: site.logo }}
+		links={site.nav.map((item) => ({ label: item.label, href: item.to }))}
+		primaryCTA={site.cta}
+		variant="transparent"
+		currentPath={pathname}
+	/>
+	<main id="main">{children}</main>
+	<StickyCTABar primaryCTA={site.cta} phone={site.phone} />
+	<Footer brand={{ name: site.name, logo: site.logo }} email={site.email} />
+</div>;
+```
+
+The menu is a native `<dialog>` opened with `showModal()`, so Escape, focus containment, and focus return come from the browser.
+
+## Releasing
+
+1. Bump `version` in `package.json` and merge it to `main`: patch for a fix, minor for a new component or prop, major for a breaking prop or class rename.
+2. Tag the merged commit `vX.Y.Z` with the same version and push the tag:
+
+   ```bash
+   git tag v0.1.1
+   git push origin v0.1.1
+   ```
+
+3. The Publish workflow checks that the tag matches the version, runs the gates, and publishes to npm with provenance. It needs the `NPM_TOKEN` repository secret and the `@atelic` npm organization.

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@atelic-action/ui",
+	"version": "0.1.0",
+	"description": "Shared UI for the Atelic templates: site chrome, base styles, and the component library they install",
+	"type": "module",
+	"license": "UNLICENSED",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/atelic-action/ui.git"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"exports": {
+		"./chrome": "./src/chrome/index.ts",
+		"./hooks": "./src/hooks/index.ts",
+		"./styles/base.css": "./src/styles/base.css",
+		"./styles/chrome.css": "./src/styles/chrome.css",
+		"./package.json": "./package.json"
+	},
+	"scripts": {
+		"lint": "biome check .",
+		"lint:fix": "biome check . --write",
+		"typecheck": "tsc --noEmit",
+		"test:run": "vitest run"
+	},
+	"peerDependencies": {
+		"lucide-react": "^1.23.0",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.13",
+		"@testing-library/jest-dom": "^6.6.2",
+		"@testing-library/react": "^16.0.1",
+		"@types/react": "^19.0.0",
+		"@types/react-dom": "^19.0.0",
+		"jsdom": "^25.0.1",
+		"lucide-react": "^1.23.0",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"typescript": "^5.6.3",
+		"vitest": "^4.0.0"
+	},
+	"trustedDependencies": [
+		"@biomejs/biome"
+	]
+}

package/src/chrome/BrandLockup.tsx

@@ -0,0 +1,29 @@
+import type { Brand } from "../types";
+
+export interface BrandLockupProps {
+	brand: Brand;
+	/** The link's accessible name. Defaults to "<name> home". */
+	ariaLabel?: string;
+}
+
+/**
+ * The header's identity as one link: the mark (a glyph tile or an image),
+ * the wordmark, and the trailing run. The image carries empty alt text
+ * because the link's own label already names it.
+ */
+export function BrandLockup({ brand, ariaLabel }: BrandLockupProps) {
+	const { name, href = "/", logo } = brand;
+	return (
+		<a className="nav-logo" href={href} aria-label={ariaLabel ?? `${name} home`}>
+			{logo?.tile ? (
+				<span className="logo-tile" aria-hidden="true">
+					{logo.tile}
+				</span>
+			) : (
+				logo?.src && <img className="mark" src={logo.src} alt="" />
+			)}
+			<span className="wordmark">{logo?.wordmark ?? name}</span>
+			{logo?.run && <span className="wordmark-run" aria-hidden="true" />}
+		</a>
+	);
+}

package/src/chrome/CreditBar.tsx

@@ -0,0 +1,18 @@
+/**
+ * The standardized developer credit: a full width band, visually separate
+ * from anything above it, centered and muted. Footer renders it at its foot,
+ * and a page that drops the footer renders it on its own.
+ *
+ * The heart ships as an escape sequence: the no emoji test bars literal
+ * pictographs from `src/`.
+ */
+export function CreditBar() {
+	return (
+		<div className="credit-bar">
+			Developed with {"\u{1F49A}"} in Denver by{" "}
+			<a href="https://atelic.me" target="_blank" rel="noopener">
+				Atelic
+			</a>
+		</div>
+	);
+}

package/src/chrome/Footer.tsx

@@ -0,0 +1,243 @@
+import { Mail, UserRound } from "lucide-react";
+import type { ComponentProps } from "react";
+import { newTabProps } from "../lib/newTabProps";
+import type {
+	Brand,
+	HoursRow,
+	NavLink,
+	Phone,
+	PostalAddress,
+	SiteLink,
+	SocialLink,
+} from "../types";
+import { CreditBar } from "./CreditBar";
+
+/*
+ * lucide-react ships no brand marks (removed upstream by policy), and a code
+ * glyph standing in for GitHub or a briefcase for LinkedIn misleads the
+ * reader. These two are the brands' own simple marks, carried by hand as a
+ * considered exception to the lucide only rule; like lucide icons they take
+ * currentColor and a size prop.
+ */
+type MarkProps = { size?: number } & ComponentProps<"svg">;
+
+function GitHubMark({ size = 18, ...rest }: MarkProps) {
+	return (
+		<svg
+			aria-hidden="true"
+			viewBox="0 0 24 24"
+			width={size}
+			height={size}
+			fill="currentColor"
+			{...rest}
+		>
+			<path d="M12 .5C5.65.5.5 5.65.5 12c0 5.08 3.29 9.39 7.86 10.91.58.11.79-.25.79-.55 0-.27-.01-1.17-.02-2.12-3.2.7-3.87-1.36-3.87-1.36-.52-1.33-1.28-1.68-1.28-1.68-1.04-.71.08-.7.08-.7 1.15.08 1.76 1.19 1.76 1.19 1.03 1.76 2.69 1.25 3.34.96.1-.75.4-1.25.72-1.54-2.55-.29-5.23-1.28-5.23-5.68 0-1.26.45-2.28 1.19-3.09-.12-.29-.52-1.46.11-3.05 0 0 .97-.31 3.17 1.18a11 11 0 0 1 5.77 0c2.2-1.49 3.16-1.18 3.16-1.18.63 1.59.23 2.76.12 3.05.74.81 1.18 1.83 1.18 3.09 0 4.41-2.69 5.38-5.25 5.67.41.35.77 1.05.77 2.12 0 1.53-.01 2.76-.01 3.14 0 .3.2.67.8.55A11.51 11.51 0 0 0 23.5 12C23.5 5.65 18.35.5 12 .5z" />
+		</svg>
+	);
+}
+
+function LinkedInMark({ size = 18, ...rest }: MarkProps) {
+	return (
+		<svg
+			aria-hidden="true"
+			viewBox="0 0 24 24"
+			width={size}
+			height={size}
+			fill="currentColor"
+			{...rest}
+		>
+			<path d="M4.98 3.5C4.98 4.88 3.87 6 2.5 6S0 4.88 0 3.5 1.12 1 2.5 1s2.48 1.12 2.48 2.5zM.22 8.1h4.56V23H.22V8.1zM8.34 8.1h4.37v2.03h.06c.61-1.15 2.1-2.37 4.32-2.37 4.62 0 5.47 3.04 5.47 6.99V23h-4.55v-7.28c0-1.74-.03-3.97-2.42-3.97-2.42 0-2.79 1.89-2.79 3.84V23H8.34V8.1z" />
+		</svg>
+	);
+}
+
+const SOCIAL_ICONS = {
+	github: GitHubMark,
+	linkedin: LinkedInMark,
+	mail: Mail,
+	user: UserRound,
+} as const;
+
+function SocialIconLink({ link }: { link: SocialLink }) {
+	const Icon = SOCIAL_ICONS[link.icon];
+	return (
+		<a
+			className="footer-social-link"
+			href={link.href}
+			aria-label={link.label}
+			title={link.label}
+			{...newTabProps(link.href, true)}
+		>
+			<Icon aria-hidden size={18} />
+		</a>
+	);
+}
+
+function FooterLink({ link }: { link: SiteLink }) {
+	return (
+		<a href={link.href} {...newTabProps(link.href, link.external)}>
+			{link.label}
+		</a>
+	);
+}
+
+export interface FooterProps {
+	/** The identity at the head of the brand column. */
+	brand: Brand;
+	/** Short brand paragraph under the identity. */
+	blurb?: string;
+	/** Icon links (socials, the founder's own site) under the blurb. */
+	socialLinks?: SocialLink[];
+	/** The site's nav, repeated in the explore column. */
+	links?: NavLink[];
+	/** Explore links beyond the nav, e.g. a patient portal. */
+	extraLinks?: SiteLink[];
+	/** Heading over the contact column. Defaults to "Visit". */
+	contactHeading?: string;
+	/**
+	 * The street address, printed under the business name. Omit it for a
+	 * practice with no storefront, and the phone and email stand alone under
+	 * the heading.
+	 */
+	address?: PostalAddress;
+	phone?: Phone;
+	email?: string;
+	/** Opening hours as display rows, already formatted by the site. */
+	hours?: HoursRow[];
+	/** Suffix on the copyright line, e.g. "Dr. Alex Rivers, PT, DPT". */
+	attribution?: string;
+	/** A short closing note beside the copyright line. */
+	note?: string;
+	legalLinks?: SiteLink[];
+	/** The developer credit band at the foot. Defaults on. */
+	credit?: boolean;
+}
+
+/** The site footer: brand blurb, explore nav, NAP block, hours, and the credit band. */
+export function Footer({
+	brand,
+	blurb,
+	socialLinks,
+	links,
+	extraLinks,
+	contactHeading = "Visit",
+	address,
+	phone,
+	email,
+	hours,
+	attribution,
+	note,
+	legalLinks,
+	credit = true,
+}: FooterProps) {
+	const { name, logo } = brand;
+	const wordmark = logo?.wordmark ?? name;
+
+	return (
+		<>
+			<footer className="footer">
+				<div className="wrap">
+					<div className="footer-grid">
+						<div className="footer-brand">
+							{logo?.tile ? (
+								<p className="footer-wordmark">
+									<span className="logo-tile" aria-hidden="true">
+										{logo.tile}
+									</span>
+									{wordmark}
+									{logo.run && <span className="wordmark-run" aria-hidden="true" />}
+								</p>
+							) : logo?.src ? (
+								<img src={logo.src} alt={logo.alt ?? name} />
+							) : (
+								<p className="footer-wordmark">
+									{wordmark}
+									{logo?.run && <span className="wordmark-run" aria-hidden="true" />}
+								</p>
+							)}
+							{blurb && <p>{blurb}</p>}
+							{socialLinks && socialLinks.length > 0 && (
+								<div className="footer-social">
+									{socialLinks.map((link) => (
+										<SocialIconLink key={link.href} link={link} />
+									))}
+								</div>
+							)}
+						</div>
+						<div>
+							<h4>Explore</h4>
+							<nav aria-label="Footer">
+								{links?.map((link) => (
+									<a key={link.href} href={link.href}>
+										{link.label}
+									</a>
+								))}
+								{extraLinks?.map((link) => (
+									<FooterLink key={link.href} link={link} />
+								))}
+							</nav>
+						</div>
+						<div>
+							<h4>{contactHeading}</h4>
+							<address className="nap">
+								{address && (
+									<>
+										<strong>{name}</strong>
+										<br />
+										{/* A business that publishes a service area but no storefront
+										    leaves street empty; a blank line reads as a broken block. */}
+										{address.street && (
+											<>
+												{address.street}
+												<br />
+											</>
+										)}
+										{address.locality}, {address.region}
+										{address.postalCode ? ` ${address.postalCode}` : ""}
+										<br />
+										<br />
+									</>
+								)}
+								{phone && (
+									<>
+										<a href={`tel:${phone.e164}`}>{phone.display}</a>
+										<br />
+									</>
+								)}
+								{email && <a href={`mailto:${email}`}>{email}</a>}
+							</address>
+						</div>
+						{hours && hours.length > 0 && (
+							<div>
+								<h4>Hours</h4>
+								<div className="footer-hours">
+									{hours.map((row) => (
+										<span key={row.label}>
+											{row.label}&nbsp;&nbsp;{row.range}
+											<br />
+										</span>
+									))}
+								</div>
+							</div>
+						)}
+					</div>
+					<div className="footer-bottom">
+						<span>
+							© {new Date().getFullYear()} {name}
+							{attribution ? ` · ${attribution}` : ""}
+						</span>
+						{note && <span>{note}</span>}
+						{legalLinks && legalLinks.length > 0 && (
+							<span className="footer-legal">
+								{legalLinks.map((link) => (
+									<FooterLink key={link.href} link={link} />
+								))}
+							</span>
+						)}
+					</div>
+				</div>
+			</footer>
+			{credit && <CreditBar />}
+		</>
+	);
+}

package/src/chrome/SiteHeader.tsx

@@ -0,0 +1,152 @@
+import { useEffect, useId, useState } from "react";
+import { type PageStop, useScrollSpy } from "../hooks/useScrollSpy";
+import { newTabProps } from "../lib/newTabProps";
+import type { Brand, CallToAction, MenuContact, NavLink } from "../types";
+import { BrandLockup } from "./BrandLockup";
+import { SiteMenu } from "./SiteMenu";
+
+/**
+ * `transparent` sits over a full bleed hero and turns solid on scroll,
+ * `solid` is the light bar, and `dark` matches a dark page surface.
+ */
+export type SiteHeaderVariant = "transparent" | "solid" | "dark";
+
+export interface SiteHeaderProps {
+	/** The identity the lockup renders. */
+	brand: Brand;
+	/** The site's primary nav. Omit on a page with no site nav, such as an artifact. */
+	links?: NavLink[];
+	/** The primary action, in the bar on desktop and in the menu. */
+	primaryCTA?: CallToAction;
+	/** Defaults to `solid`. */
+	variant?: SiteHeaderVariant;
+	/** The current path, marking the matching nav link with aria-current. */
+	currentPath?: string;
+	/**
+	 * Presentation mode: the page's own stops replace the nav links, scroll
+	 * spied, on desktop and in the menu. The CTA and the menu's contact block
+	 * step aside, since both are site chrome and the page owns its close.
+	 */
+	stops?: PageStop[];
+	/** Hides the bar's CTA (e.g. a reveal, where the ask is the letter). The menu keeps it. */
+	hideCTA?: boolean;
+	/** The contact block at the foot of the menu. */
+	contact?: MenuContact;
+}
+
+/**
+ * The fixed header every page wears: the lockup, the nav or the page's
+ * stops, the CTA, and the burger that opens the menu. It takes the current
+ * path as a prop rather than asking a router, so it runs under any of them.
+ */
+export function SiteHeader({
+	brand,
+	links,
+	primaryCTA,
+	variant = "solid",
+	currentPath,
+	stops,
+	hideCTA = false,
+	contact,
+}: SiteHeaderProps) {
+	const [scrolled, setScrolled] = useState(false);
+	const [menuOpen, setMenuOpen] = useState(false);
+	const menuId = useId();
+	const activeId = useScrollSpy(stops ? stops.map((stop) => stop.id) : []);
+
+	useEffect(() => {
+		if (variant !== "transparent") return;
+		const onScroll = () => setScrolled(window.scrollY > window.innerHeight * 0.6);
+		window.addEventListener("scroll", onScroll, { passive: true });
+		onScroll();
+		return () => window.removeEventListener("scroll", onScroll);
+	}, [variant]);
+
+	const solid = variant !== "transparent" || scrolled;
+	const menuLinks = stops
+		? stops.map((stop) => ({ label: stop.label, href: `#${stop.id}` }))
+		: (links ?? []);
+	const menuCTA = stops ? undefined : primaryCTA;
+	const barCTA = hideCTA ? undefined : menuCTA;
+	const hasMenu = menuLinks.length > 0 || menuCTA !== undefined;
+
+	return (
+		<>
+			<header
+				className={["nav", solid ? "is-solid" : "is-transparent", variant === "dark" && "nav-dark"]
+					.filter(Boolean)
+					.join(" ")}
+			>
+				<div className="nav-inner">
+					<BrandLockup brand={brand} />
+					{stops
+						? stops.length > 0 && (
+								<nav className="nav-links" aria-label="Page sections">
+									{stops.map((stop) => (
+										<a
+											key={stop.id}
+											href={`#${stop.id}`}
+											className={activeId === stop.id ? "active" : undefined}
+										>
+											{stop.label}
+										</a>
+									))}
+								</nav>
+							)
+						: links &&
+							links.length > 0 && (
+								<nav className="nav-links" aria-label="Primary">
+									{links.map((link) => (
+										<a
+											key={link.href}
+											href={link.href}
+											aria-current={currentPath === link.href ? "page" : undefined}
+										>
+											{link.label}
+										</a>
+									))}
+								</nav>
+							)}
+					{barCTA && (
+						// The class sits on a wrapper, not the button: a site's own .btn
+						// display rule lives outside the atelic-ui layer and would beat
+						// any rule here that hid the button itself.
+						<span className="nav-cta">
+							<a
+								className="btn btn-primary"
+								href={barCTA.href}
+								{...newTabProps(barCTA.href, barCTA.external)}
+							>
+								{barCTA.label}
+							</a>
+						</span>
+					)}
+					{hasMenu && (
+						<button
+							type="button"
+							className="nav-burger"
+							aria-label={menuOpen ? "Close menu" : "Open menu"}
+							aria-expanded={menuOpen}
+							aria-controls={menuId}
+							onClick={() => setMenuOpen((open) => !open)}
+						>
+							<span />
+							<span />
+							<span />
+						</button>
+					)}
+				</div>
+			</header>
+			{hasMenu && (
+				<SiteMenu
+					id={menuId}
+					open={menuOpen}
+					onClose={() => setMenuOpen(false)}
+					links={menuLinks}
+					primaryCTA={menuCTA}
+					contact={stops ? undefined : contact}
+				/>
+			)}
+		</>
+	);
+}