@rxova/astro-ui 0.0.0 → 0.2.0

package/src/components/QuickStart.astro

@@ -0,0 +1,156 @@
+---
+/**
+ * An install command with a copy button beside a "Use" pane. The snippet arrives through the slot,
+ * so a page can write a fenced block and get the same Shiki highlighting as the docs.
+ */
+interface Props {
+  command: string
+}
+
+const { command } = Astro.props
+---
+
+<div class="rx-qs">
+  <div class="rx-qs__pane">
+    <p class="rx-qs__label">Install</p>
+    <div class="rx-qs__term">
+      {/* Focusable and labelled: a nowrap command over overflow-x scrolls, and a scrollable region needs a tab stop. */}
+      <code class="rx-qs__cmd" tabindex="0" role="region" aria-label="Install command">
+        <span class="rx-qs__prompt" aria-hidden="true">
+          $
+        </span>
+        {command}
+      </code>
+      <button class="rx-qs__copy" type="button" data-copy={command}>
+        <span class="rx-qs__copy-idle">Copy</span>
+        <span class="rx-qs__copy-done" aria-hidden="true">
+          Copied
+        </span>
+      </button>
+    </div>
+  </div>
+
+  <div class="rx-qs__pane">
+    <p class="rx-qs__label">Use</p>
+    <div class="rx-qs__code">
+      <slot />
+    </div>
+  </div>
+</div>
+
+<script>
+  for (const button of document.querySelectorAll<HTMLButtonElement>('.rx-qs__copy')) {
+    button.addEventListener('click', async () => {
+      try {
+        await navigator.clipboard.writeText(button.dataset.copy ?? '')
+      } catch {
+        // Clipboard access can be denied; saying nothing beats claiming a copy that did not happen.
+        return
+      }
+      button.dataset.state = 'done'
+      window.setTimeout(() => delete button.dataset.state, 1600)
+    })
+  }
+</script>
+
+<style>
+  .rx-qs {
+    display: grid;
+    gap: 1.25rem;
+    grid-template-columns: repeat(auto-fit, minmax(19rem, 1fr));
+  }
+
+  .rx-qs__pane {
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+  }
+
+  .rx-qs__label {
+    margin: 0 0 0.6rem;
+    /* --rx-muted, not --rx-faint: faint on the card is ~3.4:1 and fails AA here. */
+    color: var(--rx-muted);
+    font-size: 0.72rem;
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+  }
+
+  /* Not `flex: 1`: a one-line command stretched to the snippet's height floats in an empty box. */
+  .rx-qs__term {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    padding: 1rem 1rem 1rem 1.15rem;
+    background: var(--rx-card);
+    border: 1px solid var(--rx-rule);
+    border-radius: var(--rx-radius);
+  }
+
+  .rx-qs__cmd {
+    flex: 1;
+    min-width: 0;
+    overflow-x: auto;
+    color: var(--rx-fg);
+    font-family: var(--rx-font-mono);
+    font-size: 0.88rem;
+    white-space: nowrap;
+  }
+
+  .rx-qs__prompt {
+    margin-right: 0.6rem;
+    color: var(--rx-primary);
+    user-select: none;
+  }
+
+  /* One label over the other, so the button keeps its size when the state flips. */
+  .rx-qs__copy {
+    display: grid;
+    flex: none;
+    padding: 0.4rem 0.85rem;
+    color: var(--rx-muted);
+    background: var(--rx-bg);
+    border: 1px solid var(--rx-rule-strong);
+    border-radius: var(--rx-radius-pill);
+    font: inherit;
+    font-size: 0.78rem;
+    font-weight: 500;
+    cursor: pointer;
+  }
+
+  .rx-qs__copy:hover {
+    color: var(--rx-fg);
+    border-color: var(--rx-primary);
+  }
+
+  .rx-qs__copy-idle,
+  .rx-qs__copy-done {
+    grid-area: 1 / 1;
+  }
+
+  .rx-qs__copy-done,
+  .rx-qs__copy[data-state='done'] .rx-qs__copy-idle {
+    visibility: hidden;
+  }
+
+  .rx-qs__copy[data-state='done'] .rx-qs__copy-done {
+    visibility: visible;
+    color: var(--rx-primary);
+  }
+
+  .rx-qs__code {
+    flex: 1;
+  }
+
+  /* The slotted block renders its own <pre>; frame it like the terminal so the panes read as a pair. */
+  .rx-qs__code :global(pre) {
+    height: 100%;
+    margin: 0;
+    padding: 1rem 1.15rem;
+    border: 1px solid var(--rx-rule);
+    border-radius: var(--rx-radius);
+    overflow-x: auto;
+    font-size: 0.84rem;
+    line-height: 1.6;
+  }
+</style>

