@rxova/brand 0.10.0 → 0.12.0

package/README.md

@@ -69,20 +69,27 @@ import { PROJECTS } from '@rxova/brand'
 ---
 ```
 
-`astro.css` pulls in `tokens.css` and adds the reset and base element styles
-that Starlight gives docs sites for free.
+`astro.css` pulls in `chrome.css` — the tokens, the footer's styles and the
+short aliases — and adds the reset and base element styles that Starlight gives
+docs sites for free.
+
+Use `chrome.css` on its own where something else already owns the document, such
+as rxova-website's shell templates: their body is composed into a built
+Starlight page, and the reset in `astro.css` is unlayered, so it would outrank
+everything in `@layer starlight.*` and flatten that page.
 
 ## What's in it
 
-| Export                            | What it is                                                            |
-| --------------------------------- | --------------------------------------------------------------------- |
-| `@rxova/brand`                    | `PROJECTS`, `docsUrl()`, `siteUrl()`, `sharedStarlightConfig()`       |
-| `@rxova/brand/tokens.css`         | The `--rx-*` custom properties. Everything derives from these.        |
-| `@rxova/brand/starlight.css`      | For docs sites: maps `--rx-*` onto Starlight's `--sl-*`, plus chrome  |
-| `@rxova/brand/astro.css`          | For plain Astro sites: tokens, a reset, and base element styling      |
-| `@rxova/brand/fonts.css`          | Self-hosted Space Grotesk + IBM Plex Mono                             |
-| `@rxova/brand/components/*.astro` | `SiteTitle`, `SocialIcons`, `Footer`, `SiteFooter`, `ProjectSwitcher` |
-| `@rxova/brand/assets/*`           | The mark, logos and per-project OG images                             |
+| Export                            | What it is                                                             |
+| --------------------------------- | ---------------------------------------------------------------------- |
+| `@rxova/brand`                    | `PROJECTS`, `docsUrl()`, `siteUrl()`, `sharedStarlightConfig()`        |
+| `@rxova/brand/tokens.css`         | The `--rx-*` custom properties. Everything derives from these.         |
+| `@rxova/brand/starlight.css`      | For docs sites: maps `--rx-*` onto Starlight's `--sl-*`, plus chrome   |
+| `@rxova/brand/astro.css`          | For plain Astro sites: `chrome.css`, a reset, and base element styling |
+| `@rxova/brand/chrome.css`         | What the shared header and footer need, with nothing document-level    |
+| `@rxova/brand/fonts.css`          | Self-hosted Space Grotesk + IBM Plex Mono                              |
+| `@rxova/brand/components/*.astro` | `SiteTitle`, `SocialIcons`, `Footer`, `SiteFooter`, `ProjectSwitcher`  |
+| `@rxova/brand/assets/*`           | The mark, logos and per-project OG images                              |
 
 ## The palette
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rxova/brand",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "Design tokens, Starlight theme and shared site chrome for rxova.org",
   "keywords": [
@@ -33,6 +33,7 @@
     ".": "./src/index.ts",
     "./tokens.css": "./src/tokens.css",
     "./astro.css": "./src/astro.css",
+    "./chrome.css": "./src/chrome.css",
     "./starlight.css": "./src/starlight.css",
     "./fonts.css": "./src/fonts.css",
     "./components/*": "./src/components/*",

package/src/astro.css

@@ -1,42 +1,21 @@
 /**
- * Entry point for plain Astro surfaces — today, the rxova.org landing.
+ * Entry point for plain Astro surfaces that own their whole document — the
+ * rxova.org landing, /blog and /updates.
  *
  * Starlight sites use `starlight.css` instead; it maps the same tokens onto
- * Starlight's own variables. This file carries what a bare Astro page needs and
+ * Starlight's own variables. This file is `chrome.css` — the tokens, the footer
+ * and the short aliases — plus the two things a bare Astro page needs and
  * Starlight already provides: a reset and base element styling.
  *
- * It also aliases the short token names the landing was written against
- * (`--bg`, `--fg`, `--rule`, …) onto their `--rx-*` equivalents, so adopting
- * this package did not require rewriting several hundred lines of scoped
- * component styles in one go. New work should use `--rx-*` directly; the
- * aliases exist to make the migration incremental, not to be a second API.
+ * Load this only where nothing else owns the document. A surface that renders
+ * the shared chrome *into* someone else's document — rxova-website's shell
+ * templates, whose body is composed into a built Starlight page — must load
+ * `chrome.css` instead. The reset below is unlayered, so inside a Starlight
+ * document it would outrank every rule in `@layer starlight.*` and flatten the
+ * page; see chrome.css.
  */
 
