@rxova/astro-ui 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonatan Kruszewski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,2 +1,76 @@
-# @rxova/astro-ui
-Placeholder release. The package is under development.
+<h1 align="center">@rxova/astro-ui</h1>
+
+<p align="center">
+  Astro components, the Starlight preset and the shared chrome for every
+  <a href="https://rxova.org">rxova.org</a> surface, built on
+  <a href="../brand"><code>@rxova/brand</code></a>.
+</p>
+
+---
+
+## Use
+
+### In a Starlight docs site
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config'
+import starlight from '@astrojs/starlight'
+import { sharedStarlightConfig } from '@rxova/astro-ui/starlight'
+
+export default defineConfig({
+  site: process.env.DOCS_URL ?? 'https://rxova.org',
+  base: process.env.DOCS_BASE_URL ?? '/',
+  integrations: [
+    starlight(
+      sharedStarlightConfig({
+        project: 'use-everywhere',
+        sidebar: [{ label: 'Learn', items: [{ autogenerate: { directory: 'learn' } }] }],
+      }),
+    ),
+  ],
+})
+```
+
+That gets you the tokens, the typefaces, the rxova mark linking back to the
+umbrella site, the cross-project switcher, the shared footer and Pagefind search.
+
+### In a plain Astro site
+
+```astro
+---
+import '@rxova/brand/fonts.css'
+import '@rxova/astro-ui/styles/document.css'
+import SiteFooter from '@rxova/astro-ui/components/SiteFooter.astro'
+---
+```
+
+`document.css` is `chrome.css` plus a reset and base element styles. Load
+`chrome.css` alone where something else owns the document: its reset is
+unlayered and would flatten a Starlight page.
+
+## What's in it
+
+| Export                                 | What it is                                                                                                              |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `@rxova/astro-ui/starlight`            | `sharedStarlightConfig()`, the preset every docs site spreads                                                           |
+| `@rxova/astro-ui/starlight/*.astro`    | The Starlight overrides: `SiteTitle`, `SocialIcons`, `Footer`, `ThemeSelect`                                            |
+| `@rxova/astro-ui/components/*.astro`   | Chrome (`SiteShell`, `Header`, `SiteFooter`, …) and primitives (`PageHeader`, `BackLink`, `ShowMore`, `VisuallyHidden`) |
+| `@rxova/astro-ui/scripts/show-more`    | `enhanceShowMore()`: batches a `[data-reveal-list]` behind a `ShowMore`                                                 |
+| `@rxova/astro-ui/lib/entries`          | Ordering, bylines, dates and excerpts shared by /blog and /updates                                                      |
+| `@rxova/astro-ui/styles/document.css`  | For sites that own their document: `chrome.css`, a reset, base element styling                                          |
+| `@rxova/astro-ui/styles/chrome.css`    | What the header and footer need, with nothing document-level                                                            |
+| `@rxova/astro-ui/styles/starlight.css` | Maps `--rx-*` onto Starlight's `--sl-*`, plus the footer                                                                |
+
+There is no barrel: each component has its own path, so a page only loads the
+CSS of the components it imports.
+
+## Development
+
+Run everything from the repo root. `apps/preview` renders the Starlight preset
+and the plain-Astro chrome; `pnpm run verify` runs `astro check`, the tests and
+the export checks for this package.
+
+## License
+
+MIT © Jonatan Kruszewski

package/package.json

@@ -1,12 +1,70 @@
 {
   "name": "@rxova/astro-ui",
-  "version": "0.0.0",
-  "description": "Placeholder. The package is under development.",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Astro components, Starlight preset and shared chrome for rxova.org",
+  "keywords": [
+    "rxova",
+    "astro",
+    "starlight",
+    "components"
+  ],
   "license": "MIT",
-  "author": "Jonatan Kruszewski",
+  "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
+  "homepage": "https://rxova.org",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/rxova/astro-ui.git"
+    "url": "git+https://github.com/rxova/rxova-website.git",
+    "directory": "packages/astro-ui"
   },
-  "files": []
-}
+  "bugs": "https://github.com/rxova/rxova-website/issues",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "src"
+  ],
+  "exports": {
+    "./components/*": "./src/components/*",
+    "./lib/entries": "./src/lib/entries.ts",
+    "./scripts/show-more": "./src/scripts/show-more.ts",
+    "./starlight": "./src/starlight/index.ts",
+    "./starlight/*": "./src/starlight/*",
+    "./styles/*": "./src/styles/*",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": ">=0.36.0",
+    "astro": ">=5.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@astrojs/starlight": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@rxova/brand": "^1.0.0"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.10",
+    "@astrojs/starlight": "^0.42.1",
+    "@rxova/repo-tooling": "0.0.0",
+    "@types/node": "^26.6.1",
+    "@vitest/coverage-v8": "^5.0.1",
+    "astro": "^7.3.2",
+    "happy-dom": "^20.14.5",
+    "publint": "^0.3.24",
+    "tsx": "^4.23.13",
+    "typescript": "6.0.3",
+    "vitest": "^5.0.1"
+  },
+  "scripts": {
+    "check:astro": "astro check",
+    "check:exports": "publint --strict",
+    "pack:smoke": "node --import tsx ../brand/scripts/pack-smoke.ts",
+    "test": "vitest run --coverage"
+  }
+}

package/src/components/BackLink.astro

@@ -0,0 +1,24 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+/** An "← up one level" link; the caller's class sets its spacing. */
+type Props = HTMLAttributes<'a'> & { href: string }
+
+const { href, class: className, ...rest } = Astro.props
+---
+
+<a class:list={['back-link', className]} href={href} {...rest}>
+  ← <slot />
+</a>
+
+<style>
+  .back-link {
+    display: inline-block;
+    color: var(--rx-muted);
+    text-decoration: none;
+    font-size: 0.95rem;
+  }
+  .back-link:hover {
+    color: var(--rx-fg);
+  }
+</style>

