soames-astro-theme 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Orbi Software
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,67 @@
+<p align="center">
+  <a href="https://soames.app">
+    <img alt="Soames" src="https://raw.githubusercontent.com/orbivision/soames-astro-theme/main/assets/soames-mark.svg" width="60" />
+  </a>
+</p>
+<h1 align="center">
+  Soames Astro Theme
+</h1>
+
+[![npm version](https://img.shields.io/npm/v/soames-astro-theme.svg?style=flat-square)](https://www.npmjs.com/package/soames-astro-theme)
+[![license](https://img.shields.io/npm/l/soames-astro-theme.svg?style=flat-square)](./LICENSE)
+
+Shared **Astro** theme for the Soames ecosystem — WordPress as a headless CMS,
+static output, React islands. Successor to `soames-gatsby-theme` (see ORBI-23/24/25).
+
+## Install
+
+```
+npm install soames-astro-theme
+```
+
+## Usage
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import soamesTheme from 'soames-astro-theme';
+
+export default defineConfig({
+  output: 'static',
+  integrations: [
+    soamesTheme({ wordpressUrl: process.env.WORDPRESS_GRAPHQL_URL }),
+  ],
+});
+```
+
+The integration registers `@astrojs/react`, sources content from WordPress at
+build time, injects the page routes (front page, WP pages, blog archive,
+blog posts), authorizes WP image domains, and installs the **theme-shadow**
+resolver.
+
+## Component overrides (the shadowing successor)
+
+Astro has no built-in component shadowing. This theme provides it via a Vite
+resolver: theme files are imported as `@theme/<path>`, and a site overrides any
+of them by creating a file at the matching path under `src/overrides/`.
+
+```
+src/overrides/components/Footer.tsx   → replaces the theme's components/Footer.tsx
+src/overrides/layouts/Base.astro      → replaces the theme's layouts/Base.astro
+```
+
+Whole-file replacement, resolved at build time, zero changes at the import site —
+the direct successor to Gatsby component shadowing.
+
+## WordPress sourcing notes
+
+- Sources via WPGraphQL (`fetch()`), with Site Assets from the Soames plugin REST
+  endpoint (`/wp-json/soames/v1/settings`).
+- **Wordfence gotcha:** some WP installs' WAF 403-blocks GraphQL whose first
+  selection-set field is `pages`/`posts`. `lib/wp.ts` aliases the root field
+  (e.g. `wpPages: pages`) to pass; the durable fix is a Wordfence allowlist rule.
+
+## Status
+
+Published to npm (ORBI-25). Under active migration — routing/URL parity, menu
+interactivity, and remaining shortcodes are being completed phase by phase.

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "soames-astro-theme",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Shared Astro theme for the Soames ecosystem (WordPress headless + React islands). Successor to soames-gatsby-theme.",
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "astro-theme",
+    "wordpress",
+    "headless-cms",
+    "typescript",
+    "react",
+    "blog",
+    "personal-site"
+  ],
+  "author": "Orbi Software",
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/orbivision/soames-astro-theme"
+  },
+  "bugs": {
+    "url": "https://github.com/orbivision/soames-astro-theme/issues"
+  },
+  "homepage": "https://github.com/orbivision/soames-astro-theme#readme",
+  "engines": {
+    "node": ">=18.20.8",
+    "npm": ">=9.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/integration.ts",
+    "./integration": "./src/integration.ts",
+    "./theme-shadow": "./src/theme-shadow.ts",
+    "./lib/wp": "./src/lib/wp.ts",
+    "./routes/*": "./src/routes/*",
+    "./components/*": "./src/components/*",
+    "./layouts/*": "./src/layouts/*",
+    "./styles/*": "./src/styles/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "astro check"
+  },
+  "peerDependencies": {
+    "astro": "^5.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@astrojs/react": "^4.2.0",
+    "bootstrap": "^5.3.8",
+    "html-react-parser": "^5.2.3"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "astro": "^5.7.0"
+  }
+}

package/src/components/Bio.tsx

@@ -0,0 +1,36 @@
+// PORTED from soames-gatsby-theme Bio.tsx. Change for Astro: author comes in as a
+// prop (from the post's author node) instead of useStaticQuery(wpUser) — the
+// standalone users query is auth/WAF-gated. Uses firstName, falling back to name.
+import React from "react";
+import type { WpAuthor } from "../lib/wp";
+
+interface BioProps {
+  author: WpAuthor | null;
+}
+
+const Bio: React.FC<BioProps> = ({ author }) => {
+  if (!author) return null;
+  const displayName = author.firstName || author.name;
+  const twitterHandle = author.name;
+
+  return (
+    <div className="bio">
+      {author.avatarUrl && (
+        <img alt={displayName ?? "Author"} className="bio-avatar" src={author.avatarUrl} />
+      )}
+      {displayName && (
+        <p>
+          Written by <strong>{displayName}</strong>
+          {author.description ? ` ${author.description}` : ""}{" "}
+          {twitterHandle && (
+            <a href={`https://twitter.com/${twitterHandle}`}>
+              You should follow them on Twitter
+            </a>
+          )}
+        </p>
+      )}
+    </div>
+  );
+};
+
+export default Bio;

