@the-smithy/create-hearth-site 0.20.0 → 0.22.0

package/template/src/hearth/forms/VolunteerForm.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { useActionState } from "react";
+import type { EventVolunteering } from "@the-smithy/hearth";
+import { theme } from "@/theme";
+import { volunteer, type VolunteerState } from "../actions";
+import { formatShift } from "../format";
+import { Alert, FieldError, Honeypot, OptionCard, Question, Submit, Success, TextField } from "./fields";
+
+const t = theme.form;
+
+/**
+ * Volunteer sign-up for an event: name and email, shifts to choose from (when the event lists them), then the
+ * event's own questions. Sign-ups land under the event's Volunteers in Hearth.
+ */
+export function VolunteerForm({ slug, timezone, volunteering }: { slug: string; timezone: string; volunteering: EventVolunteering }) {
+  const [state, action] = useActionState<VolunteerState | null, FormData>(volunteer.bind(null, slug), null);
+  const errors = state && !state.ok ? state.fieldErrors : {};
+  const values = (state && !state.ok ? state.values : undefined) ?? {};
+  const chosen = (state && !state.ok ? state.shifts : undefined) ?? [];
+  const many = volunteering.pickShifts === "many";
+
+  if (state?.ok) return <Success>{state.message}</Success>;
+
+  return (
+    <form action={action} className={t.root} noValidate>
+      {state && !state.ok ? <Alert>{state.message}</Alert> : null}
+      <Honeypot />
+      <div className={t.row}>
+        <TextField label="Name" name="name" required autoComplete="name" defaultValue={values.name} error={errors.name} />
+        <TextField label="Email" name="email" type="email" required autoComplete="email" defaultValue={values.email} error={errors.email} />
+      </div>
+      {volunteering.pickShifts !== "none" ? (
+        <fieldset>
+          <legend className={t.legend}>{many ? "Shifts you can do" : "Choose a shift"}</legend>
+          <div className={t.options}>
+            {volunteering.shifts.map((s) => (
+              <OptionCard
+                key={s.id}
+                input={<input type={many ? "checkbox" : "radio"} name="shift" value={s.id} disabled={s.full} defaultChecked={chosen.includes(s.id)} className={t.optionInput} />}
+                title={s.name}
+                meta={s.full ? "Full" : s.remaining !== null && s.remaining <= 5 ? `${s.remaining} spot${s.remaining === 1 ? "" : "s"} left` : null}
+              >
+                <span className={t.optionDetail}>{formatShift(s, timezone)}</span>
+                {s.description ? <span className={t.optionDetail}>{s.description}</span> : null}
+              </OptionCard>
+            ))}
+          </div>
+          <FieldError>{errors.shifts}</FieldError>
+        </fieldset>
+      ) : null}
+      {volunteering.fields.map((f) => (
+        <Question key={f.name} field={f} idPrefix="volunteer" error={errors[f.name]} value={values[f.name]} />
+      ))}
+      <Submit label={volunteering.submitLabel} pending="Signing up…" />
+    </form>
+  );
+}

package/template/src/hearth/forms/fields.tsx