-@import './tokens.css';
-/* The shared site footer, which /blog, /updates and the landing all render. It
-   is the one piece of chrome common to these surfaces and the Starlight ones,
-   so its rules sit in their own file and both entry points pull them in. */
-@import './footer.css';
-
-:root {
-  --bg: var(--rx-bg);
-  --fg: var(--rx-fg);
-  --muted: var(--rx-muted);
-  --faint: var(--rx-faint);
-  --rule: var(--rx-rule);
-  --card: var(--rx-card);
-  --tag-bg: var(--rx-tag-bg);
-  --glow-tint: var(--rx-glow-tint);
-  --font: var(--rx-font-sans);
-  --mono: var(--rx-font-mono);
-  --max: var(--rx-max);
-
-  /* The landing's `--accent` is the foreground, not the brand violet: its
-     design is deliberately monochrome and uses the gradient only as an accent
-     rule. Mapping this to --rx-primary would tint every focus ring on the
-     site. */
-  --accent: var(--rx-fg);
-}
+@import './chrome.css';
 
 /* --- Reset ---------------------------------------------------------------- */
 

package/src/chrome.css

@@ -0,0 +1,51 @@
+/**
+ * Everything the shared chrome needs, and nothing that touches the document.
+ *
+ * `Header`, `SiteFooter` and `ThemeToggle` are rendered on two kinds of page:
+ * plain Astro surfaces that own their whole document (the landing, /blog,
+ * /updates — see astro.css), and rxova-website's shell templates, whose body is
+ * composed into an already-complete Starlight document at deploy time.
+ *
+ * The second case is why this file exists. It carries the tokens, the footer's
+ * styles and the short aliases the chrome's scoped CSS is written against — but
+ * no reset and no base element styling. Those belong to whoever owns the
+ * document, and a shell that brings its own into a Starlight page destroys that
+ * page: Starlight puts all of its CSS in `@layer starlight.*`, and an unlayered
+ * `* { margin: 0; padding: 0 }` arriving from the shell beats every layered rule
+ * it has, whatever the specificity. That is not a hypothetical — it flattened
+ * every /packages/* docs page on rxova.org.
+ *
+ * So: load this to render the chrome, and astro.css (which is this plus the
+ * reset) to own a document.
+ */
+
+@import './tokens.css';
+/* The shared site footer, which /blog, /updates and the landing all render. It
+   is the one piece of chrome common to these surfaces and the Starlight ones,
+   so its rules sit in their own file and both entry points pull them in. */
+@import './footer.css';
+
+/* The short token names the landing and the shared chrome were written against
+   (`--bg`, `--fg`, `--rule`, …), aliased onto their `--rx-*` equivalents, so
+   adopting this package did not require rewriting several hundred lines of
+   scoped component styles in one go. New work should use `--rx-*` directly; the
+   aliases exist to make the migration incremental, not to be a second API. */
+:root {
+  --bg: var(--rx-bg);
+  --fg: var(--rx-fg);
+  --muted: var(--rx-muted);
+  --faint: var(--rx-faint);
+  --rule: var(--rx-rule);
+  --card: var(--rx-card);
+  --tag-bg: var(--rx-tag-bg);
+  --glow-tint: var(--rx-glow-tint);
+  --font: var(--rx-font-sans);
+  --mono: var(--rx-font-mono);
+  --max: var(--rx-max);
+
+  /* The landing's `--accent` is the foreground, not the brand violet: its
+     design is deliberately monochrome and uses the gradient only as an accent
+     rule. Mapping this to --rx-primary would tint every focus ring on the
+     site. */
+  --accent: var(--rx-fg);
+}

package/src/components/SiteShell.astro

