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

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

@@ -1,33 +1,181 @@
-import type { HomeGridConfig } from '@ciderpress/config'
+import type { TruncateConfig } from '@ciderpress/config'
 import { match, P } from 'massaman/match'
 import type React from 'react'
 
 import { useCiderpress } from '../../hooks/use-ciderpress'
-import type { WorkspaceGroupData } from '../../hooks/use-ciderpress'
+import type { WorkspaceCardData, WorkspaceGroupData } from '../../hooks/use-ciderpress'
+import { renderRichText } from '../../lib/rich-text.tsx'
 import { WorkspaceCard } from '../workspaces/card'
 import { WorkspaceGrid } from '../workspaces/grid'
 
 /**
- * Smart orchestrator that reads workspace data from themeConfig
- * and renders workspace groups with the correct card component per type.
+ * A single card compiled from `showcase.source` — the same shape as a
+ * workspace card, minus the grouping.
+ */
+export type ShowcaseCard = WorkspaceCardData
+
+interface FrontmatterWorkspacesHeading {
+  readonly label?: string
+  readonly title?: string
+  readonly body?: string
+}
+
+interface HomeWorkspacesProps {
+  readonly heading?: FrontmatterWorkspacesHeading
+  /**
+   * Cards compiled from an explicit `showcase.source` path list. When
+   * present they render as one ungrouped grid; otherwise the grouped
+   * workspace data from the theme config is used.
+   */
+  readonly cards?: readonly ShowcaseCard[]
+  readonly columns?: 1 | 2 | 3 | 4
+  readonly truncate?: TruncateConfig
+}
+
+const DEFAULT_COLUMNS: 1 | 2 | 3 | 4 = 2
+
+/**
+ * Showcase grid block. Renders either the cards compiled from an
+ * explicit `showcase.source` path list (one ungrouped grid) or the
+ * grouped workspace data serialized from the repo at build time. Grid
+ * layout — heading, columns, truncation — comes from props.
  *
- * @returns React element with workspace groups or null
+ * @param props - Optional heading, cards, column count, and truncation limits.
+ * @returns React element with the showcase grid, or null when empty.
  */