package/src/components/BlogSidebar.tsx

@@ -0,0 +1,48 @@
+// PORTED from soames-gatsby-theme BlogSidebar.tsx. Changes for Astro: posts come in
+// as a prop (no useStaticQuery); gatsby <Link> → <a>; links use the Astro post path
+// (/blog/post/<slug>/). Markup/classes UNCHANGED.
+import React from "react";
+import parse from "html-react-parser";
+import type { WpPost } from "../lib/wp";
+
+interface BlogSidebarProps {
+  posts: WpPost[];
+  currentId: number;
+}
+
+const BlogSidebar: React.FC<BlogSidebarProps> = ({ posts, currentId }) => {
+  return (
+    <section className="soames-blog-roll pt-3">
+      <div className="container">
+        {posts.map((post) =>
+          post.databaseId !== currentId ? (
+            <div key={post.databaseId} className="media-container-row">
+              <div className="card p-3 col-12">
+                <div className="card-wrapper">
+                  <div className="card-box">
+                    <h4 className="card-title mbr-fonts-style display-5">
+                      {parse(post.title)}
+                    </h4>
+                    <h4 className="mbr-fonts-style display-7">{post.date}</h4>
+                    {parse(post.excerpt)}
+                  </div>
+                  <div className="mbr-section-btn text-center">
+                    <a
+                      href={`/blog/post/${post.slug}/`}
+                      itemProp="url"
+                      className="btn btn-primary display-4"
+                    >
+                      <span itemProp="headline">Read More</span>
+                    </a>
+                  </div>
+                </div>
+              </div>
+            </div>
+          ) : null
+        )}
+      </div>
+    </section>
+  );
+};
+
+export default BlogSidebar;

package/src/components/DocsSidebar.tsx

@@ -0,0 +1,45 @@
+// Hierarchical documentation nav for the docs template — the docs equivalent of
+// BlogSidebar's "Recent Posts". Renders the weDocs doc tree (built by
+// buildDocTree) as a nested menu, highlighting the current doc. Static (no
+// hydration needed); links use each doc's WP `uri` (e.g. /docs/getting-started/).
+import React from "react";
+import parse from "html-react-parser";
+import type { DocTreeNode } from "../lib/wp";
+
+interface DocsSidebarProps {
+  tree: DocTreeNode[];
+  currentId: number;
+}
+
+const DocList: React.FC<{ nodes: DocTreeNode[]; currentId: number; top?: boolean }> = ({
+  nodes,
+  currentId,
+  top = false,
+}) => (
+  <ul className={top ? "soames-docs-menu" : "soames-docs-menu soames-docs-submenu"}>
+    {nodes.map((node) => {
+      const active = node.databaseId === currentId;
+      return (
+        <li
+          key={node.databaseId}
+          className={`soames-docs-menu-item${active ? " is-active" : ""}`}
+        >
+          <a href={node.uri} aria-current={active ? "page" : undefined}>
+            {parse(node.title)}
+          </a>
+          {node.children.length > 0 && (
+            <DocList nodes={node.children} currentId={currentId} />
+          )}
+        </li>
+      );
+    })}
+  </ul>
+);
+
+const DocsSidebar: React.FC<DocsSidebarProps> = ({ tree, currentId }) => (
+  <nav className="soames-docs-nav" aria-label="Documentation">
+    <DocList nodes={tree} currentId={currentId} top />
+  </nav>
+);
+
+export default DocsSidebar;

