npm - @rxova/brand - Versions diffs - 0.2.0 → 0.4.0 - Mend

@rxova/brand 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/package.json +6 -3
package/src/components/ThemeScript.astro +55 -0
package/src/components/ThemeToggle.astro +145 -0
package/src/index.ts +4 -0
package/src/sites.test.ts +126 -0
package/src/sites.ts +40 -0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@rxova/brand",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Design tokens, Starlight theme and shared site chrome for rxova.org",
   "keywords": [
@@ -57,11 +57,13 @@
     "@astrojs/starlight": "^0.41.4",
     "@resvg/resvg-js": "^2.6.2",
     "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.10",
     "astro": "^7.1.3",
     "publint": "^0.3.21",
     "satori": "^0.29.0",
     "tsx": "^4.23.1",
-    "typescript": "6.0.3"
+    "typescript": "6.0.3",
+    "vitest": "^4.1.10"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -69,6 +71,7 @@
     "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"
+    "check:og": "node --import tsx scripts/generate-og.ts --check",
+    "test": "vitest run --coverage"
   }
 }

package/src/components/ThemeScript.astro ADDED Viewed

@@ -0,0 +1,55 @@
+---
+/**
+ * The pre-paint theme script. Goes in `<head>`, before anything renders.
+ *
+ * This was copy-pasted between the landing page and the legal layout, and it had
+ * already drifted: the copy in Legal.astro read `theme`, a key nothing on this
+ * origin ever writes, so /privacy and /terms silently ignored the visitor's choice
+ * and always rendered the prefers-color-scheme default. Adding /blog and
+ * /changelog would have made four copies of a script whose whole job is to be
+ * identical everywhere, so it lives here now.
+ *
+ * The key is Starlight's, not ours. The docs sites at /packages/* are Starlight
+ * and write their choice to `starlight-theme`; same origin plus the same key means
+ * picking dark here keeps you in dark all the way into a project's docs, and back.
+ *
+ * No saved choice => no attribute => the CSS prefers-color-scheme default wins.
+ *
+ * Lives here because it is the one thing every rxova surface must do identically:
+ * the docs sites, the umbrella landing and /blog and /updates all read the same
+ * localStorage key, so a visitor keeps their choice walking between them. It was
+ * copied into three repos and had already drifted once — one copy read `theme`,
+ * which nothing on this origin writes, so those pages silently ignored the choice.
+ *
+ * Not the same thing as ThemeSelect.astro: that is the Starlight override for the
+ * docs sites' own toggle. This pair is for the surfaces that are not Starlight.
+ */
+---
+<script is:inline>
+  ;(function () {
+    function stored() {
+      try {
+        const t = localStorage.getItem('starlight-theme')
+        return t === 'light' || t === 'dark' ? t : null
+      } catch {
+        /* localStorage may be unavailable */
+        return null
+      }
+    }
+    function sync() {
+      const t = stored()
+      if (t) document.documentElement.setAttribute('data-theme', t)
+      else document.documentElement.removeAttribute('data-theme')
+    }
+    sync()
+    // Going to a docs site and pressing Back restores this document from the
+    // bfcache: the DOM is reused as it was and this script does not run again, so
+    // the page would keep the theme it had when you left — even though the docs
+    // site may have written a new one to `starlight-theme` in the meantime.
+    // `pageshow` is the only notification of that restore.
+    window.addEventListener('pageshow', function (e) {
+      if (e.persisted) sync()
+    })
+  })()
+</script>

package/src/components/ThemeToggle.astro ADDED Viewed