-export function HomeWorkspaces(): React.ReactElement | null {
-  const { workspaces, home } = useCiderpress()
-  const gridConfig = home && home.workspaces
+export function HomeWorkspaces(props: HomeWorkspacesProps): React.ReactElement | null {
+  const { workspaces } = useCiderpress()
+  const { heading, cards, columns, truncate } = props
+  const resolvedColumns = match(columns)
+    .with(P.nonNullable, (c) => c)
+    .otherwise(() => DEFAULT_COLUMNS)
 
-  return match(workspaces)
+  // A `cards` key means the block declared an explicit `showcase.source`
+  // — an empty array is "that source resolved to nothing", not "fall back
+  // to the workspace deck". Only an absent key takes the fallback.
+  const body = match(cards)
     .with(
-      P.when((w): w is readonly WorkspaceGroupData[] => Array.isArray(w) && w.length > 0),
-      (groups) => (
-        <div className="cp-workspace-section">
-          <hr className="cp-divider" />
-          {groups.map((group) => renderGroup(group, gridConfig))}
-        </div>
-      )
+      P.when((c): c is readonly ShowcaseCard[] => Array.isArray(c)),
+      (list) =>
+        match(list.length === 0)
+          .with(true, () => null)
+          .otherwise(() => [renderCardGrid(list, resolvedColumns, truncate)])
     )
-    .otherwise(() => null)
+    .otherwise(() =>
+      match(workspaces)
+        .with(
+          P.when((w): w is readonly WorkspaceGroupData[] => Array.isArray(w) && w.length > 0),
+          (groups) => groups.map((group, i) => renderGroup(group, resolvedColumns, truncate, i))
+        )
+        .otherwise(() => null)
+    )
+
+  return match(body)
+    .with(null, () => null)
+    .otherwise((content) => (
+      <div className="cp-workspace-section">
+        {/* The rule separates this band from the heading above it, so a
+            block with no heading of its own would render it as an orphan
+            line floating over the cards. */}
+        {match(renderHeading(heading))
+          .with(P.nullish, () => null)
+          .otherwise((head) => (
+            <>
+              <hr className="cp-divider" />
+              {head}
+            </>
+          ))}
+        {content}
+      </div>
+    ))
+}
+
+/**
+ * Render the block heading, or nothing when every field is absent.
+ *
+ * @private
+ * @param heading - Flat heading trio from the block
+ * @returns Heading element, or null
+ */
+function renderHeading(
+  heading: FrontmatterWorkspacesHeading | undefined
+): React.ReactElement | null {
+  if (heading === undefined) {
+    return null
+  }
+  const { label, title, body } = heading
+  const hasContent = [label, title, body].some((value) => typeof value === 'string')
+  if (!hasContent) {
+    return null
+  }
+  return (
+    <div className="cp-feature-section-head">
+      {match(label)
+        .with(P.string, (e) => (
+          <div className="cp-feature-section-head__eyebrow">{renderRichText(e)}</div>
+        ))
+        .otherwise(() => null)}
+      {match(title)
+        .with(P.string, (t) => (
+          <h2 className="cp-feature-section-head__title">{renderRichText(t)}</h2>
+        ))
+        .otherwise(() => null)}
+      {match(body)
+        .with(P.string, (s) => <p className="cp-feature-section-head__sub">{renderRichText(s)}</p>)
+        .otherwise(() => null)}
+    </div>
+  )
+}
+
+/**
+ * Render an ungrouped grid of cards compiled from `showcase.source`.
+ *
+ * @private
+ * @param cards - Resolved showcase cards
+ * @param columns - Column count for the grid
+ * @param truncate - Optional line-clamp limits for card text
+ * @returns Ungrouped workspace grid element
+ */
+function renderCardGrid(
+  cards: readonly ShowcaseCard[],
+  columns: 1 | 2 | 3 | 4,
+  truncate: TruncateConfig | undefined
+): React.ReactElement {
+  return (
+    <WorkspaceGrid key="showcase-source" columns={columns}>
+      {cards.map((card, i) => renderCard(card, i, truncate))}
+    </WorkspaceGrid>
+  )
+}
+
+/**
+ * Render a single showcase / workspace card.
+ *
+ * @private
+ * @param card - Card data
+ * @param index - Array index for key generation
+ * @param truncate - Optional line-clamp limits for card text
+ * @returns Workspace card element
+ */
+function renderCard(
+  card: WorkspaceCardData,
+  index: number,
+  truncate: TruncateConfig | undefined
+): React.ReactElement {
+  return (
+    <WorkspaceCard
+      key={`${card.title}-${index}`}
+      title={card.title}
+      href={card.href}
+      icon={card.icon}
+      scope={card.scope}
+      description={card.description}
+      tags={card.tags}
+      badge={card.badge}
+      titleLines={truncate && truncate.title}
+      descriptionLines={truncate && truncate.description}
+    />
+  )
 }
 
 /**
@@ -35,37 +183,27 @@ export function HomeWorkspaces(): React.ReactElement | null {
  *
  * @private
  * @param group - Workspace group data with heading, description, and cards
- * @param gridConfig - Optional grid layout config for columns and truncation
+ * @param columns - Column count for the grid
+ * @param truncate - Optional line-clamp limits for card text
+ * @param index - Position in the group list, to disambiguate the key
  * @returns Workspace grid element
  */
 function renderGroup(
   group: WorkspaceGroupData,
-  gridConfig: HomeGridConfig | undefined
+  columns: 1 | 2 | 3 | 4,
+  truncate: TruncateConfig | undefined,
+  index: number
 ): React.ReactElement {
-  const titleLines = gridConfig && gridConfig.truncate && gridConfig.truncate.title
-  const descLines = gridConfig && gridConfig.truncate && gridConfig.truncate.description
-
   return (
+    // Heading alone is not unique — two configured workspace groups may
+    // share a title, which collided into one React key.
     <WorkspaceGrid
-      key={group.heading}
+      key={`${group.heading}-${index}`}
       heading={group.heading}
       description={group.description}
-      columns={gridConfig && gridConfig.columns}
+      columns={columns}
     >
-      {group.cards.map((card, i) => (
-        <WorkspaceCard
-          key={`${card.title}-${i}`}
-          title={card.title}
-          href={card.href}
-          icon={card.icon}
-          scope={card.scope}
-          description={card.description}
-          tags={card.tags}
-          badge={card.badge}
-          titleLines={titleLines}
-          descriptionLines={descLines}
-        />
-      ))}
+      {group.cards.map((card, i) => renderCard(card, i, truncate))}
     </WorkspaceGrid>
   )
 }

package/dist/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/dist/theme/components/nav/ciderpress-docs-bar.css

@@ -90,11 +90,21 @@
   display: flex;
   align-items: center;
   gap: 6px;
-  flex: 1 1 auto;
+  /* Shrink-to-content (not grow) so page badges sit snug to the right of
+     the trail; long trails still truncate via `overflow: hidden`. */
+  flex: 0 1 auto;
   min-width: 0;
   overflow: hidden;
 }
 
