@rxova/astro-ui 0.0.0 → 0.1.0

package/src/starlight/SiteTitle.astro

@@ -0,0 +1,34 @@
+---
+/**
+ * Starlight `SiteTitle` override: the mark links (absolutely) to rxova.org, the wordmark to this
+ * project's docs root via `siteTitleHref`. The image comes from @rxova/brand.
+ */
+import mark from '@rxova/brand/assets/rxova-logo-256.png'
+import { RXOVA_ORIGIN } from '@rxova/brand'
+
+// Narrowed structurally, not via an `App.Locals` augmentation, which would collide with
+// Starlight's own in the consumer site's build.
+const { siteTitle, siteTitleHref } = (
+  Astro.locals as unknown as {
+    starlightRoute: { siteTitle: string; siteTitleHref: string }
+  }
+).starlightRoute
+---
+
+<div class="rx-site-title">
+  <a href={RXOVA_ORIGIN} class="rx-site-title__mark" aria-label="Rxova home">
+    <img src={mark.src} alt="" width="28" height="28" />
+  </a>
+  <span class="rx-site-title__sep" aria-hidden="true"></span>
+  <a href={siteTitleHref} class="rx-site-title__project" translate="no">
+    {siteTitle}
+  </a>
+</div>
+
+<style>
+  /* Visual styling lives in ../styles/starlight.css so the Astro landing can
+     reuse the same classnames without importing this component. */
+  .rx-site-title__mark {
+    display: inline-flex;
+  }
+</style>

package/src/starlight/SocialIcons.astro

@@ -0,0 +1,18 @@
+---
+/**
+ * Starlight `SocialIcons` override: the stock icons plus the project switcher, which lands just
+ * before search and the theme toggle.
+ */
+import Default from '@astrojs/starlight/components/SocialIcons.astro'
+import ProjectSwitcher from '../components/ProjectSwitcher.astro'
+import { projectFromBase } from '@rxova/brand'
+
+// Overrides receive no props, so the current project is inferred from the base
+// path the aggregator mounts this site at.
+const current = projectFromBase(import.meta.env.BASE_URL)
+---
+
+<ProjectSwitcher current={current} />
+<Default>
+  <slot />
+</Default>

package/src/starlight/ThemeSelect.astro