@@ -0,0 +1,137 @@
+"use client";
+
+import type { BlockOf } from "@the-smithy/hearth";
+import type { InputHTMLAttributes, ReactNode } from "react";
+import { useFormStatus } from "react-dom";
+import { theme } from "@/theme";
+
+/* The pieces every form is built from (contact form, volunteer sign-up, registration, donations), styled by `form`. */
+
+const t = theme.form;
+
+/** A question defined in Hearth (a form field, an event's volunteer question). */
+type FormField = BlockOf<"form">["data"]["fields"] extends (infer F)[] | undefined ? F : never;
+
+export function Alert({ children }: { children: ReactNode }) {
+  return (
+    <p role="alert" className={t.alert}>
+      {children}
+    </p>
+  );
+}
+
+export function Success({ children }: { children: ReactNode }) {
+  return (
+    <p role="status" className={t.success}>
+      {children}
+    </p>
+  );
+}
+
+/** Hidden from people, filled in by bots: Hearth drops submissions that fill it. */
+export function Honeypot() {
+  return (
+    <div aria-hidden className="absolute -left-[9999px]">
+      <label>
+        Leave this empty
+        <input name="_gotcha" tabIndex={-1} autoComplete="off" />
+      </label>
+    </div>
+  );
+}
+
+export function Submit({ label, pending: pendingLabel }: { label: string; pending: string }) {
+  const { pending } = useFormStatus();
+  return (
+    <button type="submit" disabled={pending} className={t.submit}>
+      {pending ? pendingLabel : label}
+    </button>
+  );
+}
+
+export function FieldError({ id, children }: { id?: string; children?: string }) {
+  return children ? (
+    <span id={id} className={t.error}>
+      {children}
+    </span>
+  ) : null;
+}
+
+/** A labelled text input (name, email, phone…), with its error under it. */
+export function TextField({ label, optional, error, textarea, rows = 3, ...input }: { label: string; optional?: boolean; error?: string; textarea?: boolean; rows?: number } & InputHTMLAttributes<HTMLInputElement> & { maxLength?: number }) {
+  const describedBy = error && input.name ? `${input.name}-error` : undefined;
+  const common = { ...input, "aria-invalid": error ? true : undefined, "aria-describedby": describedBy, className: t.input };
+  return (
+    <label className={t.field}>
+      <span className={t.label}>
+        {label}
+        {optional ? <span className={t.optional}>(optional)</span> : null}
+      </span>
+      {textarea ? <textarea {...(common as object)} rows={rows} /> : <input {...common} />}
+      <FieldError id={describedBy}>{error}</FieldError>
+    </label>
+  );
+}
+
+export function Checkbox({ name, label, defaultChecked }: { name: string; label: ReactNode; defaultChecked?: boolean }) {
+  return (
+    <label className={t.check}>
+      <input type="checkbox" name={name} defaultChecked={defaultChecked} className={t.checkbox} />
+      {label}
+    </label>
+  );
+}
+
+/** One of the questions defined in Hearth (a form's fields, an event's volunteer questions). */
+export function Question({ field: f, idPrefix, error, value }: { field: FormField; idPrefix: string; error?: string; value?: string }) {
+  const id = `${idPrefix}-${f.name}`;
+  const common = { id, name: f.name, required: f.required, "aria-invalid": error ? true : undefined, "aria-describedby": error ? `${id}-error` : undefined };
+  return (
+    <div>
+      {f.type === "checkbox" ? (
+        <label className={t.check}>
+          <input type="checkbox" {...common} defaultChecked={value === "on"} className={t.checkbox} />
+          {f.label}
+        </label>
+      ) : (
+        <>
+          <label htmlFor={id} className={t.label}>
+            {f.label}
+            {f.required ? null : <span className={t.optional}>(optional)</span>}
+          </label>
+          {f.type === "textarea" ? (
+            <textarea {...common} rows={5} defaultValue={value} placeholder={f.placeholder} className={t.input} />
+          ) : f.type === "select" ? (
+            <select {...common} defaultValue={value ?? ""} className={t.input}>
+              <option value="" disabled>
+                {f.placeholder || "Choose one…"}
+              </option>
+              {(f.options ?? []).map((o) => (
+                <option key={o}>{o}</option>
+              ))}
+            </select>
+          ) : (
+            <input {...common} type={f.type} defaultValue={value} placeholder={f.placeholder} autoComplete={f.type === "email" ? "email" : f.type === "tel" ? "tel" : f.name === "name" ? "name" : undefined} className={t.input} />
+          )}
+        </>
+      )}
+      <FieldError id={`${id}-error`}>{error}</FieldError>
+    </div>
+  );
+}
+
+/** A choice drawn as a card (a shift, a ticket): its input, title, a note on the right and details under it. */
+export function OptionCard({ input, title, meta, children }: { input: ReactNode; title: ReactNode; meta?: ReactNode; children?: ReactNode }) {
+  return (
+    <label className={t.option}>
+      {input}
+      <span className={t.optionText}>
+        <span className={t.optionTitle}>
+          <span>{title}</span>
+          {meta ? <span className={t.optionMeta}>{meta}</span> : null}
+        </span>
+        {children}
+      </span>
+    </label>
+  );
+}

