@rxova/astro-ui 0.1.0 → 0.3.0

package/README.md

@@ -51,16 +51,19 @@ 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                                                                |
+| 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 (`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.
@@ -71,6 +74,15 @@ 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,6 +1,6 @@
 {
   "name": "@rxova/astro-ui",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Astro components, Starlight preset and shared chrome for rxova.org",
   "keywords": [
@@ -46,7 +46,8 @@
     }
   },
   "dependencies": {
-    "@rxova/brand": "^1.0.0"
+    "@rxova/brand": "^1.1.1",
+    "lucide-static": "^1.45.0"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",

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>

package/src/components/Header.astro

@@ -1,6 +1,6 @@
 ---
 /**
- * The single rxova.org header, rendered by `SiteShell` and the website landing; callers pass
+ * The single rxova.org header, rendered by the website's layout; callers pass
  * the menu fully resolved. Not for the Starlight docs sites, which use `sharedStarlightConfig`.
  */
 import ThemeToggle from './ThemeToggle.astro'

package/src/components/Icon.astro

@@ -0,0 +1,29 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+/** The frame every glyph in `icons/` draws in: a 16px grid in the text colour. Decorative: label the button. */
+type Props = HTMLAttributes<'svg'> & {
+  /** Width and height, in pixels. */
+  size?: number
+  /** Fills the shape instead of stroking it. */
+  solid?: boolean
+}
+
+const { size = 16, solid = false, class: className, ...rest } = Astro.props
+---
+
+<svg
+  class:list={['icon', className]}
+  viewBox="0 0 16 16"
+  width={size}
+  height={size}
+  fill={solid ? 'currentColor' : 'none'}
+  stroke={solid ? 'none' : 'currentColor'}
+  stroke-width="1.6"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+  aria-hidden="true"
+  {...rest}
+>
+  <slot />
+</svg>

package/src/components/ModeTabs.astro

@@ -0,0 +1,124 @@
+---
+/**
+ * A numbered progression of modes, each a prose column beside a code pane. Panes are named slots
+ * (one per `mode.slot`), so a page writes fenced blocks and gets the docs' Shiki highlighting.
+ */
+export interface Mode {
+  name: string
+  /** The named slot holding this mode's code. */
+  slot: string
+  summary: string
+}
+
+interface Props {
+  modes: readonly Mode[]
+}
+
+const { modes } = Astro.props
+const panes = await Promise.all(
+  modes.map(async (mode) => ({
+    ...mode,
+    html: Astro.slots.has(mode.slot) ? await Astro.slots.render(mode.slot) : '',
+  })),
+)
+---
+
+<ol class="rx-modes">
+  {panes.map((mode, index) => (
+    <li class="rx-modes__item">
+      <div class="rx-modes__prose">
+        <div class="rx-modes__head">
+          <span class="rx-modes__step" aria-hidden="true">
+            {index + 1}
+          </span>
+          <h3 class="rx-modes__name">{mode.name}</h3>
+        </div>
+        <p class="rx-modes__summary">{mode.summary}</p>
+      </div>
+      <div class="rx-modes__code" set:html={mode.html} />
+    </li>
+  ))}
+</ol>
+
+<style>
+  .rx-modes {
+    display: grid;
+    gap: 1.25rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  /* Full-width rows, not columns: snippets are wider than a third of the page and would truncate. */
+  .rx-modes__item {
+    display: grid;
+    gap: 1.25rem;
+    min-width: 0;
+    padding: 1.5rem;
+    background: var(--rx-card);
+    border: 1px solid var(--rx-rule);
+    border-radius: var(--rx-radius);
+    grid-template-columns: 1fr;
+  }
+
+  @media (min-width: 50rem) {
+    .rx-modes__item {
+      grid-template-columns: 17rem 1fr;
+      align-items: start;
+      gap: 2rem;
+    }
+  }
+
+  .rx-modes__head {
+    display: flex;
+    align-items: center;
+    gap: 0.7rem;
+  }
+
+  .rx-modes__step {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.6rem;
+    height: 1.6rem;
+    flex: none;
+    color: var(--rx-primary);
+    background: var(--rx-tag-bg);
+    border-radius: var(--rx-radius-pill);
+    font-family: var(--rx-font-mono);
+    font-size: 0.8rem;
+    font-weight: 500;
+  }
+
+  .rx-modes__name {
+    margin: 0;
+    color: var(--rx-fg);
+    font-size: 1.05rem;
+    font-weight: 620;
+    letter-spacing: -0.01em;
+  }
+
+  .rx-modes__summary {
+    margin: 0.7rem 0 0;
+    color: var(--rx-muted);
+    font-size: 0.92rem;
+    line-height: 1.6;
+    text-wrap: pretty;
+  }
+
+  /* min-width: 0 so a long line scrolls inside the pane instead of widening the card past the page. */
+  .rx-modes__code {
+    min-width: 0;
+  }
+
+  .rx-modes__code :global(pre) {
+    margin: 0;
+    padding: 0.95rem 1.1rem;
+    background: var(--rx-bg);
+    border: 1px solid var(--rx-rule);
+    border-radius: var(--rx-radius-sm);
+    overflow-x: auto;
+    font-size: 0.8rem;
+    line-height: 1.6;
+  }
+</style>