@ciderpress/ui 1.0.0-rc.1

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

@@ -0,0 +1,106 @@
+/**
+ * Floating git-branch indicator — pinned to the bottom-right viewport
+ * corner. Collapsed shows only the git-branch icon (36px circle); on
+ * hover/focus the pill expands rightward to reveal the branch name.
+ *
+ * `right`-anchored so the expansion grows leftward and never clips off the
+ * right edge regardless of branch-name length.
+ */
+
+.cp-floating-branch {
+  position: fixed;
+  bottom: 16px;
+  right: 16px;
+  z-index: 50;
+
+  display: inline-flex;
+  align-items: center;
+  gap: 0;
+
+  height: 36px;
+  width: 36px;
+  padding: 0;
+  border-radius: 18px;
+
+  background: var(--cp-c-bg-soft);
+  border: 1px solid var(--cp-c-divider);
+  color: var(--cp-c-text-3);
+
+  font-family: var(--cp-font-family-mono);
+  font-size: 12px;
+  font-weight: 600;
+  line-height: 1;
+  white-space: nowrap;
+  overflow: hidden;
+  text-decoration: none !important;
+
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.18);
+  backdrop-filter: blur(8px);
+
+  transition:
+    width 0.2s ease,
+    padding 0.2s ease,
+    gap 0.2s ease,
+    border-color 0.2s,
+    color 0.2s,
+    background 0.2s;
+}
+
+.cp-floating-branch:hover,
+.cp-floating-branch:focus-visible {
+  width: auto;
+  max-width: 240px;
+  padding: 0 12px 0 10px;
+  gap: 6px;
+
+  border-color: var(--cp-c-brand-1);
+  color: var(--cp-c-brand-1);
+  background: var(--cp-c-bg);
+  text-decoration: none !important;
+}
+
+.cp-floating-branch:focus-visible {
+  outline: 2px solid var(--rp-c-brand);
+  outline-offset: 2px;
+}
+
+.cp-floating-branch__icon {
+  flex-shrink: 0;
+  width: 16px;
+  height: 16px;
+  margin: 0 auto;
+  transition: margin 0.2s ease;
+}
+
+.cp-floating-branch:hover .cp-floating-branch__icon,
+.cp-floating-branch:focus-visible .cp-floating-branch__icon {
+  margin: 0;
+}
+
+.cp-floating-branch__text {
+  display: inline-block;
+  max-width: 0;
+  opacity: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+
+  transition:
+    max-width 0.2s ease,
+    opacity 0.15s ease;
+}
+
+.cp-floating-branch:hover .cp-floating-branch__text,
+.cp-floating-branch:focus-visible .cp-floating-branch__text {
+  max-width: 200px;
+  opacity: 1;
+}
+
+/* ── Responsive ──────────────────────────────────────────── */
+/* Mobile: hide the floating branch indicator entirely. The hamburger
+   drawer surfaces the same chrome, and a corner-anchored chip
+   competes with the on-screen keyboard / browser UI on small viewports. */
+@media (max-width: 768px) {
+  .cp-floating-branch {
+    display: none;
+  }
+}

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