package/template/src/hearth/hearth.css

@@ -0,0 +1,52 @@
+/*
+ * Hearth's base CSS, shared by every site: the on-dark variant, rich text and focus rings. Don't edit it in a site:
+ * tokens and the site's own CSS go in src/theme/theme.css, which is loaded after this file and can override anything here.
+ */
+
+/* On an inverse or accent ground: set by sections with a dark tone, the hero, image calls to action and the footer. */
+@custom-variant on-dark (&:where([data-ground="dark"], [data-ground="dark"] *));
+
+/* Markdown from Hearth (rich text, FAQ answers, media + text). Unlayered, so its line height beats text-* sizes. */
+.prose {
+  line-height: 1.7;
+}
+.prose > * + * {
+  margin-top: 1em;
+}
+.prose h2 {
+  font-size: 1.75rem;
+  font-weight: 700;
+  line-height: 1.25;
+  margin-top: 1.6em;
+}
+.prose h3 {
+  font-size: 1.35rem;
+  font-weight: 700;
+  margin-top: 1.4em;
+}
+.prose a {
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+.prose ul {
+  list-style: disc;
+  padding-left: 1.4em;
+}
+.prose ol {
+  list-style: decimal;
+  padding-left: 1.4em;
+}
+.prose blockquote {
+  border-left: 3px solid var(--color-line);
+  padding-left: 1em;
+  font-style: italic;
+}
+.prose img {
+  border-radius: 0.75rem;
+}
+
+/* Unlayered, so it beats utilities like focus:outline-none: keyboard focus always shows. */
+:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
+}

package/template/src/hearth/layout/MobileNav.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import { useEffect, useRef } from "react";
+import { theme } from "@/theme";
+import { NavLink } from "./NavLink";
+
+type Link = { label: string; href: string };
+
+const t = theme.mobileNav;
+
+/**
+ * The menu on phones: a button that opens the links full screen, in a dialog (so focus stays in it and Escape closes
+ * it). It closes when a link is followed.
+ */
+export function MobileNav({ siteName, links, cta }: { siteName: string; links: Link[]; cta?: Link }) {
+  const dialog = useRef<HTMLDialogElement>(null);
+  const pathname = usePathname();
+  useEffect(() => dialog.current?.close(), [pathname]);
+  const close = () => dialog.current?.close();
+
+  return (
+    <div className={t.root}>
+      <button type="button" className={t.toggle} aria-haspopup="dialog" onClick={() => dialog.current?.showModal()}>
+        {theme.text.menu}
+      </button>
+      <dialog ref={dialog} aria-label="Menu" className={t.dialog}>
+        <div className={t.top}>
+          <p className={t.title}>{siteName}</p>
+          <button type="button" className={t.close} onClick={close}>
+            {theme.text.close}
+          </button>
+        </div>
+        <nav aria-label="Main" className={t.nav}>
+          {links.map((item) => (
+            <NavLink key={item.href + item.label} href={item.href} className={t.link} onClick={close}>
+              {item.label}
+            </NavLink>
+          ))}
+          {cta ? (
+            <NavLink href={cta.href} className={t.cta} onClick={close}>
+              {cta.label}
+            </NavLink>
+          ) : null}
+        </nav>
+      </dialog>
+    </div>
+  );
+}

package/template/src/hearth/layout/NavLink.tsx

@@ -0,0 +1,16 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import type { ReactNode } from "react";
+import { SmartLink } from "../ui";
+
+/** A menu link that marks itself as the current page (aria-current), for the theme's aria-[current=page]: variant. */
+export function NavLink({ href, className, onClick, children }: { href: string; className: string; onClick?: () => void; children: ReactNode }) {
+  const pathname = usePathname();
+  const current = href === "/" ? pathname === "/" : pathname === href || pathname.startsWith(`${href}/`);
+  return (
+    <SmartLink href={href} className={className} onClick={onClick} aria-current={current ? "page" : undefined}>
+      {children}
+    </SmartLink>
+  );
+}

package/template/src/hearth/layout/RootLayout.tsx