package/src/components/ScreenshotGrid.astro

@@ -0,0 +1,164 @@
+---
+/**
+ * Screenshots shown rather than described: each in a hairline frame through Astro's `<Image>`,
+ * a mono label and a line of detail under it, and an optional link beneath the row.
+ */
+import { Image } from 'astro:assets'
+import type { ImageMetadata } from 'astro'
+
+export interface Shot {
+  src: ImageMetadata
+  alt: string
+  title: string
+  body: string
+}
+
+interface Props {
+  shots: readonly Shot[]
+  link?: { href: string; text: string; external?: boolean }
+}
+
+const { shots, link } = Astro.props
+---
+
+<div class="rx-shots">
+  <ul class="rx-shots__grid">
+    {shots.map((shot, index) => (
+      <li class="rx-shots__item">
+        <figure class="rx-shots__figure">
+          <div class="rx-shots__frame">
+            <Image src={shot.src} alt={shot.alt} loading="lazy" />
+          </div>
+          <figcaption class="rx-shots__caption">
+            <span class="rx-shots__index" aria-hidden="true">
+              {String(index + 1).padStart(2, '0')}
+            </span>
+            <span class="rx-shots__title">{shot.title}</span>
+            <span class="rx-shots__body">{shot.body}</span>
+          </figcaption>
+        </figure>
+      </li>
+    ))}
+  </ul>
+
+  {link && (
+    <a class="rx-shots__link" href={link.href} rel={link.external ? 'noopener' : undefined}>
+      {link.text}
+      <svg
+        viewBox="0 0 16 16"
+        width="14"
+        height="14"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.6"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        aria-hidden="true"
+      >
+        {link.external ? <path d="M5 3h8v8M13 3 3 13" /> : <path d="M3 8h10M9 4l4 4-4 4" />}
+      </svg>
+    </a>
+  )}
+</div>
+
+<style>
+  .rx-shots__grid {
+    display: grid;
+    gap: 2rem 2.5rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    grid-template-columns: 1fr;
+  }
+
+  /* Viewport breakpoints, like ValueGrid: three across on a wide screen, two on a tablet, one on a phone. */
+  @media (min-width: 38rem) {
+    .rx-shots__grid {
+      grid-template-columns: repeat(2, 1fr);
+    }
+  }
+
+  @media (min-width: 60rem) {
+    .rx-shots__grid {
+      grid-template-columns: repeat(3, 1fr);
+    }
+  }
+
+  .rx-shots__item {
+    min-width: 0;
+  }
+
+  .rx-shots__figure {
+    margin: 0;
+  }
+
+  /* A hairline, not a card: the screenshot is the surface. The frame owns the radius. */
+  .rx-shots__frame {
+    overflow: hidden;
+    border: 1px solid var(--rx-rule);
+    border-radius: var(--rx-radius-sm);
+    background: var(--rx-card);
+  }
+
+  .rx-shots__frame :global(img) {
+    display: block;
+    width: 100%;
+    height: auto;
+  }
+
+  /* Index beside the label, detail hanging under the label; the indent binds the pair. */
+  .rx-shots__caption {
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr);
+    column-gap: 0.7rem;
+    row-gap: 0.3rem;
+    margin-top: 0.9rem;
+    align-content: start;
+  }
+
+  .rx-shots__index,
+  .rx-shots__title {
+    grid-row: 1;
+    font-family: var(--rx-font-mono);
+    font-size: 0.74rem;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+  }
+
+  .rx-shots__index {
+    grid-column: 1;
+    color: var(--rx-faint);
+  }
+
+  .rx-shots__title {
+    grid-column: 2;
+    color: var(--rx-fg);
+  }
+
+  .rx-shots__body {
+    grid-column: 2;
+    grid-row: 2;
+    color: var(--rx-muted);
+    font-size: 0.9rem;
+    line-height: 1.5;
+    text-wrap: pretty;
+  }
+
+  .rx-shots__link {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.45rem;
+    margin-top: 1.75rem;
+    color: var(--rx-fg);
+    font-size: 0.95rem;
+    font-weight: 500;
+    text-decoration: none;
+    border-bottom: 1px solid var(--rx-rule-strong);
+    padding-bottom: 0.15rem;
+  }
+
+  .rx-shots__link:hover {
+    color: var(--rx-primary);
+    border-color: currentColor;
+  }
+</style>

