@ciderpress/ui 1.0.0-rc.1 → 1.0.0-rc.4

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

@@ -1,6 +1,13 @@
+import type {
+  ButtonConfig,
+  HomeHeroDemoConfig,
+  HomeSectionId,
+  HomeSplitConfig,
+} from '@ciderpress/config'
+import { DEFAULT_HOME_LAYOUT } from '@ciderpress/config'
 import { useFrontmatter } from '@rspress/core/runtime'
-import { match } from 'massaman/match'
-import type React from 'react'
+import { match, P } from 'massaman/match'
+import React from 'react'
 
 import { SiteFooter } from '../footer/site-footer'
 import { CTA } from './cta'
@@ -8,8 +15,10 @@ import { HomeFeature } from './feature'
 import { Hero } from './hero'
 import type { HeroAction } from './hero'
 import { HeroDemo } from './hero-demo'
+import { CustomHeroDemo } from './hero-demo-custom'
 import { PageRail } from './page-rail'
 import { HomeSplit } from './split'
+import { CustomSplitVisual } from './split-visual-custom'
 import { TrustStrip } from './trust-strip'
 import { HomeWorkspaces } from './workspaces'
 
@@ -24,11 +33,11 @@ interface FrontmatterHero {
   readonly name?: string
   readonly text?: string
   readonly tagline?: string
-  readonly actions?: readonly HeroAction[]
-  readonly eyebrow?: string
+  readonly actions?: readonly ButtonConfig[]
+  readonly label?: string
 }
 
