@the-smithy/create-hearth-site 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-smithy/create-hearth-site",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Start a new client website powered by Hearth: pnpm create @the-smithy/hearth-site",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -29,7 +29,7 @@
   ],
   "devDependencies": {
     "vitest": "^5.0.3",
-    "@the-smithy/hearth-schema": "^0.21.0"
+    "@the-smithy/hearth-schema": "^0.23.0"
   },
   "scripts": {
     "test": "node --test \"test/**/*.test.js\" && vitest run test/blocks.test.ts"

package/template/README.md

@@ -72,8 +72,9 @@ Keep the API key out of chat: the agent never needs to see it, only `.env.local`
   - Headings can mark words with `*asterisks*` to highlight them (the `emphasis` slot, and `hero.emphasis`).
   - To leave a block type out, ask for it to be turned off for the site in Hearth.
 - **SEO comes from Hearth.** Titles, descriptions, canonical addresses, share images, structured data, the
-  sitemap, robots.txt, redirects for old addresses, Search Console verification and the page's language all come
-  from Hearth (`siteMetadata`, `generatePageMetadata`, `sitemapWith`, `robots`, `redirectOrNotFound`). Preview deploys
+  sitemap, robots.txt, llms.txt (the summary AI tools read), redirects for old addresses, Search Console verification
+  and the page's language all come from Hearth (`siteMetadata`, `generatePageMetadata`, `sitemapWith`, `robots`,
+  `llmsTxtHandler`, `redirectOrNotFound`). Preview deploys
   and sites hidden in Hearth are kept out of search engines. What's still yours:
   - Pages your own code serves (like `/events`) need their own `generateMetadata` and a place in `src/app/sitemap.ts`.
   - Use `<Img priority>` for the image at the top of a page, and keep one `<h1>` per page (the Hero block renders it).
@@ -119,6 +120,7 @@ States are Tailwind variants inside the slot: `on-dark:` for blocks on an invers
 | `src/app/api/revalidate/route.ts` | Hearth calls this when something is published, so changes go live in seconds |
 | `src/app/api/preview/route.ts` | Opens drafts from Hearth's "Preview on the website"; `/api/preview/exit` ends it |
 | `src/app/sitemap.ts`, `robots.ts` | Generated from Hearth. Search engines stay out until the site's web address is set |
+| `src/app/llms.txt/route.ts` | The site's summary for AI tools, generated from Hearth (not found until the site is live) |
 
 ## Deploying to Netlify
 

package/template/src/app/llms.txt/route.ts

@@ -0,0 +1,7 @@
+import { hearthNext } from "@/hearth/client";
+
+/**
+ * The summary AI tools read (https://llmstxt.org): the organization, its contact details and hours, and every
+ * page search engines may list, with a line on each. Not found on preview deploys and while the site is hidden.
+ */
+export const GET = hearthNext.llmsTxtHandler();

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

@@ -1,19 +1,20 @@
 "use client";
 
 import { usePathname } from "next/navigation";
-import { useEffect, useRef } from "react";
+import { useEffect, useRef, type ReactNode } from "react";
 import { theme } from "@/theme";
+import { NavDropdown } from "./NavDropdown";
 import { NavLink } from "./NavLink";
 
-type Link = { label: string; href: string };
+type Link = { label: string; href: string; dropdown?: 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.
+ * it). It closes when a link is followed. Items with a dropdown show its global block below them when opened.
  */
