@ciderpress/ui 1.0.0-rc.10 → 1.0.0-rc.11

package/src/theme/lib/rich-text.test.tsx

@@ -0,0 +1,342 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, it, expect, vi } from 'vitest'
+
+import { hasAccentMarker, isPlainText, renderRichText, toPlainText } from './rich-text.tsx'
+
+// `RouteLink` pulls in Rspress's router, which resolves the
+// `virtual-routes` module only inside a real build. Stand in a plain
+// anchor so link output is assertable.
+vi.mock('@rspress/core/runtime', async () => {
+  const react = await import('react')
+  return {
+    Link: (props: { readonly to: string; readonly children?: React.ReactNode }) =>
+      react.createElement('a', { href: props.to }, props.children),
+  }
+})
+
+describe('renderRichText()', () => {
+  it('should render plain copy unchanged', () => {
+    expect(html('Beautiful docs')).toBe('Beautiful docs')
+  })
+
+  it('should render emphasis markers as a branded strong', () => {
+    expect(html('Ship **fast**')).toContain('<strong class="cp-accent">fast</strong>')
+  })
+
+  it('should render html strong as plain bold, without the accent', () => {
+    const out = html('Ship <strong>fast</strong>')
+    expect(out).toContain('<strong>fast</strong>')
+    expect(out).not.toContain('cp-accent')
+  })
+
+  it('should render italic markers as em', () => {
+    expect(html('Ship *fast*')).toContain('<em>fast</em>')
+  })
+
+  it('should accent only the marked words', () => {
+    const out = html('Docs, **Zero Effort**')
+    expect(out).toContain('Docs, ')
+    expect(out).toContain('<strong class="cp-accent">Zero Effort</strong>')
+  })
+
+  it('should render highlight markers as a tinted mark', () => {
+    expect(html('Now with ==OpenAPI==')).toContain('<mark class="cp-mark">OpenAPI</mark>')
+  })
+
+  it('should keep highlight and accent distinct', () => {
+    const out = html('**accent** and ==highlight==')
+    expect(out).toContain('<strong class="cp-accent">accent</strong>')
+    expect(out).toContain('<mark class="cp-mark">highlight</mark>')
+  })
+
+  it('should render code spans literally', () => {
+    expect(html('Run `ciderpress dev`')).toContain('<code>ciderpress dev</code>')
+  })
+
+  it('should not parse markers inside a code span', () => {
+    expect(html('`**not accented**`')).toContain('<code>**not accented**</code>')
+  })
+
+  it('should render an external markdown link as an anchor', () => {
+    const out = html('See [the site](https://example.com)')
+    expect(out).toContain('href="https://example.com"')
+    expect(out).toContain('the site')
+  })
+
+  it('should render an internal markdown link', () => {
+    expect(html('See [the guide](/guides)')).toContain('href="/guides"')
+  })
+
+  it('should render a whitelisted anchor tag', () => {
+    expect(html('<a href="/guides">docs</a>')).toContain('href="/guides"')
+  })
+
+  it('should drop an anchor tag with an unsafe scheme but keep its text', () => {
+    const out = html('<a href="javascript:alert(1)">click</a>')
+    expect(out).not.toContain('javascript')
+    expect(out).toContain('click')
+  })
+
+  it('should drop a markdown link with an unsafe scheme but keep its text', () => {
+    const out = html('[click](javascript:alert(1))')
+    expect(out).not.toContain('javascript')
+    expect(out).not.toContain('<a')
+    expect(out).toContain('click')
+  })
+
+  it('should keep the class attribute on a whitelisted tag', () => {
+    expect(html('<span class="x">hi</span>')).toContain('<span class="x">hi</span>')
+  })
+
+  it('should drop event handler attributes', () => {
+    const out = html('<span onclick="alert(1)">hi</span>')
+    expect(out).not.toContain('onclick')
+    expect(out).toContain('hi')
+  })
+
+  it('should drop script tags and their contents', () => {
+    const out = html('safe<script>alert(1)</script>after')
+    expect(out).not.toContain('alert')
+    expect(out).toContain('safe')
+    expect(out).toContain('after')
+  })
+
+  it('should drop an unterminated script tag and everything after it', () => {
+    const out = html('safe<script>alert(1)')
+    expect(out).not.toContain('alert')
+    expect(out).toContain('safe')
+  })
+
+  it('should unwrap unknown tags but keep their text', () => {
+    const out = html('<div>kept</div>')
+    expect(out).not.toContain('<div>')
+    expect(out).toContain('kept')
+  })
+
+  it('should drop an img tag but keep surrounding copy', () => {
+    const out = html('<img src="x" onerror="alert(1)">shown')
+    expect(out).not.toContain('onerror')
+    expect(out).not.toContain('<img')
+    expect(out).toContain('shown')
+  })
+
+  it('should render br as a line break', () => {
+    expect(html('a<br>b')).toContain('<br/>')
+  })
+
+  it('should render a self-closed br', () => {
+    expect(html('a<br />b')).toContain('<br/>')
+  })
+
+  it('should render a self-closed whitelisted tag as empty', () => {
+    expect(html('a<span class="x" />b')).toContain('<span class="x"></span>')
+  })
+
+  it('should keep attributes on a tag with extra whitespace', () => {
+    expect(html('<span   class="x"   >hi</span>')).toContain('<span class="x">hi</span>')
+  })
+
+  it('should nest markup inside an accent', () => {
+    expect(html('**Zero `dev` Effort**')).toContain('<code>dev</code>')
+  })
+
+  it('should leave a stray closing tag out of the output', () => {
+    const out = html('text</span>')
+    expect(out).not.toContain('</span>')
+    expect(out).toContain('text')
+  })
+
+  it('should return null for empty copy', () => {
+    expect(renderRichText('')).toBeNull()
+  })
+})
+
+describe('toPlainText()', () => {
+  it('should strip accent markers', () => {
+    expect(toPlainText('Docs, **Zero Effort**')).toBe('Docs, Zero Effort')
+  })
+
+  it('should strip highlight markers', () => {
+    expect(toPlainText('Now with ==OpenAPI== support')).toBe('Now with OpenAPI support')
+  })
+
+  it('should strip emphasis and italic markers', () => {
+    expect(toPlainText('Ship **fast** and *typed*')).toBe('Ship fast and typed')
+  })
+
+  it('should keep code span contents', () => {
+    expect(toPlainText('Run `ciderpress dev`')).toBe('Run ciderpress dev')
+  })
+
+  it('should reduce a link to its label', () => {
+    expect(toPlainText('See [the guide](/guides)')).toBe('See the guide')
+  })
+
+  it('should strip html tags but keep their text', () => {
+    expect(toPlainText('Ship <strong>fast</strong>')).toBe('Ship fast')
+  })
+
+  it('should drop script contents', () => {
+    expect(toPlainText('safe<script>alert(1)</script>')).toBe('safe')
+  })
+
+  it('should return an empty string for empty copy', () => {
+    expect(toPlainText('')).toBe('')
+  })
+})
+
+describe('hasAccentMarker()', () => {
+  it('should detect an accent marker', () => {
+    expect(hasAccentMarker('Docs, **Zero Effort**')).toBe(true)
+  })
+
+  it('should return false without a marker', () => {
+    expect(hasAccentMarker('Docs, Zero Effort')).toBe(false)
+  })
+
+  it('should return false for a lone marker', () => {
+    expect(hasAccentMarker('a ** b')).toBe(false)
+  })
+
+  it('should not treat html strong as an explicit accent', () => {
+    expect(hasAccentMarker('Docs, <strong>Zero Effort</strong>')).toBe(false)
+  })
+
+  it('should not treat a highlight marker as an accent', () => {
+    expect(hasAccentMarker('Docs, ==Zero Effort==')).toBe(false)
+  })
+
+  it('should not treat a marker inside a code span as an accent', () => {
+    expect(hasAccentMarker('Write `**bold**` for the accent')).toBe(false)
+  })
+
+  it('should detect an accent nested inside a link', () => {
+    expect(hasAccentMarker('[**Docs**](/docs)')).toBe(true)
+  })
+})
+
+describe('isPlainText()', () => {
+  it('should return true for unmarked copy', () => {
+    expect(isPlainText('Beautiful Docs, Zero Effort')).toBe(true)
+  })
+
+  it('should return false for copy carrying a link', () => {
+    expect(isPlainText('See [the guide](/guides)')).toBe(false)
+  })
+
+  it('should return false for copy carrying a code span', () => {
+    expect(isPlainText('Run `ciderpress dev`')).toBe(false)
+  })
+
+  it('should return false for copy carrying html', () => {
+    expect(isPlainText('Ship <strong>fast</strong>')).toBe(false)
+  })
+})
+
+describe('tag nesting', () => {
+  // `indexOf('</' + tag)` matched `</span>` when closing `</s`, so the inner
+  // element vanished and the outer one ended early, letting trailing copy
+  // escape its styling. Every whitelisted tag that prefixes another hit it.
+  it('should not close a tag on a longer tag that shares its prefix', () => {
+    expect(html('<s>a <span>b</span> c</s>')).toBe('<s>a <span>b</span> c</s>')
+  })
+
+  it('should nest strong inside s', () => {
+    expect(html('<s>strike <strong>x</strong> tail</s>')).toBe(
+      '<s>strike <strong>x</strong> tail</s>'
+    )
+  })
+
+  it('should nest ins inside i', () => {
+    expect(html('<i>a <ins>b</ins> c</i>')).toBe('<i>a <ins>b</ins> c</i>')
+  })
+
+  it('should keep an attribute value containing a closing bracket', () => {
+    expect(html('<span title="a > b">hi</span>')).toBe('<span title="a &gt; b">hi</span>')
+  })
+
+  it('should still strip a script nested inside another tag', () => {
+    expect(html('<s>a<script>alert(1)</script>b</s>')).toBe('<s>ab</s>')
+  })
+})
+
+describe('escaping', () => {
+  // A docs framework has to be able to name a glob in its own copy.
+  it('should leave glob syntax alone', () => {
+    expect(html('Glob patterns like *.md and **/*.ts')).toBe('Glob patterns like *.md and **/*.ts')
+  })
+
+  it('should not italicise a spaced asterisk', () => {
+    expect(html('2 * 3 * 4')).toBe('2 * 3 * 4')
+  })
+
+  it('should render an escaped marker literally', () => {
+    expect(html('literal \\*not italic\\*')).toBe('literal *not italic*')
+  })
+
+  it('should strip markers out of plain text without eating the glob', () => {
+    expect(toPlainText('Glob **/*.ts')).toBe('Glob **/*.ts')
+  })
+
+  it('should still italicise a properly flanked marker', () => {
+    expect(html('*café*')).toBe('<em>café</em>')
+  })
+
+  it('should not let a stray asterisk swallow a later accent', () => {
+    expect(html('**Fast** builds * **typed** config')).toBe(
+      '<strong class="cp-accent">Fast</strong> builds * <strong class="cp-accent">typed</strong> config'
+    )
+  })
+})
+
+describe('links', () => {
+  it('should keep balanced parens in a destination', () => {
+    expect(html('[wiki](https://en.wikipedia.org/wiki/Foo_(bar))')).toContain(
+      'href="https://en.wikipedia.org/wiki/Foo_(bar)"'
+    )
+  })
+
+  it('should not leave a stray bracket after a parenthesised destination', () => {
+    expect(html('[wiki](https://en.wikipedia.org/wiki/Foo_(bar))')).not.toContain('</a>)')
+  })
+
+  // An anchor with no accessible name announces as a bare "link".
+  it('should drop a link with an empty label', () => {
+    expect(html('[](/x)')).toBe('')
+  })
+
+  // Nested anchors are invalid DOM — React warns and browsers split the tree.
+  it('should not nest an anchor inside an anchor', () => {
+    expect(html('<a href="/a">see [b](/c)</a>')).toBe('<a href="/a">see b</a>')
+  })
+
+  it('should still reject a javascript destination', () => {
+    expect(html('<a href="javascript:alert(1)">x</a>')).toBe('x')
+  })
+})
+
+describe('long input', () => {
+  // Self-recursion added a frame per token, so long copy overflowed the
+  // stack with an unattributed RangeError that failed the whole build.
+  it('should parse many tokens without exhausting the stack', () => {
+    expect(() => renderRichText('*a* '.repeat(9000))).not.toThrow()
+  })
+
+  // Closing-tag lookup had the same shape: it recursed once per `</tag`
+  // occurrence in the remainder rather than per nesting level, so a run of
+  // prefix hits overflowed the stack on markup only one level deep.
+  it('should scan past many close-tag prefixes without exhausting the stack', () => {
+    expect(() => renderRichText(`<s>${'</should'.repeat(30000)}`)).not.toThrow()
+  })
+})
+
+/**
+ * Render copy to static markup for assertions.
+ *
+ * @private
+ * @param text - Raw copy to render
+ * @returns Rendered HTML string
+ */
+function html(text: string): string {
+  return renderToStaticMarkup(<>{renderRichText(text)}</>)
+}

