@rxova/brand 0.1.2 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rxova/brand",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "Design tokens, Starlight theme and shared site chrome for rxova.org",
   "keywords": [
@@ -20,7 +20,7 @@
   },
   "bugs": "https://github.com/rxova/brand/issues",
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=24.0.0"
   },
   "sideEffects": [
     "*.css"
@@ -58,14 +58,17 @@
     "@resvg/resvg-js": "^2.6.2",
     "@types/node": "^26.1.1",
     "astro": "^7.1.3",
+    "publint": "^0.3.21",
     "satori": "^0.29.0",
+    "tsx": "^4.23.1",
     "typescript": "6.0.3"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "check:astro": "astro check",
-    "check:exports": "node scripts/check-exports.mjs",
-    "og": "node scripts/generate-og.mjs",
-    "check:og": "node scripts/generate-og.mjs --check"
+    "pack:smoke": "node --import tsx scripts/pack-smoke.ts",
+    "check:exports": "publint --strict",
+    "og": "node --import tsx scripts/generate-og.ts",
+    "check:og": "node --import tsx scripts/generate-og.ts --check"
   }
 }

package/src/components/ThemeSelect.astro

@@ -0,0 +1,57 @@
+---
+/**
+ * Starlight's theme picker, plus a resync when the page comes out of the
+ * back/forward cache.
+ *
+ * Starlight applies the stored theme in two places, both of which run exactly
+ * once, while the document is being parsed: the inline script in
+ * `ThemeProvider.astro`, and the `<starlight-theme-select>` constructor. A
+ * back/forward navigation that hits the bfcache *restores* the document rather
+ * than parsing it, so neither runs again and the page keeps whatever
+ * `data-theme` it carried when the visitor left.
+ *
+ * All of rxova.org is one origin sharing one `starlight-theme` key, so that is
+ * a visible jump rather than a curiosity: pick a theme on the landing page or
+ * on another project's docs, press Back, and the restored page is still on the
+ * old one.
+ *
+ * This wraps rather than replaces Starlight's component — the picker, its
+ * labels and its own logic are untouched, and a Starlight release that changes
+ * them changes them here too.
+ */
+import Default from '@astrojs/starlight/components/ThemeSelect.astro'
+---
+
+<Default><slot /></Default>
+
+<script>
+  type Theme = 'auto' | 'dark' | 'light'
+
+  /** Same key and coercion Starlight uses; unknown values mean "follow the OS". */
+  const STORAGE_KEY = 'starlight-theme'
+  const parseTheme = (theme: unknown): Theme =>
+    theme === 'auto' || theme === 'dark' || theme === 'light' ? theme : 'auto'
+  const preferredColorScheme = (): Theme =>
+    matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark'
+
+  // `pageshow` is the only notification of a bfcache restore. A normal load
+  // also fires it with `persisted: false`, which we ignore — Starlight has
+  // already done the work in that case.
+  window.addEventListener('pageshow', (event) => {
+    if (!event.persisted) return
+
+    let stored: string | null
+    try {
+      stored = localStorage.getItem(STORAGE_KEY)
+    } catch {
+      // Storage can throw outright (Safari private mode, blocked cookies).
+      // Leaving the restored theme alone is the right fallback.
+      return
+    }
+
+    const theme = parseTheme(stored)
+    document.documentElement.dataset.theme = theme === 'auto' ? preferredColorScheme() : theme
+    // Keeps the picker from disagreeing with the page it controls.
+    StarlightThemeProvider.updatePickers(theme)
+  })
+</script>

package/src/env.d.ts

@@ -5,3 +5,17 @@
 // Starlight's own `.ts` sources, which import `virtual:starlight/*` modules
 // that only exist inside an Astro build — so plain `tsc` fails on them.
 // The one component that reads route data narrows it structurally instead.