@@ -0,0 +1,109 @@
+import type { SiteConfig } from '@ciderpress/config'
+import { match, P } from 'massaman/match'
+import type React from 'react'
+
+import { useCiderpress } from '../../hooks/use-ciderpress'
+
+import './floating-branch-indicator.css'
+import { Icon } from '../shared/icon.tsx'
+
+declare const __CIDERPRESS_GIT_BRANCH__: string | undefined
+
+/**
+ * Floating git-branch indicator pinned to the bottom-right corner of the
+ * viewport. Collapsed: a small circular icon. On hover: expands to reveal
+ * 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
+ * not configured.
+ *
+ * @returns React element or null when hidden
+ */
+export function FloatingBranchIndicator(): React.ReactElement | null {
+  const { site } = useCiderpress()
+  const branch = resolveBranch()
+
+  if (!branch || branch === 'main' || branch === 'master') {
+    return null
+  }
+
+  const href = buildBranchHref({ repo: resolveRepo(site), branch })
+  if (href === null) {
+    return null
+  }
+
+  return (
+    <a
+      className="cp-floating-branch"
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      title={`Branch: ${branch}`}
+    >
+      <Icon
+        icon="pixelarticons:git-branch"
+        width={16}
+        height={16}
+        className="cp-floating-branch__icon"
+      />
+      <span className="cp-floating-branch__text">{branch}</span>
+    </a>
+  )
+}
+
+export { FloatingBranchIndicator as default }
+
+/**
+ * Resolves the current git branch name from the build-time global,
+ * returning an empty string when undefined.
+ *
+ * @private
+ * @returns Current git branch name or empty string
+ */
+function resolveBranch(): string {
+  if (__CIDERPRESS_GIT_BRANCH__ !== undefined) {
+    return __CIDERPRESS_GIT_BRANCH__
+  }
+  return ''
+}
+
+/**
+ * Build a GitHub `/tree/<branch>` URL from the configured `site.edit.repo`.
+ *
+ * Accepts either a full URL (used as-is) or an `org/repo` slug
+ * (prefixed with `https://github.com/`). Returns `null` when `repo` is
+ * missing so the caller can omit the component entirely.
+ *
+ * @private
+ * @param params - The configured repo and the current branch.
+ * @returns Fully-qualified URL string, or `null` when unconfigured.
+ */
+function buildBranchHref(params: {
+  readonly repo: string | undefined
+  readonly branch: string
+}): string | null {
+  return match(params.repo)
+    .with(undefined, () => null)
+    .with('', () => null)
+    .with(P.string.startsWith('http'), (full) => `${full}/tree/${params.branch}`)
+    .otherwise((slug) => `https://github.com/${slug}/tree/${params.branch}`)
+}
+
+/**
+ * Pull the configured edit-repo slug off the site config, expressed
+ * with explicit null checks rather than optional chaining.
+ *
+ * @private
+ * @param site - The ciderpress site config (may be undefined).
+ * @returns The configured `edit.repo` value or `undefined`.
+ */
+function resolveRepo(site: SiteConfig | undefined): string | undefined {
+  if (site === undefined) {
+    return undefined
+  }
+  if (site.edit === undefined) {
+    return undefined
+  }
+  return site.edit.repo
+}

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

