@rxova/brand 0.8.2 → 0.11.0

package/README.md

@@ -69,20 +69,27 @@ import { PROJECTS } from '@rxova/brand'
 ---
 ```
 
-`astro.css` pulls in `tokens.css` and adds the reset and base element styles
-that Starlight gives docs sites for free.
+`astro.css` pulls in `chrome.css` — the tokens, the footer's styles and the
+short aliases — and adds the reset and base element styles that Starlight gives
+docs sites for free.
+
+Use `chrome.css` on its own where something else already owns the document, such
+as rxova-website's shell templates: their body is composed into a built
+Starlight page, and the reset in `astro.css` is unlayered, so it would outrank
+everything in `@layer starlight.*` and flatten that page.
 
 ## What's in it
 
-| Export                            | What it is                                                            |
-| --------------------------------- | --------------------------------------------------------------------- |
-| `@rxova/brand`                    | `PROJECTS`, `docsUrl()`, `siteUrl()`, `sharedStarlightConfig()`       |
-| `@rxova/brand/tokens.css`         | The `--rx-*` custom properties. Everything derives from these.        |
-| `@rxova/brand/starlight.css`      | For docs sites: maps `--rx-*` onto Starlight's `--sl-*`, plus chrome  |
-| `@rxova/brand/astro.css`          | For plain Astro sites: tokens, a reset, and base element styling      |
-| `@rxova/brand/fonts.css`          | Self-hosted Space Grotesk + IBM Plex Mono                             |
-| `@rxova/brand/components/*.astro` | `SiteTitle`, `SocialIcons`, `Footer`, `SiteFooter`, `ProjectSwitcher` |
-| `@rxova/brand/assets/*`           | The mark, logos and per-project OG images                             |
+| Export                            | What it is                                                             |
+| --------------------------------- | ---------------------------------------------------------------------- |
+| `@rxova/brand`                    | `PROJECTS`, `docsUrl()`, `siteUrl()`, `sharedStarlightConfig()`        |
+| `@rxova/brand/tokens.css`         | The `--rx-*` custom properties. Everything derives from these.         |
+| `@rxova/brand/starlight.css`      | For docs sites: maps `--rx-*` onto Starlight's `--sl-*`, plus chrome   |
+| `@rxova/brand/astro.css`          | For plain Astro sites: `chrome.css`, a reset, and base element styling |
+| `@rxova/brand/chrome.css`         | What the shared header and footer need, with nothing document-level    |
+| `@rxova/brand/fonts.css`          | Self-hosted Space Grotesk + IBM Plex Mono                              |
+| `@rxova/brand/components/*.astro` | `SiteTitle`, `SocialIcons`, `Footer`, `SiteFooter`, `ProjectSwitcher`  |
+| `@rxova/brand/assets/*`           | The mark, logos and per-project OG images                              |
 
 ## The palette
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rxova/brand",
-  "version": "0.8.2",
+  "version": "0.11.0",
   "type": "module",
   "description": "Design tokens, Starlight theme and shared site chrome for rxova.org",
   "keywords": [
@@ -33,6 +33,7 @@
     ".": "./src/index.ts",
     "./tokens.css": "./src/tokens.css",
     "./astro.css": "./src/astro.css",
+    "./chrome.css": "./src/chrome.css",
     "./starlight.css": "./src/starlight.css",
     "./fonts.css": "./src/fonts.css",
     "./components/*": "./src/components/*",

package/src/astro.css

@@ -1,42 +1,21 @@
 /**
- * Entry point for plain Astro surfaces — today, the rxova.org landing.
+ * Entry point for plain Astro surfaces that own their whole document — the
+ * rxova.org landing, /blog and /updates.
  *
  * Starlight sites use `starlight.css` instead; it maps the same tokens onto
- * Starlight's own variables. This file carries what a bare Astro page needs and
+ * Starlight's own variables. This file is `chrome.css` — the tokens, the footer
+ * and the short aliases — plus the two things a bare Astro page needs and
  * Starlight already provides: a reset and base element styling.
  *
- * It also aliases the short token names the landing was written against
- * (`--bg`, `--fg`, `--rule`, …) onto their `--rx-*` equivalents, so adopting
- * this package did not require rewriting several hundred lines of scoped
- * component styles in one go. New work should use `--rx-*` directly; the
- * aliases exist to make the migration incremental, not to be a second API.
+ * Load this only where nothing else owns the document. A surface that renders
+ * the shared chrome *into* someone else's document — rxova-website's shell
+ * templates, whose body is composed into a built Starlight page — must load
+ * `chrome.css` instead. The reset below is unlayered, so inside a Starlight
+ * document it would outrank every rule in `@layer starlight.*` and flatten the
+ * page; see chrome.css.
  */
 
