@ciderpress/ui 1.0.0-rc.1

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

@@ -0,0 +1,372 @@
+import { useLocation } from '@rspress/core/runtime'
+import { clsx } from 'clsx'
+import { match } from 'massaman/match'
+import { useEffect, useMemo, useRef, useState } from 'react'
+import type React from 'react'
+
+import { RouteLink } from '../../lib/route-link.tsx'
+import { Icon } from '../shared/icon.tsx'
+
+import './ciderpress-nav-menu.css'
+
+/**
+ * Width reserved at the end of the menu strip for the overflow toggle
+ * (the "More ▾" button). Subtracted from the available width when
+ * deciding how many items can fit inline.
+ */
+const OVERFLOW_TOGGLE_WIDTH = 96
+
+/**
+ * Inter-item gap matching `--cp-nav-menu-gap`. Used during width
+ * accounting so we don't have to query computed style on every frame.
+ */
+const DEFAULT_GAP_PX = 16
+
+/**
+ * Single primary-nav entry — matches the shape of `site.nav[*]` in
+ * `ciderpress.config.ts`.
+ */
+export interface CiderpressNavMenuItem {
+  readonly text: string
+  readonly link: string
+}
+
+/**
+ * Props for `<CiderpressNavMenu />`.
+ */
+export interface CiderpressNavMenuProps {
+  readonly items: readonly CiderpressNavMenuItem[]
+}
+
+/**
+ * Primary nav menu with overflow → dropdown handling. Renders all items
+ * inline when they fit; when the container is too narrow, the trailing
+ * items collapse into a "More ▾" popover so the strip never pushes off
+ * screen.
+ *
+ * Sizing is measured with a `ResizeObserver` on the wrapper plus a
+ * hidden measurement row that always renders every item at full width.
+ * The hidden row gives us a stable per-item width to walk against the
+ * live available width.
+ *
+ * @param props - Item list
+ * @returns Nav element
+ */
+export function CiderpressNavMenu(props: CiderpressNavMenuProps): React.ReactElement {
+  // Pull items from props when configured, otherwise fall back to scraping
+  // Rspress's hidden `.rp-nav-menu` (it's the source of truth at runtime
+  // when the `nav` field isn't exposed on the Rspress site typings).
+  const [scrapedItems, setScrapedItems] = useState<readonly CiderpressNavMenuItem[]>([])
+  useEffect(() => {
+    if (props.items.length > 0) {
+      return
+    }
+    const initial = scrapeNavItems()
+    if (initial.length > 0) {
+      setScrapedItems(initial)
+      return
+    }
+    const observer = new MutationObserver(() => {
+      const fresh = scrapeNavItems()
+      if (fresh.length > 0) {
+        setScrapedItems(fresh)
+        observer.disconnect()
+      }
+    })
+    observer.observe(document.body, { childList: true, subtree: true })
+    return () => {
+      observer.disconnect()
+    }
+  }, [props.items])
+  const items = useMemo<readonly CiderpressNavMenuItem[]>(
+    () =>
+      match(props.items.length > 0)
+        .with(true, () => props.items)
+        .otherwise(() => scrapedItems),
+    [props.items, scrapedItems]
+  )
+
+  const containerRef = useRef<HTMLDivElement>(null)
+  const measureRef = useRef<HTMLDivElement>(null)
+  const [visibleCount, setVisibleCount] = useState(items.length)
+  const [overflowOpen, setOverflowOpen] = useState(false)
+  const overflowRef = useRef<HTMLDivElement>(null)
+  const { pathname } = useLocation()
+
+  useEffect(() => {
+    const container = containerRef.current
+    const measure = measureRef.current
+    if (container === null || measure === null) {
+      return
+    }
+
+    // We observe the menu's PARENT (the wrap), not the menu itself.
+    // Measuring the menu would self-collapse: when items hide, the
+    // menu shrinks, clientWidth drops, the budget shrinks, more items
+    // hide. Observing the parent gives us a width that's a function of
+    // the layout (not of how many items we currently render).
+    const parent = container.parentElement
+    if (parent === null) {
+      return
+    }
+
+    const observer = new ResizeObserver(() => {
+      setVisibleCount(computeMenuFit({ measure, parent, container }))
+    })
+    observer.observe(parent)
+    const observedChildren = [...parent.children].filter(
+      (child) => child !== container && inLayoutFlow(child)
+    )
+    observedChildren.map((child) => observer.observe(child))
+    setVisibleCount(computeMenuFit({ measure, parent, container }))
+    return () => {
+      observer.disconnect()
+    }
+  }, [items])
+
+  useEffect(() => {
+    if (!overflowOpen) {
+      return
+    }
+    function onDocClick(event: MouseEvent): void {
+      const target = event.target as Node | null
+      if (
+        target !== null &&
+        overflowRef.current !== null &&
+        !overflowRef.current.contains(target)
+      ) {
+        setOverflowOpen(false)
+      }
+    }
+    document.addEventListener('mousedown', onDocClick)
+    return () => {
+      document.removeEventListener('mousedown', onDocClick)
+    }
+  }, [overflowOpen])
+
+  const visible = items.slice(0, visibleCount)
+  const overflow = items.slice(visibleCount)
+  const hasOverflow = overflow.length > 0
+
+  return (
+    <>
+      <div ref={measureRef} className="cp-nav-menu-measure" aria-hidden="true">
+        {items.map((item) => (
+          <span key={item.link} data-cp-menu-item className="cp-nav-menu__item">
+            {item.text}
+          </span>
+        ))}
+      </div>
+
+      <nav ref={containerRef} className="cp-nav-menu" aria-label="Primary">
+        {visible.map((item) => (
+          <RouteLink
+            key={item.link}
+            href={item.link}
+            className={clsx('cp-nav-menu__item', {
+              'cp-nav-menu__item--active': isActive(pathname, item.link),
+            })}
+          >
+            {item.text}
+          </RouteLink>
+        ))}
+        {hasOverflow && (
+          <div ref={overflowRef} className="cp-nav-menu__overflow">
+            <button
+              type="button"
+              className="cp-nav-menu__overflow-toggle"
+              onClick={() => setOverflowOpen((open) => !open)}
+              aria-haspopup="menu"
+              aria-expanded={overflowOpen}
+            >
+              <span>More</span>
+              <Icon icon="pixelarticons:chevron-down" width={12} height={12} />
+            </button>
+            {overflowOpen && (
+              <ul className="cp-nav-menu__overflow-popover" role="menu">
+                {overflow.map((item) => (
+                  <li key={item.link} role="none">
+                    <RouteLink
+                      href={item.link}
+                      role="menuitem"
+                      className={clsx('cp-nav-menu__overflow-item', {
+                        'cp-nav-menu__overflow-item--active': isActive(pathname, item.link),
+                      })}
+                      onClick={() => setOverflowOpen(false)}
+                    >
+                      {item.text}
+                    </RouteLink>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </div>
+        )}
+      </nav>
+    </>
+  )
+}
+
+export { CiderpressNavMenu as default }
+
+/**
+ * Walk the per-item widths left-to-right, accumulating until we'd
+ * exceed the available width. When the accumulator already exceeds the
+ * cheap-fit budget, reserve space for the overflow toggle so the toggle
+ * itself doesn't push the last visible item out.
+ *
+ * @private
+ */
+function computeVisibleCount(params: {
+  readonly widths: readonly number[]
+  readonly available: number
+  readonly gap: number
+  readonly overflowReserve: number
+}): number {
+  const { widths, available, gap, overflowReserve } = params
+  // No items, or the container hasn't been laid out yet — assume every
+  // item fits. The ResizeObserver will recompute as soon as the
+  // container has a real width.
+  if (widths.length === 0 || available <= 0) {
+    return widths.length
+  }
+
+  const fullTotal = widths.reduce((acc, w, i) => acc + w + gapAt(i, gap), 0)
+  if (fullTotal <= available) {
+    return widths.length
+  }
+
+  // Otherwise we know we need overflow; reserve space for the toggle.
+  const budget = available - overflowReserve
+  const walked = widths.reduce<{
+    readonly running: number
+    readonly count: number
+    readonly done: boolean
+  }>(
+    (state, width, index) => {
+      if (state.done) {
+        return state
+      }
+      const next = state.running + width + gapAt(index, gap)
+      if (next > budget) {
+        return { ...state, done: true }
+      }
+      return { running: next, count: state.count + 1, done: false }
+    },
+    { running: 0, count: 0, done: false }
+  )
+  return walked.count
+}
+
+/**
+ * Gap to add before the item at `index` when summing widths. Index 0
+ * has no leading gap; subsequent items get the menu's inter-item gap.
+ *
+ * @private
+ * @param index - Position of the item in the width array.
+ * @param gap - Inter-item gap in pixels.
+ * @returns Leading gap to add before this item.
+ */
+function gapAt(index: number, gap: number): number {
+  if (index === 0) {
+    return 0
+  }
+  return gap
+}
+
+/**
+ * Read every anchor under Rspress's hidden `.rp-nav-menu` and project
+ * it into a `{ text, link }` item. Anchors with empty text or `href`
+ * are dropped so we never surface a placeholder entry.
+ *
+ * @private
+ * @returns Nav items currently in the DOM (empty array when not mounted).
+ */
+function scrapeNavItems(): readonly CiderpressNavMenuItem[] {
+  const anchors = document.querySelectorAll<HTMLAnchorElement>('.rp-nav-menu .rp-nav-menu__item a')
+  return [...anchors]
+    .map((anchor) => ({
+      text: readAnchorText(anchor),
+      link: anchor.getAttribute('href') ?? '',
+    }))
+    .filter((item) => item.text !== '' && item.link !== '')
+}
+
+/**
+ * Pull the trimmed text content from an anchor. Returns an empty
+ * string when `textContent` is missing — callers treat empty as "skip
+ * this anchor".
+ *
+ * @private
+ * @param anchor - Anchor element to read.
+ * @returns Trimmed inner text, or empty string when absent.
+ */
+function readAnchorText(anchor: HTMLAnchorElement): string {
+  const text = anchor.textContent
+  if (text === null) {
+    return ''
+  }
+  return text.trim()
+}
+
+/**
+ * Exclude elements removed from the layout — the hidden measure layer
+ * is `position: absolute`, anything `display: none` is gone, anything
+ * `visibility: hidden` still occupies space so it stays counted. We
+ * only want flex-contributing siblings.
+ *
+ * @private
+ * @param child - Sibling element to test.
+ * @returns True when the element contributes to the parent's flex layout.
+ */
+function inLayoutFlow(child: Element): boolean {
+  const cs = globalThis.getComputedStyle(child)
+  return cs.display !== 'none' && cs.position !== 'absolute' && cs.position !== 'fixed'
+}
+
+/**
+ * Compute how many items fit inline given the live layout. Measures
+ * each item's full-width footprint from the hidden measure row, then
+ * subtracts every layout sibling's width (plus inter-flex gaps) from
+ * the parent's clientWidth to derive the budget for the menu strip.
+ *
+ * @private
+ * @param params - Refs to the measure row, container, and parent.
+ * @returns Number of items that fit inline.
+ */
+function computeMenuFit(params: {
+  readonly measure: HTMLDivElement
+  readonly parent: HTMLElement
+  readonly container: HTMLDivElement
+}): number {
+  const { measure, parent, container } = params
+  const itemElements = measure.querySelectorAll<HTMLElement>('[data-cp-menu-item]')
+  const widths = [...itemElements].map((el) => el.getBoundingClientRect().width)
+  const parentWidth = parent.clientWidth
+  const parentGap = parseFloat(globalThis.getComputedStyle(parent).columnGap || '0') || 0
+  const layoutSiblings = [...parent.children].filter(
+    (child) => child !== container && inLayoutFlow(child)
+  )
+  const siblingsWidth = layoutSiblings.reduce(
+    (sum, child) => sum + child.getBoundingClientRect().width,
+    0
+  )
+  const gapCount = Math.max(0, layoutSiblings.length + 1 - 1)
+  const available = Math.max(0, parentWidth - siblingsWidth - gapCount * parentGap)
+  return computeVisibleCount({
+    widths,
+    available,
+    gap: DEFAULT_GAP_PX,
+    overflowReserve: OVERFLOW_TOGGLE_WIDTH,
+  })
+}
+
+/**
+ * @private
+ */
+function isActive(pathname: string, link: string): boolean {
+  if (link === '/') {
+    return pathname === '/'
+  }
+  return pathname.startsWith(link)
+}

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

@@ -0,0 +1,73 @@
+/**
+ * CiderpressNavSearch — pill-shaped trigger that opens Rspress's
+ * search modal via a synthetic Cmd+K event.
+ *
+ * Theme-author API:
+ *   --cp-nav-search-bg              background colour
+ *   --cp-nav-search-border          border colour (idle)
+ *   --cp-nav-search-border-hover    border colour on hover
+ *   --cp-nav-search-color           text colour
+ *   --cp-nav-search-width           total button width (default 200px)
+ *   --cp-nav-search-radius          pill radius (default 999px)
+ *   --cp-nav-search-padding         horizontal padding (default 12px)
+ */
+.cp-nav-search {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  width: var(--cp-nav-search-width, 160px);
+  height: 32px;
+  padding: 0 var(--cp-nav-search-padding, 12px);
+  background: var(--cp-nav-search-bg, var(--cp-c-bg-soft));
+  border: 1px solid var(--cp-nav-search-border, var(--cp-c-border));
+  border-radius: var(--cp-nav-search-radius, 8px);
+  color: var(--cp-nav-search-color, var(--cp-c-text-3));
+  font-family: var(--cp-font-family-base);
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+  transition:
+    border-color 0.15s ease,
+    color 0.15s ease;
+}
+
+.cp-nav-search:hover {
+  border-color: var(--cp-nav-search-border-hover, var(--cp-c-brand-1));
+  color: var(--cp-c-text-1);
+}
+
+.cp-nav-search__icon {
+  flex-shrink: 0;
+  color: var(--cp-c-text-3);
+}
+
+.cp-nav-search__label {
+  flex: 1 1 auto;
+  text-align: left;
+}
+
+.cp-nav-search__hotkey {
+  display: inline-flex;
+  align-items: center;
+  gap: 1px;
+  flex-shrink: 0;
+  padding: 1px 5px;
+  background: var(--cp-c-bg-elv, rgba(255, 255, 255, 0.08));
+  border: 1px solid var(--cp-c-border);
+  border-radius: 4px;
+  font-family: inherit;
+  font-size: 11px;
+  line-height: 1.2;
+  color: var(--cp-c-text-3);
+}
+
+@media (max-width: 640px) {
+  .cp-nav-search__label,
+  .cp-nav-search__hotkey {
+    display: none;
+  }
+  .cp-nav-search {
+    width: auto;
+    padding: 0 10px;
+  }
+}

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

@@ -0,0 +1,55 @@
+import type React from 'react'
+
+import { Icon } from '../shared/icon.tsx'
+
+import './ciderpress-nav-search.css'
+
+/**
+ * Search trigger button. Click dispatches a synthetic `Cmd+K` keyboard
+ * event so Rspress's underlying search modal opens — same shortcut the
+ * user can press globally. We don't reach into Rspress's search
+ * internals; the keyboard handler is the public contract.
+ *
+ * @returns Search trigger button
+ */
+export function CiderpressNavSearch(): React.ReactElement {
+  return (
+    <button
+      type="button"
+      className="cp-nav-search"
+      onClick={dispatchSearchHotkey}
+      aria-label="Search docs"
+    >
+      <Icon icon="pixelarticons:search" width={16} height={16} className="cp-nav-search__icon" />
+      <span className="cp-nav-search__label">Search</span>
+      <kbd className="cp-nav-search__hotkey" aria-hidden="true">
+        <span>⌘</span>
+        <span>K</span>
+      </kbd>
+    </button>
+  )
+}
+
+/**
+ * Dispatch a synthetic `Cmd+K` (mac) or `Ctrl+K` (everything else)
+ * `keydown` so Rspress's global search modal opens. Modifier choice is
+ * driven off `navigator.platform`, which is the same heuristic
+ * Rspress's own shortcut handler uses.
+ *
+ * @private
+ */
+function dispatchSearchHotkey(): void {
+  const isMac = typeof navigator !== 'undefined' && navigator.platform.toLowerCase().includes('mac')
+  const event = new KeyboardEvent('keydown', {
+    key: 'k',
+    code: 'KeyK',
+    keyCode: 75,
+    metaKey: isMac,
+    ctrlKey: !isMac,
+    bubbles: true,
+    cancelable: true,
+  })
+  document.dispatchEvent(event)
+}
+
+export { CiderpressNavSearch as default }

package/dist/theme/components/nav/ciderpress-nav-social-links.css

@@ -0,0 +1,35 @@
+/**
+ * CiderpressNavSocialLinks — icon cluster in the topbar right zone.
+ *
+ * Theme-author API:
+ *   --cp-nav-social-gap         spacing between icons (default 4px)
+ *   --cp-nav-social-color       icon colour (idle)
+ *   --cp-nav-social-color-hover icon colour on hover
+ *   --cp-nav-social-size        clickable area (default 32px)
+ */
+.cp-nav-social {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--cp-nav-social-gap, 4px);
+  flex-shrink: 0;
+}
+
+.cp-nav-social__item {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--cp-nav-social-size, 32px);
+  height: var(--cp-nav-social-size, 32px);
+  border-radius: 6px;
+  color: var(--cp-nav-social-color, var(--cp-c-text-2));
+  text-decoration: none;
+  transition:
+    color 0.15s ease,
+    background 0.15s ease;
+}
+
+.cp-nav-social__item:hover {
+  background: var(--cp-c-bg-soft);
+  color: var(--cp-nav-social-color-hover, var(--cp-c-brand-1));
+  text-decoration: none;
+}

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

@@ -0,0 +1,87 @@
+import type React from 'react'
+
+import { safeUrl } from '../../lib/safe-url.ts'
+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`.
+ */
+export interface CiderpressSocialLink {
+  readonly icon: string
+  readonly mode: string
+  readonly content: string
+  readonly label?: string
+}
+
+export interface CiderpressNavSocialLinksProps {
+  readonly links: readonly CiderpressSocialLink[]
+}
+
+/**
+ * Maps Rspress's social-link `icon` slugs to pixelarticons icon ids.
+ * Fallback for unmapped slugs is the generic `link` glyph.
+ */
+const ICON_MAP: Readonly<Record<string, string>> = Object.freeze({
+  github: 'pixelarticons:github',
+  npm: 'pixelarticons:package',
+  twitter: 'pixelarticons:twitter',
+  x: 'pixelarticons:twitter',
+  discord: 'pixelarticons:chat',
+  youtube: 'pixelarticons:play',
+  bluesky: 'pixelarticons:bluesky',
+  mastodon: 'pixelarticons:user',
+})
+
+/**
+ * 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`
+ * @returns Cluster of icon links, or `null`
+ */
+export function CiderpressNavSocialLinks(
+  props: CiderpressNavSocialLinksProps
+): React.ReactElement | null {
+  if (props.links.length === 0) {
+    return null
+  }
+
+  const safeLinks = props.links
+    .map((link) => ({ link, href: safeUrl(link.content) }))
+    .filter((entry): entry is { readonly link: CiderpressSocialLink; readonly href: string } => {
+      if (entry.href === null) {
+        return false
+      }
+      return entry.href.length > 0
+    })
+
+  if (safeLinks.length === 0) {
+    return null
+  }
+
+  return (
+    <div className="cp-nav-social">
+      {safeLinks.map(({ link, href }) => (
+        <a
+          key={link.content}
+          href={href}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="cp-nav-social__item"
+          aria-label={link.label ?? link.icon}
+        >
+          <Icon
+            icon={ICON_MAP[link.icon.toLowerCase()] ?? 'pixelarticons:link'}
+            width={20}
+            height={20}
+          />
+        </a>
+      ))}
+    </div>
+  )
+}
+
+export { CiderpressNavSocialLinks as default }