@@ -0,0 +1,268 @@
+import type { SiteEditConfig, SiteReportConfig } from '@ciderpress/config'
+import { useFrontmatter, useSite } from '@rspress/core/runtime'
+import { Layout as OriginalLayout } from '@rspress/core/theme-original'
+import { match, P } from 'massaman/match'
+import type React from 'react'
+import { useEffect } from 'react'
+
+import { useCiderpress } from '../../hooks/use-ciderpress'
+import { useNavItems } from '../../hooks/use-nav-items'
+import { readSocialLinks } from '../../lib/read-social-links'
+import { AnnouncementBar } from '../announcement/announcement-bar'
+import { ContentFooterPortal } from '../content-footer/content-footer-portal'
+import { Feedback } from '../content-footer/feedback'
+import type { MetaAction } from '../content-footer/meta-actions'
+import { MetaActions } from '../content-footer/meta-actions'
+import { SiteFooter } from '../footer/site-footer'
+import { SidebarLinks } from '../sidebar/sidebar-links'
+import { SidebarPromo } from '../sidebar/sidebar-promo'
+import { CiderpressDocsBar } from './ciderpress-docs-bar'
+import { CiderpressHeader } from './ciderpress-header'
+import type { CiderpressNavMenuItem } from './ciderpress-nav-menu'
+import { FloatingBranchIndicator } from './floating-branch-indicator'
+
+/**
+ * Custom Layout override for ciderpress.
+ *
+ * Renders `<CiderpressHeader />` as the entire site header chrome
+ * (Rspress's `.rp-nav` is hidden via CSS in `ciderpress-header.css`).
+ * `<OriginalLayout />` is kept around purely to render Rspress's
+ * sidebar + article body + footer; every nav-related slot is fed
+ * `null` so Rspress doesn't render its own chrome.
+ *
+ * Slots still in use:
+ * - `beforeSidebar`: SidebarLinks (above) and the `.cp-sidebar-top` band
+ * - `afterSidebar`: SidebarLinks (below) plus SidebarPromo
+ * - `afterDoc`: Feedback + MetaActions portalled into the doc footer
+ * - `bottom`: SiteFooter on doc pages
+ *
+ * @returns React element with the custom layout
+ */
+export function Layout(): React.ReactElement {
+  // Rspress's `.rp-nav` is visually hidden via `ciderpress-header.css`
+  // but stays in the a11y tree, producing duplicate `banner` landmarks
+  // alongside our `<CiderpressHeader>`. Mark it aria-hidden after mount
+  // so screen readers ignore it. The element lives for the layout's
+  // lifetime, so no cleanup is required.
+  useEffect(() => {
+    const rpNav = document.querySelector('.rp-nav')
+    if (rpNav !== null) {
+      rpNav.setAttribute('aria-hidden', 'true')
+    }
+  }, [])
+
+  const { sidebarAbove, sidebarBelow, site } = useCiderpress()
+  const { site: rspressSite } = useSite()
+  const configNavItems = readNavItems(rspressSite)
+  const scrapedNavItems = useNavItems()
+  const navItems = match(configNavItems.length > 0)
+    .with(true, () => configNavItems)
+    .otherwise(() => scrapedNavItems)
+  const socialLinks = readSocialLinks(rspressSite)
+  const { announcement, topbarCta, sidebarPromo: sidebarPromoConfig, edit, report } = site ?? {}
+  const { frontmatter } = useFrontmatter()
+  const fmRecord = frontmatter as Record<string, unknown>
+  const isHome = fmRecord.pageType === 'home'
+  const isBlank = fmRecord.pageType === 'blank'
+  const filepathValue = fmRecord.__filepath
+  const pagePath = match(filepathValue)
+    .with(P.string, (v) => v)
+    .otherwise(() => '')
+
+  const announcementSlot = match(announcement)
+    .with(undefined, () => null)
+    .otherwise((a) => (
+      <AnnouncementBar id={a.id} lead={a.lead} cta={a.cta} persistent={a.persistent}>
+        {a.message}
+      </AnnouncementBar>
+    ))
+
+  const aboveItems = sidebarAbove ?? []
+  const belowItems = sidebarBelow ?? []
+
+  const beforeSidebar = match(aboveItems.length > 0)
+    .with(true, () => (
+      <div className="cp-sidebar-top">
+        <SidebarLinks items={aboveItems} position="above" />
+      </div>
+    ))
+    .otherwise(() => null)
+
+  const sidebarPromo = match(sidebarPromoConfig)
+    .with(undefined, () => null)
+    .otherwise((p) => (
+      <SidebarPromo title={p.title} body={p.body} ctaText={p.cta.text} ctaHref={p.cta.href} />
+    ))
+
+  const belowLinks = match(belowItems.length > 0)
+    .with(true, () => <SidebarLinks items={belowItems} position="below" />)
+    .otherwise(() => null)
+
+  const afterSidebar = match(belowLinks === null && sidebarPromo === null)
+    .with(true, () => null)
+    .otherwise(() => (
+      <div className="cp-sidebar-bottom">
+        {belowLinks}
+        {sidebarPromo}
+      </div>
+    ))
+
+  const bottomSlot = match(isHome || isBlank)
+    .with(true, () => null)
+    .otherwise(() => <SiteFooter />)
+
+  const metaActions = collectMetaActions({ edit, report, pagePath })
+
+  const afterDocSlot = (
+    <ContentFooterPortal>
+      <Feedback />
+      <MetaActions actions={metaActions} />
+    </ContentFooterPortal>
+  )
+
+  return (
+    <>
+      <CiderpressHeader
+        announcement={announcementSlot}
+        navItems={navItems}
+        socialLinks={socialLinks}
+        topbarCta={topbarCta}
+        isHome={isHome}
+      />
+      <OriginalLayout
+        top={null}
+        beforeNavMenu={null}
+        afterNavMenu={null}
+        beforeSidebar={beforeSidebar}
+        afterSidebar={afterSidebar}
+        beforeDoc={<CiderpressDocsBar />}
+        afterDoc={afterDocSlot}
+        bottom={bottomSlot}
+      />
+      <FloatingBranchIndicator />
+    </>
+  )
+}
+
+/**
+ * Pull the primary nav menu items off Rspress's `site` shape. The
+ * Rspress `SiteData` type doesn't expose `nav` at compile time, so we
+ * read through an indexed access and validate the shape at runtime.
+ *
+ * @private
+ * @param site - Rspress site data
+ * @returns Array of nav items (empty array when not configured)
+ */
+function readNavItems(site: unknown): readonly CiderpressNavMenuItem[] {
+  const candidate = (site as { readonly nav?: unknown }).nav
+  if (!Array.isArray(candidate)) {
+    return []
+  }
+  return candidate.filter(
+    (item): item is CiderpressNavMenuItem =>
+      typeof item === 'object' &&
+      item !== null &&
+      typeof (item as { text?: unknown }).text === 'string' &&
+      typeof (item as { link?: unknown }).link === 'string'
+  )
+}
+
+/**
+ * Build the list of `MetaAction`s to render under each doc page,
+ * derived from `site.edit` and `site.report`. Returns an empty array
+ * when neither is configured.
+ *
+ * @private
+ * @param params - Site edit/report config plus current page path
+ * @returns Ordered list of meta actions
+ */
+function collectMetaActions(params: {
+  readonly edit: SiteEditConfig | undefined
+  readonly report: SiteReportConfig | undefined
+  readonly pagePath: string
+}): readonly MetaAction[] {
+  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 />,
+      })
+    )
+  const reportAction = match(report)
+    .with(undefined, () => null)
+    .otherwise(
+      (r): MetaAction => ({
+        label: r.label ?? 'Report an issue',
+        href: buildReportUrl(r),
+        icon: <AlertIcon />,
+      })
+    )
+  return [editAction, reportAction].filter((a): a is MetaAction => a !== null)
+}
+
+/**
+ * @private
+ */
+function buildEditUrl(edit: SiteEditConfig, pagePath: string): string {
+  if (edit.repo.startsWith('http')) {
+    return edit.repo
+  }
+  const branch = edit.branch ?? 'main'
+  const directory = match(edit.directory)
+    .with(undefined, () => '')
+    .otherwise((d) => `${d.replaceAll(/^\/+|\/+$/g, '')}/`)
+  const path = pagePath.replace(/^\/+/, '')
+  return `https://github.com/${edit.repo}/edit/${branch}/${directory}${path}`
+}
+
+/**
+ * @private
+ */
+function buildReportUrl(report: SiteReportConfig): string {
+  if (report.repo.startsWith('http')) {
+    return report.repo
+  }
+  return `https://github.com/${report.repo}/issues/new`
+}
+
+/**
+ * @private
+ */
+function EditIcon(): React.ReactElement {
+  return (
+    <svg
+      width="11"
+      height="11"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
+      <path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7" />
+      <path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z" />
+    </svg>
+  )
+}
+
+/**
+ * @private
+ */
+function AlertIcon(): React.ReactElement {
+  return (
+    <svg
+      width="11"
+      height="11"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
+      <circle cx="12" cy="12" r="10" />
+      <line x1="12" y1="8" x2="12" y2="12" />
+      <line x1="12" y1="16" x2="12.01" y2="16" />
+    </svg>
+  )
+}

