@ciderpress/ui 1.0.0-rc.1

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

@@ -0,0 +1,113 @@
+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 { NavDivider } from './nav-divider'
+import { TopbarCTA } from './topbar-cta'
+import { VariantToggle } from './variant-toggle'
+
+import './ciderpress-header.css'
+
+/**
+ * Props for the ciderpress site header.
+ */
+export interface CiderpressHeaderProps {
+  /**
+   * Pre-rendered announcement bar, pinned above the nav row. Pass
+   * `null` to omit.
+   */
+  readonly announcement: React.ReactNode
+  /**
+   * Primary nav menu items, fed straight into `<CiderpressNavMenu />`.
+   */
+  readonly navItems: readonly CiderpressNavMenuItem[]
+  /**
+   * Social-link entries (GitHub, npm, etc) read from `site.socialLinks`.
+   */
+  readonly socialLinks: readonly CiderpressSocialLink[]
+  /**
+   * Topbar CTA configuration. Pass `undefined` to omit.
+   */
+  readonly topbarCta: { readonly text: string; readonly href: string } | undefined
+  /**
+   * `true` on the home page — used to suppress the sidebar toggle.
+   */
+  readonly isHome: boolean
+}
+
+/**
+ * Custom replacement for Rspress's built-in `.rp-nav`. Owns the entire
+ * topbar chrome (logo, search trigger, primary menu with
+ * measure-and-collapse overflow, variant toggle, social cluster, CTA)
+ * using only `cp-*` class names and `cp-*` CSS custom properties so
+ * theme authors can override every surface without reaching into
+ * Rspress internals.
+ *
+ * Rspress's own `.rp-nav` is hidden by a rule in
+ * `styles/overrides/rail.css` — the two never coexist visually.
+ *
+ * @param props - Header configuration
+ * @returns Sticky header element
+ */
+export function CiderpressHeader(props: CiderpressHeaderProps): React.ReactElement {
+  // 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.
+  return (
+    <header
+      className={clsx('cp-header', {
+        'cp-header--landing': props.isHome,
+        'cp-header--docs': !props.isHome,
+      })}
+    >
+      {props.announcement}
+      <div className="cp-header-inner">
+        {/* Left: hamburger (mobile primary-nav drawer) + logo. Sidebar
+            collapse/expand lives in <CiderpressDocsBar />, the sticky
+            sub-header rendered beneath the site nav on docs pages. */}
+        <CiderpressNavHamburger
+          navItems={props.navItems}
+          socialLinks={props.socialLinks}
+          topbarCta={props.topbarCta}
+        />
+        <RouteLink href="/" className="cp-header-logo" aria-label="Home">
+          <CiderpressLogo />
+        </RouteLink>
+
+        {/* Right cluster wrapper. Grows from a zero basis so its width
+            equals the actual available room (not the content), which is
+            the stable measurement target the React overflow logic
+            inside CiderpressNavMenu needs.
+
+            Inside: search comes first, then the menu (which itself
+            fills the leftover room and right-aligns items inside).
+            That places search immediately before the menu items, both
+            anchored to the right edge of the wrapper. */}
+        <div className="cp-header-menu-wrap">
+          <CiderpressNavSearch />
+          <NavDivider />
+          <CiderpressNavMenu items={props.navItems} />
+        </div>
+
+        <NavDivider />
+        <VariantToggle />
+        <CiderpressNavSocialLinks links={props.socialLinks} />
+        {props.topbarCta !== undefined && (
+          <>
+            <NavDivider />
+            <TopbarCTA text={props.topbarCta.text} href={props.topbarCta.href} />
+          </>
+        )}
+      </div>
+    </header>
+  )
+}
+
+export { CiderpressHeader as default }

package/dist/theme/components/nav/ciderpress-layout-context.tsx