@@ -0,0 +1,40 @@
+import type { ReactNode } from "react";
+import { HearthAnalytics } from "@the-smithy/hearth/analytics";
+import { siteLang } from "@the-smithy/hearth/next";
+import { HearthPreview } from "@the-smithy/hearth/preview";
+import { theme } from "@/theme";
+import { fontVariables } from "@/theme/fonts";
+import { hearthNext } from "../client";
+import { SiteFooter } from "./SiteFooter";
+import { SiteHeader } from "./SiteHeader";
+
+/**
+ * What every page starts from: full links, the title pattern, the default description and share image, the site's
+ * language, Google and Bing verification, and no indexing on preview deploys or while the site is hidden in Hearth.
+ * Pages from Hearth then set their own title, description, canonical address and share image.
+ */
+export const generateMetadata = () => hearthNext.siteMetadata();
+
+export default async function RootLayout({ children }: { children: ReactNode }) {
+  const site = await hearthNext.getSite();
+  const preview = await hearthNext.isPreview();
+  const t = theme.page;
+  return (
+    <html lang={siteLang(site)} className={fontVariables || undefined}>
+      <body className={t.body}>
+        <a href="#main" className={t.skipLink}>
+          Skip to content
+        </a>
+        {/* Live draft preview from Hearth: shows while an editor previews, refreshes as they edit. */}
+        {preview ? <HearthPreview /> : null}
+        <SiteHeader site={site} />
+        <main id="main" className={t.main}>
+          {children}
+        </main>
+        <SiteFooter site={site} />
+        {/* Hearth's built-in visitor analytics (cookieless, no banner needed): off in draft preview and when the site turns it off. */}
+        {site.analytics && !preview ? <HearthAnalytics config={site.analytics} /> : null}
+      </body>
+    </html>
+  );
+}

package/template/src/{components → hearth/layout}/SiteFooter.tsx

@@ -1,5 +1,7 @@
 import type { Site } from "@the-smithy/hearth";