package/src/theme/components/nav/mobile-nav-cta.tsx

@@ -0,0 +1,79 @@
+import React, { useEffect, useState } from 'react'
+import { createPortal } from 'react-dom'
+
+import { TopbarCTA } from './topbar-cta'
+
+export interface MobileNavCTAProps {
+  /**
+   * CTA button text.
+   */
+  readonly text: string
+  /**
+   * CTA destination href.
+   */
+  readonly href: string
+}
+
+const HOST_ATTR = 'data-cp-mobile-nav-cta-host'
+
+/**
+ * MobileNavCTA — portals a primary CTA button into Rspress's mobile
+ * nav-screen (`.rp-nav-screen__container`) so users can still reach
+ * the get-started action when the topbar CTA is hidden on narrow
+ * viewports. Inserts the CTA right before the trailing social-links
+ * block so the existing dividers wrap it naturally.
+ *
+ * Watches DOM mutations because Rspress mounts the nav-screen
+ * lazily on first hamburger click and re-mounts on route changes.
+ *
+ * @param props - CTA configuration.
+ * @returns React element.
+ */
+export function MobileNavCTA(props: MobileNavCTAProps): React.ReactElement | null {
+  const [host, setHost] = useState<HTMLElement | null>(null)
+
+  useEffect(() => {
+    function ensureHost(): HTMLElement | null {
+      const container = globalThis.document.querySelector(
+        '.rp-nav-screen__container'
+      ) as HTMLElement | null
+      if (container === null) {
+        return null
+      }
+      const existing = container.querySelector(`[${HOST_ATTR}]`) as HTMLElement | null
+      if (existing !== null) {
+        return existing
+      }
+      const node = globalThis.document.createElement('div')
+      node.setAttribute(HOST_ATTR, '')
+      node.className = 'cp-mobile-nav-cta'
+      const socials = container.querySelector('.rp-social-links')
+      if (socials === null) {
+        container.append(node)
+      } else {
+        socials.before(node)
+      }
+      return node
+    }
+
+    setHost(ensureHost())
+
+    const observer = new globalThis.MutationObserver(() => {
+      const next = ensureHost()
+      setHost((prev) => {
+        if (prev !== null && prev.isConnected) {
+          return prev
+        }
+        return next
+      })
+    })
+    observer.observe(globalThis.document.body, { childList: true, subtree: true })
+
+    return () => observer.disconnect()
+  }, [])
+
+  if (host === null) {
+    return null
+  }
+  return createPortal(<TopbarCTA text={props.text} href={props.href} />, host)
+}