@@ -0,0 +1,49 @@
+import { createContext, useContext } from 'react'
+import type React from 'react'
+
+/**
+ * State shape for the ciderpress doc-layout drawer controls.
+ *
+ * Shared between `<CiderpressDocLayout />` (the owner) and
+ * `<CiderpressDocsBar />` (the consumer that toggles the sidebar
+ * drawer open/closed on narrow viewports).
+ */
+export interface CiderpressLayoutContextValue {
+  readonly isSidebarOpen: boolean
+  readonly setIsSidebarOpen: React.Dispatch<React.SetStateAction<boolean>>
+  readonly isOutlineOpen: boolean
+  readonly setIsOutlineOpen: React.Dispatch<React.SetStateAction<boolean>>
+}
+
+/**
+ * Empty default setter — used only when the context is read outside
+ * a provider, which happens on home / blank pages where the doc
+ * layout isn't mounted.
+ *
+ * @private
+ */
+function noop(): void {
+  // intentional no-op
+}
+
+const defaultValue: CiderpressLayoutContextValue = {
+  isSidebarOpen: false,
+  setIsSidebarOpen: noop,
+  isOutlineOpen: false,
+  setIsOutlineOpen: noop,
+}
+
+/**
+ * @internal
+ */
+export const CiderpressLayoutContext = createContext<CiderpressLayoutContextValue>(defaultValue)
+
+/**
+ * Read the shared doc-layout drawer state. Returns no-op setters when
+ * called outside a `<CiderpressDocLayout />` (e.g. on home pages).
+ *
+ * @returns Sidebar/outline open state and their setters.
+ */
+export function useCiderpressLayout(): CiderpressLayoutContextValue {
+  return useContext(CiderpressLayoutContext)
+}

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

