soames-astro-theme 0.1.3 → 0.1.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "soames-astro-theme",
   "type": "module",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Shared Astro theme for the Soames ecosystem (WordPress headless + React islands). Successor to soames-gatsby-theme.",
   "keywords": [
     "astro",

package/src/components/Breadcrumbs.tsx

@@ -0,0 +1,40 @@
+// Breadcrumb trail for single Knowledge Base articles (docs CPT). Presentational
+// and static (no hydration): the crumb list is assembled in the docs template
+// from docAncestors() + the /docs/ landing title. Crumbs with an `href` render
+// as links; the last crumb (the current page) has no href and renders as plain
+// text with aria-current="page". Separators are drawn in CSS (::before), so they
+// aren't part of the accessible name or selectable text.
+import React from "react";
+import parse from "html-react-parser";
+
+export interface Crumb {
+  label: string;
+  href?: string;
+}
+
+interface BreadcrumbsProps {
+  crumbs: Crumb[];
+}
+
+const Breadcrumbs: React.FC<BreadcrumbsProps> = ({ crumbs }) => (
+  <nav className="soames-breadcrumbs-nav" aria-label="Breadcrumb">
+    <ol className="soames-breadcrumbs">
+      {crumbs.map((crumb, i) => {
+        const isCurrent = i === crumbs.length - 1;
+        return (
+          <li key={i} className="soames-breadcrumb-item">
+            {crumb.href && !isCurrent ? (
+              <a href={crumb.href}>{parse(crumb.label)}</a>
+            ) : (
+              <span aria-current={isCurrent ? "page" : undefined}>
+                {parse(crumb.label)}
+              </span>
+            )}
+          </li>
+        );
+      })}
+    </ol>
+  </nav>
+);
+
+export default Breadcrumbs;

package/src/lib/wp.ts

@@ -46,6 +46,9 @@ export interface WpPage {
   content: string;
   excerpt: string;
   overlayOpacity: number | null;
+  // Dedicated hero background image URL from the plugin (ORBI-41). Takes priority
+  // over featuredImage for the hero backdrop; null when unset. See resolveHeroBg.
+  heroBackgroundImage: string | null;
   featuredImage: WpImage | null;
 }
 export interface WpAuthor {
@@ -93,6 +96,19 @@ function parseOverlayOpacity(value: unknown): number | null {
   return Number.isFinite(n) ? n : null;
 }
 
+// Resolve the hero backdrop URL from a page (or posts/docs page): the dedicated
+// hero background image wins, then the featured image, then null (→ HeroHeader
+// applies its picsum placeholder). Single source of truth for levels 1→2 of the
+// ORBI-41 fallback chain; level 3 (picsum) lives in HeroHeader.
+export function resolveHeroBg(
+  page:
+    | { heroBackgroundImage?: string | null; featuredImage?: WpImage | null }
+    | null
+    | undefined
+): string | null {
+  return page?.heroBackgroundImage ?? page?.featuredImage?.sourceUrl ?? null;
+}
+
 function normalizeImage(node: any): WpImage | null {
   const n = node?.featuredImage?.node;
   if (!n?.sourceUrl) return null;
@@ -107,7 +123,7 @@ function normalizeImage(node: any): WpImage | null {
 export async function getPages(): Promise<WpPage[]> {
   // NOTE the alias `wpPages:` — required to pass Wordfence.
   const data = await wpQuery<{ wpPages: { nodes: any[] } }>(
-    `{ wpPages: pages(first: 100) { nodes { databaseId title uri slug isPostsPage isFrontPage content excerpt overlayOpacity ${IMAGE_FRAGMENT} } } }`
+    `{ wpPages: pages(first: 100) { nodes { databaseId title uri slug isPostsPage isFrontPage content excerpt overlayOpacity heroBackgroundImage ${IMAGE_FRAGMENT} } } }`
   );
   return data.wpPages.nodes.map((n) => ({
     databaseId: n.databaseId,
@@ -121,6 +137,10 @@ export async function getPages(): Promise<WpPage[]> {
     // The plugin's WPGraphQL `overlayOpacity` field is typed String (e.g. "0.4"),
     // so parse it to a number; null (→ HeroHeader default 0.6) if absent/invalid.
     overlayOpacity: parseOverlayOpacity(n.overlayOpacity),
+    // Dedicated hero background image URL (ORBI-41); the plugin resolves it to
+    // null when unset. (Ships with the plugin that already provides overlayOpacity
+    // above, so the query requires no older-plugin fallback beyond that.)
+    heroBackgroundImage: n.heroBackgroundImage ?? null,
     featuredImage: normalizeImage(n),
   }));
 }
@@ -133,6 +153,7 @@ export interface WpPostsPage {
   databaseId: number;
   slug: string;
   title: string;
+  heroBackgroundImage: string | null;
   featuredImage: WpImage | null;
   overlayOpacity: number | null;
 }
@@ -143,6 +164,7 @@ export async function getPostsPage(): Promise<WpPostsPage | null> {
     databaseId: pp.databaseId,
     slug: pp.slug,
     title: pp.title,
+    heroBackgroundImage: pp.heroBackgroundImage,
     featuredImage: pp.featuredImage,
     overlayOpacity: pp.overlayOpacity,
   };
@@ -159,6 +181,7 @@ export interface WpDocsPage {
   databaseId: number;
   title: string;
   excerpt: string;
+  heroBackgroundImage: string | null;
   featuredImage: WpImage | null;
   overlayOpacity: number | null;
 }
@@ -173,6 +196,7 @@ export async function getDocsPage(): Promise<WpDocsPage | null> {
       databaseId: dp.databaseId,
       title: dp.title,
       excerpt: dp.excerpt,
+      heroBackgroundImage: dp.heroBackgroundImage,
       featuredImage: dp.featuredImage,
       overlayOpacity: dp.overlayOpacity,
     };
@@ -263,6 +287,25 @@ export function buildDocTree(docs: WpDoc[]): DocTreeNode[] {
   return roots;
 }
 
+// Walk the parentDatabaseId chain up from a doc, returning its ancestors in
+// root→parent order (excluding the doc itself). Used for breadcrumbs. Derives
+// from the data, not the URI, because slugs don't always match titles and we
+// need each ancestor's title as well as its uri. The depth cap guards against a
+// malformed cycle in parentDatabaseId.
+export function docAncestors(docs: WpDoc[], databaseId: number): WpDoc[] {
+  const byId = new Map<number, WpDoc>(docs.map((d) => [d.databaseId, d]));
+  const chain: WpDoc[] = [];
+  let current = byId.get(databaseId);
+  let guard = 0;
+  while (current && current.parentDatabaseId && guard++ < 50) {
+    const parent = byId.get(current.parentDatabaseId);
+    if (!parent) break;
+    chain.unshift(parent);
+    current = parent;
+  }
+  return chain;
+}
+
 export async function getGeneralSettings(): Promise<{ title: string; description: string }> {
   const data = await wpQuery<{ generalSettings: { title: string; description: string } }>(
     `{ generalSettings { title description } }`

package/src/routes/[...uri].astro

@@ -6,7 +6,7 @@ import Base from "@theme/layouts/Base.astro";
 import HeroHeader from "@theme/components/HeroHeader";
 import Shortcodes from "@theme/components/shortcodes/Shortcodes";
 import RemoveContentAreaPadding from "@theme/components/shortcodes/RemoveContentAreaPadding";
-import { getPages } from "../lib/wp";
+import { getPages, resolveHeroBg } from "../lib/wp";
 
 export async function getStaticPaths() {
   const pages = await getPages();
@@ -41,7 +41,7 @@ if (import.meta.env.DEV) {
   <HeroHeader
     title={page.title}
     subhead={page.excerpt}
-    backgroundImage={page.featuredImage?.sourceUrl ?? null}
+    backgroundImage={resolveHeroBg(page)}
     overlayOpacity={page.overlayOpacity}
   />
   {page.content && (

package/src/routes/blog/[...page].astro

@@ -6,7 +6,7 @@
 // Hero (title/featured image/overlay) comes from that Posts page when present.
 import Base from "@theme/layouts/Base.astro";
 import HeroHeader from "@theme/components/HeroHeader";
-import { getPosts, getPostsPerPage, getPostsPage, type WpPost } from "../../lib/wp";
+import { getPosts, getPostsPerPage, getPostsPage, resolveHeroBg, type WpPost } from "../../lib/wp";
 
 export async function getStaticPaths() {
   const [posts, perPage, postsPage] = await Promise.all([
@@ -29,7 +29,7 @@ export async function getStaticPaths() {
         prevPath: pageNum > 1 ? (pageNum === 2 ? `${base}/` : `${base}/${pageNum - 1}/`) : null,
         nextPath: pageNum < totalPages ? `${base}/${pageNum + 1}/` : null,
         heroTitle: postsPage?.title || "Blog",
-        heroBg: postsPage?.featuredImage?.sourceUrl ?? null,
+        heroBg: resolveHeroBg(postsPage),
         heroOverlay: postsPage?.overlayOpacity ?? 0.6,
       },
     };
@@ -55,7 +55,7 @@ if (import.meta.env.DEV) {
   prevPath = pageNum > 1 ? (pageNum === 2 ? `${base}/` : `${base}/${pageNum - 1}/`) : null;
   nextPath = pageNum < totalPages ? `${base}/${pageNum + 1}/` : null;
   heroTitle = postsPage?.title || "Blog";
-  heroBg = postsPage?.featuredImage?.sourceUrl ?? null;
+  heroBg = resolveHeroBg(postsPage);
   heroOverlay = postsPage?.overlayOpacity ?? 0.6;
 }
 

package/src/routes/blog/post/[...slug].astro

@@ -8,7 +8,7 @@ import HeroHeader from "@theme/components/HeroHeader";
 import Shortcodes from "@theme/components/shortcodes/Shortcodes";
 import Bio from "@theme/components/Bio";
 import BlogSidebar from "@theme/components/BlogSidebar";
-import { getPosts, getPostsPage } from "../../../lib/wp";
+import { getPosts, getPostsPage, resolveHeroBg } from "../../../lib/wp";
 
 export async function getStaticPaths() {
   const posts = await getPosts();
@@ -17,7 +17,7 @@ export async function getStaticPaths() {
   // Fetched once here and shared across all paths (one WP round-trip).
   const postsPage = await getPostsPage();
   const heroTitle = postsPage?.title ?? "Blog";
-  const heroBg = postsPage?.featuredImage?.sourceUrl ?? null;
+  const heroBg = resolveHeroBg(postsPage);
   const heroOverlay = postsPage?.overlayOpacity ?? null;
   return posts.map((post, i) => ({
     params: { slug: post.slug },
@@ -49,7 +49,7 @@ if (import.meta.env.DEV) {
   }
   const pp = await getPostsPage();
   heroTitle = pp?.title ?? "Blog";
-  heroBg = pp?.featuredImage?.sourceUrl ?? null;
+  heroBg = resolveHeroBg(pp);
   heroOverlay = pp?.overlayOpacity ?? null;
 }
 

package/src/routes/docs/[...slug].astro

@@ -7,7 +7,8 @@ import Base from "@theme/layouts/Base.astro";
 import HeroHeader from "@theme/components/HeroHeader";
 import Shortcodes from "@theme/components/shortcodes/Shortcodes";
 import DocsSidebar from "@theme/components/DocsSidebar";
-import { getDocs, buildDocTree, getDocsPage } from "../../lib/wp";
+import Breadcrumbs from "@theme/components/Breadcrumbs";
+import { getDocs, buildDocTree, getDocsPage, docAncestors, resolveHeroBg } from "../../lib/wp";
 
 export async function getStaticPaths() {
   // Derive the [...slug] param from the doc's WP uri (e.g. /docs/getting-started/
@@ -24,25 +25,25 @@ export async function getStaticPaths() {
   // here and shared across all paths (one WP round-trip).
   const docsPage = await getDocsPage();
   const heroTitle = docsPage?.title ?? "Documentation";
-  const heroBg = docsPage?.featuredImage?.sourceUrl ?? null;
+  const heroBg = resolveHeroBg(docsPage);
   const heroOverlay = docsPage?.overlayOpacity ?? null;
   return docs
     .map((doc) => ({ doc, slug: toSlug(doc.uri) }))
     .filter(({ slug }) => slug.length > 0)
     .map(({ doc, slug }) => ({
       params: { slug },
-      props: { doc, tree, heroTitle, heroBg, heroOverlay },
+      props: { doc, docs, tree, heroTitle, heroBg, heroOverlay },
     }));
 }
 
-let { doc, tree, heroTitle, heroBg, heroOverlay } = Astro.props;
+let { doc, docs, tree, heroTitle, heroBg, heroOverlay } = Astro.props;
 
 // Dev only: re-fetch on each request so WP doc edits show on refresh without
 // restarting `astro dev` (getStaticPaths props are cached otherwise). Stripped
 // from production builds (import.meta.env.DEV).
 if (import.meta.env.DEV) {
   const toSlug = (uri: string) => uri.replace(/^\/+|\/+$/g, "").replace(/^docs\/?/, "");
-  const docs = await getDocs();
+  docs = await getDocs();
   const fresh = docs.find((d) => toSlug(d.uri) === Astro.params.slug);
   if (fresh) {
     doc = fresh;
@@ -50,9 +51,18 @@ if (import.meta.env.DEV) {
   }
   const dp = await getDocsPage();
   heroTitle = dp?.title ?? "Documentation";
-  heroBg = dp?.featuredImage?.sourceUrl ?? null;
+  heroBg = resolveHeroBg(dp);
   heroOverlay = dp?.overlayOpacity ?? null;
 }
+
+// Breadcrumb trail: Home › <docs landing> › <ancestors…> › current (plain text).
+// Ancestors come from the parentDatabaseId chain (data, not the URI).
+const crumbs = [
+  { label: "Home", href: "/" },
+  { label: heroTitle, href: "/docs/" },
+  ...docAncestors(docs, doc.databaseId).map((a) => ({ label: a.title, href: a.uri })),
+  { label: doc.title },
+];
 ---
 <Base pageTitle={doc.title} description={doc.excerpt}>
   <HeroHeader title={heroTitle} subhead="" backgroundImage={heroBg} overlayOpacity={heroOverlay} />
@@ -62,6 +72,7 @@ if (import.meta.env.DEV) {
         <section id="soames-gatsby-content-container" class="soames-gatsby-blog-content">
           <article class="blog-post soames-prose" itemscope itemtype="http://schema.org/TechArticle">
             <header>
+              <Breadcrumbs crumbs={crumbs} />
               <h1 itemprop="headline">{doc.title}</h1>
             </header>
             {doc.content && (

package/src/routes/docs/index.astro

@@ -5,7 +5,7 @@
 // menuOrder order). If no docs exist, getDocs() returns [] → empty state.
 import Base from "@theme/layouts/Base.astro";
 import HeroHeader from "@theme/components/HeroHeader";
-import { getDocs, getDocsPage, buildDocTree, type WpDoc, type DocTreeNode } from "../../lib/wp";
+import { getDocs, getDocsPage, buildDocTree, resolveHeroBg, type WpDoc, type DocTreeNode } from "../../lib/wp";
 
 const docs = await getDocs();
 // Hero is driven by the WP page chosen in Soames Settings → Documentation page,
@@ -32,7 +32,7 @@ const rows: WpDoc[][] = flat.reduce((groups: WpDoc[][], doc: WpDoc, i: number) =
   <HeroHeader
     title={docsPage?.title ?? "Documentation"}
     subhead={docsPage?.excerpt ?? ""}
-    backgroundImage={docsPage?.featuredImage?.sourceUrl ?? null}
+    backgroundImage={resolveHeroBg(docsPage)}
     overlayOpacity={docsPage?.overlayOpacity ?? 0.6}
   />
 

package/src/routes/index.astro

@@ -6,7 +6,7 @@ import Base from "@theme/layouts/Base.astro";
 import HeroHeader from "@theme/components/HeroHeader";
 import Shortcodes from "@theme/components/shortcodes/Shortcodes";
 import RemoveContentAreaPadding from "@theme/components/shortcodes/RemoveContentAreaPadding";
-import { getPages, getPosts } from "../lib/wp";
+import { getPages, getPosts, resolveHeroBg } from "../lib/wp";
 
 const pages = await getPages();
 const front = pages.find((p) => p.uri === "/");
@@ -17,7 +17,7 @@ const posts = front ? [] : await getPosts();
     <HeroHeader
       title={front.title}
       subhead={front.excerpt}
-      backgroundImage={front.featuredImage?.sourceUrl ?? null}
+      backgroundImage={resolveHeroBg(front)}
       overlayOpacity={front.overlayOpacity}
     />
     {front.content && (

package/src/styles/soames/overrides.css

@@ -1153,6 +1153,53 @@ section.lazy-placeholder:after {
   font-weight: 500;
 }
 
+/* ── Article breadcrumbs (Breadcrumbs) ─────────────────────────────────────── */
+.soames-breadcrumbs-nav {
+  font-family: 'Rubik', sans-serif;
+}
+
+.soames-breadcrumbs {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  list-style: none;
+  margin: 0 0 0.75rem;
+  padding: 0;
+  font-size: 0.9rem;
+  line-height: 1.4;
+  color: #6c6c6c;
+}
+
+.soames-breadcrumb-item {
+  display: inline-flex;
+  align-items: center;
+  margin: 0;
+}
+
+/* Separator between crumbs, drawn in CSS so it isn't selectable or announced. */
+.soames-breadcrumb-item + .soames-breadcrumb-item::before {
+  content: "›";
+  margin: 0 0.5rem;
+  color: #b3b0aa;
+}
+
+.soames-breadcrumb-item a {
+  color: #6c6c6c;
+  text-decoration: none;
+  transition: color 0.15s ease-in-out;
+}
+
+.soames-breadcrumb-item a:hover,
+.soames-breadcrumb-item a:focus {
+  color: #bc361b;
+  text-decoration: underline;
+}
+
+/* Current page: no link, reads a touch stronger than the ancestors. */
+.soames-breadcrumb-item [aria-current="page"] {
+  color: #232323;
+}
+
 .soames-menu .navbar {
   padding: .5rem 0;
   background: #bc361b;