package/src/theme/components/nav/nav-divider.css

@@ -0,0 +1,15 @@
+/**
+ * Vertical nav divider — used inline between groups of topbar elements.
+ *
+ * Theme-customisable via:
+ *   --cp-c-divider   colour (defaults via the active theme's --cp-c-divider)
+ *   --cp-nav-divider-height   height of the line (default 18px)
+ *   --cp-nav-divider-width    width of the line (default 1px)
+ */
+.cp-nav-divider {
+  display: inline-block;
+  flex-shrink: 0;
+  width: var(--cp-nav-divider-width, 1px);
+  height: var(--cp-nav-divider-height, 18px);
+  background: var(--cp-c-divider);
+}

package/src/theme/components/nav/nav-divider.tsx

@@ -0,0 +1,19 @@
+import type React from 'react'
+
+import './nav-divider.css'
+
+/**
+ * Thin vertical divider used to separate adjacent groups of nav items
+ * in the topbar (logo / search / menu / icons / CTA).
+ *
+ * Themable via the `--cp-c-divider` CSS custom property and the
+ * `.cp-nav-divider` class. The divider is `aria-hidden` so it does not
+ * pollute the accessibility tree.
+ *
+ * @returns Inline-flex divider element
+ */
+export function NavDivider(): React.ReactElement {
+  return <span className="cp-nav-divider" aria-hidden="true" />
+}
+
+export { NavDivider as default }

package/src/theme/components/nav/nav-logo.css

@@ -0,0 +1,42 @@
+/**
+ * NavLogo slot — portaled into `.rp-nav__title__link` to render ciderpress's
+ * theme-aware `<CiderpressLogo />` SVG or the user's function-form logo.
+ *
+ * Render pipeline:
+ *   1. Initial paint: Rspress emits its native `<img src="/logo.svg">`
+ *      (the auto-generated static SVG with hardcoded brand color).
+ *   2. After hydration: NavLogo's portal mounts a `<span class="cp-nav-logo">`
+ *      child with an inline SVG that reads `var(--rp-c-brand)` via
+ *      `currentColor`, giving us theme-aware color switching.
+ *   3. CSS below hides the native img + fallback span when our portal mounts
+ *      so only the theme-aware version shows.
+ *
+ * The `:has(.cp-nav-logo)` guard means CSS only hides Rspress's native logo
+ * when our slot actually mounted — if NavLogo fails for any reason, the
+ * static `/logo.svg` stays visible as a graceful fallback.
+ */
+
+.cp-nav-logo {
+  display: inline-flex;
+  align-items: center;
+  line-height: 0;
+}
+
+.cp-nav-logo > svg {
+  display: block;
+  height: 1.75rem;
+  width: auto;
+}
+
+/* When our theme-aware portal mounts, hide Rspress's stock title elements
+   so we don't double-render. Covers both:
+   - the fallback `<span>title</span>` (rendered when no logo string)
+   - the native `<img class="rspress-logo">` (rendered for string logos
+     including our `/logo.svg` default).
+   The `:not(.cp-nav-logo)` guard is critical — our portal IS a span, so
+   a bare `> span` selector would hide it too. */
+.rp-nav__title__link:has(.cp-nav-logo) > span:not(.cp-nav-logo),
+.rp-nav__title__link:has(.cp-nav-logo) > .rp-nav__title__logo,
+.rp-nav__title__link:has(.cp-nav-logo) > img.rspress-logo {
+  display: none;
+}