@@ -0,0 +1,193 @@
+/**
+ * CiderpressNavHamburger — mobile drawer trigger and slide-in panel.
+ *
+ * Theme-author API:
+ *   --cp-nav-hamburger-breakpoint   max viewport width to show
+ *                                    hamburger / hide desktop chrome
+ *                                    (default 768px)
+ *   --cp-nav-drawer-width           drawer panel width (default 320px)
+ *   --cp-nav-drawer-bg              drawer background colour
+ *   --cp-nav-drawer-backdrop        backdrop colour
+ *   --cp-nav-drawer-shadow          drawer drop shadow
+ */
+.cp-nav-hamburger {
+  display: none;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  padding: 0;
+  background: transparent;
+  border: 1px solid var(--cp-c-border);
+  border-radius: 8px;
+  color: var(--cp-c-text-2);
+  cursor: pointer;
+  transition:
+    border-color 0.15s ease,
+    color 0.15s ease;
+}
+
+.cp-nav-hamburger:hover {
+  border-color: var(--cp-c-brand-1);
+  color: var(--cp-c-brand-1);
+}
+
+/* Show the hamburger at the same breakpoint where `<CiderpressHeader />`
+   collapses its desktop chrome (see `ciderpress-header.css`) and where
+   `<CiderpressDocsBar />` flips to its mobile layout, so all three
+   pieces transition together. */
+@media (max-width: 1024px) {
+  .cp-nav-hamburger {
+    display: inline-flex;
+  }
+}
+
+/* ── Drawer ─────────────────────────────────────────────────────── */
+/*
+ * `.cp-nav-drawer-root` is the react-aria-components <ModalOverlay>
+ * (acts as the backdrop). `.cp-nav-drawer-modal` is the <Modal> wrapper.
+ * `.cp-nav-drawer` is the <Dialog> — the focus-trapped panel.
+ */
+.cp-nav-drawer-root {
+  position: fixed;
+  inset: 0;
+  z-index: 100;
+  background: var(--cp-nav-drawer-backdrop, rgba(0, 0, 0, 0.55));
+  backdrop-filter: blur(4px);
+  animation: cp-nav-drawer-fade-in 0.18s ease-out forwards;
+}
+
+.cp-nav-drawer-modal {
+  position: absolute;
+  top: 0;
+  left: 0;
+  height: 100vh;
+  width: min(var(--cp-nav-drawer-width, 320px), 100vw);
+}
+
+.cp-nav-drawer {
+  outline: none;
+  height: 100%;
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  background: var(--cp-nav-drawer-bg, var(--cp-c-bg));
+  border-right: 1px solid var(--cp-c-border);
+  box-shadow: var(--cp-nav-drawer-shadow, 8px 0 32px rgba(0, 0, 0, 0.3));
+  animation: cp-nav-drawer-slide-in 0.22s cubic-bezier(0.2, 0.6, 0.2, 1) forwards;
+  overflow-y: auto;
+}
+
+.cp-nav-drawer__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px 20px;
+  border-bottom: 1px solid var(--cp-c-divider);
+}
+
+.cp-nav-drawer__title {
+  font-family: var(--cp-font-family-base);
+  font-size: 14px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--cp-c-text-3);
+}
+
+.cp-nav-drawer__close {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  background: transparent;
+  border: 1px solid var(--cp-c-border);
+  border-radius: 6px;
+  color: var(--cp-c-text-2);
+  cursor: pointer;
+  transition:
+    color 0.15s ease,
+    border-color 0.15s ease;
+}
+
+.cp-nav-drawer__close:hover {
+  border-color: var(--cp-c-brand-1);
+  color: var(--cp-c-brand-1);
+}
+
+.cp-nav-drawer__nav {
+  display: flex;
+  flex-direction: column;
+  padding: 12px 8px;
+}
+
+.cp-nav-drawer__link {
+  display: block;
+  padding: 12px 16px;
+  border-radius: 8px;
+  color: var(--cp-c-text-1);
+  font-size: 15px;
+  font-weight: 500;
+  text-decoration: none;
+  transition:
+    background 0.12s ease,
+    color 0.12s ease;
+}
+
+.cp-nav-drawer__link:hover {
+  background: var(--cp-c-bg-soft);
+  color: var(--cp-c-brand-1);
+  text-decoration: none;
+}
+
+.cp-nav-drawer__divider {
+  height: 1px;
+  margin: 4px 20px;
+  background: var(--cp-c-divider);
+}
+
+.cp-nav-drawer__row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 12px 20px;
+}
+
+.cp-nav-drawer__row-label {
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--cp-c-text-3);
+}
+
+.cp-nav-drawer__footer {
+  margin-top: auto;
+  padding: 16px 20px;
+  border-top: 1px solid var(--cp-c-divider);
+  display: flex;
+}
+
+.cp-nav-drawer__footer > .cp-topbar-cta {
+  flex: 1;
+  justify-content: center;
+}
+
+@keyframes cp-nav-drawer-fade-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes cp-nav-drawer-slide-in {
+  from {
+    transform: translateX(-100%);
+  }
+  to {
+    transform: translateX(0);
+  }
+}

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