-export function MobileNav({ siteName, links, cta }: { siteName: string; links: Link[]; cta?: Link }) {
+export function MobileNav({ siteName, links, cta, dropdowns = {} }: { siteName: string; links: Link[]; cta?: Link; dropdowns?: Record<string, ReactNode> }) {
   const dialog = useRef<HTMLDialogElement>(null);
   const pathname = usePathname();
   useEffect(() => dialog.current?.close(), [pathname]);
@@ -32,11 +33,23 @@ export function MobileNav({ siteName, links, cta }: { siteName: string; links: L
           </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>
-          ))}
+          {links.map((item) =>
+            item.dropdown && dropdowns[item.dropdown] ? (
+              <NavDropdown
+                key={item.href + item.label}
+                href={item.href}
+                label={item.label}
+                onNavigate={close}
+                slots={{ root: t.dropdown, link: t.dropdownLink, toggle: t.dropdownToggle, panel: t.dropdownPanel }}
+              >
+                {dropdowns[item.dropdown]}
+              </NavDropdown>
+            ) : (
+              <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}

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

@@ -0,0 +1,64 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import { useEffect, useId, useRef, useState, type ReactNode } from "react";
+import { theme } from "@/theme";
+import { NavLink } from "./NavLink";
+
+/** Classes for one place the dropdown is drawn (the header, or the phone menu). */
+export type DropdownSlots = { root: string; link: string; toggle: string; panel: string };
+
+/**
+ * A main menu item with a dropdown (Navigation in Hearth: the item's Dropdown is a global block): the link, and a
+ * button beside it that shows the block in a panel. Escape, a click elsewhere or following a link closes it.
+ */
+export function NavDropdown({ href, label, slots, onNavigate, children }: { href: string; label: string; slots: DropdownSlots; onNavigate?: () => void; children: ReactNode }) {
+  const pathname = usePathname();
+  // Open on the page it was opened on: following a link closes it.
+  const [openOn, setOpenOn] = useState<string | null>(null);
+  const open = openOn === pathname;
+  const setOpen = (next: boolean) => setOpenOn(next ? pathname : null);
+  const root = useRef<HTMLDivElement>(null);
+  const panelId = useId();
+  useEffect(() => {
+    if (!open) return;
+    // On click, not pointerdown: in the phone menu the panel collapsing mid-tap would move the item being tapped.
+    const away = (e: MouseEvent) => {
+      if (!root.current?.contains(e.target as Node)) setOpenOn(null);
+    };
+    document.addEventListener("click", away, true);
+    return () => document.removeEventListener("click", away, true);
+  }, [open]);
+
+  return (
+    <div
+      ref={root}
+      className={slots.root}
+      onKeyDown={(e) => {
+        if (e.key === "Escape" && open) {
+          setOpen(false);
+          root.current?.querySelector("button")?.focus();
+        }
+      }}
+    >
+      <NavLink href={href} className={slots.link} onClick={onNavigate}>
+        {label}
+      </NavLink>
+      <button
+        type="button"
+        className={slots.toggle}
+        aria-expanded={open}
+        aria-controls={panelId}
+        aria-label={theme.text.more.replace("{label}", label)}
+        onClick={() => setOpen(!open)}
+      >
+        <svg aria-hidden="true" viewBox="0 0 20 20" fill="currentColor" className="size-4">
+          <path d="M5.2 7.2a.75.75 0 0 1 1.06.02L10 11.1l3.74-3.88a.75.75 0 1 1 1.08 1.04l-4.28 4.44a.75.75 0 0 1-1.08 0L5.18 8.26a.75.75 0 0 1 .02-1.06Z" />
+        </svg>
+      </button>
+      <div id={panelId} hidden={!open} className={slots.panel}>
+        {children}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,77 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import { useEffect, useId, useRef, type ReactNode } from "react";
+import { theme } from "@/theme";
+
+const t = theme.popup;
+
+/**
+ * A global block made a pop-up in Hearth, in a dialog (focus stays in it, Escape closes it). Any link to
+ * `#popup-<key>` opens it (editors pick it under Pop-ups when they choose where a link goes), as does arriving at an
+ * address ending in it; `button` adds a floating button that opens it on every page.
+ */
+export function Popup({ popupKey, name, title, button, children }: { popupKey: string; name: string; title?: string; button?: string; children: ReactNode }) {
+  const dialog = useRef<HTMLDialogElement>(null);
+  const titleId = useId();
+  const pathname = usePathname();
+  const href = `#popup-${popupKey}`;
+  const open = () => {
+    if (dialog.current && !dialog.current.open) dialog.current.showModal();
+  };
+
+  useEffect(() => {
+    // Capturing, so it runs before the link's own navigation.
+    const onClick = (e: MouseEvent) => {
+      if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+      const link = e.target instanceof Element ? e.target.closest("a") : null;
+      if (link?.getAttribute("href") !== href) return;
+      e.preventDefault();
+      e.stopPropagation();
+      if (dialog.current && !dialog.current.open) dialog.current.showModal();
+    };
+    document.addEventListener("click", onClick, true);
+    if (window.location.hash === href && dialog.current && !dialog.current.open) dialog.current.showModal();
+    return () => document.removeEventListener("click", onClick, true);
+  }, [href]);
+  // Following a link inside it closes it (only a change of page: it may have just opened from the address).
+  const shownOn = useRef(pathname);
+  useEffect(() => {
+    if (shownOn.current !== pathname) dialog.current?.close();
+    shownOn.current = pathname;
+  }, [pathname]);
+
+  return (
+    <>
+      <dialog
+        ref={dialog}
+        aria-labelledby={title ? titleId : undefined}
+        aria-label={title ? undefined : name}
+        className={t.dialog}
+        // A click on the backdrop lands on the dialog itself.
+        onClick={(e) => {
+          if (e.target === e.currentTarget) e.currentTarget.close();
+        }}
+      >
+        <div className={t.top}>
+          {title ? (
+            <h2 id={titleId} className={t.title}>
+              {title}
+            </h2>
+          ) : (
+            <span />
+          )}
+          <button type="button" className={t.close} onClick={() => dialog.current?.close()}>
+            {theme.text.close}
+          </button>
+        </div>
+        <div className={t.body}>{children}</div>
+      </dialog>
+      {button ? (
+        <button type="button" aria-haspopup="dialog" className={t.floating} onClick={open}>
+          {button}
+        </button>
+      ) : null}
+    </>
+  );
+}

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

@@ -3,8 +3,10 @@ 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 { Blocks } from "../blocks";
 import { fontVariables } from "@/theme/fonts";
 import { hearthNext } from "../client";
+import { Popup } from "./Popup";
 import { SiteFooter } from "./SiteFooter";
 import { SiteHeader } from "./SiteHeader";
 
@@ -16,9 +18,12 @@ import { SiteHeader } from "./SiteHeader";
 export const generateMetadata = () => hearthNext.siteMetadata();
 
 export default async function RootLayout({ children }: { children: ReactNode }) {
-  const site = await hearthNext.getSite();
-  const preview = await hearthNext.isPreview();
+  const [site, preview, globals] = await Promise.all([hearthNext.getSite(), hearthNext.isPreview(), hearthNext.getGlobalBlocks()]);
   const t = theme.page;
+  // Global blocks (Global blocks in Hearth) shown outside pages: under menu items, and as pop-ups.
+  const dropdowns = Object.fromEntries(
+    globals.filter((g) => site.settings.navigation.some((n) => n.dropdown === g.key)).map((g) => [g.key, <Blocks key={g.key} blocks={[g.block]} />]),
+  );
   return (
     <html lang={siteLang(site)} className={fontVariables || undefined}>
       <body className={t.body}>
@@ -27,11 +32,18 @@ export default async function RootLayout({ children }: { children: ReactNode })
         </a>
         {/* Live draft preview from Hearth: shows while an editor previews, refreshes as they edit. */}
         {preview ? <HearthPreview /> : null}
-        <SiteHeader site={site} />
+        <SiteHeader site={site} dropdowns={dropdowns} />
         <main id="main" className={t.main}>
           {children}
         </main>
         <SiteFooter site={site} />
+        {globals.map((g) =>
+          g.popup ? (
+            <Popup key={g.key} popupKey={g.key} name={g.name} title={g.popup.title} button={g.popup.button}>
+              <Blocks blocks={[g.block]} />
+            </Popup>
+          ) : null,
+        )}
         {/* 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>

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

@@ -1,14 +1,19 @@
 import Link from "next/link";
+import type { ReactNode } from "react";
 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 { NavDropdown } from "./NavDropdown";
 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 }) {
+/**
+ * Logo, menu, menu button and announcement banner, all edited in Hearth (Settings → General, and Navigation).
+ * `dropdowns` holds the global blocks menu items open in a dropdown, drawn, by key.
+ */
+export function SiteHeader({ site, dropdowns = {} }: { site: Site; dropdowns?: Record<string, ReactNode> }) {
   const { announcement, seo, tagline, navigation, navigationCta } = site.settings;
   const t = theme.header;
   const tone = toTone(t.tone);
@@ -32,11 +37,22 @@ export function SiteHeader({ site }: { site: Site }) {
         {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>
-              ))}
+              {navigation.map((item) =>
+                item.dropdown && dropdowns[item.dropdown] ? (
+                  <NavDropdown
+                    key={item.href + item.label}
+                    href={item.href}
+                    label={item.label}
+                    slots={{ root: t.dropdown, link: t.dropdownLink, toggle: t.dropdownToggle, panel: t.dropdownPanel }}
+                  >
+                    {dropdowns[item.dropdown]}
+                  </NavDropdown>
+                ) : (
+                  <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}>
@@ -44,7 +60,7 @@ export function SiteHeader({ site }: { site: Site }) {
                 </NavLink>
               ) : null}
             </nav>
-            <MobileNav siteName={site.name} links={navigation} cta={navigationCta} />
+            <MobileNav siteName={site.name} links={navigation} cta={navigationCta} dropdowns={dropdowns} />
           </>
         ) : null}
       </div>

package/template/src/hearth/manifest.json

@@ -16,6 +16,7 @@
     "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",

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

@@ -52,6 +52,12 @@ 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",
+    /** 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",
   },
   /** The menu on phones: a button that opens the links full screen. */
   mobileNav: {
@@ -64,6 +70,20 @@ export const defaults = {
     nav: "flex flex-col px-4 py-4",
     link: "border-b border-line py-4 text-2xl font-semibold aria-[current=page]:text-highlight",
     cta: "mt-8 inline-block rounded-lg bg-accent px-6 py-3.5 text-center font-semibold text-accent-ink",
+    /** A menu item with a dropdown: its link and button on one row, the global block below when opened. */
+    dropdown: "flex flex-wrap items-center justify-between border-b border-line",
+    dropdownLink: "py-4 text-2xl font-semibold aria-[current=page]:text-highlight",
+    dropdownToggle: "inline-flex size-11 items-center justify-center rounded-lg ring-1 ring-line aria-expanded:rotate-180",
+    dropdownPanel: "basis-full pb-4 [&_section>div]:px-0 [&_section>div]:py-4",
+  },
+  /** A global block made a pop-up in Hearth: the dialog, its top bar (heading, close), the block, and the floating button. */
+  popup: {
+    dialog: "m-auto max-h-[calc(100dvh-2rem)] w-[calc(100%-2rem)] max-w-2xl overflow-y-auto rounded-2xl bg-bg p-0 text-ink shadow-2xl backdrop:bg-black/50",
+    top: "sticky top-0 z-10 flex items-center justify-between gap-4 border-b border-line bg-bg px-6 py-4",
+    title: "text-xl font-bold",
+    close: "inline-flex min-h-11 items-center rounded-lg px-4 font-semibold ring-1 ring-line",
+    body: "[&_section>div]:px-6 [&_section>div]:py-8",
+    floating: "fixed bottom-4 right-4 z-40 rounded-full bg-accent px-6 py-3.5 font-semibold text-accent-ink shadow-lg hover:opacity-90 sm:bottom-6 sm:right-6",
   },
   footer: {
     /** The footer's ground (it sets on-dark: for everything in it). */
@@ -503,6 +523,8 @@ export const defaults = {
     completed: "Completed",
     menu: "Menu",
     close: "Close",
+    /** The button beside a menu item that opens its dropdown (read out, not shown). */
+    more: "More under {label}",
     share: "Share",
     visitProject: "Visit {name}",
     mapFailed: "The map couldn't load.",