@@ -22,14 +22,46 @@ interface Props {
   /** Canonical path, e.g. `/blog/why-rxova-has-a-blog`. Normalised below. */
   path: string
   ogType?: 'website' | 'article'
+  /**
+   * Absolute URL of the social card. Defaults to the umbrella card.
+   *
+   * A prop rather than something derived here, because what makes the best card
+   * differs per surface and only the caller knows: a post with a cover should
+   * share its cover, an update belongs to a project and should carry that
+   * project's card, and an index has neither.
+   */
+  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`.
+   *
+   * Structured data is the only way a crawler learns that /blog carries articles
+   * with an author and a date rather than prose it has to infer that from. Typed
+   * as unknown because the shapes differ per surface and schema.org is not worth
+   * modelling in TypeScript for three call sites.
+   */
+  jsonLd?: unknown
 }
 
-const { title, description, path, ogType = 'website' } = Astro.props
+const { title, description, path, ogType = 'website', image, feed, jsonLd } = Astro.props
 
 // Normalised here rather than at the four call sites: every one of them had
 // dropped the trailing slash, so every blog and updates page was declaring itself
 // canonical at a URL that 301s. A caller can forget again; this cannot.
 const canonical = canonicalUrl(path)
+
+const ogImage = image ?? siteUrl('/og/rxova.png')
+
+/**
+ * Serialise JSON-LD for an inline `<script>`.
+ *
+ * `<` is escaped because a `</script>` anywhere inside a string value — a post
+ * title about a tag, a description quoting markup — closes the element early and
+ * spills the rest of the payload into the document as text. `<` is valid
+ * JSON and parses back to `<`, so the structured data is unchanged.
+ */
+const serialiseJsonLd = (value: unknown): string => JSON.stringify(value).replace(/</g, '\\u003c')
 ---
 
 <!doctype html>
@@ -44,8 +76,14 @@ const canonical = canonicalUrl(path)
     <meta property="og:description" content={description} />
     <meta property="og:type" content={ogType} />
     <meta property="og:url" content={canonical} />
-    <meta property="og:image" content={siteUrl('/og/rxova.png')} />
+    <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)} />}
   </head>
   <body>
     <main>

package/src/feed.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest'
+
+import { escapeXml, renderFeed, rfc822, type FeedItem } from './feed.ts'
+
+const item = (over: Partial<FeedItem> = {}): FeedItem => ({
+  title: 'A post',
+  link: 'https://rxova.org/blog/a-post/',
+  description: 'What it is about.',
+  pubDate: new Date('2026-08-03T09:00:00Z'),
+  ...over,
+})
+
+describe('escapeXml', () => {
+  it('escapes the five XML entities', () => {
+    expect(escapeXml(`<a href="x">&'</a>`)).toBe(
+      '&lt;a href=&quot;x&quot;&gt;&amp;&apos;&lt;/a&gt;',
+    )
+  })
+
+  // The ordering bug this guards is silent: escape `<` before `&` and the
+  // ampersand introduced by `&lt;` is escaped again, shipping `&amp;lt;`.
+  it('does not double-escape the ampersands it introduces', () => {
+    expect(escapeXml('a < b')).toBe('a &lt; b')
+    expect(escapeXml('Tom & Jerry')).toBe('Tom &amp; Jerry')
+  })
+})
+
+describe('rfc822', () => {
+  // RSS 2.0 requires RFC 822 dates, not ISO 8601. A reader handed an ISO date
+  // either drops the item or dates it "now", and both look like the feed works.
+  it('formats as RFC 822, not ISO 8601', () => {
+    expect(rfc822(new Date('2026-08-09T09:00:00Z'))).toBe('Sun, 09 Aug 2026 09:00:00 GMT')
+  })
+})
+
+describe('renderFeed', () => {
+  const base = {
+    title: 'Rxova Blog',
+    description: 'Essays from the Rxova projects.',
+    siteUrl: 'https://rxova.org/blog/',
+    feedUrl: 'https://rxova.org/blog/rss.xml',
+  }
+
+  it('renders a channel with a self-referencing atom link', () => {
+    const xml = renderFeed({ ...base, items: [item()] })
+    expect(xml).toContain('<?xml version="1.0" encoding="UTF-8"?>')
+    expect(xml).toContain('<title>Rxova Blog</title>')
+    expect(xml).toContain(
+      '<atom:link href="https://rxova.org/blog/rss.xml" rel="self" type="application/rss+xml" />',
+    )
+  })
+
+  it('uses the entry URL as a permalink guid', () => {
+    const xml = renderFeed({ ...base, items: [item()] })
+    expect(xml).toContain('<guid isPermaLink="true">https://rxova.org/blog/a-post/</guid>')
+  })
+
+  it('keeps the order it was given', () => {
+    const xml = renderFeed({
+      ...base,
+      items: [item({ title: 'Newer' }), item({ title: 'Older' })],
+    })
+    expect(xml.indexOf('Newer')).toBeLessThan(xml.indexOf('Older'))
+  })
+
+  it('dates the build from the newest item when not told otherwise', () => {
+    const xml = renderFeed({ ...base, items: [item()] })
+    expect(xml).toContain('<lastBuildDate>Mon, 03 Aug 2026 09:00:00 GMT</lastBuildDate>')
+  })
+
+  it('omits lastBuildDate for an empty feed rather than emitting an invalid date', () => {
+    const xml = renderFeed({ ...base, items: [] })
+    expect(xml).not.toContain('lastBuildDate')
+    expect(xml).toContain('</channel>')
+  })
+
+  it('renders bylines as dc:creator, never as an email-shaped author', () => {
+    const xml = renderFeed({ ...base, items: [item({ authors: ['Jonatan Kruszewski'] })] })
+    expect(xml).toContain('<dc:creator>Jonatan Kruszewski</dc:creator>')
+    expect(xml).not.toContain('<author>')
+  })
+
+  it('escapes titles that carry markup characters', () => {
+    const xml = renderFeed({ ...base, items: [item({ title: 'Why <input> & you' })] })
+    expect(xml).toContain('<title>Why &lt;input&gt; &amp; you</title>')
+  })
+
+  it('renders categories from tags', () => {
+    const xml = renderFeed({ ...base, items: [item({ categories: ['react', 'intl'] })] })
+    expect(xml).toContain('<category>react</category>')
+    expect(xml).toContain('<category>intl</category>')
+  })
+})