@@ -0,0 +1,112 @@
+import { useState } from 'react'
+import type React from 'react'
+import { Dialog, Modal, ModalOverlay } from 'react-aria-components'
+
+import { RouteLink } from '../../lib/route-link.tsx'
+import { Icon } from '../shared/icon.tsx'
+import type { CiderpressNavMenuItem } from './ciderpress-nav-menu'
+import { CiderpressNavSocialLinks } from './ciderpress-nav-social-links'
+import type { CiderpressSocialLink } from './ciderpress-nav-social-links'
+import { TopbarCTA } from './topbar-cta'
+import { VariantToggle } from './variant-toggle'
+
+import './ciderpress-nav-hamburger.css'
+
+/**
+ * Props for the mobile hamburger menu.
+ */
+export interface CiderpressNavHamburgerProps {
+  readonly navItems: readonly CiderpressNavMenuItem[]
+  readonly socialLinks: readonly CiderpressSocialLink[]
+  readonly topbarCta: { readonly text: string; readonly href: string } | undefined
+}
+
+/**
+ * Mobile hamburger trigger + slide-in drawer. Shown only at narrow
+ * viewports (CSS-driven via `--cp-nav-hamburger-breakpoint`). Drawer
+ * surfaces the full primary nav, variant toggle, social cluster, and
+ * CTA on screens where the desktop chrome can't fit.
+ *
+ * Built on `react-aria-components` `<ModalOverlay>` + `<Dialog>`, which
+ * provides a proper focus trap, focus restoration to the trigger,
+ * inert/aria-hidden on the rest of the page, ESC dismissal, and
+ * scroll-locking. Hand-rolling that correctly is famously hard, so we
+ * delegate.
+ *
+ * @param props - Nav items / social / CTA configuration
+ * @returns Hamburger button (mobile) + drawer (when open)
+ */
+export function CiderpressNavHamburger(props: CiderpressNavHamburgerProps): React.ReactElement {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <>
+      <button
+        type="button"
+        className="cp-nav-hamburger"
+        onClick={() => setOpen(true)}
+        aria-label="Open navigation menu"
+        aria-expanded={open}
+      >
+        <Icon icon="pixelarticons:menu" width={20} height={20} />
+      </button>
+      <ModalOverlay
+        className="cp-nav-drawer-root"
+        isOpen={open}
+        onOpenChange={setOpen}
+        isDismissable
+      >
+        <Modal className="cp-nav-drawer-modal">
+          <Dialog className="cp-nav-drawer" aria-label="Site navigation">
+            <header className="cp-nav-drawer__header">
+              <span className="cp-nav-drawer__title">Menu</span>
+              <button
+                type="button"
+                className="cp-nav-drawer__close"
+                onClick={() => setOpen(false)}
+                aria-label="Close navigation menu"
+              >
+                <Icon icon="pixelarticons:close" width={18} height={18} />
+              </button>
+            </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>
+              ))}
+            </nav>
+
+            <div className="cp-nav-drawer__divider" />
+
+            <div className="cp-nav-drawer__row">
+              <span className="cp-nav-drawer__row-label">Theme</span>
+              <VariantToggle />
+            </div>
+
+            {props.socialLinks.length > 0 && (
+              <div className="cp-nav-drawer__row">
+                <span className="cp-nav-drawer__row-label">Links</span>
+                <CiderpressNavSocialLinks links={props.socialLinks} />
+              </div>
+            )}
+
+            {props.topbarCta !== undefined && (
+              <div className="cp-nav-drawer__footer">
+                <TopbarCTA text={props.topbarCta.text} href={props.topbarCta.href} />
+              </div>
+            )}
+          </Dialog>
+        </Modal>
+      </ModalOverlay>
+    </>
+  )
+}
+
+export { CiderpressNavHamburger as default }

package/dist/theme/components/nav/ciderpress-nav-menu.css