package/src/components/Footer.tsx

@@ -0,0 +1,59 @@
+// PORTED from soames-gatsby-theme/src/components/Footer.tsx (post-ORBI-22).
+// Changes for Astro: FooterMenu's useStaticQuery → `menuItems` prop (fetched in the
+// layout). Copyright logic (companyName || title) UNCHANGED from ORBI-22.
+import React from "react";
+import FooterMenu from "./FooterMenu";
+import type { MenuItem } from "../lib/wp";
+
+interface FooterProps {
+  title: string;
+  contactBlurb?: string | null;
+  companyName?: string | null;
+  menuItems?: MenuItem[];
+}
+
+const Footer: React.FC<FooterProps> = ({
+  title,
+  contactBlurb = null,
+  companyName = null,
+  menuItems = [],
+}) => {
+  return (
+    <section className="soames-footer mt-5">
+      <div className="container">
+        <div className="media-container-row content text-white">
+          <div className="col-12 col-md-2">
+            <div className="media-wrap">{` `}</div>
+          </div>
+          <div className="col-12 col-md-4 mbr-fonts-style display-7">
+            <FooterMenu items={menuItems} />
+          </div>
+          <div className="col-12 col-md-4 mbr-fonts-style display-7">
+            {contactBlurb && (
+              <>
+                <h5 className="pb-3">Contact</h5>
+                <div
+                  className="soames-text pr-3"
+                  dangerouslySetInnerHTML={{ __html: contactBlurb }}
+                />
+              </>
+            )}
+            <p className="soames-text pt-3" data-testid="footer-copyright">
+              © {new Date().getFullYear()} {companyName || title}
+              <br />
+              Built with{" "}
+              <a href="https://www.soames.app" target="_blank" rel="noreferrer">Soames</a>,{" "}
+              <a href="https://astro.build" target="_blank" rel="noreferrer">Astro</a>, and{" "}
+              <a href="https://wordpress.org/" target="_blank" rel="noreferrer">WordPress</a>
+            </p>
+          </div>
+          <div className="col-12 col-md-2 mbr-fonts-style display-7">
+            <h5 className="pb-3">{` `}</h5>
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+};
+
+export default Footer;

package/src/components/FooterMenu.tsx

@@ -0,0 +1,36 @@
+// PORTED from soames-gatsby-theme FooterMenu.tsx. Changes: useStaticQuery → `items`
+// prop (getMenuByLocation("FOOTER")); gatsby <Link> → <a>. Markup UNCHANGED.
+import React from "react";
+import type { MenuItem } from "../lib/wp";
+
+interface FooterMenuProps {
+  items: MenuItem[];
+}
+
+const FooterMenu: React.FC<FooterMenuProps> = ({ items }) => {
+  const topLevel = items.filter((item) => item.parentDatabaseId === 0);
+  if (topLevel.length === 0) return null;
+
+  return (
+    <div className="soames-footer-content">
+      <h5 className="pb-3">Links</h5>
+      <ul>
+        {topLevel.map((item) =>
+          item.uri.includes("http") ? (
+            <li className="soames-footer-list-item" key={item.id}>
+              <a href={item.uri} target="_blank" rel="noreferrer">
+                {item.label}
+              </a>
+            </li>
+          ) : (
+            <li className="soames-footer-list-item" key={item.id}>
+              <a href={item.uri}>{item.label}</a>
+            </li>
+          )
+        )}
+      </ul>
+    </div>
+  );
+};
+
+export default FooterMenu;

package/src/components/Header.tsx

@@ -0,0 +1,57 @@
+// PORTED from soames-gatsby-theme Header.tsx. Logo/menu data now flow as props
+// (no useStaticQuery). Markup UNCHANGED.
+import React from "react";
+import HeaderMenu from "./HeaderMenu";
+import Logo from "./Logo";
+import type { MenuItem } from "../lib/wp";
+
+interface HeaderProps {
+  title: string;
+  logoUrl?: string | null;
+  logoAlt?: string | null;
+  companyName?: string | null;
+  showCompanyName?: boolean;
+  menuItems: MenuItem[];
+}
+
+const Header: React.FC<HeaderProps> = ({
+  title,
+  logoUrl = null,
+  logoAlt = null,
+  companyName = null,
+  showCompanyName = true,
+  menuItems,
+}) => {
+  return (
+    <section className="menu soames-menu">
+      <nav className="navbar navbar-expand beta-menu navbar-dropdown align-items-center navbar-fixed-top navbar-toggleable-sm">
+        <button
+          className="navbar-toggler navbar-toggler-right"
+          type="button"
+          data-bs-toggle="collapse"
+          data-bs-target="#navbarSupportedContent"
+          aria-controls="navbarSupportedContent"
+          aria-expanded="false"
+          aria-label="Toggle navigation"
+        >
+          <div className="hamburger">
+            <span></span>
+            <span></span>
+            <span></span>
+            <span></span>
+          </div>
+        </button>
+        <Logo
+          title={title}
+          logoUrl={logoUrl}
+          logoAlt={logoAlt}
+          companyName={companyName}
+          showCompanyName={showCompanyName}
+        />
+        <HeaderMenu items={menuItems} />
+      </nav>
+    </section>
+  );
+};
+
+export default Header;

package/src/components/HeaderMenu.tsx

@@ -0,0 +1,77 @@
+// PORTED from soames-gatsby-theme HeaderMenu.tsx. Changes: useStaticQuery → `items`
+// prop (fetched in the layout via getMenuByLocation("HEADER")); gatsby <Link> → <a>.
+// Markup/classes UNCHANGED — Bootstrap dropdown behavior is wired by global JS
+// (Phase 4), not React, so this renders as static HTML.
+import React from "react";
+import type { MenuItem } from "../lib/wp";
+
+interface HeaderMenuProps {
+  items: MenuItem[];
+}
+
+const HeaderMenu: React.FC<HeaderMenuProps> = ({ items }) => {
+  return (
+    <div className="collapse navbar-collapse" id="navbarSupportedContent">
+      <ul className="navbar-nav nav-dropdown nav-right" data-app-modern-menu="true">
+        {items.map((item) =>
+          item.path !== "/home/" && item.parentDatabaseId === 0 ? (
+            item.childItems.length === 0 ? (
+              <li key={item.id} className="nav-item">
+                {item.uri.includes("http") ? (
+                  <a
+                    className="nav-link link text-white display-4"
+                    href={item.uri}
+                    target="_blank"
+                    rel="noreferrer"
+                  >
+                    {item.label}
+                  </a>
+                ) : (
+                  <a href={item.uri} className="nav-link link text-white display-4">
+                    {item.label}
+                  </a>
+                )}
+              </li>
+            ) : (
+              <li key={item.id} className="nav-item dropdown">
+                <a
+                  className="nav-link link text-white dropdown-toggle display-4"
+                  href={item.uri}
+                  data-toggle="dropdown-submenu"
+                  aria-expanded="false"
+                >
+                  {item.label}
+                </a>
+                <div className="dropdown-menu">
+                  <ul className="navbar-nav nav-dropdown nav-right">
+                    {item.childItems.map((childItem) => (
+                      <li key={childItem.id}>
+                        {childItem.uri.includes("http") ? (
+                          <a
+                            className="text-white dropdown-item display-4"
+                            target="_blank"
+                            rel="noreferrer"
+                            href={childItem.uri}
+                          >
+                            {childItem.label}
+                            <br />
+                          </a>
+                        ) : (
+                          <a href={childItem.uri} className="text-white dropdown-item display-4">
+                            {childItem.label}
+                          </a>
+                        )}
+                      </li>
+                    ))}
+                  </ul>
+                </div>
+              </li>
+            )
+          ) : null
+        )}
+      </ul>
+    </div>
+  );
+};
+
+export default HeaderMenu;

package/src/components/HeroHeader.tsx

@@ -0,0 +1,66 @@
+// PORTED from soames-gatsby-theme HeroHeader.tsx. Change for Astro: title/subhead
+// come in as HTML strings and are run through html-react-parser here (the Gatsby
+// page template parsed them before passing). Parallax/overlay markup UNCHANGED.
+import React from "react";
+import parse from "html-react-parser";
+
+export interface HeroHeaderProps {
+  title: string;
+  subhead?: string | null;
+  backgroundImage?: string | null;
+  overlayOpacity?: number | null;
+}
+
+const HeroHeader: React.FC<HeroHeaderProps> = ({
+  title,
+  subhead,
+  backgroundImage,
+  overlayOpacity,
+}) => {
+  const bg = backgroundImage || "https://picsum.photos/1080/720";
+  const opacity = overlayOpacity ?? 0.6;
+
+  const css = `
+    .soames-background-lg::after {
+      background: url(${bg});
+      background-position: 50% 50%;
+      background-size: cover;
+      background-repeat: no-repeat;
+      position: fixed;
+      top: 0px;
+      left: 0px;
+      overflow: hidden;
+      pointer-events: none;
+      margin-top: -180px;
+    }
+  `;
+
+  return (
+    <>
+      <style>{css}</style>
+      <section
+        className="soames-header-lg soames-parallax soames-background-lg"
+        id="header1"
+      >
+        <div
+          className="soames-overlay"
+          style={{ opacity, backgroundColor: "rgb(46, 46, 46)" }}
+        />
+        <div className="container">
+          <div className="row justify-content-md-center">
+            <div className="soames-hero-header soames-white col-md-10">
+              <h1 className="soames-section-title align-center soames-bold mbr-fonts-style display-1">
+                {parse(title || "")}
+              </h1>
+              <div className="soames-section-subtitle align-center soames-light soames-white mbr-fonts-style display-5">
+                {subhead ? parse(subhead) : ""}
+              </div>
+            </div>
+          </div>
+        </div>
+      </section>
+    </>
+  );
+};
+
+export default HeroHeader;

package/src/components/Logo.tsx

@@ -0,0 +1,37 @@
+// PORTED from soames-gatsby-theme Logo.tsx. Change: useStaticQuery(soamesSettings)
+// → props supplied by the layout at build time (Astro has no useStaticQuery).
+import React from "react";
+
+interface LogoProps {
+  title: string;
+  logoUrl?: string | null;
+  logoAlt?: string | null;
+  companyName?: string | null;
+  showCompanyName?: boolean;
+}
+
+const Logo: React.FC<LogoProps> = ({
+  title,
+  logoUrl = null,
+  logoAlt = null,
+  companyName = null,
+  showCompanyName = true,
+}) => {
+  const displayName = companyName || title;
+  const alt = logoAlt || title;
+
+  return (
+    <div className="menu-logo">
+      <div className="navbar-brand">
+        <span className="navbar-caption-wrap">
+          <a className="navbar-caption text-white display-5" href="/">
+            {logoUrl && <img width="108" alt={alt} src={logoUrl} />}
+            {showCompanyName && <>&nbsp;&nbsp;{displayName}</>}
+          </a>
+        </span>
+      </div>
+    </div>
+  );
+};
+
+export default Logo;

package/src/components/shortcodes/RemoveContentAreaPadding.tsx

@@ -0,0 +1,13 @@
+import React from "react";
+
+const RemoveContentAreaPadding: React.FC = () => {
+  const css = `
+    .soames-gatsby-content {
+      padding: 0px;
+    }
+  `;
+
+  return <style>{css}</style>;
+};
+
+export default RemoveContentAreaPadding;