@@ -0,0 +1,42 @@
+---
+/**
+ * Wraps Starlight's theme picker and resyncs the theme on a bfcache restore, where Starlight's
+ * parse-time theme code does not run again and the page would keep a stale `data-theme`.
+ */
+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 (`persisted: false`)
+  // is left to Starlight.
+  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/starlight/index.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared Starlight configuration for the rxova docs sites; each site adds only its sidebar and
+ * extras. Imported under Node (no CSS or components) and typed structurally, not as Starlight's.
+ */
+
+import { RXOVA_ORIGIN, getProject, type ProjectId } from '@rxova/brand'
+
+export interface SharedStarlightOptions {
+  /** Which project's docs this site is. */
+  project: ProjectId
+  /** Starlight sidebar config — the one thing every site defines itself. */
+  sidebar: unknown[]
+  /** Extra stylesheets, appended after the shared ones so they win. */
+  customCss?: string[]
+  /** Extra Starlight component overrides, merged over the shared ones. */
+  components?: Record<string, string>
+  /** Path under the repo root that holds the docs site, for the edit link. */
+  editLinkBase?: string
+  /** Build body-only docs for rxova-website's shell: Starlight's page UI stays, the footer goes. */
+  pageComponent?: boolean
+}
+
+export function sharedStarlightConfig({
+  project,
+  sidebar,
+  customCss = [],
+  components = {},
+  editLinkBase = 'apps/docs',
+  pageComponent = false,
+}: SharedStarlightOptions) {
+  const self = getProject(project)
+
+  return {
+    title: self.label,
+    description: self.tagline,
+    // One origin, one tab icon. Each site must have this file in `public/`: Starlight resolves
+    // `favicon` against the site's own static directory.
+    favicon: '/favicon.svg',
+
+    // No `logo` on purpose: the SiteTitle override renders the mark from @rxova/brand's assets.
+
+    social: [
+      { icon: 'github' as const, label: 'GitHub', href: self.repo },
+      { icon: 'npm' as const, label: 'npm', href: self.npm },
+    ],
+
+    editLink: {
+      baseUrl: `${self.repo}/edit/main/${editLinkBase}/`,
+    },
+
+    // Order matters: fonts, then tokens+mapping, then per-site overrides.
+    customCss: ['@rxova/brand/fonts.css', '@rxova/astro-ui/styles/starlight.css', ...customCss],
+
+    components: {
+      // The rxova mark (linking back to the umbrella site) plus the project wordmark.
+      SiteTitle: '@rxova/astro-ui/starlight/SiteTitle.astro',
+      // Appends the cross-project switcher to the social icons. Without it the
+      // three docs sites are three islands under one domain.
+      SocialIcons: '@rxova/astro-ui/starlight/SocialIcons.astro',
+      // Starlight's default footer (pagination, edit link, last updated) plus
+      // the shared four-column site footer beneath it.
+      ...(!pageComponent ? { Footer: '@rxova/astro-ui/starlight/Footer.astro' } : {}),
+      // Starlight's own picker, plus a resync when a page is restored from the bfcache.
+      ThemeSelect: '@rxova/astro-ui/starlight/ThemeSelect.astro',
+      ...components,
+    },
+
+    head: [
+      {
+        tag: 'meta' as const,
+        attrs: { property: 'og:image', content: `${RXOVA_ORIGIN}/og/${project}.png` },
+      },
+      {
+        tag: 'meta' as const,
+        attrs: { name: 'twitter:card', content: 'summary_large_image' },
+      },
+      // SoftwareSourceCode JSON-LD built from PROJECTS, on every docs page: Starlight has no
+      // "site index only" hook.
+      {
+        tag: 'script' as const,
+        attrs: { type: 'application/ld+json' },
+        content: JSON.stringify({
+          '@context': 'https://schema.org',
+          '@type': 'SoftwareSourceCode',
+          name: self.label,
+          description: self.tagline,
+          url: `${RXOVA_ORIGIN}${self.mount}`,
+          codeRepository: self.repo,
+          programmingLanguage: 'TypeScript',
+          runtimePlatform: 'Node.js',
+          license: 'https://opensource.org/licenses/MIT',
+          author: { '@type': 'Person', name: 'Jonatan Kruszewski' },
+        }).replace(/</g, '\\u003c'),
+      },
+    ],
+
+    // Pagefind ships with Starlight and replaces the third-party search plugin
+    // journey was carrying.
+    pagefind: true,
+
+    sidebar,
+  }
+}

package/src/styles/chrome.css

@@ -0,0 +1,8 @@
+/**
+ * What the shared header and footer need, and nothing document-level: the tokens and the footer.
+ * No reset, which is document.css: unlayered, it would flatten a Starlight page this is composed into.
+ */
+
+@import '@rxova/brand/tokens.css';
+/* The footer every surface renders, Starlight or not. */
+@import './footer.css';

package/src/styles/document.css

@@ -0,0 +1,72 @@
+/**
+ * For sites that own their document (the landing, /blog, /updates): chrome.css plus a reset and base
+ * element styles. Never inside a Starlight document, where the unlayered reset would flatten the page.
+ */
+
+@import './chrome.css';
+
+/* --- Reset ---------------------------------------------------------------- */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  -webkit-text-size-adjust: 100%;
+  scroll-behavior: smooth;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html {
+    scroll-behavior: auto;
+  }
+}
+
+body {
+  position: relative;
+  background: var(--rx-bg);
+  color: var(--rx-fg);
+  font-family: var(--rx-font-sans);
+  font-size: 1.0625rem;
+  line-height: 1.65;
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+  transition:
+    background-color 0.2s ease,
+    color 0.2s ease;
+
+  /* At least a screen tall, with `main` taking the slack, so a short page keeps its footer at the
+     bottom. Flex rather than grid because the number of children varies. */
+  display: flex;
+  flex-direction: column;
+  min-height: 100dvh;
+}
+
+/* Flex items with `margin: 0 auto` shrink to their content; full width restores block behaviour.
+   `:where()` keeps both rules at zero specificity. */
+:where(body > *) {
+  width: 100%;
+}
+
+:where(body > main) {
+  flex-grow: 1;
+}
+
+a {
+  color: inherit;
+}
+
+a:focus-visible {
+  outline: 2px solid var(--rx-fg);
+  outline-offset: 3px;
+  border-radius: 2px;
+}
+
+img {
+  max-width: 100%;
+  height: auto;
+}

