@rxova/astro-ui 0.0.0 → 0.1.0

package/src/components/SiteFooter.astro

@@ -0,0 +1,149 @@
+---
+/**
+ * The rxova footer on every surface: brand block, link columns, then copyright and legal links.
+ * Styles live in `../styles/footer.css`; all cross-project hrefs are absolute.
+ */
+import { PROJECTS, RXOVA_ORIGIN, getProject, siteUrl, type ProjectId } from '@rxova/brand'
+
+/** A standalone surface of rxova.org, for the "Site" column. */
+export interface SiteLink {
+  label: string
+  /** Absolute — see sites.ts in @rxova/brand. */
+  href: string
+}
+
+interface Props {
+  /** Current project, if this is a docs site. Omitted on the landing. */
+  project?: ProjectId
+  /** Optional per-site "Docs" column. */
+  docs?: { label: string; href: string }[]
+  /**
+   * Standalone surfaces listed under "Site", below Home. Only the umbrella repo knows which are
+   * deployed; the default (for docs sites) includes /about, a page of the landing build.
+   */
+  site?: readonly SiteLink[]
+  /**
+   * Projects whose docs are actually mounted; only the umbrella repo knows which are deployed.
+   * Defaults to every project, which is right for a docs site.
+   */
+  projects?: readonly SiteLink[]
+}
+
+const { project, docs, site, projects } = Astro.props
+const self = project ? getProject(project) : undefined
+const year = new Date().getFullYear()
+
+const projectLinks: readonly SiteLink[] =
+  projects ?? PROJECTS.map((p) => ({ label: p.label, href: `${RXOVA_ORIGIN}${p.mount}` }))
+
+const surfaces: readonly SiteLink[] = site ?? [
+  { label: 'Blog', href: siteUrl('/blog') },
+  { label: 'Updates', href: siteUrl('/updates') },
+  { label: 'About', href: siteUrl('/about') },
+]
+---
+
+<footer class="rx-footer">
+  <div class="rx-footer__top">
+    <div class="rx-footer__brand">
+      <a class="rx-footer__mark" href={RXOVA_ORIGIN}>
+        <img src={siteUrl('/rxova-logo-256.png')} alt="" width="28" height="28" loading="lazy" />
+        <span>Rxova</span>
+      </a>
+      {/* Not "React libraries": most ship a framework-agnostic core; some are extensions/CLIs. */}
+      <p class="rx-footer__blurb">
+        Small TypeScript libraries and developer tools, documented in one place. MIT licensed, built
+        in the open.
+      </p>
+    </div>
+
+    <div class="rx-footer__columns">
+      {docs && docs.length > 0 && (
+        <div>
+          <h2 class="rx-footer__title">Docs</h2>
+          <ul class="rx-footer__list">
+            {docs.map((link) => (
+              <li>
+                <a href={link.href}>{link.label}</a>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {projectLinks.length > 0 && (
+        <div>
+          <h2 class="rx-footer__title">Projects</h2>
+          <ul class="rx-footer__list">
+            {projectLinks.map((link) => (
+              <li>
+                <a href={link.href}>{link.label}</a>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {self && (
+        <div>
+          <h2 class="rx-footer__title">Community</h2>
+          <ul class="rx-footer__list">
+            <li>
+              <a href={self.repo}>GitHub</a>
+            </li>
+            <li>
+              <a href={`${self.repo}/issues`}>Issues</a>
+            </li>
+            <li>
+              <a href={`${self.repo}/discussions`}>Discussions</a>
+            </li>
+            <li>
+              <a href={self.npm}>npm</a>
+            </li>
+            <li>
+              <a href={`${self.repo}/blob/main/CONTRIBUTING.md`}>Contributing</a>
+            </li>
+          </ul>
+        </div>
+      )}
+
+      {/* Blog and Updates on every surface, so readers landing on a docs page find the rest. */}
+      <div>
+        <h2 class="rx-footer__title">Site</h2>
+        <ul class="rx-footer__list">
+          <li>
+            <a href={RXOVA_ORIGIN}>Home</a>
+          </li>
+          {surfaces.map((s) => (
+            <li>
+              <a href={s.href}>{s.label}</a>
+            </li>
+          ))}
+        </ul>
+      </div>
+
+      <div>
+        <h2 class="rx-footer__title">Connect</h2>
+        <ul class="rx-footer__list">
+          <li>
+            <a href="https://github.com/rxova">GitHub</a>
+          </li>
+          <li>
+            <a href="https://www.npmjs.com/org/rxova">npm</a>
+          </li>
+          <li>
+            <a href="mailto:rxova@proton.me">rxova@proton.me</a>
+          </li>
+        </ul>
+      </div>
+    </div>
+  </div>
+
+  <div class="rx-footer__legal">
+    <p>© {year} Rxova · MIT licensed</p>
+    <div class="rx-footer__legal-links">
+      <a href={siteUrl('/privacy')}>Privacy</a>
+      <a href={siteUrl('/terms')}>Terms</a>
+    </div>
+  </div>
+</footer>

package/src/components/SiteShell.astro

@@ -0,0 +1,155 @@
+---
+/**
+ * Artifact document for rxova.org's non-Starlight pages: metadata and assets only, no header,
+ * footer, analytics or theme bootstrap. rxova-website supplies the public shell at deploy time.
+ */
+import '@rxova/brand/fonts.css'
+import '../styles/document.css'
+
+import { canonicalUrl, siteUrl } from '@rxova/brand'
+
+interface Props {
+  title: string
+  description: string
+  /** Canonical path, e.g. `/blog/why-rxova-has-a-blog`. Normalised below. */
+  path: string
+  ogType?: 'website' | 'article'
+  /** Absolute URL of the social card, chosen by the caller; defaults to the umbrella card. */
+  image?: string
+  /** Advertises an RSS feed for this surface, as `rel="alternate"`. */
+  feed?: { href: string; title: string }
+  /** JSON-LD for this page, emitted verbatim as `application/ld+json`. */
+  jsonLd?: unknown
+}
+
+const { title, description, path, ogType = 'website', image, feed, jsonLd } = Astro.props
+
+// Normalised here so no caller can declare a canonical URL without the trailing slash (a 301).
+const canonical = canonicalUrl(path)
+
+const ogImage = image ?? siteUrl('/og/rxova.png')
+
+/** Serialise JSON-LD for an inline `<script>`; `<` is escaped so a `</script>` cannot close it. */
+const serialiseJsonLd = (value: unknown): string => JSON.stringify(value).replace(/</g, '\\u003c')
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="canonical" href={canonical} />
+    <title>{title}</title>
+    <meta name="description" content={description} />
+    <meta property="og:title" content={title} />
+    <meta property="og:description" content={description} />
+    <meta property="og:type" content={ogType} />
+    <meta property="og:url" content={canonical} />
+    <meta property="og:image" content={ogImage} />
+    <meta name="twitter:card" content="summary_large_image" />
+    {feed && (
+      <link rel="alternate" type="application/rss+xml" title={feed.title} href={feed.href} />
+    )}
+    {jsonLd && (
+      <script type="application/ld+json" is:inline set:html={serialiseJsonLd(jsonLd)}></script>
+    )}
+  </head>
+  <body>
+    <main>
+      <slot />
+    </main>
+
+    <style>
+      main {
+        max-width: var(--rx-max-wide);
+        margin: 0 auto;
+        padding: clamp(2rem, 6vh, 3.5rem) 1.5rem 4rem;
+      }
+    </style>
+
+    <!-- Prose styling for rendered markdown. Global because <Content /> markup carries no Astro
+         scoping attributes. -->
+    <style is:global>
+      .prose {
+        color: var(--rx-muted);
+        line-height: 1.7;
+      }
+      .prose > * + * {
+        margin-top: 1.1rem;
+      }
+      .prose h2 {
+        color: var(--rx-fg);
+        font-size: 1.25rem;
+        font-weight: 640;
+        letter-spacing: -0.01em;
+        margin-top: 2.5rem;
+      }
+      .prose h3 {
+        color: var(--rx-fg);
+        font-size: 1.05rem;
+        font-weight: 620;
+        margin-top: 2rem;
+      }
+      .prose a {
+        color: var(--rx-fg);
+        text-decoration: underline;
+        text-underline-offset: 2px;
+      }
+      .prose strong {
+        color: var(--rx-fg);
+        font-weight: 620;
+      }
+      .prose ul,
+      .prose ol {
+        margin-left: 1.2rem;
+      }
+      .prose li + li {
+        margin-top: 0.35rem;
+      }
+      .prose code {
+        font-family: var(--rx-font-mono);
+        font-size: 0.88em;
+        background: var(--rx-tag-bg);
+        padding: 0.05rem 0.35rem;
+        border-radius: 4px;
+      }
+      .prose pre {
+        background: var(--rx-card);
+        border: 1px solid var(--rx-rule);
+        border-radius: 10px;
+        padding: 1rem 1.1rem;
+        /* Long lines scroll inside the block; the page itself never does. */
+        overflow-x: auto;
+      }
+      .prose pre code {
+        background: none;
+        padding: 0;
+      }
+      .prose blockquote {
+        border-left: 2px solid var(--rx-rule);
+        padding-left: 1rem;
+        color: var(--rx-faint);
+      }
+      .prose img {
+        max-width: 100%;
+        height: auto;
+        border-radius: 10px;
+      }
+      .prose table {
+        width: 100%;
+        border-collapse: collapse;
+        font-size: 0.95rem;
+      }
+      .prose th,
+      .prose td {
+        border-bottom: 1px solid var(--rx-rule);
+        padding: 0.5rem 0.6rem;
+        text-align: left;
+      }
+      .prose th {
+        color: var(--rx-fg);
+        font-weight: 620;
+      }
+    </style>
+  </body>
+</html>

package/src/components/ThemeScript.astro

@@ -0,0 +1,31 @@
+---
+/**
+ * The pre-paint theme script for non-Starlight surfaces; goes in `<head>`. It reads Starlight's
+ * `starlight-theme` key so the choice carries across the origin; no saved choice => CSS default.
+ */
+---
+
+<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()
+    // Back from a docs site restores this page from the bfcache without rerunning the script;
+    // `pageshow` is the only notification, so re-sync the theme there.
+    window.addEventListener('pageshow', function (e) {
+      if (e.persisted) sync()
+    })
+  })()
+</script>

package/src/components/ThemeToggle.astro

@@ -0,0 +1,163 @@
+---
+/**
+ * The light/dark toggle for non-Starlight surfaces. Pairs with ThemeScript.astro in <head>, which
+ * avoids the flash; this only handles clicks and keeps the icon honest.
+ */
+
+interface Props {
+  /** Pin the button to the viewport's top-right corner; `false` when it sits in a header. */
+  floating?: boolean
+}
+
+const { floating = true } = Astro.props
+---
+
+<button
+  id="theme-toggle"
+  class:list={['theme-toggle', { 'theme-toggle--floating': floating }]}
+  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>
+  /* Quiet by default: no border, no fill, the same muted ink as the nav links beside it. */
+  .theme-toggle {
+    flex: none;
+    width: 2rem;
+    height: 2rem;
+    display: grid;
+    place-items: center;
+    border: 1px solid transparent;
+    border-radius: 8px;
+    background: none;
+    color: var(--rx-muted);
+    cursor: pointer;
+    transition:
+      color 0.15s ease,
+      border-color 0.15s ease,
+      background-color 0.2s ease;
+  }
+
+  /* Floating over arbitrary content, it keeps the border and fill so it still reads as a button. */
+  .theme-toggle--floating {
+    position: fixed;
+    top: 1rem;
+    right: 1rem;
+    /* Above SiteShell's sticky header (z-index 10), so the fixed button stays reachable. */
+    z-index: 20;
+    width: 2.25rem;
+    height: 2.25rem;
+    border-color: var(--rx-rule);
+    background: var(--rx-card);
+    color: var(--rx-fg);
+  }
+
+  .theme-toggle .icon {
+    display: grid;
+    place-items: center;
+  }
+
+  /* `:global` because the script swaps the icon via innerHTML, which carries no Astro scoping
+     attributes. */
+  .theme-toggle :global(svg) {
+    width: 1.05rem;
+    height: 1.05rem;
+    display: block;
+    stroke-width: 1.6;
+  }
+
+  .theme-toggle:hover {
+    color: var(--rx-fg);
+  }
+
+  .theme-toggle--floating:hover {
+    border-color: var(--rx-faint);
+  }
+
+  .theme-toggle:focus-visible {
+    outline: 2px solid var(--rx-fg);
+    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()
+    })
+    // Back from a docs site restores this page from the bfcache without rerunning any script;
+    // `pageshow` is the only notification, so re-sync the theme there.
+    window.addEventListener('pageshow', function (e) {
+      if (e.persisted) sync()
+    })
+    render()
+  })()
+</script>

package/src/components/VisuallyHidden.astro

@@ -0,0 +1,23 @@
+---
+/** Text only screen readers get; unlike `display: none`, it stays in the accessibility tree. */
+import type { HTMLAttributes } from 'astro/types'
+
+type Props = HTMLAttributes<'span'>
+
+const { class: className, ...rest } = Astro.props
+---
+
+<span class:list={['visually-hidden', className]} {...rest}>
+  <slot />
+</span>
+
+<style>
+  .visually-hidden {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+</style>

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/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} />