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

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

@@ -1,10 +1,98 @@
 .cp-hero {
   position: relative;
+  overflow: hidden;
   padding: 96px 0 72px;
   text-align: center;
 }
 
+.cp-hero__background {
+  position: absolute;
+  z-index: 0;
+  inset: 0;
+  pointer-events: none;
+}
+
+.cp-hero__background > * {
+  position: absolute;
+  inset: 0;
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.cp-hero--has-background {
+  background-color: var(--cp-c-home-bg);
+  background-image: var(--cp-hero-background-image);
+  background-position: var(--cp-hero-background-position, center);
+  background-size: var(--cp-hero-background-size, cover);
+  background-repeat: var(--cp-hero-background-repeat, no-repeat);
+}
+
+.cp-hero--has-background .cp-hero__inner {
+  position: relative;
+  z-index: 2;
+}
+
+.cp-hero--has-background::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  backdrop-filter: brightness(0.5);
+}
+
+:where([data-cp-variant='light']) .cp-hero--has-background::before {
+  backdrop-filter: brightness(0.8);
+}
+
+.cp-hero--background-dark,
+.cp-hero--background-variants {
+  --cp-hero-text-1: #f5f5f5;
+  --cp-hero-text-2: #d4d4d4;
+  --cp-hero-border: rgb(255 255 255 / 18%);
+  --cp-hero-surface: rgb(10 10 10 / 72%);
+  --cp-hero-soft: rgb(255 255 255 / 10%);
+
+  background-color: #080506;
+}
+
+:where([data-cp-variant='light']) .cp-hero--background-dark::before,
+.cp-hero--background-dark::before {
+  backdrop-filter: brightness(0.5);
+}
+
+.cp-hero--background-light,
+:where([data-cp-variant='light']) .cp-hero--background-variants {
+  --cp-hero-text-1: #1a1a1a;
+  --cp-hero-text-2: #4a4a4a;
+  --cp-hero-border: rgb(0 0 0 / 18%);
+  --cp-hero-surface: rgb(255 255 255 / 76%);
+  --cp-hero-soft: rgb(0 0 0 / 8%);
+}
+
+.cp-hero--background-light::before,
+:where([data-cp-variant='light']) .cp-hero--background-variants::before {
+  backdrop-filter: none;
+}
+
+.cp-hero--has-background .cp-hero__title code,
+.cp-hero--has-background .cp-hero__tagline code {
+  color: var(--cp-hero-text-1);
+  background: var(--cp-hero-soft);
+  border-color: var(--cp-hero-border);
+}
+
+:where([data-cp-variant='light']) .cp-hero--background-variants {
+  background-image: var(--cp-hero-background-light-image);
+  background-position: var(--cp-hero-background-light-position, center);
+  background-size: var(--cp-hero-background-light-size, cover);
+  background-repeat: var(--cp-hero-background-light-repeat, no-repeat);
+}
+
 .cp-hero__inner {
+  position: relative;
+  z-index: 2;
   max-width: 1100px;
   margin: 0 auto;
   padding: 0 32px;
@@ -15,12 +103,12 @@
   align-items: center;
   gap: 8px;
   padding: 6px 12px;
-  border: 1px solid var(--cp-c-border);
+  border: 1px solid var(--cp-hero-border, var(--cp-c-border));
   border-radius: var(--cp-radius-pill);
-  background: var(--cp-c-bg-elv);
+  background: var(--cp-hero-surface, var(--cp-c-bg-elv));
   font-family: var(--cp-font-family-mono);
   font-size: 11px;
-  color: var(--cp-c-text-2);
+  color: var(--cp-hero-text-2, var(--cp-c-text-2));
   text-transform: uppercase;
   letter-spacing: 0.06em;
   margin-bottom: 28px;
@@ -32,7 +120,7 @@
   letter-spacing: -0.04em;
   line-height: 1;
   margin: 0 0 24px;
-  color: var(--cp-c-text-1);
+  color: var(--cp-hero-text-1, var(--cp-c-text-1));
 }
 
 .cp-hero__title .cp-hero__grad {
@@ -44,7 +132,7 @@
   margin: 0 auto 40px;
   font-size: 18px;
   line-height: 1.6;
-  color: var(--cp-c-text-2);
+  color: var(--cp-hero-text-2, var(--cp-c-text-2));
 }
 
 .cp-hero__cta {
@@ -63,9 +151,9 @@
   font-size: 14px;
   font-weight: 500;
   border-radius: var(--cp-radius-pill);
-  border: 1px solid var(--cp-c-border);
+  border: 1px solid var(--cp-hero-border, var(--cp-c-border));
   background: transparent;
-  color: var(--cp-c-text-1);
+  color: var(--cp-hero-text-1, var(--cp-c-text-1));
   cursor: pointer;
   transition: all 0.15s ease;
   white-space: nowrap;
@@ -73,8 +161,8 @@
 }
 
 .cp-hero__btn:hover {
-  background: var(--cp-c-bg-soft);
-  border-color: var(--cp-c-border);
+  background: var(--cp-hero-soft, var(--cp-c-bg-soft));
+  border-color: var(--cp-hero-border, var(--cp-c-border));
 }
 
 .cp-hero__btn--primary {
@@ -94,3 +182,48 @@
   margin: 0 auto;
   text-align: left;
 }