package/src/components/Header.astro

@@ -0,0 +1,148 @@
+---
+/**
+ * The single rxova.org header, rendered by `SiteShell` and the website landing; callers pass
+ * the menu fully resolved. Not for the Starlight docs sites, which use `sharedStarlightConfig`.
+ */
+import ThemeToggle from './ThemeToggle.astro'
+
+export interface HeaderItem {
+  label: string
+  /** Fully resolved by the caller — absolute or root-relative as its base needs. */
+  href: string
+  /** Marks the item for the surface the reader is on. */
+  current?: boolean
+}
+
+interface Props {
+  /** Where the brand mark links — the site root, resolved by the caller. */
+  homeHref: string
+  /** Logo `src`, resolved by the caller for its base. */
+  logoSrc: string
+  /** The menu, in the one fixed order every surface shows it. */
+  items: readonly HeaderItem[]
+}
+
+const { homeHref, logoSrc, items } = Astro.props
+---
+
+{/* Outside <main> so it spans the viewport; sticky, not fixed, so nothing needs a top margin. */}
+<header class="site">
+  <div class="site__inner">
+    <a class="brand" href={homeHref}>
+      <img src={logoSrc} alt="" width="28" height="28" />
+      <span>Rxova</span>
+    </a>
+    <nav aria-label="Sections">
+      {items.map((item) => (
+        <a href={item.href} aria-current={item.current ? 'page' : undefined}>
+          {item.label}
+        </a>
+      ))}
+    </nav>
+    {/* In the header, not floating over it — see ThemeToggle's `floating`. */}
+    <ThemeToggle floating={false} />
+  </div>
+</header>
+
+<style>
+  /* Sticky, translucent, full-bleed. */
+  .site {
+    position: sticky;
+    top: 0;
+    z-index: 10;
+    border-bottom: 1px solid var(--rx-rule);
+    background: color-mix(in srgb, var(--rx-bg) 88%, transparent);
+  }
+
+  /* The blur keeps text legible under the bar; where unsupported, the 88% mix above stays
+     nearly opaque. */
+  @supports (backdrop-filter: blur(8px)) or (-webkit-backdrop-filter: blur(8px)) {
+    .site {
+      background: color-mix(in srgb, var(--rx-bg) 72%, transparent);
+      -webkit-backdrop-filter: blur(10px);
+      backdrop-filter: blur(10px);
+    }
+  }
+
+  .site__inner {
+    max-width: var(--rx-max-wide);
+    margin: 0 auto;
+    padding: 0.75rem 1.5rem;
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    /* No wrapping: a two-line header would eat a phone's viewport, and the row
+       is sized to fit at the narrowest widths we support. */
+    min-height: 3.5rem;
+  }
+
+  .brand {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.55rem;
+    color: var(--rx-fg);
+    text-decoration: none;
+    font-weight: 640;
+    letter-spacing: -0.01em;
+  }
+  .brand img {
+    display: block;
+    border-radius: 6px;
+  }
+
+  /* The nav takes the space between the brand and the toggle, and pushes itself
+     to the right of it. */
+  nav {
+    margin-left: auto;
+    display: flex;
+    gap: 1.4rem;
+  }
+  nav a {
+    color: var(--rx-muted);
+    text-decoration: none;
+    font-size: 0.95rem;
+    white-space: nowrap;
+  }
+  nav a:hover {
+    color: var(--rx-fg);
+  }
+  /* The current section is marked for everyone, not only for assistive tech —
+     aria-current on its own is invisible. */
+  nav a[aria-current='page'] {
+    color: var(--rx-fg);
+    text-decoration: underline;
+    text-underline-offset: 5px;
+  }
+  nav a:focus-visible {
+    outline: 2px solid var(--rx-fg);
+    outline-offset: 3px;
+    border-radius: 2px;
+  }
+
+  /* Brand mark, the links and the toggle stay on one row at the narrowest phones
+     by dropping the wordmark — the logo carries the identity in the space left. */
+  @media (max-width: 34rem) {
+    .site__inner {
+      gap: 0.75rem;
+      padding-inline: 1rem;
+      min-height: 3.25rem;
+    }
+    nav {
+      gap: 0.9rem;
+    }
+    nav a {
+      font-size: 0.875rem;
+    }
+    .brand span {
+      display: none;
+    }
+  }
+</style>
+
+<!-- Global because `html` sits outside Astro's scoping. Without it a jump to an
+     in-page anchor would land under the sticky header. -->
+<style is:global>
+  html {
+    scroll-padding-top: 4.5rem;
+  }
+</style>