package/src/theme/lib/rich-text.tsx

@@ -0,0 +1,86 @@
+import { match } from 'massaman/match'
+import type React from 'react'
+import { createElement } from 'react'
+
+import type { InlineNode } from './rich-text-parse.ts'
+import { parseRichText } from './rich-text-parse.ts'
+import { RouteLink } from './route-link.tsx'
+
+export { hasAccentMarker, isPlainText, toPlainText } from './rich-text-parse.ts'
+
+/**
+ * Render config copy as React nodes, applying an inline-only markdown
+ * subset plus a whitelist of inline HTML.
+ *
+ * Supported: `**accent**`, `*italic*`, `` `code` ``, `[text](/href)`,
+ * `<br>`, and a whitelist of inline tags. Parsing and
+ * sanitizing happen in `rich-text-parse`; this renders the resulting
+ * nodes as React elements, so `dangerouslySetInnerHTML` is never
+ * involved and unknown markup cannot execute.
+ *
+ * @param text - Raw string from config or frontmatter
+ * @returns React nodes ready to render inline
+ *
+ * @example
+ * renderRichText('Beautiful Docs, **Zero Effort**')
+ * renderRichText('Runs on `ciderpress dev` — see [the guide](/guides).')
+ */
+export function renderRichText(text: string): React.ReactNode {
+  const nodes = parseRichText(text)
+  if (nodes.length === 0) {
+    return null
+  }
+  return renderNodes(nodes)
+}
+
+interface RichTextProps {
+  /**
+   * Raw copy to render.
+   */
+  readonly text: string
+}
+
+/**
+ * Component form of {@link renderRichText}, for call sites that read
+ * better as an element than a function call.
+ *
+ * @param props - Raw copy to render
+ * @returns Rendered inline nodes
+ */
+export function RichText(props: RichTextProps): React.ReactElement {
+  return <>{renderRichText(props.text)}</>
+}
+
+/**
+ * Render parsed nodes to React, keyed by position.
+ *
+ * @private
+ * @param nodes - Parsed inline nodes
+ * @returns React nodes
+ */
+function renderNodes(nodes: readonly InlineNode[]): React.ReactNode {
+  return nodes.map((node, index) => <RichNode key={index} node={node} />)
+}
+
+interface RichNodeProps {
+  readonly node: InlineNode
+}
+
+/**
+ * Render one parsed node.
+ *
+ * @private
+ * @param props - The node to render
+ * @returns React element
+ */
+function RichNode(props: RichNodeProps): React.ReactElement {
+  return match(props.node)
+    .with({ kind: 'text' }, (n) => <>{n.value}</>)
+    .with({ kind: 'code' }, (n) => <code>{n.value}</code>)
+    .with({ kind: 'break' }, () => <br />)
+    .with({ kind: 'link' }, (n) => <RouteLink href={n.href}>{renderNodes(n.children)}</RouteLink>)
+    .with({ kind: 'element' }, (n) =>
+      createElement(n.tag, { className: n.className, title: n.title }, renderNodes(n.children))
+    )
+    .exhaustive()
+}