package/src/styles/footer.css

@@ -0,0 +1,124 @@
+/**
+ * Styles for `components/SiteFooter.astro`, shared by Starlight and plain Astro surfaces.
+ * Imported by `starlight.css` and `chrome.css`; uses `--rx-*` tokens only.
+ */
+
+@import '@rxova/brand/tokens.css';
+
+.rx-footer {
+  margin-top: 4rem;
+  padding: 3rem 0 2rem;
+  border-top: 1px solid var(--rx-rule);
+  color: var(--rx-muted);
+  font-size: 0.875rem;
+}
+
+/* Brand block and link columns side by side where the container (not viewport) has room.
+   `min(100%, 20rem)` lets the track floor collapse so a narrow footer never overflows the page. */
+.rx-footer__top {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 20rem), 1fr));
+  gap: 2.5rem 3rem;
+}
+
+.rx-footer__brand {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  align-items: flex-start;
+}
+
+.rx-footer__mark {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.55rem;
+  color: var(--rx-fg);
+  font-size: 1rem;
+  font-weight: 640;
+  letter-spacing: -0.01em;
+  text-decoration: none;
+}
+
+.rx-footer__mark img {
+  display: block;
+  border-radius: 6px;
+}
+
+.rx-footer__blurb {
+  margin: 0;
+  max-width: 30ch;
+  color: var(--rx-faint);
+  line-height: 1.6;
+}
+
+/* 8rem: the widest track that still fits two columns on a 360px phone. */
+.rx-footer__columns {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 8rem), 1fr));
+  gap: 2rem 1.5rem;
+}
+
+.rx-footer__title {
+  margin-bottom: 0.75rem;
+  color: var(--rx-fg);
+  font-size: 0.75rem;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.rx-footer__list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.45rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.rx-footer__list a {
+  color: var(--rx-muted);
+  text-decoration: none;
+}
+
+.rx-footer__list a:hover {
+  color: var(--rx-fg);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+/* The bottom bar: copyright on the left, the legal links on the right, and one
+   column on a phone. */
+.rx-footer__legal {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  flex-wrap: wrap;
+  gap: 0.5rem 1.25rem;
+  margin-top: 2.5rem;
+  padding-top: 1.25rem;
+  border-top: 1px solid var(--rx-rule);
+  color: var(--rx-faint);
+  font-size: 0.8125rem;
+}
+
+.rx-footer__legal p {
+  margin: 0;
+}
+
+.rx-footer__legal-links {
+  display: flex;
+  align-items: center;
+  gap: 1.25rem;
+}
+
+.rx-footer__legal a {
+  color: var(--rx-faint);
+  text-decoration: none;
+}
+
+.rx-footer__legal a:hover {
+  color: var(--rx-fg);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}

package/src/styles/starlight.css

@@ -0,0 +1,162 @@
+/**
+ * Maps rxova tokens onto Starlight's theme variables; load via `customCss` so it wins without
+ * !important. One block covers both modes because every --rx-* neutral already flips.
+ */
+
+@import '@rxova/brand/tokens.css';
+@import './footer.css';
+
+:root {
+  /* Accent. */
+  --sl-color-accent: var(--rx-primary);
+  --sl-color-accent-low: color-mix(in srgb, var(--rx-primary) 20%, var(--rx-bg));
+  --sl-color-accent-high: var(--rx-primary-lightest);
+  --sl-color-text-accent: var(--rx-primary);
+
+  /* Neutral ladder. "white" and "black" are Starlight's names for the two
+     contrast extremes, not literal colours — they invert with the theme. */
+  --sl-color-white: var(--rx-fg);
+  --sl-color-gray-1: var(--rx-fg);
+  --sl-color-gray-2: var(--rx-muted);
+  --sl-color-gray-3: var(--rx-faint);
+  --sl-color-gray-4: var(--rx-rule-strong);
+  --sl-color-gray-5: var(--rx-rule);
+  --sl-color-gray-6: var(--rx-tag-bg);
+  --sl-color-gray-7: var(--rx-card);
+  --sl-color-black: var(--rx-bg);
+
+  /* Surfaces. Nav and sidebar sit flush with the page — the hairline does the
+     separating, not a fill change. */
+  --sl-color-bg: var(--rx-bg);
+  --sl-color-bg-nav: var(--rx-bg);
+  --sl-color-bg-sidebar: var(--rx-bg);
+  --sl-color-bg-inline-code: var(--rx-tag-bg);
+  --sl-color-bg-badge: var(--rx-tag-bg);
+
+  --sl-color-hairline: var(--rx-rule);
+  --sl-color-hairline-light: var(--rx-rule);
+  --sl-color-hairline-shade: var(--rx-rule-strong);
+  --sl-color-backdrop-overlay: color-mix(in srgb, var(--rx-bg) 80%, transparent);
+
+  /* Type. */
+  --sl-font: var(--rx-font-sans);
+  --sl-font-mono: var(--rx-font-mono);
+
+  --sl-shadow-sm: 0 1px 2px rgb(0 0 0 / 0.06);
+  --sl-shadow-md: 0 4px 12px -4px rgb(0 0 0 / 0.12);
+  --sl-shadow-lg: var(--rx-shadow-soft);
+}
+
+/* Starlight ships a slightly cooler focus ring; align it with the accent. */
+:root {
+  --sl-color-focus: var(--rx-primary);
+}
+
+/* --- Shared chrome ------------------------------------------------------- */
+
+/* The gradient, the brand's only chroma, gets exactly two placements: the header hairline and
+   the switcher's current-project dot. */
+.site-title::after {
+  content: none;
+}
+
+header.header {
+  border-bottom: 1px solid var(--sl-color-hairline);
+  background: var(--sl-color-bg-nav);
+}
+
+/* In a schema-2 page bundle rxova-website renders the umbrella header outside `.page`; keep
+   Starlight's sticky docs bar below it. */
+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);
+}
+
+/* Starlight 0.42 dropped the <starlight-menu-button> wrapper for a bare
+   button.sl-menu-button; the peer range still covers the older markup. */
+html[data-rxova-shell] starlight-menu-button button,
+html[data-rxova-shell] .sl-menu-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;
+  align-items: center;
+  gap: 0.625rem;
+  color: var(--rx-fg);
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  text-decoration: none;
+}
+
+.rx-site-title a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.rx-site-title a:hover {
+  color: var(--rx-fg);
+}
+
+.rx-site-title img {
+  width: 28px;
+  height: 28px;
+  border-radius: var(--rx-radius-sm);
+}
+
+.rx-site-title__sep {
+  width: 1px;
+  height: 1.1rem;
+  background: var(--rx-rule-strong);
+}
+
+.rx-site-title__project {
+  color: var(--rx-muted);
+  font-weight: 500;
+}
+
+/* Project switcher. */
+.rx-switcher {
+  position: relative;
+}
+
+.rx-switcher__current::before {
+  content: '';
+  display: inline-block;
+  width: 0.5rem;
+  height: 0.5rem;
+  margin-inline-end: 0.5rem;
+  border-radius: var(--rx-radius-pill);
+  background: var(--rx-gradient);
+}
+
+/* --- Footer -------------------------------------------------------------- */
+
+/* Footer styles live in footer.css (imported above) because /blog and /updates need them too. */