@rxova/brand 0.8.1 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rxova/brand",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "type": "module",
   "description": "Design tokens, Starlight theme and shared site chrome for rxova.org",
   "keywords": [

package/src/components/SiteFooter.astro

@@ -35,11 +35,15 @@ interface Props {
   /**
    * The standalone surfaces to list under "Site", below Home.
    *
-   * Defaults to Blog and Updates, which is what every surface showed when this
-   * column was hardcoded. It is a prop because only the umbrella repo knows
-   * which surfaces are actually *deployed* — `sources.json` gates the mount and
-   * the link together — and a hardcoded list advertises a 404 for a surface
-   * whose first build has not landed yet. Same reason `Header` takes `items`.
+   * It is a prop because only the umbrella repo knows which *mounted* surfaces
+   * are actually deployed — `sources.json` gates the mount and the link
+   * together — and a hardcoded list advertises a 404 for a surface whose first
+   * build has not landed yet. Same reason `Header` takes `items`.
+   *
+   * The default covers the caller that cannot know: a docs site, or this
+   * package's own shell. /about is safe to include there unconditionally
+   * because it is a page of the landing's Astro build rather than a mount —
+   * there is no artifact to wait for, so it exists whenever the landing does.
    */
   site?: readonly SiteLink[]
 }
@@ -51,6 +55,7 @@ const year = new Date().getFullYear()
 const surfaces: readonly SiteLink[] = site ?? [
   { label: 'Blog', href: siteUrl('/blog') },
   { label: 'Updates', href: siteUrl('/updates') },
+  { label: 'About', href: siteUrl('/about') },
 ]
 ---
 

package/src/components/SiteShell.astro

@@ -1,71 +1,35 @@
 ---
 /**
- * The shell for rxova.org's non-Starlight surfaces — /blog and /updates.
+ * Artifact document for rxova.org's non-Starlight page components.
  *
  * It lived in both packages as a 244-line file that differed on four lines, which
  * is exactly how the menu came to render in a different order on each: a fix has to
  * be made twice, and once was enough to forget.
  *
- * Not for the docs sites — those are Starlight and take their chrome from
- * `sharedStarlightConfig`. This is for the surfaces that are plain Astro.
+ * This deliberately owns no site header, footer, analytics or theme bootstrap.
+ * It gives an independently-built page component a standards-compliant document
+ * for its metadata and assets; rxova-website consumes its body and supplies the
+ * public shell at deploy time.
  */
 import '../fonts.css'
 import '../astro.css'
 
-import { RXOVA_ORIGIN, siteUrl } from '../sites.ts'
-
-import Header, { type HeaderItem } from './Header.astro'
-import SiteFooter from './SiteFooter.astro'
-import ThemeScript from './ThemeScript.astro'
+import { canonicalUrl, siteUrl } from '../sites.ts'
 
 interface Props {
   title: string
   description: string
-  /** Canonical path, e.g. `/blog/why-rxova-has-a-blog`. */
+  /** Canonical path, e.g. `/blog/why-rxova-has-a-blog`. Normalised below. */
   path: string
   ogType?: 'website' | 'article'
 }
 
 const { title, description, path, ogType = 'website' } = Astro.props
-const canonical = `${RXOVA_ORIGIN}${path}`
-
-/**
- * The menu, in one fixed order for every surface.
- *
- * Which item is current is *derived* from the base the surface was built for, not
- * declared per package — declaring it is what let the two drift into different
- * orders. `BASE_URL` is substituted by the consuming app's build, so this is
- * `/blog` inside @rxova/blog and `/updates` inside @rxova/updates.
- */
-const base = import.meta.env.BASE_URL.replace(/\/$/, '')
-
-const SECTIONS = [
-  { label: 'Blog', path: '/blog' },
-  { label: 'Updates', path: '/updates' },
-]
-
-/**
- * A URL inside this surface.
- *
- * Anything *leaving* it goes through `siteUrl`: a bare `/updates` would resolve
- * against the mount and point at `/blog/updates`.
- */
-const inside = (p = '') => `${base}/${p}`.replace(/\/{2,}/g, '/')
 
-/**
- * The menu, fully resolved for this surface, in the one fixed order every surface
- * shows it. The current section links inside its own base; every other link is
- * absolute so it does not resolve against this mount. `Header` owns how it looks;
- * this owns where it points.
- */
-const items: HeaderItem[] = [
-  { label: 'Projects', href: siteUrl('/') },
-  ...SECTIONS.map((section) =>
-    section.path === base
-      ? { label: section.label, href: inside(), current: true }
-      : { label: section.label, href: siteUrl(section.path) },
-  ),
-]
+// Normalised here rather than at the four call sites: every one of them had
+// dropped the trailing slash, so every blog and updates page was declaring itself
+// canonical at a URL that 301s. A caller can forget again; this cannot.
+const canonical = canonicalUrl(path)
 ---
 
 <!doctype html>
@@ -73,8 +37,6 @@ const items: HeaderItem[] = [
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <link rel="icon" type="image/png" href={siteUrl('/rxova-logo-256.png')} />
-    <link rel="apple-touch-icon" href={siteUrl('/rxova-logo-256.png')} />
     <link rel="canonical" href={canonical} />
     <title>{title}</title>
     <meta name="description" content={description} />
@@ -84,35 +46,18 @@ const items: HeaderItem[] = [
     <meta property="og:url" content={canonical} />
     <meta property="og:image" content={siteUrl('/og/rxova.png')} />
     <meta name="twitter:card" content="summary_large_image" />
-    <ThemeScript />
   </head>
   <body>
-    <Header homeHref={siteUrl('/')} logoSrc={siteUrl('/rxova-logo-256.png')} items={items} />
-
     <main>
       <slot />
     </main>
 
-    <div class="foot">
-      <SiteFooter />
-    </div>
-
     <style>
-      /* The header is `Header` (its own component, shared with the landing); the
-         only chrome styled here is the page body and the footer's measure. */
       main {
         max-width: var(--max);
         margin: 0 auto;
         padding: clamp(2rem, 6vh, 3.5rem) 1.5rem 4rem;
       }
-
-      /* The footer's own rules are unscoped (footer.css, shared with the docs
-         sites); this only puts it on the page's measure. */
-      .foot {
-        max-width: var(--max);
-        margin: 0 auto;
-        padding: 0 1.5rem;
-      }
     </style>
 
     <!-- Prose styling for rendered markdown. Global rather than scoped: the

package/src/index.ts

@@ -15,6 +15,7 @@ export {
   getRepo,
   docsUrl,
   siteUrl,
+  canonicalUrl,
   type Project,
   type ProjectId,
   type RepoId,

package/src/sites.test.ts

@@ -18,6 +18,7 @@ import {
   getRepo,
   docsUrl,
   siteUrl,
+  canonicalUrl,
   projectFromBase,
   type ProjectId,
 } from './sites.ts'
@@ -111,6 +112,31 @@ describe('urls', () => {
   })
 })
 
+describe('canonicalUrl', () => {
+  // The bug this exists to prevent: /blog answers 301 and only /blog/ answers
+  // 200, so a canonical without the slash points a crawler at a redirect.
+  it('always ends in a slash, whatever the caller passed', () => {
+    expect(canonicalUrl('/blog')).toBe(`${RXOVA_ORIGIN}/blog/`)
+    expect(canonicalUrl('/blog/')).toBe(`${RXOVA_ORIGIN}/blog/`)
+    expect(canonicalUrl('/updates/repos/journey')).toBe(`${RXOVA_ORIGIN}/updates/repos/journey/`)
+  })
+
+  it('roots a path that arrives without a leading slash', () => {
+    expect(canonicalUrl('blog')).toBe(`${RXOVA_ORIGIN}/blog/`)
+  })
+
+  it('defaults to the origin root', () => {
+    expect(canonicalUrl()).toBe(`${RXOVA_ORIGIN}/`)
+  })
+
+  // siteUrl builds nav hrefs, where following a redirect costs nothing. Keeping
+  // them different is the point; collapsing them would reintroduce the bug.
+  it('differs from siteUrl, which does not normalise', () => {
+    expect(siteUrl('/blog')).toBe(`${RXOVA_ORIGIN}/blog`)
+    expect(canonicalUrl('/blog')).not.toBe(siteUrl('/blog'))
+  })
+})
+
 describe('projectFromBase', () => {
   it('recognises a mount with and without its trailing slash', () => {
     expect(projectFromBase('/packages/journey/')).toBe('journey')

package/src/sites.ts

@@ -121,6 +121,23 @@ export function siteUrl(path = '/'): string {
   return `${RXOVA_ORIGIN}${path.startsWith('/') ? path : `/${path}`}`
 }
 
+/**
+ * Absolute canonical URL for a *page* on the umbrella site.
+ *
+ * Trailing slash, always — which is the whole reason this is not `siteUrl`.
+ * rxova.org is published as a directory-style tree on GitHub Pages, so `/blog`
+ * answers 301 and only `/blog/` answers 200. A self-referencing canonical naming
+ * the redirecting form points a crawler at a URL that does not serve the page,
+ * which is the one thing a canonical must never do. `siteUrl` stays as it is:
+ * a nav link may follow a redirect, a canonical may not.
+ *
+ * Pages only. Assets keep their exact path and want `siteUrl`.
+ */
+export function canonicalUrl(path = '/'): string {
+  const rooted = path.startsWith('/') ? path : `/${path}`
+  return `${RXOVA_ORIGIN}${rooted.endsWith('/') ? rooted : `${rooted}/`}`
+}
+
 /**
  * Which project a page belongs to, inferred from Astro's `BASE_URL`.
  *

package/src/starlight.css

@@ -78,6 +78,44 @@ header.header {
   background: var(--sl-color-bg-nav);
 }
 
+/* In a schema-2 page bundle the umbrella header is rendered by rxova-website
+   outside Starlight's `.page`. Keep Starlight's own sticky documentation bar
+   below it instead of letting the two sticky headers occupy the same top edge. */
+html[data-rxova-shell] {
+  --rx-shell-header-height: 3.5rem;
+}
+
+html[data-rxova-shell] .page > header.header {
+  inset-block-start: var(--rx-shell-header-height);
+}
+
+html[data-rxova-shell] .sidebar-pane {
+  inset-block-start: calc(var(--rx-shell-header-height) + var(--sl-nav-height));
+}
+
+html[data-rxova-shell] mobile-starlight-toc nav {
+  top: calc(var(--rx-shell-header-height) + var(--sl-nav-height) - 1px);
+}
+
+html[data-rxova-shell] starlight-menu-button button {
+  top: calc(
+    var(--rx-shell-header-height) + (var(--sl-nav-height) - var(--sl-menu-button-size)) / 2
+  );
+}
+
+@media (min-width: 72rem) {
+  html[data-rxova-shell] .right-sidebar {
+    top: var(--rx-shell-header-height);
+    height: calc(100vh - var(--rx-shell-header-height));
+  }
+}
+
+@media (max-width: 34rem) {
+  html[data-rxova-shell] {
+    --rx-shell-header-height: 3.25rem;
+  }
+}
+
 /* Site title: the rxova mark sits beside the project wordmark. */
 .rx-site-title {
   display: flex;

package/src/starlight.ts

@@ -27,6 +27,12 @@ export interface SharedStarlightOptions {
   components?: Record<string, string>
   /** Path under the repo root that holds the docs site, for the edit link. */
   editLinkBase?: string
+  /**
+   * Build body-only documentation for rxova-website to place in its global
+   * shell. Starlight's search, sidebar and page navigation remain page UI; only
+   * the umbrella footer is omitted.
+   */
+  pageComponent?: boolean
 }
 
 export function sharedStarlightConfig({
@@ -35,6 +41,7 @@ export function sharedStarlightConfig({
   customCss = [],
   components = {},
   editLinkBase = 'apps/docs',
+  pageComponent = false,
 }: SharedStarlightOptions) {
   const self = getProject(project)
 
@@ -72,7 +79,7 @@ export function sharedStarlightConfig({
       SocialIcons: '@rxova/brand/components/SocialIcons.astro',
       // Starlight's default footer (pagination, edit link, last updated) plus
       // the shared four-column site footer beneath it.
-      Footer: '@rxova/brand/components/Footer.astro',
+      ...(!pageComponent ? { Footer: '@rxova/brand/components/Footer.astro' } : {}),
       // Starlight's own picker, plus a resync when a page is restored from the
       // back/forward cache — without it, changing the theme on one rxova.org
       // surface and pressing Back leaves the restored page on the old theme.