package/src/components/Section.astro

@@ -0,0 +1,103 @@
+---
+/**
+ * A landing-page section: eyebrow, heading, lede, then the slot. `not-content` opts the subtree out
+ * of Starlight's prose rules, which would otherwise give every stat and card title a paragraph's measure.
+ */
+interface Props {
+  id?: string
+  eyebrow?: string
+  title: string
+  lede?: string
+  /** Draws the gradient hairline above the heading; the brand spends the gradient sparingly. */
+  accent?: boolean
+}
+
+const { id, eyebrow, title, lede, accent = false } = Astro.props
+---
+
+<section class:list={['rx-sec', 'not-content', { 'rx-sec--accent': accent }]} id={id}>
+  <header class="rx-sec__head">
+    {eyebrow && <p class="rx-sec__eyebrow">{eyebrow}</p>}
+    <h2 class="rx-sec__title">{title}</h2>
+    {lede && <p class="rx-sec__lede">{lede}</p>}
+  </header>
+  <slot />
+</section>
+
+<style>
+  /* Unlayered, so it beats Starlight's `.sl-container > * + *` gap without a specificity fight. */
+  .rx-sec {
+    margin-block: 5.5rem 0;
+  }
+
+  /* rem, not ch: `ch` resolves against this 1rem block, not the ~2.35rem heading it wraps. */
+  .rx-sec__head {
+    max-width: 48rem;
+    margin-bottom: 2rem;
+  }
+
+  .rx-sec__eyebrow {
+    margin: 0 0 0.75rem;
+    /* --rx-muted, not --rx-faint: faint on the card is ~3.4:1 and fails AA here. */
+    color: var(--rx-muted);
+    font-size: 0.75rem;
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+  }
+
+  .rx-sec__title {
+    margin: 0;
+    color: var(--rx-fg);
+    font-size: clamp(1.6rem, 1.15rem + 1.7vw, 2.35rem);
+    font-weight: 640;
+    line-height: 1.15;
+    letter-spacing: -0.02em;
+    text-wrap: balance;
+  }
+
+  .rx-sec__lede {
+    max-width: 62ch;
+    margin: 0.9rem 0 0;
+    color: var(--rx-muted);
+    font-size: 1.05rem;
+    line-height: 1.6;
+    text-wrap: pretty;
+  }
+
+  .rx-sec--accent .rx-sec__head {
+    padding-top: 1.75rem;
+    border-top: 2px solid transparent;
+    border-image: var(--rx-gradient) 1;
+  }
+
+  /* Direct children only: a descendant selector would outrank the slotted components' own scoped rules. */
+  .rx-sec > :global(pre) {
+    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;
+    font-size: 0.86rem;
+    line-height: 1.65;
+  }
+
+  .rx-sec > :global(p) {
+    margin: 1.5rem 0 0;
+    color: var(--rx-muted);
+    font-size: 0.98rem;
+    line-height: 1.62;
+  }
+
+  .rx-sec > :global(p a) {
+    color: var(--rx-primary);
+    font-weight: 500;
+  }
+
+  @media (min-width: 50rem) {
+    .rx-sec {
+      margin-block: 7rem 0;
+    }
+  }
+</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>

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>