@rxova/astro-ui 0.0.0 → 0.2.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,88 @@
-# @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`, …), primitives (`PageHeader`, `BackLink`, `ShowMore`, `VisuallyHidden`, `Icon`) and the components in the gallery |
+| `@rxova/astro-ui/components/icons/*.astro` | Glyphs in the `Icon` frame: `Prev`, `Next`, `Play`, `Pause`, `Replay`, `Expand`, `Collapse`                                                                    |
+| `@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                                                                                                       |
+| `@rxova/astro-ui/styles/landing.css`       | The Starlight overrides a splash landing page needs; load it through `customCss`                                                                               |
+| `@rxova/astro-ui/styles/mermaid.css`       | Restyles `rehype-mermaid`'s build-time SVG with the tokens, so diagrams follow the theme                                                                       |
+
+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.
+
+`apps/preview` also carries the gallery: one page per component under
+`/gallery/`, each state in a `Story` frame. `pnpm --filter @rxova/preview
+screenshots` rebuilds it and writes `screenshots/<component>.png` here, light and
+dark, for the pull request that adds or changes a component.
+
+`apps/storybook` is the Storybook: a story file per component with its states,
+a Docs page built from the component's frontmatter, and a light/dark toolbar.
+`pnpm --filter @rxova/storybook dev` serves it with live controls.
+
+## License
+
+MIT © Jonatan Kruszewski

package/package.json

@@ -1,12 +1,71 @@
 {
   "name": "@rxova/astro-ui",
-  "version": "0.0.0",
-  "description": "Placeholder. The package is under development.",
+  "version": "0.2.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.1.0",
+    "lucide-static": "^1.45.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/CodeRecipes.astro

@@ -0,0 +1,67 @@
+---
+/** Titled source listings, one per recipe: a heading linking to the library, then the source in a code frame. */
+export interface Recipe {
+  id: string
+  label: string
+  href: string
+  source: string
+}
+
+interface Props {
+  recipes: readonly Recipe[]
+  /** Heading ids are `<idPrefix>-<recipe.id>`, so a page can link to one recipe. */
+  idPrefix?: string
+}
+
+const { recipes, idPrefix = 'recipe' } = Astro.props
+---
+
+<div class="rx-recipes">
+  {recipes.map(({ id, label, href, source }) => (
+    <section class="rx-recipe">
+      <h3 class="rx-recipe__title" id={`${idPrefix}-${id}`}>
+        <a href={href}>{label}</a>
+      </h3>
+      <pre class="rx-recipe__source"><code>{source}</code></pre>
+    </section>
+  ))}
+</div>
+
+<style>
+  .rx-recipes {
+    display: grid;
+    gap: 2rem;
+  }
+
+  .rx-recipe__title {
+    margin: 0 0 0.75rem;
+    font-size: 1.05rem;
+    font-weight: 620;
+    letter-spacing: -0.015em;
+  }
+
+  .rx-recipe__title a {
+    color: var(--rx-fg);
+    text-decoration: none;
+  }
+
+  .rx-recipe__title a:hover {
+    color: var(--rx-primary);
+    text-decoration: underline;
+    text-underline-offset: 3px;
+  }
+
+  .rx-recipe__source {
+    margin: 0;
+    padding: 1.1rem 1.25rem;
+    background: var(--rx-card);
+    border: 1px solid var(--rx-rule);
+    border-radius: var(--rx-radius);
+    overflow-x: auto;
+    color: var(--rx-fg);
+    font-family: var(--rx-font-mono);
+    font-size: 0.86rem;
+    line-height: 1.65;
+    tab-size: 2;
+  }
+</style>

package/src/components/CtaBand.astro

@@ -0,0 +1,121 @@
+---
+/**
+ * A centred call to action: title, lede and a row of pill buttons. Internal hrefs must arrive
+ * base-aware; external ones get `rel="noopener"` and a visible marker.
+ */
+export interface CtaAction {
+  text: string
+  href: string
+  variant?: 'primary' | 'minimal'
+  external?: boolean
+}
+
+interface Props {
+  title: string
+  lede: string
+  actions: readonly CtaAction[]
+}
+
+const { title, lede, actions } = Astro.props
+---
+
+<aside class="rx-cta not-content">
+  <h2 class="rx-cta__title">{title}</h2>
+  <p class="rx-cta__lede">{lede}</p>
+  <div class="rx-cta__actions">
+    {actions.map((action) => (
+      <a
+        class:list={['rx-btn', `rx-btn--${action.variant ?? 'minimal'}`]}
+        href={action.href}
+        rel={action.external ? 'noopener' : undefined}
+      >
+        {action.text}
+        {action.external && (
+          <svg
+            viewBox="0 0 24 24"
+            width="14"
+            height="14"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            aria-hidden="true"
+          >
+            <path d="M14 4h6v6M20 4l-9 9M18 14v5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1h5" />
+          </svg>
+        )}
+      </a>
+    ))}
+  </div>
+</aside>
+
+<style>
+  .rx-cta {
+    margin-block: 6rem 1rem;
+    padding: clamp(2rem, 1rem + 4vw, 3.5rem);
+    text-align: center;
+    background: var(--rx-card);
+    border: 1px solid var(--rx-rule);
+    border-radius: var(--rx-radius);
+    box-shadow: var(--rx-shadow-soft);
+  }
+
+  .rx-cta__title {
+    margin: 0;
+    color: var(--rx-fg);
+    font-size: clamp(1.5rem, 1.15rem + 1.5vw, 2.1rem);
+    font-weight: 640;
+    line-height: 1.15;
+    letter-spacing: -0.02em;
+    text-wrap: balance;
+  }
+
+  .rx-cta__lede {
+    max-width: 46ch;
+    margin: 0.9rem auto 0;
+    color: var(--rx-muted);
+    font-size: 1rem;
+    line-height: 1.6;
+    text-wrap: pretty;
+  }
+
+  .rx-cta__actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.75rem;
+    justify-content: center;
+    margin-top: 2rem;
+  }
+
+  .rx-btn {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.7rem 1.4rem;
+    border: 1px solid transparent;
+    border-radius: var(--rx-radius-pill);
+    font-size: 0.95rem;
+    font-weight: 600;
+    text-decoration: none;
+  }
+
+  /* --rx-on-primary, not #fff: white on the lightened dark-mode violet is about 2.9:1 as a fill. */
+  .rx-btn--primary {
+    color: var(--rx-on-primary);
+    background: var(--rx-primary);
+  }
+
+  .rx-btn--primary:hover {
+    background: var(--rx-primary-dark);
+  }
+
+  .rx-btn--minimal {
+    color: var(--rx-fg);
+    border-color: var(--rx-rule-strong);
+  }
+
+  .rx-btn--minimal:hover {
+    border-color: var(--rx-primary);
+  }
+</style>

package/src/components/DataTable.astro

@@ -0,0 +1,114 @@
+---
+/**
+ * Facts a page reads from somewhere else, as a framed table: column headings, a row heading per
+ * row, cells that may render as code. Scrollable and focusable when narrow, so a keyboard can reach it.
+ */
+export type Cell = string | { code: string }
+
+export interface DataRow {
+  label: string
+  cells: readonly Cell[]
+}
+
+interface Props {
+  /** The accessible name of the scrollable region: "Framework compatibility". */
+  label: string
+  columns: readonly string[]
+  rows: readonly DataRow[]
+  /** Where the facts come from, under the table. */
+  caption?: string
+}
+
+const { label, columns, rows, caption } = Astro.props
+---
+
+<div class="rx-table" tabindex="0" role="region" aria-label={label}>
+  <table class="rx-table__table">
+    {caption && <caption class="rx-table__caption">{caption}</caption>}
+    <thead>
+      <tr>
+        {columns.map((column) => (
+          <th scope="col">{column}</th>
+        ))}
+      </tr>
+    </thead>
+    <tbody>
+      {rows.map((row) => (
+        <tr>
+          <th scope="row" class="rx-table__label">
+            {row.label}
+          </th>
+          {row.cells.map((cell) => (
+            <td>{typeof cell === 'string' ? cell : <code>{cell.code}</code>}</td>
+          ))}
+        </tr>
+      ))}
+    </tbody>
+  </table>
+</div>
+
+<style>
+  .rx-table {
+    overflow-x: auto;
+    border: 1px solid var(--rx-rule);
+    border-radius: var(--rx-radius);
+  }
+
+  .rx-table__table {
+    width: 100%;
+    margin: 0;
+    border-collapse: collapse;
+    font-size: 0.9rem;
+    line-height: 1.5;
+  }
+
+  .rx-table__caption {
+    padding: 1rem 1.25rem;
+    color: var(--rx-muted);
+    font-size: 0.82rem;
+    line-height: 1.5;
+    text-align: start;
+    caption-side: bottom;
+    border-top: 1px solid var(--rx-rule);
+  }
+
+  .rx-table__table th,
+  .rx-table__table td {
+    padding: 0.85rem 1.25rem;
+    text-align: start;
+    vertical-align: top;
+    color: var(--rx-fg);
+    border-bottom: 1px solid var(--rx-rule);
+  }
+
+  .rx-table__table thead th {
+    background: var(--rx-card);
+    color: var(--rx-muted);
+    font-size: 0.75rem;
+    font-weight: 700;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    white-space: nowrap;
+  }
+
+  .rx-table__table tbody tr:last-child th,
+  .rx-table__table tbody tr:last-child td {
+    border-bottom: 0;
+  }
+
+  .rx-table__label {
+    font-weight: 600;
+    white-space: nowrap;
+  }
+
+  .rx-table__table td {
+    color: var(--rx-muted);
+  }
+
+  .rx-table__table code {
+    color: var(--rx-fg);
+    font-family: var(--rx-font-mono);
+    font-size: 0.84rem;
+    white-space: nowrap;
+  }
+</style>

package/src/components/DocAccordion.astro

@@ -0,0 +1,15 @@
+---
+/** A stack of `DocAccordionItem`s: `<details>` does the collapsing, so there is no client script. */
+---
+
+<div class="doc-accordion">
+  <slot />
+</div>
+
+<style>
+  .doc-accordion {
+    display: grid;
+    gap: 1rem;
+    margin: 1.5rem 0 2rem;
+  }
+</style>

package/src/components/DocAccordionItem.astro

@@ -0,0 +1,83 @@
+---
+/** One collapsible block of a `DocAccordion`: a title, an optional one-line summary, and the slot. */
+interface Props {
+  title: string
+  summary?: string
+  defaultOpen?: boolean
+}
+
+const { title, summary, defaultOpen = false } = Astro.props
+---
+
+<details class="doc-accordion-item" open={defaultOpen}>
+  <summary>
+    <span class="summary-text">
+      <span class="title">{title}</span>
+      {summary && <span class="summary-copy">{summary}</span>}
+    </span>
+  </summary>
+  <div class="content">
+    <slot />
+  </div>
+</details>
+
+<style>
+  .doc-accordion-item {
+    border: 1px solid var(--rx-rule);
+    border-radius: 1rem;
+    background: var(--rx-bg);
+    overflow: hidden;
+  }
+
+  summary {
+    list-style: none;
+    cursor: pointer;
+    padding: 1rem 1.1rem 1rem 1.25rem;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 1rem;
+    font-weight: 600;
+    color: var(--rx-fg);
+  }
+
+  summary::-webkit-details-marker {
+    display: none;
+  }
+
+  summary::after {
+    content: '+';
+    flex: 0 0 auto;
+    font-size: 1.3rem;
+    line-height: 1;
+    color: var(--rx-primary);
+  }
+
+  .doc-accordion-item[open] summary::after {
+    content: '−';
+  }
+
+  .summary-text {
+    display: grid;
+    gap: 0.18rem;
+  }
+
+  .title {
+    font-size: 1.02rem;
+  }
+
+  .summary-copy {
+    font-size: 0.92rem;
+    font-weight: 500;
+    color: var(--rx-muted);
+  }
+
+  .content {
+    border-top: 1px solid var(--rx-rule);
+    padding: 1rem 1.25rem 1.25rem;
+  }
+
+  .content > :last-child {
+    margin-bottom: 0;
+  }
+</style>