+
+@media (max-width: 880px) {
+  .cp-hero--has-background {
+    background-image: var(--cp-hero-background-tablet-image, var(--cp-hero-background-image));
+  }
+
+  :where([data-cp-variant='light']) .cp-hero--background-variants {
+    background-image: var(
+      --cp-hero-background-light-tablet-image,
+      var(--cp-hero-background-light-image)
+    );
+  }
+}
+
+@media (max-width: 640px) {
+  .cp-hero {
+    padding: 72px 0 48px;
+  }
+
+  .cp-hero--has-background {
+    background-image: var(
+      --cp-hero-background-mobile-image,
+      var(--cp-hero-background-tablet-image, var(--cp-hero-background-image))
+    );
+  }
+
+  :where([data-cp-variant='light']) .cp-hero--background-variants {
+    background-image: var(
+      --cp-hero-background-light-mobile-image,
+      var(--cp-hero-background-light-tablet-image, var(--cp-hero-background-light-image))
+    );
+  }
+
+  .cp-hero__inner {
+    padding: 0 20px;
+  }
+
+  .cp-hero__title .cp-hero__grad {
+    display: block;
+  }
+
+  .cp-hero__tagline {
+    font-size: 16px;
+  }
+}

package/dist/theme/components/home/hero.test.tsx