-import { SmartLink } from "@/components/ui";
+import { theme } from "@/theme";
+import { cx } from "../theme";
+import { ground, SmartLink, toTone } from "../ui";
 
 const platformName: Record<string, string> = {
   facebook: "Facebook",
@@ -12,28 +14,31 @@ const platformName: Record<string, string> = {
 
 /** Contact details, footer links and social links from Hearth (Settings → Content). */
 export function SiteFooter({ site }: { site: Site }) {
-  const { footerLinks, contact, social } = site.settings;
+  const { footerLinks, contact, social, tagline } = site.settings;
+  const t = theme.footer;
+  const tone = toTone(t.tone);
   return (
-    <footer className="bg-inverse text-inverse-ink">
-      <div className="mx-auto grid max-w-site gap-10 px-4 py-12 sm:grid-cols-3 sm:px-6">
-        <div className="flex flex-col gap-2">
-          <p className="text-lg font-bold">{site.name}</p>
-          {contact.address ? <address className="whitespace-pre-line not-italic opacity-80">{contact.address}</address> : null}
+    <footer {...ground(tone)} className={cx(theme.tones[tone], t.root)}>
+      <div className={t.inner}>
+        <div className={t.about}>
+          <p className={t.name}>{site.name}</p>
+          {tagline ? <p className={t.tagline}>{tagline}</p> : null}
+          {contact.address ? <address className={t.address}>{contact.address}</address> : null}
           {contact.phone ? (
-            <a href={`tel:${contact.phone.replace(/[^\d+]/g, "")}`} className="opacity-80 hover:opacity-100">
+            <a href={`tel:${contact.phone.replace(/[^\d+]/g, "")}`} className={t.contact}>
               {contact.phone}
             </a>
           ) : null}
           {contact.email ? (
-            <a href={`mailto:${contact.email}`} className="opacity-80 hover:opacity-100">
+            <a href={`mailto:${contact.email}`} className={t.contact}>
               {contact.email}
             </a>
           ) : null}
         </div>
         {footerLinks.length ? (
-          <nav aria-label="Footer" className="flex flex-col gap-2">
+          <nav aria-label="Footer" className={t.nav}>
             {footerLinks.map((item) => (
-              <SmartLink key={item.href + item.label} href={item.href} className="opacity-80 hover:opacity-100">
+              <SmartLink key={item.href + item.label} href={item.href} className={t.link}>
                 {item.label}
               </SmartLink>
             ))}
@@ -42,10 +47,10 @@ export function SiteFooter({ site }: { site: Site }) {
           <div />
         )}
         {social.length ? (
-          <ul className="flex flex-col gap-2">
+          <ul className={t.social}>
             {social.map((s) => (
               <li key={s.url}>
-                <a href={s.url} rel="me noopener" className="opacity-80 hover:opacity-100">
+                <a href={s.url} rel="me noopener" className={t.socialLink}>
                   {s.label ?? platformName[s.platform] ?? new URL(s.url).hostname.replace(/^www\./, "")}
                 </a>
               </li>
@@ -53,7 +58,7 @@ export function SiteFooter({ site }: { site: Site }) {
           </ul>
         ) : null}
       </div>
-      <p className="mx-auto max-w-site px-4 pb-8 text-sm opacity-60 sm:px-6">
+      <p className={t.copyright}>
         © {new Date().getFullYear()} {site.name}
       </p>
     </footer>

package/template/src/hearth/layout/SiteHeader.tsx

@@ -0,0 +1,53 @@
+import Link from "next/link";
+import type { Site } from "@the-smithy/hearth";
+import { theme } from "@/theme";
+import { Logo } from "@/theme/overrides";
+import { cx } from "../theme";
+import { ground, Img, toTone } from "../ui";
+import { MobileNav } from "./MobileNav";
+import { NavLink } from "./NavLink";
+
+/** Logo, menu, menu button and announcement banner, all edited in Hearth (Settings → General, and Navigation). */
+export function SiteHeader({ site }: { site: Site }) {
+  const { announcement, seo, tagline, navigation, navigationCta } = site.settings;
+  const t = theme.header;
+  const tone = toTone(t.tone);
+  return (
+    <header {...ground(tone)} className={cx(theme.tones[tone], t.root)}>
+      {announcement ? <p className={t.announcement}>{announcement}</p> : null}
+      <div className={t.inner}>
+        <Link href="/" className={t.brand}>
+          {Logo ? (
+            <Logo site={site} />
+          ) : (
+            <>
+              {seo.logo ? <Img image={{ src: seo.logo.src, alt: "" }} className={t.logo} /> : null}
+              <span className={t.names}>
+                <span>{site.name}</span>
+                {tagline ? <span className={t.tagline}>{tagline}</span> : null}
+              </span>
+            </>
+          )}
+        </Link>
+        {navigation.length || navigationCta ? (
+          <>
+            <nav aria-label="Main" className={t.nav}>
+              {navigation.map((item) => (
+                <NavLink key={item.href + item.label} href={item.href} className={t.link}>
+                  {item.label}
+                </NavLink>
+              ))}
+              {/* The menu button (Navigation → Menu button in Hearth): one action that stands out from the links. */}
+              {navigationCta ? (
+                <NavLink href={navigationCta.href} className={t.cta}>
+                  {navigationCta.label}
+                </NavLink>
+              ) : null}
+            </nav>
+            <MobileNav siteName={site.name} links={navigation} cta={navigationCta} />
+          </>
+        ) : null}
+      </div>
+    </header>
+  );
+}

package/template/src/hearth/manifest.json

@@ -0,0 +1,37 @@
+{
+  "$comment": "Files Hearth manages in this site. pnpm hearth:update replaces the managed ones with the latest release and adds seeded files that are new; it never touches anything else (src/theme, your own routes). Don't edit managed files: style through src/theme.",
+  "version": "dev",
+  "managed": [
+    "src/hearth/",
+    "src/app/layout.tsx",
+    "src/app/globals.css",
+    "src/app/not-found.tsx",
+    "src/app/[[...slug]]/page.tsx",
+    "src/app/events/page.tsx",
+    "src/app/events/[slug]/page.tsx",
+    "src/app/fundraisers/page.tsx",
+    "src/app/fundraisers/[slug]/page.tsx",
+    "src/app/donate/page.tsx",
+    "src/app/donate/thank-you/page.tsx",
+    "src/app/registered/page.tsx",
+    "src/app/robots.ts",
+    "src/app/sitemap.ts",
+    "src/app/llms.txt/route.ts",
+    "src/app/api/preview/route.ts",
+    "src/app/api/preview/exit/route.ts",
+    "src/app/api/revalidate/route.ts",
+    "scripts/hearth.mjs",
+    "CLAUDE.md",
+    "AGENTS.md"
+  ],
+  "seeded": [
+    "src/theme/",
+    "src/app/icon.tsx",
+    "src/app/apple-icon.tsx",
+    "SITE.md",
+    "README.md",
+    "next.config.ts",
+    "netlify.toml",
+    ".env.example"
+  ]
+}

package/template/src/hearth/pages/donate.tsx

@@ -0,0 +1,36 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { theme } from "@/theme";
+import { hearthNext } from "../client";
+import { DonateForm } from "../forms/DonateForm";
+import { hasFeature } from "../site";
+import { Section } from "../ui";
+
+export async function generateMetadata(): Promise<Metadata> {
+  const site = await hearthNext.getSite();
+  return {
+    title: "Donate",
+    description: `Support ${site.name} with a donation.`,
+    alternates: { canonical: "/donate" },
+    openGraph: { title: "Donate", url: "/donate" },
+  };
+}
+
+/**
+ * A general donation page (sites with Giving). Ask staff to reserve "donate" on the site's Plan card in Hearth so
+ * no page takes this address. For a page built in Hearth instead, use the Donation form block there.
+ */
+export default async function DonatePage() {
+  const site = await hearthNext.getSite();
+  if (!hasFeature(site, "giving")) notFound();
+  const giving = site.settings.giving;
+  return (
+    <Section block="donatePage">
+      <div className={theme.donate.wrap}>
+        <h1 className={theme.page.title}>Donate</h1>
+        <p className={theme.page.lead}>Your gift supports {giving.legalName || site.name}.</p>
+        <DonateForm presetsCents={giving.presetsCents} minCents={giving.minCents} maxCents={giving.maxCents} />
+      </div>
+    </Section>
+  );
+}

package/template/src/hearth/pages/event.tsx

@@ -0,0 +1,26 @@
+import { metadataFromMeta } from "@the-smithy/hearth/next";
+import { permanentRedirect } from "next/navigation";
+import { hearthNext } from "../client";
+import { EventView } from "../components/EventView";
+import { hasFeature } from "../site";
+
+type Props = { params: Promise<{ slug: string }> };
+
+async function load(slug: string) {
+  const site = await hearthNext.getSite();
+  return hasFeature(site, "events") ? hearthNext.getEvent(slug) : null;
+}
+
+export async function generateMetadata({ params }: Props) {
+  const event = await load((await params).slug);
+  return event ? metadataFromMeta(event.meta) : {};
+}
+
+/** Events without a type live here. Events in a collection (e.g. Talks) live at their collection's address. */
+export default async function EventPage({ params }: Props) {
+  const slug = (await params).slug;
+  const event = await load(slug);
+  if (!event) return hearthNext.redirectOrNotFound(`/events/${slug}`);
+  if (event.path !== `/events/${event.slug}`) permanentRedirect(event.path);
+  return <EventView event={event} />;
+}

package/template/src/hearth/pages/events.tsx

@@ -0,0 +1,30 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { theme } from "@/theme";
+import { EventList } from "../blocks/events";
+import { hearthNext } from "../client";
+import { hasFeature } from "../site";
+import { Section } from "../ui";
+
+export async function generateMetadata(): Promise<Metadata> {
+  const site = await hearthNext.getSite();
+  return {
+    title: "Events",
+    description: `Upcoming events from ${site.name}.`,
+    alternates: { canonical: "/events" },
+    openGraph: { title: "Events", url: "/events" },
+  };
+}
+
+/** Upcoming events (only on sites with the Events feature in Hearth). */
+export default async function EventsPage() {
+  const site = await hearthNext.getSite();
+  if (!hasFeature(site, "events")) notFound();
+  const events = await hearthNext.getEvents({ when: "upcoming" });
+  return (
+    <Section block="events">
+      <h1 className={theme.page.title}>Events</h1>
+      <EventList events={events} />
+    </Section>
+  );
+}