-interface FrontmatterTrust {
+interface FrontmatterProof {
   readonly lead?: string
   readonly names?: readonly string[]
 }
@@ -36,7 +45,7 @@ interface FrontmatterTrust {
 interface FrontmatterCTA {
   readonly title?: string
   readonly subtitle?: string
-  readonly actions?: readonly HeroAction[]
+  readonly actions?: readonly ButtonConfig[]
 }
 
 /**
@@ -52,25 +61,48 @@ interface FrontmatterCTA {
  */
 export function HomeLayout(props: HomeLayoutProps): React.ReactElement {
   const { frontmatter } = useFrontmatter()
+
+  // SSG-MD short-circuit: the React tree is walked by
+  // `react-render-to-markdown` to produce `.md` files served to
+  // `<LlmsCopyButton />`. Rendering the home shell would dump hero
+  // text, demo blocks, and footer columns into every copied page.
+  // Return an empty fragment for SSG-MD — the home page has no
+  // canonical markdown body. The `useFrontmatter` hook above runs in
+  // both passes so hook order stays consistent.
+  if (import.meta.env.SSG_MD) {
+    return <></>
+  }
+
   const fm = frontmatter as Record<string, unknown>
 
   const hero = fm.hero as FrontmatterHero | undefined
-  const trust = fm.trust as FrontmatterTrust | undefined
+  const proof = fm.proof as FrontmatterProof | undefined
   const cta = fm.cta as FrontmatterCTA | undefined
+  // heroDemo / split frontmatter:
+  //   undefined → render the framework default
+  //   false     → suppress entirely
+  //   object    → render the user-supplied custom variant
+  const heroDemoFm = fm.heroDemo as false | HomeHeroDemoConfig | undefined
+  const splitFm = fm.split as false | HomeSplitConfig | undefined
+
+  const heroDemoEl = match(heroDemoFm)
+    .with(false, () => null)
+    .with(undefined, () => <HeroDemo />)
+    .otherwise((d) => <CustomHeroDemo config={d} />)
 
   const heroSection = match(hero)
     .with(undefined, () => null)
     .otherwise((h) => (
       <Hero
-        eyebrow={h.eyebrow}
+        eyebrow={h.label}
         title={renderTitle(h.text ?? h.name ?? '')}
         tagline={h.tagline}
-        actions={h.actions}
-        demo={<HeroDemo />}
+        actions={mapButtonsToHeroActions(h.actions)}
+        demo={heroDemoEl}
       />
     ))
 
-  const trustSection = match(trust)
+  const proofSection = match(proof)
     .with(undefined, () => null)
     .otherwise((t) => {
       const names = t.names ?? []
@@ -84,18 +116,18 @@ export function HomeLayout(props: HomeLayoutProps): React.ReactElement {
     .otherwise((c) =>
       match(c.title === undefined)
         .with(true, () => null)
-        .otherwise(() => <CTA title={c.title ?? ''} subtitle={c.subtitle} actions={c.actions} />)
+        .otherwise(() => (
+          <CTA
+            title={c.title ?? ''}
+            subtitle={c.subtitle}
+            actions={mapButtonsToHeroActions(c.actions)}
+          />
+        ))
     )
 
-  return (
-    <PageRail>
-      {props.beforeHero}
-      {heroSection}
-      {props.afterHero}
-      {trustSection}
-      {props.beforeFeatures}
-      <HomeFeature />
-      {props.afterFeatures}
+  const splitSection = match(splitFm)
+    .with(false, () => null)
+    .with(undefined, () => (
       <HomeSplit
         eyebrow="Configuration"
         title="One file. Validated. Type-safe."
@@ -109,8 +141,57 @@ export function HomeLayout(props: HomeLayoutProps): React.ReactElement {
         action={{ theme: 'brand', text: 'Read the docs', link: '/getting-started/quick-start' }}
         visual={<ConfigPreview />}
       />
-      <HomeWorkspaces />
-      {ctaSection}
+    ))
+    .with(P.nonNullable, (s) => (
+      <HomeSplit
+        eyebrow={s.label}
+        title={s.title}
+        body={s.body}
+        bullets={s.bullets ?? []}
+        action={match(s.cta)
+          .with(undefined, () => undefined)
+          .otherwise((c) => ({ theme: 'brand' as const, text: c.text, link: c.href }))}
+        visual={match(s.visual)
+          .with(undefined, () => null)
+          .otherwise((v) => (
+            <CustomSplitVisual code={v.code} language={v.language} />
+          ))}
+      />
+    ))
+    .exhaustive()
+
+  // Section render order. `home.layout` (when provided) controls both
+  // order and visibility — sections omitted from the array are not
+  // rendered. The framework default (`DEFAULT_HOME_LAYOUT`) preserves
+  // the historical fixed order. Unknown ids are ignored at render time
+  // (the schema rejects them at config-load anyway).
+  const layout = (fm.layout as readonly HomeSectionId[] | undefined) ?? DEFAULT_HOME_LAYOUT
+  const sectionsById: Readonly<Record<HomeSectionId, React.ReactNode>> = {
+    hero: (
+      <>
+        {props.beforeHero}
+        {heroSection}
+        {props.afterHero}
+      </>
+    ),
+    proof: proofSection,
+    features: (
+      <>
+        {props.beforeFeatures}
+        <HomeFeature />
+        {props.afterFeatures}
+      </>
+    ),
+    split: splitSection,
+    showcase: <HomeWorkspaces />,
+    cta: ctaSection,
+  }
+
+  return (
+    <PageRail>
+      {layout.map((id) => (
+        <React.Fragment key={id}>{sectionsById[id]}</React.Fragment>
+      ))}
       <SiteFooter />
     </PageRail>
   )
@@ -134,16 +215,16 @@ function ConfigPreview(): React.ReactElement {
       {'  title: '}
       <span className="tok-str">'Acme Docs'</span>
       {',\n'}
-      {'  sections: [\n'}
+      {'  pages: [\n'}
       {'    { title: '}
       <span className="tok-str">'Guides'</span>
       {', include: '}
       <span className="tok-str">'docs/guides/*.md'</span>
       {' },\n'}
       {'  ],\n'}
-      {'  theme: { name: '}
+      {'  theme: { themes: ['}
       <span className="tok-str">'mulled'</span>
-      {' },\n'}
+      {'] },\n'}
       {'})'}
     </pre>
   )
@@ -181,3 +262,45 @@ function renderTitle(raw: string): React.ReactNode {
         })
     })
 }
+
+/**
+ * Map the unified `ButtonConfig[]` shape (used by the new `home.hero`
+ * / `home.cta` configs) into the legacy `HeroAction[]` shape still
+ * consumed by `<Hero />` and `<CTA />`. `'primary'` → `'brand'`,
+ * `'secondary' | 'ghost'` → `'alt'`, `undefined` → `undefined`.
+ *
+ * @private
+ * @param actions - Optional list of unified button configs from frontmatter
+ * @returns Hero-action array consumed by the existing component API
+ */
+function mapButtonsToHeroActions(
+  actions: readonly ButtonConfig[] | undefined
+): readonly HeroAction[] | undefined {
+  if (actions === undefined) {
+    return undefined
+  }
+  return actions.map((action) => ({
+    text: action.text,
+    link: action.href,
+    theme: mapButtonVariantToHeroTheme(action.variant),
+  }))
+}
+
+/**
+ * Project the new `'primary' | 'secondary' | 'ghost'` variant token
+ * back into the legacy `'brand' | 'alt'` token that `<Hero />` accepts.
+ *
+ * @private
+ * @param variant - Optional variant from the unified button config
+ * @returns `'brand'`, `'alt'`, or `undefined`
+ */
+function mapButtonVariantToHeroTheme(
+  variant: ButtonConfig['variant']
+): 'brand' | 'alt' | undefined {
+  return match(variant)
+    .with(undefined, () => undefined)
+    .with('primary', () => 'brand' as const)
+    .with('secondary', () => 'alt' as const)
+    .with('ghost', () => 'alt' as const)
+    .exhaustive()
+}

package/src/theme/components/home/split-visual-custom.tsx

@@ -0,0 +1,26 @@
+import type React from 'react'
+
+interface CustomSplitVisualProps {
+  readonly code: string
+  readonly language?: string
+}
+
+/**
+ * Custom Split visual — renders a user-supplied code snippet inside the
+ * same `<pre>` shell as the default `ConfigPreview`. Language hint is
+ * surfaced as a `data-language` attribute so themes can hook into it
+ * for syntax-highlighter overlays. No client-side highlighting is
+ * performed in the framework (keeps the bundle slim); the rendered
+ * `<pre>` matches the default surface so themes that style the
+ * default block also style the custom one.
+ *
+ * @param props - Code snippet + optional language hint
+ * @returns Pre-formatted code block
+ */
+export function CustomSplitVisual(props: CustomSplitVisualProps): React.ReactElement {
+  return (
+    <pre data-language={props.language ?? 'ts'} className="cp-split__code">
+      {props.code}
+    </pre>
+  )
+}

package/src/theme/components/home/workspaces.tsx

@@ -1,4 +1,5 @@
-import type { HomeGridConfig } from '@ciderpress/config'
+import type { HomeShowcaseConfig } from '@ciderpress/config'
+import { useFrontmatter } from '@rspress/core/runtime'
 import { match, P } from 'massaman/match'
 import type React from 'react'
 
@@ -7,15 +8,29 @@ import type { WorkspaceGroupData } from '../../hooks/use-ciderpress'
 import { WorkspaceCard } from '../workspaces/card'
 import { WorkspaceGrid } from '../workspaces/grid'
 
+interface FrontmatterWorkspacesHeading {
+  readonly label?: string
+  readonly title?: string
+  readonly subtitle?: string
+}
+
 /**
  * Smart orchestrator that reads workspace data from themeConfig
  * and renders workspace groups with the correct card component per type.
  *
+ * Optionally renders a top-level heading above the workspace groups
+ * when `home.showcase.heading` is configured. The sync engine writes
+ * it into frontmatter as `workspacesHeading`.
+ *
  * @returns React element with workspace groups or null
  */
 export function HomeWorkspaces(): React.ReactElement | null {
   const { workspaces, home } = useCiderpress()
-  const gridConfig = home && home.workspaces
+  const gridConfig = home && home.showcase
+  const { frontmatter } = useFrontmatter()
+  const heading = (frontmatter as Record<string, unknown>).workspacesHeading as
+    | FrontmatterWorkspacesHeading
+    | undefined
 
   return match(workspaces)
     .with(
@@ -23,6 +38,27 @@ export function HomeWorkspaces(): React.ReactElement | null {
       (groups) => (
         <div className="cp-workspace-section">
           <hr className="cp-divider" />
+          {match(heading)
+            .with(undefined, () => null)
+            .otherwise((h) => (
+              <div className="cp-feature-section-head">
+                {match(h.label)
+                  .with(undefined, () => null)
+                  .otherwise((e) => (
+                    <div className="cp-feature-section-head__eyebrow">{e}</div>
+                  ))}
+                {match(h.title)
+                  .with(undefined, () => null)
+                  .otherwise((t) => (
+                    <h2 className="cp-feature-section-head__title">{t}</h2>
+                  ))}
+                {match(h.subtitle)
+                  .with(undefined, () => null)
+                  .otherwise((s) => (
+                    <p className="cp-feature-section-head__sub">{s}</p>
+                  ))}
+              </div>
+            ))}
           {groups.map((group) => renderGroup(group, gridConfig))}
         </div>
       )
@@ -40,7 +76,7 @@ export function HomeWorkspaces(): React.ReactElement | null {
  */
 function renderGroup(
   group: WorkspaceGroupData,
-  gridConfig: HomeGridConfig | undefined
+  gridConfig: HomeShowcaseConfig | undefined
 ): React.ReactElement {
   const titleLines = gridConfig && gridConfig.truncate && gridConfig.truncate.title
   const descLines = gridConfig && gridConfig.truncate && gridConfig.truncate.description

package/src/theme/components/nav/branch-tag.tsx

@@ -1,7 +1,7 @@
-import type { SiteConfig } from '@ciderpress/config'
 import { match, P } from 'massaman/match'
 import type React from 'react'
 
+import type { CiderpressSiteBlock } from '../../hooks/use-ciderpress'
 import { useCiderpress } from '../../hooks/use-ciderpress'
 
 import './branch-tag.css'
@@ -12,7 +12,7 @@ declare const __CIDERPRESS_GIT_BRANCH__: string | undefined
 /**
  * Git branch tag — pill-shaped badge rendered via the `beforeNavMenu`
  * layout slot. Hidden when on default branches (`main` or `master`) or
- * when no `site.edit.repo` is configured. Uses the pixelarticons:git-branch
+ * when no `editLink.repo` is configured. Uses the pixelarticons:git-branch
  * icon.
  *
  * @returns React element, or `null` when on a default branch / unconfigured.
@@ -61,7 +61,7 @@ function resolveBranch(): string {
 }
 
 /**
- * Build a GitHub `/tree/<branch>` URL from the configured `site.edit.repo`.
+ * Build a GitHub `/tree/<branch>` URL from the configured `editLink.repo`.
  *
  * Accepts either a full URL (used as-is) or an `org/repo` slug
  * (prefixed with `https://github.com/`). Returns `null` when `repo` is
@@ -83,14 +83,14 @@ function buildBranchHref(params: {
 }
 
 /**
- * Pull the configured edit-repo slug off the site config, expressed
- * with explicit null checks rather than optional chaining.
+ * Pull the configured edit-repo slug off the serialised site block,
+ * expressed with explicit null checks rather than optional chaining.
  *
  * @private
- * @param site - The ciderpress site config (may be undefined).
+ * @param site - The runtime site block (may be undefined).
  * @returns The configured `edit.repo` value or `undefined`.
  */
-function resolveRepo(site: SiteConfig | undefined): string | undefined {
+function resolveRepo(site: CiderpressSiteBlock | undefined): string | undefined {
   if (site === undefined) {
     return undefined
   }

package/src/theme/components/nav/ciderpress-header.css

@@ -76,7 +76,8 @@
   text-decoration: none;
 }
 
-.cp-header-logo > svg {
+.cp-header-logo > svg,
+.cp-header-logo > img {
   height: var(--cp-header-logo-height, 28px);
   width: auto;
 }

package/src/theme/components/nav/ciderpress-header.tsx

@@ -2,19 +2,29 @@ import { clsx } from 'clsx'
 import type React from 'react'
 
 import { RouteLink } from '../../lib/route-link.tsx'
-import { CiderpressLogo } from '../shared/ciderpress-logo'
 import { CiderpressNavHamburger } from './ciderpress-nav-hamburger'
 import { CiderpressNavMenu } from './ciderpress-nav-menu'
 import type { CiderpressNavMenuItem } from './ciderpress-nav-menu'
 import { CiderpressNavSearch } from './ciderpress-nav-search'
 import { CiderpressNavSocialLinks } from './ciderpress-nav-social-links'
 import type { CiderpressSocialLink } from './ciderpress-nav-social-links'
+import { HeaderIcon } from './header-icon'
+import { HeaderLogo } from './header-logo'
 import { NavDivider } from './nav-divider'
 import { TopbarCTA } from './topbar-cta'
 import { VariantToggle } from './variant-toggle'
 
 import './ciderpress-header.css'
 
+/**
+ * Build-time flag: `true` when the active theme declares more than one
+ * variant AND `data-cp-variants` won't collapse the `<VariantToggle />`
+ * to `display: none`. Drives whether the trailing-cluster divider is
+ * rendered — when the toggle is hidden and neither socials nor CTA
+ * follow, the divider has nothing to separate and is omitted.
+ */
+declare const __CIDERPRESS_HAS_VARIANT_TOGGLE__: boolean
+
 /**
  * Props for the ciderpress site header.
  */
@@ -57,6 +67,18 @@ export interface CiderpressHeaderProps {
  * @returns Sticky header element
  */
 export function CiderpressHeader(props: CiderpressHeaderProps): React.ReactElement {
+  // Dividers only render when they actually separate two visible
+  // clusters — orphan dividers (nothing on the right) are visually
+  // noisy. `<VariantToggle />` is hidden by CSS for single-variant
+  // themes; the build-time flag captures that decision so the React
+  // tree matches the painted output. The search/menu inner divider is
+  // unconditional — both clusters always render some chrome, and
+  // gating on `navItems.length` would flip after hydration (Rspress's
+  // nav data isn't populated at SSG) and produce a hydration warning.
+  const hasSocials = props.socialLinks.length > 0
+  const hasCta = props.topbarCta !== undefined
+  const hasTrailingCluster = __CIDERPRESS_HAS_VARIANT_TOGGLE__ || hasSocials || hasCta
+
   // Landing / home pages live inside a constrained max-width container;
   // doc pages stretch full-width (sidebar + article). The header mirrors
   // the content shell so it never floats outside the page rhythm.
@@ -78,7 +100,8 @@ export function CiderpressHeader(props: CiderpressHeaderProps): React.ReactEleme
           topbarCta={props.topbarCta}
         />
         <RouteLink href="/" className="cp-header-logo" aria-label="Home">
-          <CiderpressLogo />
+          <HeaderIcon />
+          <HeaderLogo />
         </RouteLink>
 
         {/* Right cluster wrapper. Grows from a zero basis so its width
@@ -96,7 +119,7 @@ export function CiderpressHeader(props: CiderpressHeaderProps): React.ReactEleme
           <CiderpressNavMenu items={props.navItems} />
         </div>
 
-        <NavDivider />
+        {hasTrailingCluster && <NavDivider />}
         <VariantToggle />
         <CiderpressNavSocialLinks links={props.socialLinks} />
         {props.topbarCta !== undefined && (

package/src/theme/components/nav/ciderpress-nav-social-links.tsx

@@ -6,13 +6,15 @@ import { Icon } from '../shared/icon.tsx'
 import './ciderpress-nav-social-links.css'
 
 /**
- * Single social-link entry — matches the shape of `socialLinks` in
- * `ciderpress.config.ts`.
+ * Single social-link entry — matches the serialised `socials` shape
+ * written into `themeConfig.socialLinks` by `packages/ui/src/config.ts`.
+ *
+ * The Rspress `mode` / `content` discriminator was killed in the
+ * `rc.4` API overhaul; every link is now a plain anchor.
  */
 export interface CiderpressSocialLink {
   readonly icon: string
-  readonly mode: string
-  readonly content: string
+  readonly url: string
   readonly label?: string
 }
 
@@ -39,7 +41,7 @@ const ICON_MAP: Readonly<Record<string, string>> = Object.freeze({
  * Renders the configured social links as a cluster of icon buttons in
  * the topbar. Returns `null` when no links are configured.
  *
- * @param props - List of social links from `site.socialLinks`
+ * @param props - List of social links from `site.socials`
  * @returns Cluster of icon links, or `null`
  */
 export function CiderpressNavSocialLinks(
@@ -50,7 +52,7 @@ export function CiderpressNavSocialLinks(
   }
 
   const safeLinks = props.links
-    .map((link) => ({ link, href: safeUrl(link.content) }))
+    .map((link) => ({ link, href: safeUrl(link.url) }))
     .filter((entry): entry is { readonly link: CiderpressSocialLink; readonly href: string } => {
       if (entry.href === null) {
         return false
@@ -66,7 +68,7 @@ export function CiderpressNavSocialLinks(
     <div className="cp-nav-social">
       {safeLinks.map(({ link, href }) => (
         <a
-          key={link.content}
+          key={link.url}
           href={href}
           target="_blank"
           rel="noopener noreferrer"

package/src/theme/components/nav/floating-branch-indicator.tsx

@@ -1,7 +1,7 @@
-import type { SiteConfig } from '@ciderpress/config'
 import { match, P } from 'massaman/match'
 import type React from 'react'
 
+import type { CiderpressSiteBlock } from '../../hooks/use-ciderpress'
 import { useCiderpress } from '../../hooks/use-ciderpress'
 
 import './floating-branch-indicator.css'
@@ -15,7 +15,7 @@ declare const __CIDERPRESS_GIT_BRANCH__: string | undefined
  * the branch name. Click anywhere on the pill opens the branch on GitHub.
  *
  * Hidden when on default branches (`main` / `master`), when the
- * build-time branch global is undefined, or when `site.edit.repo` is
+ * build-time branch global is undefined, or when `editLink.repo` is
  * not configured.
  *
  * @returns React element or null when hidden
@@ -69,7 +69,7 @@ function resolveBranch(): string {
 }
 
 /**
- * Build a GitHub `/tree/<branch>` URL from the configured `site.edit.repo`.
+ * Build a GitHub `/tree/<branch>` URL from the configured `editLink.repo`.
  *
  * Accepts either a full URL (used as-is) or an `org/repo` slug
  * (prefixed with `https://github.com/`). Returns `null` when `repo` is
@@ -91,14 +91,14 @@ function buildBranchHref(params: {
 }
 
 /**
- * Pull the configured edit-repo slug off the site config, expressed
- * with explicit null checks rather than optional chaining.
+ * Pull the configured edit-repo slug off the serialised site block,
+ * expressed with explicit null checks rather than optional chaining.
  *
  * @private
- * @param site - The ciderpress site config (may be undefined).
+ * @param site - The runtime site block (may be undefined).
  * @returns The configured `edit.repo` value or `undefined`.
  */
-function resolveRepo(site: SiteConfig | undefined): string | undefined {
+function resolveRepo(site: CiderpressSiteBlock | undefined): string | undefined {
   if (site === undefined) {
     return undefined
   }

package/src/theme/components/nav/header-icon.css

@@ -0,0 +1,24 @@
+/**
+ * Small brand chip rendered immediately before `<HeaderLogo />` inside
+ * `cp-header-logo`. Sized to match `--cp-header-icon-size` (default
+ * 28px — same as the logo height token) so the two slots line up
+ * vertically by default. Themes can override either token to break
+ * the lockstep.
+ */
+
+.cp-header-icon {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  height: var(--cp-header-icon-size, var(--cp-header-logo-height, 28px));
+  width: var(--cp-header-icon-size, var(--cp-header-logo-height, 28px));
+  margin-right: var(--cp-header-icon-gap, 8px);
+  color: var(--cp-header-icon-color, currentColor);
+}
+
+.cp-header-icon > svg,
+.cp-header-icon__img {
+  height: 100%;
+  width: 100%;
+  display: block;
+}