@@ -0,0 +1,130 @@
+/**
+ * CiderpressNavMenu — primary topbar nav with overflow → dropdown.
+ *
+ * Theme-author API (all overridable per theme):
+ *   --cp-nav-menu-gap                inline gap between items (default 16px)
+ *   --cp-nav-menu-item-padding-x     horizontal padding inside each item
+ *   --cp-nav-menu-item-color         item text colour
+ *   --cp-nav-menu-item-color-hover   item text colour on hover
+ *   --cp-nav-menu-item-color-active  item text colour on the active route
+ *   --cp-nav-menu-item-font-size     item font size
+ *   --cp-nav-menu-item-font-weight   item font weight
+ *   --cp-nav-menu-overflow-bg        overflow popover surface colour
+ *   --cp-nav-menu-overflow-border    overflow popover border colour
+ */
+.cp-nav-menu {
+  display: flex;
+  align-items: center;
+  gap: var(--cp-nav-menu-gap, 16px);
+  /* Take the full width of the parent wrapper so that
+     `container.clientWidth` (used by the ResizeObserver) reflects the
+     actual space available for items, not just the natural width of
+     whatever items happen to currently render. Without this the menu
+     shrinks to fit its content, reports a tiny available width, and
+     collapses every item into the overflow popover. */
+  flex: 1 1 auto;
+  width: 100%;
+  min-width: 0;
+  white-space: nowrap;
+}
+
+.cp-nav-menu__item {
+  display: inline-flex;
+  align-items: center;
+  padding: 0 var(--cp-nav-menu-item-padding-x, 4px);
+  color: var(--cp-nav-menu-item-color, var(--cp-c-text-2, #cdd6f4));
+  font-size: var(--cp-nav-menu-item-font-size, 13px);
+  font-weight: var(--cp-nav-menu-item-font-weight, 500);
+  line-height: 1;
+  text-decoration: none;
+  white-space: nowrap;
+  transition: color 0.15s ease;
+}
+
+.cp-nav-menu__item:hover {
+  color: var(--cp-nav-menu-item-color-hover, var(--cp-c-brand-1, currentColor));
+  text-decoration: none;
+}
+
+.cp-nav-menu__item--active {
+  color: var(--cp-nav-menu-item-color-active, var(--cp-c-brand-1, currentColor));
+}
+
+/* ── Hidden measurement layer ──────────────────────────────────────────
+   Renders every item at full natural width so the JS layer always has
+   a stable per-item measurement no matter how narrow the live menu
+   gets. `position: absolute` + `visibility: hidden` keeps it out of
+   the layout flow while remaining measurable. */
+.cp-nav-menu-measure {
+  position: absolute;
+  visibility: hidden;
+  pointer-events: none;
+  display: inline-flex;
+  gap: var(--cp-nav-menu-gap, 16px);
+  white-space: nowrap;
+}
+
+/* ── Overflow toggle + popover ─────────────────────────────────────── */
+.cp-nav-menu__overflow {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+}
+
+.cp-nav-menu__overflow-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 0 var(--cp-nav-menu-item-padding-x, 4px);
+  background: transparent;
+  border: none;
+  color: var(--cp-nav-menu-item-color, var(--cp-c-text-2, #cdd6f4));
+  font-size: var(--cp-nav-menu-item-font-size, 13px);
+  font-weight: var(--cp-nav-menu-item-font-weight, 500);
+  line-height: 1;
+  cursor: pointer;
+  transition: color 0.15s ease;
+}
+
+.cp-nav-menu__overflow-toggle:hover {
+  color: var(--cp-nav-menu-item-color-hover, var(--cp-c-brand-1, currentColor));
+}
+
+.cp-nav-menu__overflow-popover {
+  position: absolute;
+  top: calc(100% + 6px);
+  right: 0;
+  z-index: 60;
+  min-width: 200px;
+  margin: 0;
+  padding: 6px;
+  list-style: none;
+  background: var(--cp-nav-menu-overflow-bg, var(--cp-c-bg, #1e1e2e));
+  border: 1px solid var(--cp-nav-menu-overflow-border, var(--cp-c-border, #313244));
+  border-radius: 8px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.24);
+}
+
+.cp-nav-menu__overflow-item {
+  display: block;
+  padding: 8px 12px;
+  border-radius: 6px;
+  color: var(--cp-nav-menu-item-color, var(--cp-c-text-2, #cdd6f4));
+  font-size: 13px;
+  font-weight: 500;
+  text-decoration: none;
+  white-space: nowrap;
+  transition:
+    background 0.1s ease,
+    color 0.1s ease;
+}
+
+.cp-nav-menu__overflow-item:hover {
+  background: var(--cp-c-bg-soft, rgba(255, 255, 255, 0.04));
+  color: var(--cp-nav-menu-item-color-hover, var(--cp-c-brand-1, currentColor));
+  text-decoration: none;
+}
+
+.cp-nav-menu__overflow-item--active {
+  color: var(--cp-nav-menu-item-color-active, var(--cp-c-brand-1, currentColor));
+}