@@ -0,0 +1,105 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, it, expect, vi } from 'vitest'
+
+import { Hero } from './hero.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),
+    withBase: (v: string) => v,
+  }
+})
+
+describe('Hero — background', () => {
+  it('should render React content in the background layer', () => {
+    const out = renderToStaticMarkup(
+      <Hero title="Docs" backgroundContent={<canvas data-testid="field" />} />
+    )
+    expect(out).toContain('<div class="cp-hero__background" aria-hidden="true"><canvas')
+  })
+
+  it('should add the modifier class when a background is configured', () => {
+    const out = renderToStaticMarkup(<Hero title="Docs" background={{ src: '/hero.jpg' }} />)
+    expect(out).toContain('cp-hero cp-hero--has-background')
+  })
+
+  it('should paint the image src into the CSS custom property', () => {
+    const out = renderToStaticMarkup(<Hero title="Docs" background={{ src: '/hero.jpg' }} />)
+    expect(out).toContain('--cp-hero-background-image:url(&quot;/hero.jpg&quot;)')
+  })
+
+  it('should use CSS defaults when sizing fields are omitted', () => {
+    const out = renderToStaticMarkup(<Hero title="Docs" background={{ src: '/hero.jpg' }} />)
+    expect(out).toContain('--cp-hero-background-position:center')
+    expect(out).toContain('--cp-hero-background-size:cover')
+    expect(out).toContain('--cp-hero-background-repeat:no-repeat')
+  })
+
+  it('should respect custom sizing fields', () => {
+    const out = renderToStaticMarkup(
+      <Hero title="Docs" background={{ src: '/hero.jpg', position: '50% 25%', size: 'contain' }} />
+    )
+    expect(out).toContain('--cp-hero-background-position:50% 25%')
+    expect(out).toContain('--cp-hero-background-size:contain')
+  })
+
+  it('should add the configured background mode class', () => {
+    const out = renderToStaticMarkup(
+      <Hero title="Docs" background={{ src: '/hero.jpg', mode: 'dark' }} />
+    )
+    expect(out).toContain('cp-hero--background-dark')
+  })
+
+  it('should paint responsive sources into CSS custom properties', () => {
+    const out = renderToStaticMarkup(
+      <Hero
+        title="Docs"
+        background={{
+          src: '/hero.jpg',
+          sources: { tablet: '/hero-tablet.jpg', mobile: '/hero-mobile.jpg' },
+        }}
+      />
+    )
+    expect(out).toContain('--cp-hero-background-tablet-image:url(&quot;/hero-tablet.jpg&quot;)')
+    expect(out).toContain('--cp-hero-background-mobile-image:url(&quot;/hero-mobile.jpg&quot;)')
+  })
+
+  it('should paint dark and light variant sources into CSS custom properties', () => {
+    const out = renderToStaticMarkup(
+      <Hero
+        title="Docs"
+        background={{
+          dark: { src: '/hero-dark.jpg', sources: { mobile: '/hero-dark-mobile.jpg' } },
+          light: { src: '/hero-light.jpg', sources: { mobile: '/hero-light-mobile.jpg' } },
+        }}
+      />
+    )
+    expect(out).toContain('cp-hero--background-variants')
+    expect(out).toContain('--cp-hero-background-image:url(&quot;/hero-dark.jpg&quot;)')
+    expect(out).toContain('--cp-hero-background-light-image:url(&quot;/hero-light.jpg&quot;)')
+    expect(out).toContain(
+      '--cp-hero-background-light-mobile-image:url(&quot;/hero-light-mobile.jpg&quot;)'
+    )
+  })
+
+  it('should not add the modifier when background is absent', () => {
+    const out = renderToStaticMarkup(<Hero title="Docs" />)
+    expect(out).not.toContain('cp-hero--has-background')
+    expect(out).not.toContain('--cp-hero-background-image')
+  })
+
+  it('should not render an empty demo wrapper when the demo is suppressed', () => {
+    const out = renderToStaticMarkup(<Hero title="Docs" demo={null} />)
+    expect(out).not.toContain('cp-hero__demo')
+  })
+
+  it('should not paint a background when src is an empty string', () => {
+    const out = renderToStaticMarkup(<Hero title="Docs" background={{ src: '' }} />)
+    expect(out).not.toContain('cp-hero--has-background')
+  })
+})

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

@@ -3,6 +3,7 @@ import type React from 'react'
 
 import { RouteLink } from '../../lib/route-link.tsx'
 import { safeUrl } from '../../lib/safe-url.ts'
+import { withMountBase } from '../../lib/with-mount-base.ts'
 
 import './hero.css'
 
@@ -21,6 +22,55 @@ export interface HeroAction {
   readonly theme?: 'brand' | 'alt'
 }
 
