@rxova/astro-ui 0.0.0 → 0.2.0

package/src/env.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="astro/client" />
+
+// Not referencing `@astrojs/starlight/locals`: it imports `virtual:starlight/*` modules that
+// only exist in an Astro build, so plain `tsc` fails. Route data is narrowed structurally instead.
+
+// Mirrors Starlight's `global.d.ts`: set by its `ThemeProvider.astro`, called by ThemeSelect.astro.
+// Re-check against Starlight's `global.d.ts` on a major bump.
+declare global {
+  interface StarlightThemeProvider {
+    updatePickers(theme?: string): void
+  }
+  var StarlightThemeProvider: StarlightThemeProvider
+}
+
+export {}

package/src/lib/entries.ts

@@ -0,0 +1,72 @@
+/** Ordering, bylines, dates, facets and excerpts shared by /blog and /updates. Pure, so tests need no Astro. */
+
+/** Newest first, ties broken by `id` so the order never depends on filesystem order. Sorts a copy. */
+export function newestFirst<T extends { id: string }>(entries: readonly T[], date: (e: T) => Date) {
+  return [...entries].sort(
+    (a, b) => date(b).valueOf() - date(a).valueOf() || a.id.localeCompare(b.id),
+  )
+}
+
+/** "Rxova" · "Rxova and Ada" · "Rxova, Ada, and Grace" */
+export function byline(names: readonly string[]): string {
+  if (names.length <= 1) return names[0] ?? ''
+  if (names.length === 2) return `${names[0]} and ${names[1]}`
+  return `${names.slice(0, -1).join(', ')}, and ${names[names.length - 1]}`
+}
+
+/** The distinct values some entry carries, so a filter row never offers a chip that matches nothing. */
+export function usedValues<T>(entries: readonly T[], pick: (e: T) => readonly string[]): string[] {
+  return [...new Set(entries.flatMap((e) => pick(e)))]
+}
+
+const DATE = new Intl.DateTimeFormat('en', {
+  year: 'numeric',
+  month: 'long',
+  day: 'numeric',
+  timeZone: 'UTC',
+})
+
+/** "July 27, 2026". UTC, so the rendered date matches the filename it came from. */
+export function formatDate(d: Date): string {
+  return DATE.format(d)
+}
+
+/** `2026-07-27`, for `<time datetime>`. */
+export function isoDate(d: Date): string {
+  return d.toISOString().slice(0, 10)
+}
+
+/** The next "show more" limit: one `step` further, clamped to `total` so the control never outlives the list. */
+export function nextLimit(current: number, step: number, total: number): number {
+  return Math.min(current + Math.max(step, 0), total)
+}
+
+/**
+ * The opening prose of a markdown body, up to `max` characters, cut on a word boundary.
+ * Skips headings, images, quotes, code, tables and lists; reports whether anything was cut.
+ */
+export function excerpt(body: string, max: number): { text: string; truncated: boolean } {
+  const prose = body
+    .split(/\n\s*\n/)
+    .map((p) => p.trim())
+    .filter((p) => p.length > 0 && !/^(#|!\[|>|```|\||-{3,}|\d+\.|[-*+]\s)/.test(p))
+    .join(' ')
+
+  const plain = prose
+    .replace(/!\[[^[\]]*\]\([^()]*\)/g, '')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/(\*\*|__)(.*?)\1/g, '$2')
+    .replace(/(\*|_)(.*?)\1/g, '$2')
+    .replace(/\s+/g, ' ')
+    .trim()
+
+  if (plain.length <= max) return { text: plain, truncated: false }
+
+  const cut = plain.slice(0, max)
+  const lastSpace = cut.lastIndexOf(' ')
+  return {
+    text: (lastSpace > 0 ? cut.slice(0, lastSpace) : cut).replace(/[,;:.—–-]+$/, ''),
+    truncated: true,
+  }
+}

package/src/lib/icons.ts

@@ -0,0 +1,15 @@
+/** Lucide icons as inline markup, read from `lucide-static` at build time so nothing ships to the client. */
+
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+/** What sits inside a Lucide icon's root `<svg>`, so the caller's own element owns size and accessibility. */
+export function lucideGlyph(name: string): string {
+  const svg = readFileSync(require.resolve(`lucide-static/icons/${name}.svg`), 'utf8')
+  return svg
+    .replace(/^[\s\S]*?<svg[^>]*>/, '')
+    .replace(/<\/svg>[\s\S]*$/, '')
+    .trim()
+}

package/src/scripts/show-more.ts

@@ -0,0 +1,46 @@
+import { nextLimit } from '../lib/entries.ts'
+
+/** Shows `list`'s children `data-reveal-step` at a time, driven by a ShowMore's `controls`. */
+export function batchList(list: HTMLElement, controls: HTMLElement): void {
+  const items = Array.from(list.children) as HTMLElement[]
+  const moreBtn = controls.querySelector<HTMLElement>('[data-reveal-more]')
+  const allBtn = controls.querySelector<HTMLElement>('[data-reveal-all]')
+  const progress = controls.querySelector<HTMLElement>('[data-reveal-progress]')
+
+  const step = Number(list.dataset.revealStep) || items.length
+  let limit = step
+
+  function apply() {
+    items.forEach((el, i) => {
+      el.hidden = i >= limit
+    })
+    controls.hidden = limit >= items.length
+    if (progress) {
+      progress.textContent = limit < items.length ? `Showing ${limit} of ${items.length}` : ''
+    }
+  }
+
+  /** Raise the limit, then focus the first item that appeared. */
+  function reveal(next: number) {
+    const first = items[limit]
+    limit = next
+    apply()
+    if (!first) return
+    // The new batch starts where the button was, so the viewport is already right.
+    first.tabIndex = -1
+    first.focus({ preventScroll: true })
+  }
+
+  moreBtn?.addEventListener('click', () => reveal(nextLimit(limit, step, items.length)))
+  // Also the way out of find-in-page missing what is batched away.
+  allBtn?.addEventListener('click', () => reveal(items.length))
+
+  apply()
+}
+
+/** Batches the page's `[data-reveal-list]` behind its `[data-reveal-controls]`, when it has both. */
+export function enhanceShowMore(root: ParentNode = document): void {
+  const list = root.querySelector<HTMLElement>('[data-reveal-list]')
+  const controls = root.querySelector<HTMLElement>('[data-reveal-controls]')
+  if (list && controls) batchList(list, controls)
+}

package/src/starlight/Footer.astro

@@ -0,0 +1,16 @@
+---
+/**
+ * Starlight `Footer` override: keeps Starlight's pagination, edit link and last-updated, and adds
+ * the shared rxova site footer beneath them.
+ */
+import Default from '@astrojs/starlight/components/Footer.astro'
+import SiteFooter from '../components/SiteFooter.astro'
+import { projectFromBase } from '@rxova/brand'
+
+const project = projectFromBase(import.meta.env.BASE_URL)
+---
+
+<Default>
+  <slot />
+</Default>
+<SiteFooter project={project} />

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/landing.css

@@ -0,0 +1,55 @@
+/**
+ * The rules a Starlight splash landing needs around the landing components. Load it through
+ * `customCss`; every rule is gated on `[data-has-hero]`, which Starlight sets only on a page with a hero.
+ */
+
+/* Starlight's 45rem prose measure is wrong for a stat band or a card grid; take the brand's wide bound. */
+html[data-has-hero] .sl-container {
+  max-width: var(--rx-max-wide);
+}
+
+/* The sections carry their own rhythm, so Starlight's 1.5rem between top-level children compounds. */
+html[data-has-hero] .sl-container > * + * {
+  margin-top: 0;
+}
+
+/* Starlight's clamp tops out at 10rem of padding, which pushes the first call to action below the fold. */
+html[data-has-hero] .hero {
+  padding-block: clamp(2.5rem, 1rem + 6vmin, 5rem);
+}
+
+/* Without a hero image the second grid column is dead space holding the headline off to one side. */
+html[data-has-hero] .hero:not(:has(img)) {
+  grid-template-columns: 1fr;
+}
+
+/* Starlight caps every hero child at 50ch: right for the tagline, far too wide for a display headline. */
+html[data-has-hero] .hero h1 {
+  max-width: 22ch;
+  text-wrap: balance;
+}
+
+html[data-has-hero] .hero .tagline {
+  max-width: 56ch;
+  text-wrap: pretty;
+}
+
+/* The first section's 7rem margin is separating from the hero, which already ends in its own padding. */
+html[data-has-hero] .sl-markdown-content > :first-child {
+  margin-top: 2rem;
+}
+
+/* A pill above the headline, for a version: the hero title is frontmatter HTML, so it is styled by class. */
+html[data-has-hero] .hero .rx-tag {
+  display: inline-block;
+  margin-bottom: 0.9rem;
+  padding: 0.28rem 0.7rem;
+  color: var(--rx-primary);
+  background: var(--rx-tag-bg);
+  border-radius: var(--rx-radius-pill);
+  font-family: var(--rx-font-mono);
+  font-size: 0.78rem;
+  font-weight: 500;
+  letter-spacing: 0;
+  line-height: 1.4;
+}