@@ -0,0 +1,145 @@
+---
+/**
+ * The fixed light/dark toggle in the top-right corner.
+ *
+ * Button, styles and behaviour in one place. It was inline on the landing page;
+ * /blog and /changelog want the same control, and a second copy of the icon
+ * swapping and the bfcache handling is exactly the duplication that let the
+ * pre-paint script drift (see ThemeScript.astro).
+ *
+ * Pairs with `<ThemeScript />` in `<head>`, which is what actually avoids the
+ * flash — this only handles clicks and keeps the icon honest.
+ *
+ * For the surfaces that are not Starlight — the umbrella landing, /blog, /updates.
+ * The docs sites get their toggle from Starlight, themed by ThemeSelect.astro.
+ *
+ * Pairs with ThemeScript.astro in <head>, which is what actually avoids the flash;
+ * this only handles clicks and keeps the icon honest.
+ */
+---
+<button id="theme-toggle" class="theme-toggle" type="button" aria-label="Toggle theme">
+  <span class="icon" aria-hidden="true"
+    ><svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      width="24"
+      height="24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"><path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"></path></svg
+    ></span
+  >
+</button>
+<style>
+  .theme-toggle {
+    position: fixed;
+    top: 1rem;
+    right: 1rem;
+    width: 2.25rem;
+    height: 2.25rem;
+    display: grid;
+    place-items: center;
+    border: 1px solid var(--rule);
+    border-radius: 8px;
+    background: var(--card);
+    color: var(--fg);
+    cursor: pointer;
+    z-index: 3;
+    transition:
+      border-color 0.15s ease,
+      background-color 0.2s ease;
+  }
+  .theme-toggle .icon {
+    display: grid;
+    place-items: center;
+  }
+  .theme-toggle svg {
+    width: 1.15rem;
+    height: 1.15rem;
+    display: block;
+  }
+  .theme-toggle:hover {
+    border-color: var(--faint);
+  }
+  .theme-toggle:focus-visible {
+    outline: 2px solid var(--accent);
+    outline-offset: 2px;
+  }
+</style>
+<script is:inline>
+  ;(function () {
+    const root = document.documentElement
+    const btn = document.getElementById('theme-toggle')
+    const glyph = btn.querySelector('.icon')
+    const media = window.matchMedia('(prefers-color-scheme: dark)')
+    // Lucide icons (ISC licensed).
+    const ICON_MOON =
+      '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"/></svg>'
+    const ICON_SUN =
+      '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/></svg>'
+    function current() {
+      return root.getAttribute('data-theme') || (media.matches ? 'dark' : 'light')
+    }
+    function stored() {
+      try {
+        const t = localStorage.getItem('starlight-theme')
+        return t === 'light' || t === 'dark' ? t : null
+      } catch {
+        /* localStorage may be unavailable */
+        return null
+      }
+    }
+    // Re-read the saved choice and reflect it in the DOM. Same job as the
+    // pre-paint script in <head>, minus the write.
+    function sync() {
+      const t = stored()
+      if (t) root.setAttribute('data-theme', t)
+      else root.removeAttribute('data-theme')
+      render()
+    }
+    function render() {
+      const dark = current() === 'dark'
+      // Show the icon of the theme you'd switch TO.
+      glyph.innerHTML = dark ? ICON_SUN : ICON_MOON
+      btn.setAttribute('aria-label', dark ? 'Switch to light theme' : 'Switch to dark theme')
+    }
+    function apply(t) {
+      root.setAttribute('data-theme', t)
+      try {
+        // Starlight's key — see the pre-paint script in <head>.
+        localStorage.setItem('starlight-theme', t)
+      } catch {
+        /* localStorage may be unavailable */
+      }
+      render()
+    }
+    btn.addEventListener('click', function () {
+      apply(current() === 'dark' ? 'light' : 'dark')
+    })
+    // Track the OS preference while the user hasn't overridden it.
+    media.addEventListener('change', function () {
+      if (!root.getAttribute('data-theme')) render()
+    })
+    // Going to a docs site and pressing Back restores this document from the
+    // bfcache: the DOM is reused as it was, so neither the pre-paint script nor
+    // this one runs again, and the page keeps the theme it had when you left —
+    // even though the docs site wrote a new one to `starlight-theme` in the
+    // meantime. `pageshow` is the only notification of that restore.
+    window.addEventListener('pageshow', function (e) {
+      if (e.persisted) sync()
+    })
+    render()
+  })()
+</script>

package/src/index.ts CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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/schemas. */
+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}`