+/* Page badges (ALPHA / WIP …) immediately right of the breadcrumb trail. */
+.cp-docs-bar__badges {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  flex: 0 0 auto;
+}
+
 .cp-docs-bar__crumb-wrap {
   display: inline-flex;
   align-items: center;
@@ -358,6 +368,8 @@ html[data-cp-outline-collapsed='true'] .cp-docs-bar__chev {
    `styles/overrides/rspress.css`. ──────────────────────────────── */
 .cp-docs-bar__llms {
   flex-shrink: 0;
+  /* Crumbs no longer grow, so push the LLMs cluster to the far right. */
+  margin-left: auto;
 }
 
 .cp-docs-bar__llms .rp-llms-container {

package/dist/theme/components/nav/ciderpress-docs-bar.tsx

@@ -1,3 +1,4 @@
+import type { BadgeConfig } from '@ciderpress/config'
 import { useFrontmatter, useLocation } from '@rspress/core/runtime'
 import {
   LlmsContainer,
@@ -13,8 +14,10 @@ import { match, P } from 'massaman/match'
 import { useCallback, useEffect, useRef, useState } from 'react'
 import type React from 'react'
 
+import { useCiderpress } from '../../hooks/use-ciderpress'
 import { RouteLink } from '../../lib/route-link.tsx'
 import { Icon } from '../shared/icon.tsx'
+import { BadgeChips } from '../sidebar/sidebar-badge'
 import { useCiderpressLayout } from './ciderpress-layout-context'
 
 import './ciderpress-docs-bar.css'
@@ -117,6 +120,9 @@ export function CiderpressDocsBar(): React.ReactElement | null {
 
   const pageTitle = readStringField(fmRecord.title)
 
+  const { pageBadges } = useCiderpress()
+  const badges = lookupPageBadges({ pageBadges, pathname })
+
   const breadcrumbs = buildBreadcrumbs(pathname, pageTitle)
   const outlineEnabled = match(fmRecord.outline)
     .with(false, () => false)
@@ -174,12 +180,12 @@ export function CiderpressDocsBar(): React.ReactElement | null {
                 <span className="cp-docs-bar__sep">›</span>
                 {match(crumb.current)
                   .with(true, () => (
-                    <span className="cp-docs-bar__crumb" aria-current="page">
+                    <span className="cp-docs-bar__crumb" aria-current="page" title={crumb.label}>
                       {crumb.label}
                     </span>
                   ))
                   .otherwise(() => (
-                    <RouteLink href={crumb.href} className="cp-docs-bar__crumb">
+                    <RouteLink href={crumb.href} className="cp-docs-bar__crumb" title={crumb.label}>
                       {crumb.label}
                     </RouteLink>
                   ))}
@@ -187,6 +193,11 @@ export function CiderpressDocsBar(): React.ReactElement | null {
             ))}
           </nav>
         )}
+        {badges.length > 0 && (
+          <span className="cp-docs-bar__badges">
+            <BadgeChips badges={badges} />
+          </span>
+        )}
         <div className="cp-docs-bar__llms">
           <LlmsContainer>
             <LlmsCopyButton />
@@ -254,6 +265,26 @@ interface Crumb {
   readonly current: boolean
 }
 
+/**
+ * Look up the current page's badges from the route→badges map, tolerating
+ * a trailing slash on the pathname (map keys are stored without one).
+ *
+ * @private
+ * @param params - The route→badges map (if present) and current pathname.
+ * @returns The page's badges, or an empty array when none apply.
+ */
+function lookupPageBadges(params: {
+  readonly pageBadges: Record<string, readonly BadgeConfig[]> | undefined
+  readonly pathname: string
+}): readonly BadgeConfig[] {
+  const { pageBadges, pathname } = params
+  if (pageBadges === undefined) {
+    return []
+  }
+  const stripped = pathname.replace(/\/$/, '')
+  return pageBadges[pathname] ?? pageBadges[stripped] ?? []
+}
+
 /**
  * Build a 1- or 2-level breadcrumb trail from the current path and the
  * page's frontmatter title. The section label comes from titlecasing

package/dist/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/dist/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/dist/theme/components/nav/ciderpress-nav-hamburger.css

@@ -141,6 +141,56 @@
   text-decoration: none;
 }
 
+.cp-nav-drawer__group {
+  display: flex;
+  flex-direction: column;
+}
+
+.cp-nav-drawer__group-toggle {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: 12px 16px;
+  background: transparent;
+  border: none;
+  border-radius: 8px;
+  color: var(--cp-c-text-1);
+  font-family: inherit;
+  font-size: 15px;
+  font-weight: 500;
+  text-align: left;
+  cursor: pointer;
+  transition:
+    background 0.12s ease,
+    color 0.12s ease;
+}
+
+.cp-nav-drawer__group-toggle:hover {
+  background: var(--cp-c-bg-soft);
+  color: var(--cp-c-brand-1);
+}
+
+.cp-nav-drawer__group-chevron {
+  flex-shrink: 0;
+  color: var(--cp-c-text-2);
+  transition: transform 0.18s ease;
+}
+
+.cp-nav-drawer__group-toggle[aria-expanded='true'] .cp-nav-drawer__group-chevron {
+  transform: rotate(180deg);
+}
+
+.cp-nav-drawer__group-items {
+  display: flex;
+  flex-direction: column;
+}
+
+.cp-nav-drawer__link--nested {
+  padding-left: 28px;
+  font-size: 14px;
+}
+
 .cp-nav-drawer__divider {
   height: 1px;
   margin: 4px 20px;

package/dist/theme/components/nav/ciderpress-nav-hamburger.tsx

@@ -1,3 +1,4 @@
+import { match } from 'massaman/match'
 import { useState } from 'react'
 import type React from 'react'
 import { Dialog, Modal, ModalOverlay } from 'react-aria-components'
@@ -71,15 +72,12 @@ export function CiderpressNavHamburger(props: CiderpressNavHamburgerProps): Reac
             </header>
 
             <nav className="cp-nav-drawer__nav" aria-label="Primary">
-              {props.navItems.map((item) => (
-                <RouteLink
-                  key={item.link}
-                  href={item.link}
-                  className="cp-nav-drawer__link"
-                  onClick={() => setOpen(false)}
-                >
-                  {item.text}
-                </RouteLink>
+              {props.navItems.map((item, index) => (
+                <DrawerNavEntry
+                  key={`${drawerItemKey(item)}::${index}`}
+                  item={item}
+                  onNavigate={() => setOpen(false)}
+                />
               ))}
             </nav>
 
@@ -110,3 +108,91 @@ export function CiderpressNavHamburger(props: CiderpressNavHamburgerProps): Reac
 }
 
 export { CiderpressNavHamburger as default }
+
+/**
+ * Render one entry in the mobile drawer nav. Leaf items are a single
+ * link; dropdown parents become a collapsible {@link DrawerNavGroup}.
+ *
+ * @private
+ * @param props - The nav item and a callback to close the drawer.
+ * @returns The drawer entry element.
+ */
+function DrawerNavEntry(props: {
+  readonly item: CiderpressNavMenuItem
+  readonly onNavigate: () => void
+}): React.ReactElement {
+  const { item, onNavigate } = props
+  const children = item.items ?? []
+  return match(children.length > 0)
+    .with(true, () => <DrawerNavGroup item={item} onNavigate={onNavigate} />)
+    .otherwise(() => (
+      <RouteLink href={item.link ?? '#'} className="cp-nav-drawer__link" onClick={onNavigate}>
+        {item.text}
+      </RouteLink>
+    ))
+}
+
+/**
+ * A collapsible dropdown section in the mobile drawer: a tappable header
+ * that toggles its child links open/closed. Collapsed by default so a
+ * deep nav doesn't fill the drawer on open.
+ *
+ * @private
+ * @param props - The dropdown item and a callback to close the drawer.
+ * @returns The collapsible group element.
+ */
+function DrawerNavGroup(props: {
+  readonly item: CiderpressNavMenuItem
+  readonly onNavigate: () => void
+}): React.ReactElement {
+  const { item, onNavigate } = props
+  const [expanded, setExpanded] = useState(false)
+  const children = item.items ?? []
+  return (
+    <div className="cp-nav-drawer__group" role="group" aria-label={item.text}>
+      <button
+        type="button"
+        className="cp-nav-drawer__group-toggle"
+        onClick={() => setExpanded((current) => !current)}
+        aria-expanded={expanded}
+      >
+        <span>{item.text}</span>
+        <Icon
+          className="cp-nav-drawer__group-chevron"
+          icon="pixelarticons:chevron-down"
+          width={16}
+          height={16}
+        />
+      </button>
+      {expanded && (
+        <div className="cp-nav-drawer__group-items">
+          {children.map((child, index) => (
+            <RouteLink
+              key={`${drawerItemKey(child)}::${index}`}
+              href={child.link ?? '#'}
+              className="cp-nav-drawer__link cp-nav-drawer__link--nested"
+              onClick={onNavigate}
+            >
+              {child.text}
+            </RouteLink>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Stable React key for a drawer nav item — its link when present,
+ * otherwise its label (dropdown parents may have no link of their own).
+ *
+ * @private
+ * @param item - Nav item to key.
+ * @returns Key string.
+ */
+function drawerItemKey(item: CiderpressNavMenuItem): string {
+  if (item.link !== undefined && item.link !== '') {
+    return item.link
+  }
+  return item.text
+}