package/src/theme/styles/overrides/fonts.css

@@ -1,10 +1,13 @@
 /**
  * Self-hosted Geist fonts (vercel/geist-font).
  *
- * `Geist` is the base sans-serif (used everywhere by default).
- * `Geist Pixel Square` is a decorative pixel font kept available via
- * `--cp-font-family-pixel` for the brand mark and any opt-in surfaces.
- * `Geist Mono` is used for code, eyebrow labels, status pills, etc.
+ * These `@font-face` rules only make the faces *available*. Which face a
+ * surface actually uses is decided by the active theme's `fonts.family`
+ * tokens — see `styles/overrides/tokens.css`. The built-in themes map
+ * `mono` to `Geist Mono` and `display` to `Geist Pixel Square`, and leave
+ * `sans` proportional (the Inter stack) so body, nav, sidebar and hero copy
+ * stay readable; `Geist` is shipped for custom themes that want a
+ * proportional face from this family instead.
  */
 
 @font-face {

package/src/theme/styles/overrides/home.css

@@ -158,10 +158,18 @@
     font-size: 11px;
     text-transform: uppercase;
     letter-spacing: 0.1em;
-    color: var(--cp-c-brand-1);
+    /* Eyebrows are 11px, so the 4.5:1 bar applies. `--cp-c-brand-1` is a fill
+       colour and misses it in four theme/variant pairs (2.38:1 on mulled dark,
+       4.10:1 on honeycrisp dark, ~3.1:1 on amber and grannysmith light), so
+       take the same shade pair `.cp-accent` uses — see styles/rich-text.css. */
+    color: var(--cp-c-brand-2, var(--cp-c-brand-1));
     margin-bottom: 12px;
   }
 