-@import './tokens.css';
-/* The shared site footer, which /blog, /updates and the landing all render. It
-   is the one piece of chrome common to these surfaces and the Starlight ones,
-   so its rules sit in their own file and both entry points pull them in. */
-@import './footer.css';
-
-:root {
-  --bg: var(--rx-bg);
-  --fg: var(--rx-fg);
-  --muted: var(--rx-muted);
-  --faint: var(--rx-faint);
-  --rule: var(--rx-rule);
-  --card: var(--rx-card);
-  --tag-bg: var(--rx-tag-bg);
-  --glow-tint: var(--rx-glow-tint);
-  --font: var(--rx-font-sans);
-  --mono: var(--rx-font-mono);
-  --max: var(--rx-max);
-
-  /* The landing's `--accent` is the foreground, not the brand violet: its
-     design is deliberately monochrome and uses the gradient only as an accent
-     rule. Mapping this to --rx-primary would tint every focus ring on the
-     site. */
-  --accent: var(--rx-fg);
-}
+@import './chrome.css';
 
 /* --- Reset ---------------------------------------------------------------- */
 

package/src/chrome.css

@@ -0,0 +1,51 @@
+/**
+ * Everything the shared chrome needs, and nothing that touches the document.
+ *
+ * `Header`, `SiteFooter` and `ThemeToggle` are rendered on two kinds of page:
+ * plain Astro surfaces that own their whole document (the landing, /blog,
+ * /updates — see astro.css), and rxova-website's shell templates, whose body is
+ * composed into an already-complete Starlight document at deploy time.
+ *
+ * The second case is why this file exists. It carries the tokens, the footer's
+ * styles and the short aliases the chrome's scoped CSS is written against — but
+ * no reset and no base element styling. Those belong to whoever owns the
+ * document, and a shell that brings its own into a Starlight page destroys that
+ * page: Starlight puts all of its CSS in `@layer starlight.*`, and an unlayered
+ * `* { margin: 0; padding: 0 }` arriving from the shell beats every layered rule
+ * it has, whatever the specificity. That is not a hypothetical — it flattened
+ * every /packages/* docs page on rxova.org.
+ *
+ * So: load this to render the chrome, and astro.css (which is this plus the
+ * reset) to own a document.
+ */
+
+@import './tokens.css';
+/* The shared site footer, which /blog, /updates and the landing all render. It
+   is the one piece of chrome common to these surfaces and the Starlight ones,
+   so its rules sit in their own file and both entry points pull them in. */
+@import './footer.css';
+
+/* The short token names the landing and the shared chrome were written against
+   (`--bg`, `--fg`, `--rule`, …), aliased onto their `--rx-*` equivalents, so
+   adopting this package did not require rewriting several hundred lines of
+   scoped component styles in one go. New work should use `--rx-*` directly; the
+   aliases exist to make the migration incremental, not to be a second API. */
+:root {
+  --bg: var(--rx-bg);
+  --fg: var(--rx-fg);
+  --muted: var(--rx-muted);
+  --faint: var(--rx-faint);
+  --rule: var(--rx-rule);
+  --card: var(--rx-card);
+  --tag-bg: var(--rx-tag-bg);
+  --glow-tint: var(--rx-glow-tint);
+  --font: var(--rx-font-sans);
+  --mono: var(--rx-font-mono);
+  --max: var(--rx-max);
+
+  /* The landing's `--accent` is the foreground, not the brand violet: its
+     design is deliberately monochrome and uses the gradient only as an accent
+     rule. Mapping this to --rx-primary would tint every focus ring on the
+     site. */
+  --accent: var(--rx-fg);
+}

package/src/components/SiteShell.astro

@@ -1,83 +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(/\/$/, '')
-
-/**
- * The surfaces that can be the *current* one here — the mounted ones this shell
- * is ever built for. /about is not among them: it is a page of the landing's own
- * Astro build rather than a mount, so it can never match `base`, and it is added
- * as a fixed trailing item below.
- */
-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) },
-  ),
-  // Fixed trailing item, like Projects is a fixed leading one, and for the same
-  // reason: it belongs to the landing's build, so it is always deployed and can
-  // never be the current surface here. The landing grew an About entry and these
-  // two did not, which left a reader on a post with no way to reach it — the
-  // failure mode this shell exists to prevent.
-  { label: 'About', href: siteUrl('/about') },
-]
+// 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>
@@ -85,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} />
@@ -96,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/footer.css

@@ -7,9 +7,9 @@
  * is why /blog and /updates shipped a dot-separated link row instead — the
  * shared footer would have rendered unstyled there.
  *
- * Imported by both `starlight.css` and `astro.css`; nothing needs to import it
+ * Imported by both `starlight.css` and `chrome.css`; nothing needs to import it
  * directly. Written against `--rx-*` tokens only, so it does not depend on the
- * short aliases astro.css defines.
+ * short aliases chrome.css defines.
  */
 
 @import './tokens.css';

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.