+
+// Same reasoning for this one. It mirrors Starlight's own `global.d.ts`, which
+// we cannot `/// <reference>` because the package's types entry is `index.ts`
+// and drags in those same virtual modules. The global is defined at runtime by
+// the inline script in Starlight's `ThemeProvider.astro`; ThemeSelect.astro
+// calls it. Re-check this against Starlight's `global.d.ts` on a major bump.
+declare global {
+  interface StarlightThemeProvider {
+    updatePickers(theme?: string): void
+  }
+  var StarlightThemeProvider: StarlightThemeProvider
+}
+
+export {}

package/src/index.ts

@@ -9,11 +9,15 @@
 export {
   RXOVA_ORIGIN,
   PROJECTS,
+  REPOS,
+  REPO_IDS,
   getProject,
+  getRepo,
   docsUrl,
   siteUrl,
   type Project,
   type ProjectId,
+  type RepoId,
 } from './sites.ts'
 
 export { sharedStarlightConfig, type SharedStarlightOptions } from './starlight.ts'

package/src/sites.test.ts

@@ -0,0 +1,126 @@
+/**
+ * The site map: which projects and repos exist, and the URLs that reach them.
+ *
+ * Every rxova.org surface reads this — the landing, the docs switcher, and the
+ * updates feed's repo filter. It is plain data with a few lookups over it, which is
+ * exactly the kind of module that never gets tested until one of its consumers
+ * 404s in production.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import {
+  RXOVA_ORIGIN,
+  PROJECTS,
+  REPOS,
+  REPO_IDS,
+  getProject,
+  getRepo,
+  docsUrl,
+  siteUrl,
+  projectFromBase,
+  type ProjectId,
+} from './sites.ts'
+
+describe('PROJECTS', () => {
+  it('has no duplicate ids', () => {
+    expect(new Set(PROJECTS.map((p) => p.id)).size).toBe(PROJECTS.length)
+  })
+
+  // The aggregator derives `packages/<id>` from the id and only relocates the
+  // built tree; a mount that disagrees deploys a page with every asset 404ing.
+  it('mounts every project at the path its id derives', () => {
+    for (const p of PROJECTS) expect(p.mount).toBe(`/packages/${p.id}/`)
+  })
+
+  it('gives every project a tagline, a repo, an npm link and at least one package', () => {
+    for (const p of PROJECTS) {
+      expect(p.tagline.length).toBeGreaterThan(0)
+      expect(p.repo).toMatch(/^https:\/\/github\.com\//)
+      expect(p.npm).toMatch(/^https:\/\/www\.npmjs\.com\//)
+      expect(p.packages.length).toBeGreaterThan(0)
+    }
+  })
+})
+
+describe('getProject', () => {
+  it('finds a project by id', () => {
+    expect(getProject('journey').label).toBe('Journey')
+  })
+
+  it('throws rather than returning undefined for an unknown id', () => {
+    expect(() => getProject('nope' as ProjectId)).toThrow(/unknown project id: nope/)
+  })
+})
+
+describe('REPOS', () => {
+  // The whole reason REPOS exists: an update about the website or the brand repo
+  // has to be representable, and neither ships a package.
+  it('covers every project plus the repos that ship no package', () => {
+    for (const p of PROJECTS) expect(REPO_IDS).toContain(p.id)
+    expect(REPO_IDS).toContain('rxova-website')
+    expect(REPO_IDS).toContain('brand')
+  })
+
+  it('marks which entries are projects', () => {
+    expect(REPOS.filter((r) => r.project).map((r) => r.id)).toEqual(PROJECTS.map((p) => p.id))
+    expect(REPOS.filter((r) => !r.project).map((r) => r.id)).toEqual(['rxova-website', 'brand'])
+  })
+
+  it('lists projects first, which is the order the repo filter renders', () => {
+    const firstNonProject = REPOS.findIndex((r) => !r.project)
+    expect(REPOS.slice(0, firstNonProject).every((r) => r.project)).toBe(true)
+  })
+
+  it('has no duplicate ids and a label and repo for each', () => {
+    expect(new Set(REPO_IDS).size).toBe(REPOS.length)
+    for (const r of REPOS) {
+      expect(r.label.length).toBeGreaterThan(0)
+      expect(r.repo).toMatch(/^https:\/\/github\.com\//)
+    }
+  })
+
+  it('keeps REPO_IDS in step with REPOS', () => {
+    expect([...REPO_IDS]).toEqual(REPOS.map((r) => r.id))
+  })
+})
+
+describe('getRepo', () => {
+  it('finds a project repo and a non-project repo alike', () => {
+    expect(getRepo('journey').project).toBe(true)
+    expect(getRepo('brand').label).toBe('Brand')
+  })
+
+  it('throws on an unknown id', () => {
+    expect(() => getRepo('nope' as never)).toThrow(/unknown repo id: nope/)
+  })
+})
+
+describe('urls', () => {
+  it('builds an absolute docs url', () => {
+    expect(docsUrl('journey')).toBe(`${RXOVA_ORIGIN}/packages/journey/`)
+  })
+
+  it('builds a site url from a path with or without a leading slash', () => {
+    expect(siteUrl('/privacy')).toBe(`${RXOVA_ORIGIN}/privacy`)
+    expect(siteUrl('privacy')).toBe(`${RXOVA_ORIGIN}/privacy`)
+  })
+
+  it('defaults to the origin root', () => {
+    expect(siteUrl()).toBe(`${RXOVA_ORIGIN}/`)
+  })
+})
+
+describe('projectFromBase', () => {
+  it('recognises a mount with and without its trailing slash', () => {
+    expect(projectFromBase('/packages/journey/')).toBe('journey')
+    expect(projectFromBase('/packages/journey')).toBe('journey')
+  })
+
+  // A standalone docs build has base "/" and belongs to no project. Returning
+  // undefined is correct there — the switcher simply omits the current marker.
+  it('returns undefined for a base that is not a mount', () => {
+    expect(projectFromBase('/')).toBeUndefined()
+    expect(projectFromBase('/packages/nope/')).toBeUndefined()
+  })
+})

package/src/sites.ts

@@ -71,6 +71,46 @@ export function getProject(id: ProjectId): Project {
   return project
 }
 
+/**
+ * Every rxova repo a changelog entry can be about — the published projects plus
+ * the ones that ship no package.
+ *
+ * `PROJECTS` deliberately stays what it is: the things with docs, an npm package
+ * and a landing card. But "we rebuilt the deploy pipeline" is exactly the kind of
+ * progress `/changelog` exists to record, and it belongs to `rxova-website`, which
+ * is not a project and never will be. Validating changelog entries against
+ * `PROJECTS` would make those entries unrepresentable.
+ *
+ * Order is display order for the changelog's repo filter: projects first, then
+ * infrastructure.
+ */
+export const REPOS = [
+  ...PROJECTS.map((p) => ({ id: p.id, label: p.label, repo: p.repo, project: true as const })),
+  {
+    id: 'rxova-website',
+    label: 'Website',
+    repo: 'https://github.com/rxova/rxova-website',
+    project: false as const,
+  },
+  {
+    id: 'brand',
+    label: 'Brand',
+    repo: 'https://github.com/rxova/brand',
+    project: false as const,
+  },
+] as const
+
+export type RepoId = (typeof REPOS)[number]['id']
+
+/** The ids only, for schema validation — see packages/content-schema. */
+export const REPO_IDS: readonly RepoId[] = REPOS.map((r) => r.id)
+
+export function getRepo(id: RepoId): (typeof REPOS)[number] {
+  const found = REPOS.find((r) => r.id === id)
+  if (!found) throw new Error(`[@rxova/brand] unknown repo id: ${id}`)
+  return found
+}
+
 /** Absolute URL to a project's docs root. */
 export function docsUrl(id: ProjectId): string {
   return `${RXOVA_ORIGIN}${getProject(id).mount}`

package/src/starlight.ts

@@ -73,6 +73,10 @@ export function sharedStarlightConfig({
       // Starlight's default footer (pagination, edit link, last updated) plus
       // the shared four-column site footer beneath it.
       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.
+      ThemeSelect: '@rxova/brand/components/ThemeSelect.astro',
       ...components,
     },