package/src/components/PageHeader.astro

@@ -0,0 +1,63 @@
+---
+/**
+ * A page's title and lede, with an optional back link. The default slot is the lede.
+ * `detail` keeps the repo pages' heavier title, which still inherits the body's line height.
+ */
+import BackLink from './BackLink.astro'
+
+interface Props {
+  title: string
+  back?: { href: string; label: string }
+  variant?: 'index' | 'detail'
+  /** The lede's measure: `narrow` is 46ch, `wide` 56ch. */
+  measure?: 'narrow' | 'wide'
+}
+
+const { title, back, variant = 'index', measure = 'wide' } = Astro.props
+---
+
+<header class:list={['head', variant]}>
+  {back && (
+    <BackLink class="back" href={back.href}>
+      {back.label}
+    </BackLink>
+  )}
+  <h1>{title}</h1>
+  <p class:list={['lede', measure]}>
+    <slot />
+  </p>
+</header>
+
+<style>
+  .head {
+    margin-bottom: clamp(2rem, 6vh, 3rem);
+  }
+  .back {
+    margin-bottom: 1.25rem;
+  }
+  h1 {
+    font-size: clamp(1.8rem, 5vw, 2.4rem);
+    letter-spacing: -0.02em;
+    margin-bottom: 0.6rem;
+  }
+  /* One title across /about, /blog and /updates, so switching pages does not move it. */
+  .index h1 {
+    line-height: 1.15;
+    font-weight: 650;
+  }
+  .detail h1 {
+    font-weight: 660;
+  }
+  .lede {
+    color: var(--rx-muted);
+  }
+  .narrow {
+    max-width: 46ch;
+  }
+  .wide {
+    max-width: 56ch;
+  }
+  .lede :global(a) {
+    color: var(--rx-fg);
+  }
+</style>

package/src/components/ProjectSwitcher.astro

