@the-smithy/create-hearth-site 0.24.1 → 0.26.0

package/template/src/hearth/pages/thank-you.tsx

@@ -1,19 +1,32 @@
 import type { Metadata } from "next";
 import Link from "next/link";
 import { theme } from "@/theme";
+import { hearthNext } from "../client";
+import { PageContent } from "../components/PageContent";
 import { Section } from "../ui";
 
-export const metadata: Metadata = { title: "Thank you", robots: { index: false, follow: false } };
+/** Never in search results, whatever the page in Hearth says. */
+export async function generateMetadata(): Promise<Metadata> {
+  const own = await hearthNext.generatePageMetadata("donate/thank-you");
+  return { ...(Object.keys(own).length ? own : { title: theme.text.thankYouTitle }), robots: { index: false, follow: false } };
+}
 
-/** Where the payment page sends donors back. The receipt is emailed once the payment completes. */
-export default function ThankYouPage() {
+/** Where the payment page sends donors back. The receipt is emailed once the payment completes. A page in Hearth at `donate/thank-you` replaces these words. */
+export default async function Page() {
+  const page = await hearthNext.getPage("donate/thank-you");
   return (
-    <Section block="thankYou">
-      <h1 className={theme.page.title}>Thank you</h1>
-      <p className={theme.page.lead}>Your gift makes a difference. If you gave your email, a receipt is on its way.</p>
-      <Link href="/" className={theme.page.back}>
-        Back to the homepage
-      </Link>
-    </Section>
+    <div data-page="thank-you">
+      {page ? (
+        <PageContent page={page} />
+      ) : (
+        <Section block="thankYou">
+          <h1 className={theme.page.title}>{theme.text.thankYouTitle}</h1>
+          <p className={theme.page.lead}>{theme.text.thankYouLead}</p>
+          <Link href="/" className={theme.page.back}>
+            {theme.text.thankYouBack}
+          </Link>
+        </Section>
+      )}
+    </div>
   );
 }

package/template/src/hearth/theme/defaults.ts

@@ -8,8 +8,14 @@
  *   data-[size=full]: data-[size=small]:  data-[width=narrow]:  data-[columns=4]:  data-[fit=contain]:
  *   data-highlight:   data-cancelled:  data-full:  data-flip:  aria-invalid:  aria-[current=page]:  has-checked:
  *   in-data-[…]:      the same, set on an ancestor (Tailwind's in-* variant)
+ * For CSS that picks out something in particular (site CSS in src/theme/theme.css, or in-data-[…]: in a slot):
+ *   [data-block="hero"]  a block's type, with [data-tone] and, on a hero, [data-size] beside it
+ *   [data-page="events"]  the pages the code serves (events, fundraisers, donate, thank-you, registered, not-found)
+ *   [data-card="our-history"]  a card in a Cards block, by its title; [data-icon="graduation-cap"]  by its Icon in Hearth
  * Slots named `tone` aren't classes: they pick the ground (default, muted, inverse or accent) a block sits on.
- * Slots under `text` are the words the code shows (labels, buttons), for sites that word them differently.
+ * Slots under `text` are the words the code shows (labels, buttons), for sites that word them differently; {name} marks a
+ * value the code fills in. A few others hold a setting, not classes: `page.themeColor`, `page.externalLinks`,
+ * `page.navMatch`, `page.dateStyle` and `map.style`.
  */
 
 const card = "rounded-2xl bg-surface ring-1 ring-line on-dark:bg-white/10 on-dark:ring-0";
@@ -38,6 +44,14 @@ export const defaults = {
     lead: "-mt-6 mb-10 max-w-2xl text-lg opacity-85",
     back: more,
     notFound: "py-12",
+    /** A setting: the browser's color around the page on phones, e.g. "#1c1c1a". Empty for none. */
+    themeColor: "",
+    /** A setting: "new-tab" opens web links off the site in a new tab (buttons, footer links, logos, registration, directions); "same-tab" doesn't. Rich text and social links stay as they are. */
+    externalLinks: "same-tab",
+    /** A setting: when a menu link counts as the current page. "prefix": on its address and the ones under it; "exact": only its own. */
+    navMatch: "prefix",
+    /** A setting: event dates, "short" (Sat, Oct 18, 2026) or "long" (Saturday, October 18, 2026). */
+    dateStyle: "short",
   },
   header: {
     /** The header's ground: `tones` colors it, and inverse or accent turn on on-dark: inside it. */
@@ -52,12 +66,14 @@ export const defaults = {
     nav: "hidden flex-wrap items-center justify-end gap-x-6 gap-y-1 font-medium md:flex",
     link: "py-2 hover:text-highlight aria-[current=page]:text-highlight",
     cta: "rounded-lg bg-accent px-4 py-2 font-semibold text-accent-ink hover:opacity-90",
+    /** What a site inside an app adds beside the menu, at every width (see SiteFrame). */
+    actions: "flex items-center gap-2",
     /** A menu item with a dropdown (a global block in a panel): the item, its link, the button that opens it, the panel. */
     dropdown: "relative flex items-center gap-0.5",
     dropdownLink: "py-2 hover:text-highlight aria-[current=page]:text-highlight",
     dropdownToggle: "inline-flex size-8 items-center justify-center rounded-md hover:text-highlight aria-expanded:rotate-180",
     dropdownPanel:
-      "absolute right-0 top-full z-40 mt-2 max-h-[80dvh] w-[min(32rem,calc(100vw-2rem))] overflow-y-auto rounded-2xl text-ink shadow-xl ring-1 ring-line [&_h2]:text-2xl [&_section>div]:px-6 [&_section>div]:py-6",
+      "absolute right-0 top-full z-40 mt-2 max-h-[80dvh] w-[min(32rem,calc(100vw-2rem))] overflow-y-auto rounded-2xl text-ink shadow-xl ring-1 ring-line [&_h2:not(li_*)]:text-2xl [&_section>div]:px-6 [&_section>div]:py-6",
   },
   /** The menu on phones: a button that opens the links full screen. */
   mobileNav: {
@@ -100,6 +116,10 @@ export const defaults = {
     social: "flex flex-col gap-2",
     socialLink: "opacity-80 hover:opacity-100",
     copyright: "mx-auto max-w-site px-4 pb-8 text-sm opacity-60 sm:px-6",
+    /** Small print under the copyright line (Footer in Hearth's Navigation). */
+    note: "mx-auto -mt-6 max-w-site whitespace-pre-line px-4 pb-8 text-sm opacity-60 sm:px-6",
+    /** The Logo from src/theme/overrides.tsx, above the site's name. Empty, it isn't drawn, as a header logo often doesn't suit the footer: set classes here to show it. */
+    logo: "",
   },
 
   /* ─── Shared pieces ─── */
@@ -107,6 +127,8 @@ export const defaults = {
   section: {
     root: "",
     inner: "mx-auto max-w-site px-4 py-16 sm:px-6 sm:py-20",
+    /** On a block with an anchor, or anything else links jump to: the space kept above it (for a sticky header, make it larger). */
+    anchored: "scroll-mt-8",
   },
   tones: {
     default: "bg-bg text-ink",
@@ -132,6 +154,8 @@ export const defaults = {
   /* ─── Blocks ─── */
   hero: {
     root: "relative overflow-hidden bg-inverse text-inverse-ink",
+    /** In place of `root` on a hero given a tone in Hearth, whose `tones` set its colors. */
+    toned: "relative overflow-hidden",
     image: "absolute inset-0 size-full object-cover opacity-35",
     inner: "relative mx-auto max-w-site px-4 py-16 sm:px-6 sm:py-20 data-[size=full]:py-28 sm:data-[size=full]:py-36",
     logo: "mb-6 h-20 w-auto sm:h-24",
@@ -214,6 +238,11 @@ export const defaults = {
     question: "flex min-h-14 cursor-pointer list-none items-center justify-between gap-4 py-4 text-lg font-semibold [&::-webkit-details-marker]:hidden",
     icon: "text-highlight transition before:content-['+'] group-open:rotate-45",
     answer: "prose pb-5 text-lg opacity-85",
+    /** Set to show every answer in Hearth: the list, each question and answer, the question, the answer. */
+    terms: "grid max-w-3xl gap-8",
+    term: "",
+    termQuestion: "text-lg font-semibold",
+    termAnswer: "prose mt-2 text-lg opacity-85",
   },
   quote: {
     figure: "flex max-w-3xl flex-col gap-6",
@@ -528,5 +557,99 @@ export const defaults = {
     share: "Share",
     visitProject: "Visit {name}",
     mapFailed: "The map couldn't load.",
+    mapOf: "Map of {name}",
+    mapHeading: "Map: {heading}",
+    mapPlaces: "Map of our locations",
+    /** Read out after Get directions, in a list of places. */
+    directionsTo: "to {name}",
+    /** Read out after a link, with `page.externalLinks` set to "new-tab". */
+    opensInNewTab: "(opens in a new tab)",
+    skipLink: "Skip to content",
+    /** Upcoming events limited to a collection, as a link to it. */
+    allCollectionEvents: "All {collection}",
+
+    /* The pages the code serves, until they're replaced by a page in Hearth at the same address. */
+    eventsTitle: "Events",
+    eventsDescription: "Upcoming events from {site}.",
+    fundraisersTitle: "Fundraisers",
+    fundraisersDescription: "Fundraisers and campaigns from {site}: see how each is doing and give.",
+    completedFundraisers: "Completed",
+    donateTitle: "Donate",
+    donateDescription: "Support {site} with a donation.",
+    donateLead: "Your gift supports {site}.",
+    thankYouTitle: "Thank you",
+    thankYouLead: "Your gift makes a difference. If you gave your email, a receipt is on its way.",
+    thankYouBack: "Back to the homepage",
+    registeredTitle: "You're registered",
+    registeredLead: "Thanks for signing up. A confirmation is on its way to your email.",
+    registeredBack: "See all events",
+    notFoundTitle: "Page not found",
+    notFoundLead: "The page you're looking for has moved or no longer exists.",
+    notFoundHome: "Go to the homepage",
+
+    /* Fundraisers. */
+    fundraiserLabel: "Fundraiser",
+    completedFundraiserLabel: "Completed fundraiser",
+    raised: "raised",
+    raisedOfGoal: "raised of {goal}",
+    progressLabel: "Progress toward the goal",
+    oneDonation: "{count} online donation",
+    donations: "{count} online donations",
+
+    /* Share (the button's dialog). */
+    shareEventHeading: "Share {title}",
+    shareEventMessage: "{title}, {date}: {url}",
+    shareFundraiserHeading: "Share this fundraiser",
+    shareFundraiserMessage: "I'm supporting {title}. Give here: {url}",
+    shareFundraiserGoalMessage: "I'm supporting {title}: {raised} raised of {goal} so far. Give here: {url}",
+    shareMessageLabel: "Your message",
+    shareCopyMessage: "Copy message",
+    shareCopyLink: "Copy link",
+    shareTheMessage: "Message",
+    shareTheLink: "Link",
+    shareCopied: "{what} copied.",
+    shareCopyFailed: "Couldn't copy automatically. Select the text and copy it.",
+    shareTo: "Or share to",
+    shareMoreApps: "More apps…",
+    shareEmail: "Email",
+    shareTextMessage: "Text message",
+
+    /* Forms. */
+    optional: "(optional)",
+    chooseOne: "Choose one…",
+    honeypot: "Leave this empty",
+    sending: "Sending…",
+    yourName: "Name",
+    yourEmail: "Email",
+    yourPhone: "Phone",
+    openingCheckout: "Opening secure checkout…",
+    /* The donation form. */
+    donateAmount: "Amount",
+    donateOther: "Other",
+    donateCustomAmount: "Amount in dollars",
+    donateRange: "{min} to {max}.",
+    donateChoice: "Where should your gift go?",
+    donateAnywhere: "Where it's needed most",
+    donateEmail: "Email for your receipt",
+    donateMessage: "Message",
+    donateAnonymous: "Don't show my name publicly",
+    donateUpdates: "Send me updates about this fundraiser",
+    donateNote: "You'll finish on a secure payment page.",
+    /* Registration. */
+    ticket: "Ticket",
+    ticketsLeft: "{count} left",
+    teamName: "Team or organization",
+    attendee: "Attendee",
+    notes: "Notes",
+    free: "Free",
+    continueToPayment: "Continue to payment",
+    registering: "Registering…",
+    /* Volunteer sign-up. */
+    shiftsMany: "Shifts you can do",
+    shiftsOne: "Choose a shift",
+    shiftFull: "Full",
+    oneSpotLeft: "{count} spot left",
+    spotsLeft: "{count} spots left",
+    signingUp: "Signing up…",
   },
 };

package/template/src/hearth/ui.tsx

@@ -1,6 +1,7 @@
 import Link from "next/link";
 import { Fragment, type AnchorHTMLAttributes, type ReactNode } from "react";
 import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
 import { focalPosition, type ImageRef } from "@the-smithy/hearth";
 import { theme } from "@/theme";
 import { cx } from "./theme";
@@ -23,10 +24,13 @@ export const ground = (tone?: Tone) => ({ "data-ground": isDark(tone) ? "dark" :
 /** Fills {name} placeholders in a theme text: fill(theme.text.giveTo, { fundraiser: f.title }). */
 export const fill = (text: string, values: Record<string, string>) => text.replace(/\{(\w+)\}/g, (m, k: string) => values[k] ?? m);
 
-/** A full-width band with the site's content width inside. `block` names the block type, for CSS that targets it. */
+/**
+ * A full-width band with the site's content width inside. `block` names the block type, for CSS that targets it; `id`
+ * is what links jump to: blocks pass their anchor from Hearth (`block.anchor`).
+ */
 export function Section({ tone = "default", id, block, className, innerClassName, children }: { tone?: Tone; id?: string; block?: string; className?: string; innerClassName?: string; children: ReactNode }) {
   return (
-    <section id={id} data-block={block} {...ground(tone)} className={cx(theme.tones[tone], theme.section.root, id && "scroll-mt-8", className)}>
+    <section id={id} data-block={block} {...ground(tone)} className={cx(theme.tones[tone], theme.section.root, id && theme.section.anchored, className)}>
       <div className={cx(theme.section.inner, innerClassName)}>{children}</div>
     </section>
   );
@@ -75,19 +79,30 @@ export function SectionHeading({ eyebrow, heading, intro }: { eyebrow?: string;
 export function Markdown({ children, className = theme.markdown.root, ...data }: { children: string; className?: string } & Record<`data-${string}`, string | undefined>) {
   return (
     <div className={className} {...data}>
-      <ReactMarkdown>{children}</ReactMarkdown>
+      <ReactMarkdown remarkPlugins={[remarkGfm]}>{children}</ReactMarkdown>
     </div>
   );
 }
 
 export const isExternal = (href: string) => /^(https?:|mailto:|tel:)/.test(href);
 
+/** A plain link off the site. With `page.externalLinks` set to "new-tab", web links open in a new tab and say so to screen readers. */
+export function ExternalLink({ href, rel, children, ...rest }: { href: string; children: ReactNode } & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href">) {
+  const newTab = theme.page.externalLinks === "new-tab" && /^https?:/.test(href);
+  return (
+    <a href={href} rel={newTab ? (rel ?? "noopener") : rel} target={newTab ? "_blank" : undefined} {...rest}>
+      {children}
+      {newTab ? <span className="sr-only"> {theme.text.opensInNewTab}</span> : null}
+    </a>
+  );
+}
+
 /** A link to a path on the site or to anywhere else. */
 export function SmartLink({ href, className, children, ...rest }: { href: string; className?: string; children: ReactNode } & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href">) {
   return isExternal(href) ? (
-    <a href={href} className={className} {...rest}>
+    <ExternalLink href={href} className={className} {...rest}>
       {children}
-    </a>
+    </ExternalLink>
   ) : (
     <Link href={href} className={className} {...rest}>
       {children}

package/template/src/theme/overrides.tsx

@@ -3,14 +3,28 @@ import type { ComponentType } from "react";
 import type { Site } from "@the-smithy/hearth";
 
 /**
- * The last resort, when a design can't be reached with slots and tokens: replace a whole block's component, or draw
- * the header's logo yourself. Replaced components are this site's own code: `pnpm hearth:update` won't update them,
- * so check them against src/hearth/blocks after each update. Build them from src/hearth/ui.tsx and the theme.
+ * The last resort, when a design can't be reached with slots and tokens: replace a whole block's component, or the
+ * parts below. Replaced components are this site's own code: `pnpm hearth:update` won't update them, so check them
+ * against src/hearth after each update. Build them from src/hearth/ui.tsx and the theme, and say why in SITE.md.
  *
  *   import { CountingStats } from "./CountingStats";
  *   export const blocks: Partial<BlockComponents> = { stats: CountingStats };
+ *
+ * Export any of these too, used everywhere the template draws them (types in src/hearth/overrides.ts). They can import
+ * Hearth's components, Blocks too. Words, dates and hiding things are slots: try those first.
+ *
+ *   export const Footer: Overrides["Footer"] = ({ site }) => …                the whole footer
+ *   export const EventPage: Overrides["EventPage"] = ({ event }) => …         an event's page, reusing EventRegisterSection
+ *                                                                             and EventVolunteerSection from EventView
+ *   export const FundraiserPage: Overrides["FundraiserPage"] = ({ fundraiser }) => …
+ *   export const EventCard: Overrides["EventCard"] = async ({ event, heading }) => <li>…</li>
+ *   export const FundraiserCard: Overrides["FundraiserCard"] = ({ fundraiser, heading }) => <li>…</li>
+ *   export const DonateForm: Overrides["DonateForm"] = (props) => …
  */
 export const blocks: Partial<BlockComponents> = {};
 
-/** The header's logo; leave null to show the logo uploaded in Hearth (Settings → Search & sharing) and the site name. */
-export const Logo: ComponentType<{ site: Site }> | null = null;
+/**
+ * The header's logo; leave null to show the logo uploaded in Hearth (Settings → Search & sharing) and the site name.
+ * Set the `footer.logo` slot to draw it in the footer too (`place` says which).
+ */
+export const Logo: ComponentType<{ site: Site; place: "header" | "footer" }> | null = null;