package/src/feed.ts

@@ -0,0 +1,117 @@
+/**
+ * RSS 2.0 for the rxova.org surfaces that publish a stream.
+ *
+ * Hand-written rather than `@astrojs/rss`, for the same reason rxova-website
+ * hand-writes its sitemaps: this is a few hundred bytes of well-specified XML,
+ * both consumers are static Astro builds where the feed is one prerendered
+ * endpoint, and the dependency would be carried by two packages to save a
+ * `map()`. The escaping is the only part with teeth, and it is one function
+ * with its own tests.
+ *
+ * Deliberately in `@rxova/brand` rather than in either consumer: /blog and
+ * /updates are separate Astro projects that already share this package for
+ * their chrome, and a feed each would be the same file twice — which is how
+ * their two document shells came to differ before `SiteShell` existed.
+ *
+ * Node-only imports are avoided so this stays importable from an Astro
+ * endpoint in any runtime.
+ */
+
+/**
+ * Escape text for an XML text node or attribute value.
+ *
+ * `&` first, or the ampersands introduced by the later replacements get escaped
+ * a second time and `<` ships as `&amp;lt;`.
+ */
+export const escapeXml = (value: string): string =>
+  value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+
+export interface FeedItem {
+  title: string
+  /** Absolute URL. Also used as the guid, which is why it must be stable. */
+  link: string
+  description: string
+  pubDate: Date
+  /** Plain author names. Rendered as `<dc:creator>`, not `<author>`. */
+  authors?: readonly string[]
+  categories?: readonly string[]
+}
+
+export interface FeedOptions {
+  title: string
+  description: string
+  /** Absolute URL of the page this feed describes. */
+  siteUrl: string
+  /** Absolute URL of the feed document itself, for `atom:link rel="self"`. */
+  feedUrl: string
+  items: readonly FeedItem[]
+  /** Defaults to the newest item's date. */
+  lastBuildDate?: Date
+}
+
+/**
+ * RFC 822, which is what RSS 2.0 requires — not ISO 8601.
+ *
+ * `toUTCString()` produces exactly this shape ("Sun, 09 Aug 2026 09:00:00 GMT")
+ * and is locale-independent, so it is used directly rather than assembled from
+ * day and month tables that would need their own test.
+ */
+export const rfc822 = (date: Date): string => date.toUTCString()
+
+/**
+ * A complete RSS 2.0 document.
+ *
+ * `dc:creator` carries bylines because RSS's own `<author>` element is specified
+ * as an email address, and publishing the maintainer's address to every
+ * aggregator that has ever scraped a feed is not worth a byline.
+ *
+ * Items are emitted in the order given; both callers hand them over newest-first
+ * already, and re-sorting here would quietly disagree with the page the feed
+ * describes.
+ */
+export function renderFeed({
+  title,
+  description,
+  siteUrl,
+  feedUrl,
+  items,
+  lastBuildDate,
+}: FeedOptions): string {
+  const newest = items[0]?.pubDate
+  const built = lastBuildDate ?? newest
+
+  const entries = items.map((item) => {
+    const parts = [
+      `      <title>${escapeXml(item.title)}</title>`,
+      `      <link>${escapeXml(item.link)}</link>`,
+      // Permalink: the URL is the identity, so a re-dated entry keeps its guid
+      // and does not resurface in every reader as a new item.
+      `      <guid isPermaLink="true">${escapeXml(item.link)}</guid>`,
+      `      <description>${escapeXml(item.description)}</description>`,
+      `      <pubDate>${rfc822(item.pubDate)}</pubDate>`,
+      ...(item.authors ?? []).map((a) => `      <dc:creator>${escapeXml(a)}</dc:creator>`),
+      ...(item.categories ?? []).map((c) => `      <category>${escapeXml(c)}</category>`),
+    ]
+    return `    <item>\n${parts.join('\n')}\n    </item>`
+  })
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
+  <channel>
+    <title>${escapeXml(title)}</title>
+    <link>${escapeXml(siteUrl)}</link>
+    <description>${escapeXml(description)}</description>
+    <language>en</language>
+    <atom:link href="${escapeXml(feedUrl)}" rel="self" type="application/rss+xml" />${
+      built ? `\n    <lastBuildDate>${rfc822(built)}</lastBuildDate>` : ''
+    }
+${entries.join('\n')}
+  </channel>
+</rss>
+`
+}

package/src/footer.css

@@ -7,9 +7,9 @@
  * is why /blog and /updates shipped a dot-separated link row instead — the
  * shared footer would have rendered unstyled there.
  *
- * Imported by both `starlight.css` and `astro.css`; nothing needs to import it
+ * Imported by both `starlight.css` and `chrome.css`; nothing needs to import it
  * directly. Written against `--rx-*` tokens only, so it does not depend on the
- * short aliases astro.css defines.
+ * short aliases chrome.css defines.
  */
 
 @import './tokens.css';

package/src/index.ts

@@ -22,3 +22,5 @@ export {
 } from './sites.ts'
 
 export { sharedStarlightConfig, type SharedStarlightOptions } from './starlight.ts'
+
+export { renderFeed, escapeXml, rfc822, type FeedItem, type FeedOptions } from './feed.ts'

package/src/sites.ts

@@ -50,8 +50,14 @@ export const PROJECTS: readonly Project[] = [
     packages: [
       '@rxova/react-inputs',
       '@rxova/react-intl-currency-input',
-      '@rxova/react-otp-input',
       '@rxova/react-rating-input',
+      '@rxova/react-otp-input',
+      '@rxova/react-password-input',
+      '@rxova/react-phone-input',
+      '@rxova/react-date-input',
+      '@rxova/react-time-input',
+      '@rxova/react-tags-input',
+      '@rxova/react-file-input',
     ],
   },
   {

package/src/starlight.ts

@@ -96,6 +96,33 @@ export function sharedStarlightConfig({
         tag: 'meta' as const,
         attrs: { name: 'twitter:card', content: 'summary_large_image' },
       },
+      // What this project *is*, in the vocabulary a crawler already parses.
+      //
+      // Every field is read from PROJECTS, so a project that changes its tagline
+      // or adds a package updates its structured data with it — the failure this
+      // avoids is the usual one for hand-written JSON-LD, which is that it
+      // describes the site as it was when someone last remembered to edit it.
+      //
+      // Emitted on every page of the docs rather than only the root: Starlight
+      // has no "site index only" hook, and repeating an identical
+      // SoftwareSourceCode across a subtree is well-formed — each page really is
+      // documentation for that one piece of software.
+      {
+        tag: 'script' as const,
+        attrs: { type: 'application/ld+json' },
+        content: JSON.stringify({
+          '@context': 'https://schema.org',
+          '@type': 'SoftwareSourceCode',
+          name: self.label,
+          description: self.tagline,
+          url: `${RXOVA_ORIGIN}${self.mount}`,
+          codeRepository: self.repo,
+          programmingLanguage: 'TypeScript',
+          runtimePlatform: 'Node.js',
+          license: 'https://opensource.org/licenses/MIT',
+          author: { '@type': 'Person', name: 'Jonatan Kruszewski' },
+        }).replace(/</g, '\\u003c'),
+      },
     ],
 
     // Pagefind ships with Starlight and replaces the third-party search plugin