+  html[data-cp-variant='dark'] .cp-feature-section-head__eyebrow {
+    color: var(--cp-c-brand-light, var(--cp-c-brand-1));
+  }
+
   .cp-feature-section-head__title {
     font-size: clamp(28px, 4vw, 44px);
     font-weight: 600;
@@ -183,7 +191,8 @@
    through as hairlines between cells. Each cell paints its own panel bg. */
   .cp-feature-grid {
     display: grid;
-    grid-template-columns: repeat(3, 1fr);
+    /* `--cp-feature-cols` is set inline from the block's `columns` key. */
+    grid-template-columns: repeat(var(--cp-feature-cols, 3), 1fr);
     gap: 1px;
     background: var(--cp-c-border);
     border: 1px solid var(--cp-c-border);

package/src/theme/styles/overrides/rspress.css

@@ -16,11 +16,16 @@
  */
 
 @layer ciderpress.overrides {
-  html:root {
-    /* Fonts — map Geist into Rspress's font stack */
-    --rp-font-family-base: 'Geist', ui-sans-serif, system-ui, sans-serif;
-    --rp-font-family-mono: 'Geist Mono', ui-monospace, 'SFMono-Regular', monospace;
-  }
+  /* ── Fonts — deliberately NOT set here.
+
+     Rspress declares `--rp-font-family-base` / `--rp-font-family-mono` on
+     `:root` *unlayered*, and unlayered declarations beat every cascade
+     layer regardless of selector specificity — so a `html:root` rule in
+     this layer silently lost and Rspress's Inter/Menlo defaults stayed in
+     force. Both vars are now emitted from the active theme's own unlayered
+     block (`COMPAT_VAR_MAP` in `@ciderpress/theme`), which wins on
+     specificity, with a fallback declaration in
+     `styles/overrides/tokens.css`. ─────────────────────────────────── */
 
   /* ── LLMs UI — Ciderpress mounts its own `<LlmsContainer />` inside
      `<CiderpressDocsBar />`. The H1 placement is suppressed natively

package/src/theme/styles/overrides/tokens.css

@@ -35,30 +35,43 @@
   :root {
     /* ── Font families ──────────────────────────────────────── */
     /**
-   * Default body / UI font — Geist Mono. Whole site reads as a
-   * terminal-style mono surface.
+   * The active theme owns every font on the page. `--cp-ff-sans`,
+   * `--cp-ff-mono`, and `--cp-ff-display` are the canonical tokens
+   * (`fonts.family.{sans,mono,display}` in `@ciderpress/theme`); each theme
+   * emits all three from its own unlayered block, so the values below only
+   * apply when no theme CSS is present at all.
+   *
+   * Semantics:
+   *   sans     base UI + prose font — body, nav, sidebar, hero, cards, docs
+   *   mono     code, terminal chrome, eyebrow labels
+   *   display  decorative headline / brand-mark face (falls back to sans)
+   *
+   * These values mirror `SHARED_FONTS.family` in `@ciderpress/theme`, so a
+   * themeless page degrades to the house default rather than to a different
+   * design: `sans` is proportional (Inter), `mono` is Geist Mono, `display`
+   * is Geist Pixel Square. Putting the mono stack in `sans` turns every
+   * proportional surface — hero, body, nav, sidebar — monospace; the
+   * regression guard in `packages/theme/src/fonts.test.ts` exists for that.
    */
-    --cp-font-family-base: 'Geist Mono', ui-monospace, 'SFMono-Regular', monospace;
-    /**
-   * Optional sans fallback — exposed for cases that explicitly want
-   * proportional Geist (e.g. very long prose passages).
-   */
-    --cp-font-family-sans: 'Geist', ui-sans-serif, system-ui, sans-serif;
-    /**
-   * Decorative pixel-art font — opt-in for brand marks, headlines, etc.
-   * Apply with `font-family: var(--cp-font-family-pixel)` on the target.
-   */
-    --cp-font-family-pixel: 'Geist Pixel Square', ui-sans-serif, system-ui, sans-serif;
+    --cp-ff-sans:
+      'Inter var experimental', 'Inter var', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
+      Oxygen, Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
+    --cp-ff-mono: 'Geist Mono', ui-monospace, 'SFMono-Regular', monospace;
+    --cp-ff-display: 'Geist Pixel Square', ui-sans-serif, system-ui, sans-serif;
+
     /**
-   * Monospace alias — same as base. Kept for callsites that explicitly
-   * tag "this should be monospace" (code, shortcuts, eyebrow labels) so
-   * the intent stays readable in the stylesheet.
+   * Compatibility aliases. Every one of these resolves through a canonical
+   * token above, so a rule written against the older name still follows the
+   * active theme. Themes re-declare them in their own block (see
+   * `COMPAT_VAR_MAP` in `@ciderpress/theme`) — the declarations here are the
+   * no-theme-CSS fallback.
    */
-    --cp-font-family-mono: 'Geist Mono', ui-monospace, 'SFMono-Regular', monospace;
-
-    /* Canonical aliases matching TOKEN_TO_CSS_VAR (fonts.family.sans/mono). */
-    --cp-ff-sans: var(--cp-font-family-sans);
-    --cp-ff-mono: var(--cp-font-family-mono);
+    --cp-font-family-base: var(--cp-ff-sans);
+    --cp-font-family-sans: var(--cp-ff-sans);
+    --cp-font-family-mono: var(--cp-ff-mono);
+    --cp-font-family-pixel: var(--cp-ff-display);
+    --rp-font-family-base: var(--cp-ff-sans);
+    --rp-font-family-mono: var(--cp-ff-mono);
 
     /* ── Font weights ───────────────────────────────────────── */
     --cp-fw-regular: 400;
@@ -272,13 +285,18 @@
     --cp-announce-h: 36px;
   }
 
-  /* ── Typography defaults — match the mockup (14px / 1.5 / Geist) ── */
+  /* ── Typography defaults — match the mockup (14px / 1.5) ──────────
+     `body` is listed for completeness only: Rspress's own unlayered
+     `body { font-family: var(--rp-font-family-base) }` outranks anything
+     in a layer, so the document font is really carried by the theme's
+     `--rp-font-family-base` declaration. Both sides resolve to
+     `fonts.family.sans`, so the two agree. ──────────────────────────── */
   html body,
   html .rp-doc,
   html .rspress-doc,
   html .rp-home-hero,
   html .rp-nav {
-    font-family: var(--cp-font-family-base);
+    font-family: var(--cp-ff-sans);
   }
 
   html body {