@@ -0,0 +1,95 @@
+---
+/**
+ * Cross-project navigation as a zero-JS `<details>`. Every href is absolute: a relative one would
+ * resolve under the current site's base path.
+ */
+import { PROJECTS, RXOVA_ORIGIN, type ProjectId } from '@rxova/brand'
+
+interface Props {
+  /** Which project this site is, so it can be marked as current. */
+  current?: ProjectId
+}
+
+const { current } = Astro.props
+---
+
+<details class="rx-switcher">
+  <summary class="rx-switcher__trigger" aria-label="Switch project">
+    Projects
+    <svg aria-hidden="true" viewBox="0 0 16 16" width="12" height="12">
+      <path d="M4 6l4 4 4-4" fill="none" stroke="currentColor" stroke-width="1.75"></path>
+    </svg>
+  </summary>
+  <ul class="rx-switcher__menu">
+    <li>
+      <a href={RXOVA_ORIGIN}>rxova.org</a>
+    </li>
+    {PROJECTS.map((project) => (
+      <li>
+        <a
+          href={`${RXOVA_ORIGIN}${project.mount}`}
+          class={project.id === current ? 'rx-switcher__current' : undefined}
+          aria-current={project.id === current ? 'page' : undefined}
+        >
+          {project.label}
+        </a>
+      </li>
+    ))}
+  </ul>
+</details>
+
+<style>
+  .rx-switcher__trigger {
+    display: flex;
+    align-items: center;
+    gap: 0.3rem;
+    padding: 0.25rem 0.5rem;
+    border-radius: var(--rx-radius-sm);
+    color: var(--sl-color-gray-2);
+    font-size: var(--sl-text-sm);
+    cursor: pointer;
+    list-style: none;
+  }
+
+  .rx-switcher__trigger::-webkit-details-marker {
+    display: none;
+  }
+
+  .rx-switcher__trigger:hover {
+    color: var(--sl-color-white);
+    background: var(--sl-color-gray-6);
+  }
+
+  .rx-switcher[open] > .rx-switcher__trigger svg {
+    transform: rotate(180deg);
+  }
+
+  .rx-switcher__menu {
+    position: absolute;
+    z-index: var(--sl-z-index-navbar, 20);
+    inset-inline-end: 0;
+    min-width: 12rem;
+    margin: 0.4rem 0 0;
+    padding: 0.35rem;
+    border: 1px solid var(--sl-color-hairline);
+    border-radius: var(--rx-radius);
+    background: var(--sl-color-bg-nav);
+    box-shadow: var(--sl-shadow-md);
+    list-style: none;
+  }
+
+  .rx-switcher__menu a {
+    display: flex;
+    align-items: center;
+    padding: 0.4rem 0.6rem;
+    border-radius: var(--rx-radius-sm);
+    color: var(--sl-color-gray-2);
+    font-size: var(--sl-text-sm);
+    text-decoration: none;
+  }
+
+  .rx-switcher__menu a:hover {
+    color: var(--sl-color-white);
+    background: var(--sl-color-gray-6);
+  }
+</style>

package/src/components/ShowMore.astro

@@ -0,0 +1,82 @@
+---
+/**
+ * "Show more" controls for a batched list; they ship `hidden` until a script drives them.
+ * `enhanceShowMore` from `@rxova/astro-ui/scripts/show-more` batches a plain list.
+ */
+import VisuallyHidden from './VisuallyHidden.astro'
+
+interface Props {
+  /** What the list holds, for the button's accessible name: "Show more posts". */
+  noun: string
+}
+
+const { noun } = Astro.props
+---
+
+<div class="more" data-reveal-controls hidden>
+  <button class="more-btn" type="button" data-reveal-more>
+    Show more<VisuallyHidden>{` ${noun}`}</VisuallyHidden>
+  </button>
+  <button class="show-all" type="button" data-reveal-all>
+    Show all
+  </button>
+  <p class="progress" data-reveal-progress></p>
+</div>
+
+<style>
+  .more {
+    display: flex;
+    align-items: baseline;
+    gap: 0.75rem;
+    flex-wrap: wrap;
+    margin-top: 2.5rem;
+    padding-top: 1.5rem;
+    border-top: 1px solid var(--rx-rule);
+  }
+  /* `display: flex` outranks the UA's `[hidden]` rule. */
+  .more[hidden] {
+    display: none;
+  }
+  .more-btn {
+    font: inherit;
+    font-size: 0.9rem;
+    color: var(--rx-fg);
+    background: var(--rx-tag-bg);
+    border: 1px solid var(--rx-rule);
+    border-radius: 999px;
+    padding: 0.35rem 1rem;
+    cursor: pointer;
+  }
+  .more-btn:hover {
+    border-color: var(--rx-fg);
+  }
+  .show-all {
+    font: inherit;
+    font-size: 0.85rem;
+    color: var(--rx-muted);
+    background: none;
+    border: 0;
+    padding: 0;
+    text-decoration: underline;
+    text-underline-offset: 3px;
+    cursor: pointer;
+  }
+  .show-all:hover {
+    color: var(--rx-fg);
+  }
+  .more-btn:focus-visible,
+  .show-all:focus-visible {
+    outline: 2px solid var(--rx-fg);
+    outline-offset: 2px;
+  }
+  .progress {
+    margin-left: auto;
+    color: var(--rx-faint);
+    font-size: 0.85rem;
+  }
+  @media print {
+    .more {
+      display: none;
+    }
+  }
+</style>