@rxova/brand 0.11.0 → 0.13.0

package/README.md

@@ -9,17 +9,18 @@
 
 ## Why this exists
 
-`rxova.org` serves four surfaces from one origin — an Astro landing at `/`, plus
+`rxova.org` serves one surface per project from a single origin — an Astro
+landing at `/`, plus [overlock](https://github.com/rxova/overlock),
 [journey](https://github.com/rxova/journey),
 [react-inputs](https://github.com/rxova/react-inputs) and
 [use-everywhere](https://github.com/rxova/use-everywhere) docs, each built in its
 own repo and mounted as a static tree under `/packages/<name>/`.
 
-They were built independently and ended up looking like four unrelated products:
-three different accent colours, three different footers, no way to navigate from
+They were built independently and ended up looking like unrelated products:
+a different accent colour each, a different footer each, no way to navigate from
 one project's docs to another's. This package is the single source of truth that
-makes them one site — and it lives in its own repo because it is consumed by four
-and owned by none.
+makes them one site — and it lives in its own repo because it is consumed by all
+of them and owned by none.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rxova/brand",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "Design tokens, Starlight theme and shared site chrome for rxova.org",
   "keywords": [
@@ -59,7 +59,7 @@
     "@resvg/resvg-js": "^2.6.2",
     "@types/node": "^26.1.1",
     "@vitest/coverage-v8": "^4.1.10",
-    "astro": "^7.1.3",
+    "astro": "^7.3.2",
     "publint": "^0.3.21",
     "satori": "^0.29.0",
     "tsx": "^4.23.1",

package/src/components/SiteFooter.astro

@@ -67,14 +67,15 @@ const surfaces: readonly SiteLink[] = site ?? [
         <span>Rxova</span>
       </a>
       {
-        /* Not "React libraries": two of the three ship a framework-agnostic
-           core that runs in a worker or a plain script, and Journey also ships a
-           browser extension. React is a binding we provide, not the boundary of
+        /* Not "React libraries": most of these ship a framework-agnostic core
+           that runs in a worker or a plain script, Journey also ships a browser
+           extension, and overlock is a command-line tool that never sees a
+           browser at all. React is a binding we provide, not the boundary of
            what these are. Same correction as the landing's hero. */
       }
       <p class="rx-footer__blurb">
-        Small TypeScript libraries for the browser, documented in one place. MIT licensed, built in
-        the open.
+        Small TypeScript libraries and developer tools, documented in one place. MIT licensed, built
+        in the open.
       </p>
     </div>
 

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/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

@@ -3,7 +3,7 @@
  *
  * rxova.org is an aggregator: an Astro landing at `/`, plus each project's docs
  * built in its own repo and mounted as a static tree under `/packages/<name>/`.
- * That means four surfaces live on one origin at four different base paths, so
+ * That means every surface lives on one origin at its own base path, so
  * **every cross-project link must be absolute**. A relative href would resolve
  * against the local base and produce `/packages/journey/packages/react-inputs/`.
  *
@@ -14,7 +14,7 @@
 /** Canonical origin. Override for a staging deploy (e.g. https://web.rxova.org). */
 export const RXOVA_ORIGIN = process.env.RXOVA_ORIGIN ?? 'https://rxova.org'
 
-export type ProjectId = 'journey' | 'react-inputs' | 'use-everywhere'
+export type ProjectId = 'overlock' | 'journey' | 'react-inputs' | 'use-everywhere'
 
 export interface Project {
   id: ProjectId
@@ -31,6 +31,15 @@ export interface Project {
 }
 
 export const PROJECTS: readonly Project[] = [
+  {
+    id: 'overlock',
+    label: 'overlock',
+    mount: '/packages/overlock/',
+    tagline: 'A deterministic gate on test integrity in a git patch.',
+    repo: 'https://github.com/rxova/overlock',
+    npm: 'https://www.npmjs.com/package/overlock',
+    packages: ['overlock'],
+  },
   {
     id: 'journey',
     label: 'Journey',
@@ -50,8 +59,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