+/** Background image source and responsive rendering controls. */
+export interface HeroBackgroundSource {
+  /**
+   * Image URL or path. Runs through {@link withMountBase} so paths on a
+   * mounted `base` still resolve.
+   */
+  readonly src: string
+  /**
+   * Optional image overrides for the 880px tablet and 640px mobile
+   * breakpoints.
+   */
+  readonly sources?: {
+    readonly tablet?: string
+    readonly mobile?: string
+  }
+  /**
+   * CSS `background-position` value (e.g. `'center'`). Default `'center'`.
+   */
+  readonly position?: string
+  /**
+   * CSS `background-size` value. Default `'cover'`.
+   */
+  readonly size?: string
+  /**
+   * CSS `background-repeat` value. Default `'no-repeat'`.
+   */
+  readonly repeat?: string
+}
+
+/** A single hero background image with fixed foreground contrast. */
+export interface HeroBackgroundImage extends HeroBackgroundSource {
+  /**
+   * Color mode used for the hero foreground and scrim. When omitted, the
+   * active site variant is used.
+   */
+  readonly mode?: 'dark' | 'light'
+}
+
+/** Hero background sources selected from the active site variant. */
+export interface HeroBackgroundVariants {
+  /** Artwork displayed in dark mode. */
+  readonly dark: HeroBackgroundSource
+  /** Artwork displayed in light mode. */
+  readonly light: HeroBackgroundSource
+}
+
+/** Background image painted behind the hero copy. */
+export type HeroBackground = HeroBackgroundImage | HeroBackgroundVariants
+
 export interface HeroProps {
   /**
    * Optional eyebrow chip (e.g. "★ 2.1k stars · v0.4.2").
@@ -43,22 +93,39 @@ export interface HeroProps {
    * Optional visual block beneath the CTAs (terminal demo, screenshot, etc).
    */
   readonly demo?: React.ReactNode
+  /**
+   * Optional background image painted behind the hero copy.
+   */
+  readonly background?: HeroBackground
+  /**
+   * Optional React content painted behind the hero copy. Intended for
+   * procedural canvas, WebGL, or inline SVG backgrounds.
+   */
+  readonly backgroundContent?: React.ReactNode
 }
 
 /**
  * Hero — landing-page hero with eyebrow chip, gradient-friendly headline,
- * tagline, CTAs, and an optional demo slot. The radial accent glow + dotted
- * grid backdrop are baked in via CSS and adapt to the active theme.
+ * tagline, CTAs, an optional demo slot, and an optional background image.
+ * The radial accent glow + dotted grid backdrop are baked in via CSS and
+ * adapt to the active theme.
  *
  * @param props - Hero configuration.
  * @returns React element.
  */
 export function Hero(props: HeroProps): React.ReactElement {
-  const { eyebrow, title, tagline, actions, demo } = props
+  const { eyebrow, title, tagline, actions, demo, background, backgroundContent } = props
   const list = actions ?? []
 
   return (
-    <section className="cp-hero">
+    <section className={heroClassName(background)} style={heroBackgroundStyle(background)}>
+      {match(backgroundContent)
+        .with(undefined, () => null)
+        .otherwise((content) => (
+          <div className="cp-hero__background" aria-hidden="true">
+            {content}
+          </div>
+        ))}
       <div className="cp-hero__inner">
         {match(eyebrow)
           .with(undefined, () => null)
@@ -77,6 +144,7 @@ export function Hero(props: HeroProps): React.ReactElement {
             <div className="cp-hero__cta">{list.map(renderAction)}</div>
           ))}
         {match(demo)
+          .with(null, () => null)
           .with(undefined, () => null)
           .otherwise((d) => (
             <div className="cp-hero__demo">{d}</div>
@@ -86,6 +154,135 @@ export function Hero(props: HeroProps): React.ReactElement {
   )
 }
 
+/**
+ * Compute the `<section>` className. The modifier class carries the
+ * background-image CSS variables' consumers; the base class alone when no
+ * background is configured.
+ *
+ * @private
+ * @param background - Hero background config (may be `undefined`)
+ * @returns ClassName string
+ */
+function heroClassName(background: HeroBackground | undefined): string {
+  if (background === undefined) {
+    return 'cp-hero'
+  }
+  if (isVariantBackground(background)) {
+    return 'cp-hero cp-hero--has-background cp-hero--background-variants'
+  }
+  if (background.src.length === 0) {
+    return 'cp-hero'
+  }
+  if (background.mode === undefined) {
+    return 'cp-hero cp-hero--has-background'
+  }
+  return `cp-hero cp-hero--has-background cp-hero--background-${background.mode}`
+}
+
+/**
+ * Build the inline CSS custom properties for the hero background. Returns
+ * `undefined` when no background is configured, so the `<section>` carries
+ * no `style` attr at all in the default case.
+ *
+ * @private
+ * @param background - Hero background config (may be `undefined`)
+ * @returns CSS properties keyed as custom properties, or `undefined`
+ */
+function heroBackgroundStyle(
+  background: HeroBackground | undefined
+): React.CSSProperties | undefined {
+  if (background === undefined) {
+    return undefined
+  }
+  if (isVariantBackground(background)) {
+    const dark = heroBackgroundSourceStyle(background.dark)
+    const light = heroBackgroundSourceStyle(background.light)
+    return {
+      '--cp-hero-background-image': dark.image,
+      '--cp-hero-background-position': dark.position,
+      '--cp-hero-background-size': dark.size,
+      '--cp-hero-background-repeat': dark.repeat,
+      '--cp-hero-background-tablet-image': dark.tabletImage,
+      '--cp-hero-background-mobile-image': dark.mobileImage,
+      '--cp-hero-background-light-image': light.image,
+      '--cp-hero-background-light-position': light.position,
+      '--cp-hero-background-light-size': light.size,
+      '--cp-hero-background-light-repeat': light.repeat,
+      '--cp-hero-background-light-tablet-image': light.tabletImage,
+      '--cp-hero-background-light-mobile-image': light.mobileImage,
+    } as React.CSSProperties
+  }
+  if (background.src.length === 0) {
+    return undefined
+  }
+  const style = heroBackgroundSourceStyle(background)
+  return {
+    '--cp-hero-background-image': style.image,
+    '--cp-hero-background-position': style.position,
+    '--cp-hero-background-size': style.size,
+    '--cp-hero-background-repeat': style.repeat,
+    '--cp-hero-background-tablet-image': style.tabletImage,
+    '--cp-hero-background-mobile-image': style.mobileImage,
+  } as React.CSSProperties
+}
+
+interface HeroBackgroundStyleValues {
+  readonly image: string
+  readonly position: string
+  readonly size: string
+  readonly repeat: string
+  readonly tabletImage: string | undefined
+  readonly mobileImage: string | undefined
+}
+
+/**
+ * Build normalized CSS values for one background source.
+ *
+ * @private
+ * @param source - Background source and rendering controls.
+ * @returns Normalized CSS values.
+ */
+function heroBackgroundSourceStyle(source: HeroBackgroundSource): HeroBackgroundStyleValues {
+  const sources = source.sources
+  return {
+    image: `url("${withMountBase(source.src)}")`,
+    position: source.position ?? 'center',
+    size: source.size ?? 'cover',
+    repeat: source.repeat ?? 'no-repeat',
+    tabletImage: match(sources)
+      .with(undefined, () => undefined)
+      .otherwise((responsive) => heroSourceImage(responsive.tablet)),
+    mobileImage: match(sources)
+      .with(undefined, () => undefined)
+      .otherwise((responsive) => heroSourceImage(responsive.mobile)),
+  }
+}
+
+/**
+ * Test whether a background provides site-variant sources.
+ *
+ * @private
+ * @param background - Hero background configuration.
+ * @returns Whether the background contains dark and light sources.
+ */
+function isVariantBackground(background: HeroBackground): background is HeroBackgroundVariants {
+  return 'dark' in background
+}
+
+/**
+ * Convert an optional responsive source into a base-aware CSS image value.
+ *
+ * @private
+ * @param src - Optional image URL or path.
+ * @returns CSS `url()` value, or `undefined` when no override is configured.
+ */
+function heroSourceImage(src: string | undefined): string | undefined {
+  if (src === undefined) {
+    return undefined
+  }
+  return `url("${withMountBase(src)}")`
+}
+
 /**
  * Render a single hero CTA action.
  *

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

@@ -0,0 +1,98 @@
+.cp-home-terminal {
+  width: 100%;
+  min-width: 0;
+  overflow: hidden;
+  background: var(--cp-c-term-bg);
+  color: var(--cp-c-term-text);
+}
+
+.cp-home-terminal--framed {
+  width: min(920px, 100%);
+  margin: 0 auto;
+  border: 1px solid var(--cp-c-term-border);
+  border-radius: var(--cp-radius-lg);
+}
+
+.cp-home-terminal__bar {
+  display: grid;
+  grid-template-columns: 1fr auto 1fr;
+  align-items: center;
+  min-height: var(--cp-size-titlebar);
+  padding: var(--cp-s-8) var(--cp-s-12);
+  border-bottom: 1px solid var(--cp-c-term-border);
+  background: var(--cp-c-term-titlebar-bg);
+}
+
+.cp-home-terminal__dots {
+  display: flex;
+  gap: var(--cp-s-6);
+  justify-self: start;
+}
+
+.cp-home-terminal__dot {
+  width: var(--cp-size-window-dot);
+  height: var(--cp-size-window-dot);
+  border-radius: 50%;
+}
+
+.cp-home-terminal__dot--close {
+  background: var(--cp-c-window-dot-close);
+}
+
+.cp-home-terminal__dot--minimize {
+  background: var(--cp-c-window-dot-minimize);
+}
+
+.cp-home-terminal__dot--maximize {
+  background: var(--cp-c-window-dot-maximize);
+}
+
+.cp-home-terminal__title {
+  overflow: hidden;
+  color: var(--cp-c-term-title);
+  font-family: var(--rp-font-family-mono);
+  font-size: var(--cp-fs-window-title);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.cp-home-terminal__body {
+  min-height: 220px;
+  margin: 0;
+  overflow-x: auto;
+  padding: var(--cp-s-20) var(--cp-s-24);
+  color: var(--cp-c-term-text);
+  font-family: var(--rp-font-family-mono);
+  font-size: clamp(11px, 1.2vw, var(--cp-fs-term-body));
+  line-height: var(--cp-lh-relaxed);
+  overflow-wrap: anywhere;
+  white-space: pre-wrap;
+}
+
+.cp-home-terminal__prompt {
+  color: var(--cp-c-term-prompt-prefix);
+}
+
+.cp-home-terminal__ok {
+  color: var(--cp-c-term-green);
+}
+
+.cp-home-terminal__info {
+  color: var(--cp-c-term-cyan);
+}
+
+.cp-home-terminal__cmt {
+  color: var(--cp-c-term-muted);
+}
+
+.cp-home-terminal__err {
+  color: var(--cp-c-term-red);
+}
+
+@media (max-width: 640px) {
+  .cp-home-terminal__body {
+    min-height: 190px;
+    padding: var(--cp-s-16);
+    font-size: 11px;
+  }
+}

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

@@ -0,0 +1,27 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it, vi } from 'vitest'
+
+import { HomeVisualView } from './home-visual.tsx'
+
+vi.mock('@rspress/core/theme', () => ({ CodeBlockRuntime: (): null => null }))
+vi.mock('@rspress/core/runtime', () => ({ withBase: (value: string): string => value }))
+
+describe('home visual', () => {
+  it('should render terminal visuals with dedicated compact chrome', () => {
+    expect.assertions(3)
+    const output = renderToStaticMarkup(
+      <HomeVisualView
+        context="tabs"
+        visual={{
+          type: 'terminal',
+          windowTitle: 'ciderpress dev',
+          command: 'ciderpress dev',
+          lines: [{ kind: 'ok', text: 'ready' }],
+        }}
+      />
+    )
+    expect(output).toContain('role="group" aria-label="Terminal output"')
+    expect(output).toContain('ciderpress dev')
+    expect(output).toContain('ready')
+  })
+})