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

package/dist/theme/components/home/home-visual.tsx

@@ -6,6 +6,7 @@ import type React from 'react'
 import { withMountBase } from '../../lib/with-mount-base.ts'
 
 import './hero-demo.css'
+import './home-visual.css'
 
 /**
  * Surface a {@link HomeVisual} is rendered into.
@@ -47,7 +48,7 @@ export function HomeVisualView(props: HomeVisualViewProps): React.ReactElement |
   return match(visual)
     .with({ type: 'code' }, (v) => renderCode(v.code, v.language, context))
     .with({ type: 'image' }, (v) => renderImage(v, context))
-    .with({ type: 'terminal' }, (v) => <VisualTerminal config={v} />)
+    .with({ type: 'terminal' }, (v) => <VisualTerminal config={v} context={context} />)
     .otherwise(() => null)
 }
 
@@ -122,6 +123,7 @@ function renderImage(image: VisualImageFields, context: HomeVisualContext): Reac
 
 interface VisualTerminalProps {
   readonly config: HomeVisualTerminal
+  readonly context: HomeVisualContext
 }
 
 /**
@@ -135,6 +137,9 @@ interface VisualTerminalProps {
  */
 function VisualTerminal(props: VisualTerminalProps): React.ReactElement {
   const { windowTitle, command, lines } = props.config
+  const className = match(props.context)
+    .with('hero', () => 'cp-home-terminal cp-home-terminal--framed')
+    .otherwise(() => 'cp-home-terminal')
   // Hand-authored frontmatter bypasses the schema; a non-string here
   // reaches React as a child and throws mid-render.
   const commandText = match(command)
@@ -153,17 +158,19 @@ function VisualTerminal(props: VisualTerminalProps): React.ReactElement {
     )
     .otherwise(() => [])
   return (
-    <div className="cp-hero-demo">
-      <div className="cp-hero-demo__bar">
-        <span className="cp-hero-demo__dot" />
-        <span className="cp-hero-demo__dot" />
-        <span className="cp-hero-demo__dot" />
+    <div className={className} role="group" aria-label="Terminal output">
+      <div className="cp-home-terminal__bar">
+        <span className="cp-home-terminal__dots" aria-hidden="true">
+          <span className="cp-home-terminal__dot cp-home-terminal__dot--close" />
+          <span className="cp-home-terminal__dot cp-home-terminal__dot--minimize" />
+          <span className="cp-home-terminal__dot cp-home-terminal__dot--maximize" />
+        </span>
         {match(title)
-          .with(P.string, (w) => <span className="cp-hero-demo__title">{w}</span>)
+          .with(P.string, (w) => <span className="cp-home-terminal__title">{w}</span>)
           .otherwise(() => null)}
       </div>
-      <pre className="cp-hero-demo__body">
-        <span className="cp-hero-demo__prompt">$ </span>
+      <pre className="cp-home-terminal__body">
+        <span className="cp-home-terminal__prompt">$ </span>
         {commandText}
         {'\n\n'}
         {output.map((line, i) => (
@@ -208,10 +215,10 @@ function TerminalLine(props: TerminalLineProps): React.ReactElement {
   // hand-authored frontmatter — fall back to the neutral marker rather
   // than throwing on an unknown value.
   const className = match(props.line.kind)
-    .with('ok', () => 'cp-hero-demo__ok')
-    .with('cmt', () => 'cp-hero-demo__cmt')
-    .with('err', () => 'cp-hero-demo__err')
-    .otherwise(() => 'cp-hero-demo__info')
+    .with('ok', () => 'cp-home-terminal__ok')
+    .with('cmt', () => 'cp-home-terminal__cmt')
+    .with('err', () => 'cp-home-terminal__err')
+    .otherwise(() => 'cp-home-terminal__info')
   const glyph = match(props.line.kind)
     .with('ok', () => ' ✓')
     .with('cmt', () => ' ↻')

package/dist/theme/components/home/layout.tsx

@@ -9,7 +9,14 @@ import { CTA } from './cta'
 import { HomeFeature } from './feature'
 import type { FeatureItem } from './feature-card'
 import { Hero } from './hero'
-import type { HeroAction } from './hero'
+import type {
+  HeroAction,
+  HeroBackground,
+  HeroBackgroundImage,
+  HeroBackgroundSource,
+  HeroBackgroundVariants,
+} from './hero'
+import { HeroBanner } from './hero-banner'
 import { HeroDemo } from './hero-demo'
 import { HomeVisualView } from './home-visual'
 import { PageRail } from './page-rail'
@@ -151,6 +158,10 @@ export function HomeLayout(props: HomeLayoutProps): React.ReactElement {
   //   false     → suppress entirely
   //   object    → render the user-supplied custom variant
   const heroDemoFm = fm.heroDemo as false | HomeVisual | undefined
+  // heroBackground frontmatter arrives as an unvalidated object (or `null`
+  // when hand-authored with a blank `heroBackground:` line). Treat anything
+  // without a string `src` or valid dark/light sources as absent.
+  const heroBackground = parseHeroBackground(fm.heroBackground)
   const blocks = (fm.blocks as readonly FrontmatterBlock[] | undefined) ?? []
 
   // `P.nullish`, not `undefined`: a blank `heroDemo:` in a hand-authored
@@ -170,6 +181,10 @@ export function HomeLayout(props: HomeLayoutProps): React.ReactElement {
         tagline={renderOptionalRichText(h.tagline)}
         actions={mapButtonsToHeroActions(h.actions)}
         demo={heroDemoEl}
+        background={heroBackground}
+        backgroundContent={match(heroBackground)
+          .with(undefined, () => <HeroBanner />)
+          .otherwise(() => undefined)}
       />
     ))
 
@@ -186,6 +201,115 @@ export function HomeLayout(props: HomeLayoutProps): React.ReactElement {
   )
 }
 
+/**
+ * Validate untrusted hero background frontmatter before rendering it as CSS.
+ *
+ * @private
+ * @param value - Raw frontmatter value.
+ * @returns A renderable background, or undefined for malformed input.
+ */
+function parseHeroBackground(value: unknown): HeroBackground | undefined {
+  if (!isRecord(value)) {
+    return undefined
+  }
+  if (isHeroBackgroundImage(value)) {
+    return value
+  }
+  if (isHeroBackgroundVariants(value)) {
+    return value
+  }
+  return undefined
+}
+
+/**
+ * Validate one fixed-mode background image.
+ *
+ * @private
+ * @param value - Raw background record.
+ * @returns Whether the record is a valid fixed-mode image.
+ */
+function isHeroBackgroundImage(value: unknown): value is HeroBackgroundImage {
+  if (!isRecord(value)) {
+    return false
+  }
+  return (
+    isHeroBackgroundSource(value) &&
+    (value.mode === undefined || value.mode === 'dark' || value.mode === 'light')
+  )
+}
+
+/**
+ * Validate dark and light background source variants.
+ *
+ * @private
+ * @param value - Raw background record.
+ * @returns Whether both variants are valid sources.
+ */
+function isHeroBackgroundVariants(value: unknown): value is HeroBackgroundVariants {
+  if (!isRecord(value)) {
+    return false
+  }
+  return isHeroBackgroundSource(value.dark) && isHeroBackgroundSource(value.light)
+}
+
+/**
+ * Validate a background source and every optional CSS field.
+ *
+ * @private
+ * @param value - Raw source value.
+ * @returns Whether the value is safe to pass into inline styles.
+ */
+function isHeroBackgroundSource(value: unknown): value is HeroBackgroundSource {
+  if (!isRecord(value) || typeof value.src !== 'string') {
+    return false
+  }
+  return (
+    isOptionalString(value.position) &&
+    isOptionalString(value.size) &&
+    isOptionalString(value.repeat) &&
+    isResponsiveSources(value.sources)
+  )
+}
+
+/**
+ * Validate optional tablet and mobile source overrides.
+ *
+ * @private
+ * @param value - Raw responsive sources value.
+ * @returns Whether the value is absent or contains only valid source strings.
+ */
+function isResponsiveSources(value: unknown): boolean {
+  if (value === undefined) {
+    return true
+  }
+  if (!isRecord(value)) {
+    return false
+  }
+  return isOptionalString(value.tablet) && isOptionalString(value.mobile)
+}
+
+/**
+ * Test whether an unknown value is absent or a string.
+ *
+ * @private
+ * @param value - Unknown optional field.
+ * @returns Whether the value is safe for a string-valued option.
+ */
+function isOptionalString(value: unknown): value is string | undefined {
+  return value === undefined || typeof value === 'string'
+}
+
+/**
+ * Narrow an unknown value to an object record.
+ *
+ * @private
+ * @param value - Unknown value.
+ * @returns Whether the value is a non-null, non-array object.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
 /**
  * Render a single home block by its discriminated `type`.
  *

package/dist/theme/components/home/split.css

@@ -158,9 +158,9 @@ html[data-cp-variant='dark'] .cp-split__eyebrow {
   overflow-x: auto;
 }
 
-/* Terminal visual reuses the hero demo chrome; the split frame already
+/* Terminal visual supplies its own chrome; the split frame already
    owns the border, radius, and shadow, so flatten the inner shell. */
-.cp-split__visual .cp-hero-demo {
+.cp-split__visual .cp-home-terminal {
   max-width: none;
   border: 0;
   border-radius: 0;

package/dist/theme/components/home/tabs.css

@@ -285,7 +285,7 @@
   overflow-x: auto;
 }
 
-.cp-tabs__visual .cp-hero-demo {
+.cp-tabs__visual .cp-home-terminal {
   max-width: none;
   border: 0;
   border-radius: 0;

package/dist/theme/components/home/trust-strip.css

@@ -38,6 +38,18 @@
   vertical-align: middle;
 }
 
+.cp-trust__logo--light {
+  display: none;
+}
+
+html[data-cp-variant='light'] .cp-trust__logo--dark {
+  display: none;
+}
+
+html[data-cp-variant='light'] .cp-trust__logo--light {
+  display: inline-block;
+}
+
 /*
  * Mono variant: paint a solid block of the current text color, clipped
  * to the asset's alpha channel. One file then tracks every theme and

package/dist/theme/components/home/trust-strip.test.tsx

@@ -0,0 +1,33 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it, vi } from 'vitest'
+
+import { TrustStrip } from './trust-strip.tsx'
+
+vi.mock('@rspress/core/runtime', () => ({ withBase: (value: string) => value }))
+
+describe('TrustStrip', () => {
+  it('should render one image for a shared logo source', () => {
+    const output = renderToStaticMarkup(
+      <TrustStrip names={[{ src: '/logos/acme.svg', alt: 'Acme' }]} />
+    )
+    expect(output).toContain('class="cp-trust__logo"')
+    expect(output.match(/<img/g)).toHaveLength(1)
+  })
+
+  it('should render dark and light images for a variant logo source', () => {
+    const output = renderToStaticMarkup(
+      <TrustStrip
+        names={[
+          {
+            src: { dark: '/logos/acme-dark.svg', light: '/logos/acme-light.svg' },
+            alt: 'Acme',
+          },
+        ]}
+      />
+    )
+    expect(output).toContain('class="cp-trust__logo cp-trust__logo--dark"')
+    expect(output).toContain('src="/logos/acme-dark.svg"')
+    expect(output).toContain('class="cp-trust__logo cp-trust__logo--light"')
+    expect(output).toContain('src="/logos/acme-light.svg"')
+  })
+})

package/dist/theme/components/home/trust-strip.tsx

@@ -13,14 +13,19 @@ import './trust-strip.css'
 const DEFAULT_LOGO_HEIGHT = 20
 
 /**
- * A logo entry in the trust strip. Drawn as a mask filled with the
- * current text color, so one asset covers every theme and both variants.
+ * A logo entry in the trust strip. Supports shared, variant-specific,
+ * full-color, and monochrome artwork.
  */
 export interface TrustLogo {
   /**
    * Public URL of the logo asset.
    */
-  readonly src: string
+  readonly src:
+    | string
+    | {
+        readonly dark: string
+        readonly light: string
+      }
   /**
    * Accessible name for the logo.
    */
@@ -99,7 +104,11 @@ export function TrustStrip(props: TrustStripProps): React.ReactElement | null {
 function itemKey(item: TrustItem): string {
   return match(item)
     .with(P.string, (name) => name)
-    .otherwise((logo) => logo.src)
+    .otherwise((logo) =>
+      match(logo.src)
+        .with(P.string, (src) => src)
+        .otherwise((src) => `${src.dark}:${src.light}`)
+    )
 }
 
 /**
@@ -153,14 +162,14 @@ function renderLogo(logo: TrustLogo): React.ReactNode {
  */
 function renderColorMark(logo: TrustLogo): React.ReactNode {
   const { src, alt, height = DEFAULT_LOGO_HEIGHT } = logo
-  return (
-    <img
-      alt={alt}
-      className="cp-trust__logo"
-      src={withMountBase(src)}
-      style={{ height: `${height}px` }}
-    />
-  )
+  return match(src)
+    .with(P.string, (source) => renderColorSource({ source, alt, height }))
+    .otherwise((sources) => (
+      <>
+        {renderColorSource({ source: sources.dark, alt, height, variant: 'dark' })}
+        {renderColorSource({ source: sources.light, alt, height, variant: 'light' })}
+      </>
+    ))
 }
 
 /**
@@ -175,18 +184,70 @@ function renderColorMark(logo: TrustLogo): React.ReactNode {
  */
 function renderMonoMark(logo: TrustLogo): React.ReactNode {
   const { src, alt, height = DEFAULT_LOGO_HEIGHT } = logo
+  return match(src)
+    .with(P.string, (source) => renderMonoSource({ source, alt, height }))
+    .otherwise((sources) => (
+      <>
+        {renderMonoSource({ source: sources.dark, alt, height, variant: 'dark' })}
+        {renderMonoSource({ source: sources.light, alt, height, variant: 'light' })}
+      </>
+    ))
+}
+
+interface RenderLogoSourceParams {
+  readonly source: string
+  readonly alt: string
+  readonly height: number
+  readonly variant?: 'dark' | 'light'
+}
+
+/**
+ * Render one color logo source.
+ *
+ * @private
+ * @param params - Source, accessible name, height, and optional site variant
+ * @returns Image element for the source
+ */
+function renderColorSource(params: RenderLogoSourceParams): React.ReactNode {
+  const { source, alt, height, variant } = params
+  const className = match(variant)
+    .with(P.string, (value) => `cp-trust__logo cp-trust__logo--${value}`)
+    .otherwise(() => 'cp-trust__logo')
+  return (
+    <img
+      alt={alt}
+      className={className}
+      src={withMountBase(source)}
+      style={{ height: `${height}px` }}
+    />
+  )
+}
+
+/**
+ * Render one monochrome logo source.
+ *
+ * @private
+ * @param params - Source, accessible name, height, and optional site variant
+ * @returns Masked logo element for the source
+ */
+function renderMonoSource(params: RenderLogoSourceParams): React.ReactNode {
+  const { source, alt, height, variant } = params
   // `encodeURI` so a `"` or `)` in the filename cannot terminate the
   // `url()` token — the CSSOM would reject the whole declaration, and a
   // mask that fails to load leaves the fill unclipped, painting a solid
   // text-coloured rectangle where the logo should be.
-  const mask = `url("${encodeURI(withMountBase(src))}")`
+  const resolvedSource = withMountBase(source)
+  const mask = `url("${encodeURI(resolvedSource)}")`
+  const className = match(variant)
+    .with(P.string, (value) => `cp-trust__logo cp-trust__logo--mono cp-trust__logo--${value}`)
+    .otherwise(() => 'cp-trust__logo cp-trust__logo--mono')
   // The inner image is hidden but still laid out, so the masked wrapper
   // inherits the asset's intrinsic aspect ratio. A mask alone has no
   // intrinsic size, so without it every logo would collapse to zero width.
   return (
     <span
       aria-label={alt}
-      className="cp-trust__logo cp-trust__logo--mono"
+      className={className}
       role="img"
       style={{
         height: `${height}px`,
@@ -194,7 +255,7 @@ function renderMonoMark(logo: TrustLogo): React.ReactNode {
         WebkitMaskImage: mask,
       }}
     >
-      <img alt="" aria-hidden="true" src={withMountBase(src)} />
+      <img alt="" aria-hidden="true" src={resolvedSource} />
     </span>
   )
 }

package/dist/theme/components/nav/layout.tsx

@@ -272,22 +272,18 @@ function collectMetaActions(params: {
   const { edit, report, pagePath } = params
   const editAction = match(edit)
     .with(undefined, () => null)
-    .otherwise(
-      (e): MetaAction => ({
-        label: e.label ?? 'Edit this page on GitHub',
-        href: buildEditUrl(e, pagePath),
-        icon: <EditIcon />,
-      })
-    )
+    .otherwise((e): MetaAction => ({
+      label: e.label ?? 'Edit this page on GitHub',
+      href: buildEditUrl(e, pagePath),
+      icon: <EditIcon />,
+    }))
   const reportAction = match(report)
     .with(undefined, () => null)
-    .otherwise(
-      (r): MetaAction => ({
-        label: r.label ?? 'Report an issue',
-        href: buildReportUrl(r),
-        icon: <AlertIcon />,
-      })
-    )
+    .otherwise((r): MetaAction => ({
+      label: r.label ?? 'Report an issue',
+      href: buildReportUrl(r),
+      icon: <AlertIcon />,
+    }))
   return [editAction, reportAction].filter((a): a is MetaAction => a !== null)
 }
 

package/dist/theme/components/nav/nav-logo.tsx

@@ -74,9 +74,9 @@ export function NavLogo(): React.ReactElement | null {
     // so a single querySelector at effect time misses the element. We
     // belt-and-suspenders with both rAF polling AND MutationObserver in
     // case the polling stops before the nav appears (e.g. tab inactive).
-    // oxlint-disable-next-line functional/no-let -- raf id retained for cleanup
+    // oxlint-disable-next-line ciderpress/no-let -- raf id retained for cleanup
     let rafId: number | null = null
-    // oxlint-disable-next-line functional/no-let -- captured below for closure equality
+    // oxlint-disable-next-line ciderpress/no-let -- captured below for closure equality
     let resolved = false
 
     function tryResolve() {
@@ -85,7 +85,6 @@ export function NavLogo(): React.ReactElement | null {
       }
       const link = findTarget()
       if (link !== null) {
-        // oxlint-disable-next-line functional/immutable-data -- flag flip to stop polling
         resolved = true
         setTarget(link)
         return