@ciderpress/ui 1.0.0-rc.1

package/dist/theme/components/sidebar/sidebar-scope.tsx

@@ -0,0 +1,151 @@
+/**
+ * Custom Sidebar component with multi-scope support.
+ *
+ * Rspress's `_meta.json` auto-discovery generates a single unified sidebar
+ * keyed by `"/"`. This component filters the unified sidebar at runtime to
+ * isolate standalone sections (e.g. Packages, Contributing) into their own
+ * scope while merging the remaining sections into a shared scope.
+ *
+ * HMR works because `_meta.json` changes trigger Rspress's auto-discovery
+ * re-run via `addDependency()` — the sidebar data updates reactively.
+ */
+
+import type { SidebarData } from '@rspress/core'
+import { useActiveMatcher, useLocation, useSidebar } from '@rspress/core/runtime'
+import { SidebarList } from '@rspress/core/theme-original'
+import type React from 'react'
+import { useLayoutEffect, useMemo, useState } from 'react'
+
+import { useCiderpress } from '../../hooks/use-ciderpress'
+import { resolveScopedSidebar } from './sidebar-filter'
+
+/**
+ * Union element of `SidebarData` — sidebar items may be groups, leaf items,
+ * dividers, or section headers.
+ *
+ * @private
+ */
+type SidebarDataItem = SidebarData[number]
+
+/**
+ * Scoped Sidebar that supports standalone section isolation.
+ *
+ * When the current path matches a standalone scope (e.g. `/packages`),
+ * only that section's sidebar items are shown. For all other paths,
+ * standalone sections are hidden and the remaining sections form a
+ * unified sidebar.
+ *
+ * @returns React element rendering the filtered sidebar
+ */
+export function Sidebar(): React.ReactElement {
+  const rawSidebarData = useSidebar()
+  const activeMatcher = useActiveMatcher()
+  const { pathname: rawPathname } = useLocation()
+  const { standaloneScopePaths } = useCiderpress()
+
+  const pathname = decodeURIComponent(rawPathname)
+  const scopes = standaloneScopePaths ?? []
+
+  const filteredData = useMemo(
+    () => resolveScopedSidebar(rawSidebarData, pathname, scopes),
+    [rawSidebarData, pathname, scopes]
+  )
+
+  const [sidebarData, setSidebarData] = useState<SidebarData>(() =>
+    initializeCollapsed(structuredClone(filteredData), activeMatcher)
+  )
+
+  useLayoutEffect(() => {
+    setSidebarData(initializeCollapsed(filteredData, activeMatcher))
+  }, [activeMatcher, filteredData])
+
+  return <SidebarList sidebarData={sidebarData} setSidebarData={setSidebarData} />
+}
+
+/**
+ * Walk the sidebar tree and uncollapse groups that contain the active path.
+ *
+ * Mirrors Rspress's `createInitialSidebar` logic: groups whose descendants
+ * match the active route get `collapsed = false` so the active page is
+ * visible on initial render.
+ *
+ * @private
+ * @param items - Sidebar items (will be mutated for collapsed state)
+ * @param activeMatcher - Function that checks if a link matches the current route
+ * @returns The same items array with collapsed state applied
+ */
+function initializeCollapsed(
+  items: SidebarData,
+  activeMatcher: (link: string) => boolean
+): SidebarData {
+  const cache = new WeakMap<SidebarDataItem, boolean>()
+  const flat = items.filter(Boolean).flat()
+  flat.reduce<null>((_, item) => {
+    expandItem(item, activeMatcher, cache)
+    return null
+  }, null)
+  return flat
+}
+
+/**
+ * Check whether a sidebar item or any of its descendants match the active route.
+ *
+ * @private
+ * @param item - Sidebar item to check
+ * @param activeMatcher - Route matcher function
+ * @param cache - Memoization cache for match results
+ * @returns True when the item or a descendant matches
+ */
+function isItemActive(
+  item: SidebarDataItem,
+  activeMatcher: (link: string) => boolean,
+  cache: WeakMap<SidebarDataItem, boolean>
+): boolean {
+  const cached = cache.get(item)
+  if (cached !== undefined) {
+    return cached
+  }
+  if (Object.hasOwn(item, 'link')) {
+    const { link } = item as { readonly link?: string }
+    if (link && activeMatcher(link)) {
+      cache.set(item, true)
+      return true
+    }
+  }
+  if (Object.hasOwn(item, 'items')) {
+    const { items } = item as { readonly items: readonly SidebarDataItem[] }
+    const childMatch = items.some((child) => isItemActive(child, activeMatcher, cache))
+    if (childMatch) {
+      cache.set(item, true)
+      return true
+    }
+  }
+  cache.set(item, false)
+  return false
+}
+
+/**
+ * Recursively expand a sidebar item if it contains the active route.
+ *
+ * @private
+ * @param item - Sidebar item to process
+ * @param activeMatcher - Route matcher function
+ * @param cache - Memoization cache for match results
+ */
+function expandItem(
+  item: SidebarDataItem,
+  activeMatcher: (link: string) => boolean,
+  cache: WeakMap<SidebarDataItem, boolean>
+): void {
+  if (Object.hasOwn(item, 'items')) {
+    const group = item as { readonly items: readonly SidebarDataItem[]; collapsed?: boolean }
+    group.items.reduce<null>((_, child) => {
+      expandItem(child, activeMatcher, cache)
+      return null
+    }, null)
+    if (isItemActive(item, activeMatcher, cache)) {
+      // oxlint-disable-next-line eslint/no-param-reassign -- intentional mutation matching Rspress's createInitialSidebar
+      group.collapsed = false
+    }
+  }
+}

package/dist/theme/components/sidebar/sidebar-toggle.css

@@ -0,0 +1,181 @@
+.cp-sidebar-toggle {
+  /* Pinned to the far-left of the nav, matching the mockup hamburger
+     position. The nav itself is set to position: relative below. */
+  position: absolute;
+  left: 16px;
+  top: 50%;
+  transform: translateY(-50%);
+  z-index: 5;
+  width: 28px;
+  height: 28px;
+  display: grid;
+  place-items: center;
+  border: 0;
+  background: transparent;
+  border-radius: var(--cp-radius-card);
+  color: var(--cp-c-text-2);
+  cursor: pointer;
+  transition: all 0.15s ease;
+  padding: 0;
+}
+
+/* Hide Rspress's mobile hamburger always — our `.cp-sidebar-toggle`
+   owns the role of "menu trigger" across all widths. On mobile our
+   toggle programmatically forwards the click to Rspress's hamburger
+   (its handler is preserved, only the visual is hidden) so the
+   slide-over mobile menu still works. */
+html .rp-nav-hamburger {
+  display: none !important;
+}
+
+/* Replace the hamburger icon inside Rspress's mobile sub-bar
+   (`.rp-sidebar-menu__left`) with a "panel-left" affordance so it
+   doesn't visually echo the navbar's hamburger. The bar itself stays
+   visible because it serves a distinct role (show sidebar / outline
+   on mobile). */
+html .rp-sidebar-menu__left > svg {
+  display: none;
+}
+html .rp-sidebar-menu__left::before {
+  content: '';
+  display: inline-block;
+  width: 14px;
+  height: 14px;
+  background: currentColor;
+  -webkit-mask: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'><rect x='3' y='3' width='18' height='18' rx='2'/><line x1='9' y1='3' x2='9' y2='21'/></svg>")
+    no-repeat center / contain;
+  mask: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'><rect x='3' y='3' width='18' height='18' rx='2'/><line x1='9' y1='3' x2='9' y2='21'/></svg>")
+    no-repeat center / contain;
+}
+
+.cp-sidebar-toggle:hover {
+  background: var(--cp-c-bg-soft);
+  color: var(--cp-c-text-1);
+}
+
+/* Pin the nav to the top of the viewport AND make it the positioning
+   context for the absolutely-positioned toggle. `sticky` covers both:
+   it pins on scroll while still acting as the offset parent for
+   `position: absolute` children. */
+html .rp-nav,
+html .rspress-nav {
+  position: sticky;
+  top: 0;
+}
+
+html .rp-nav__left,
+html .rspress-nav__left {
+  padding-left: 36px;
+}
+
+/* When collapsed, hide the sidebar + placeholder. Scoped to >=1280px
+   where the sidebar is a sticky desktop rail; at ≤1279px the sidebar
+   is a fixed overlay drawer (rules below), where the same
+   `display: none` would also hide the drawer state and
+   `<CiderpressDocsBar />`'s "Menu" button would have nothing to open.
+   Threshold mirrors the Outline rail's collapse-vs-drawer cutoff so
+   sidebar and outline switch modes in lockstep. */
+@media (min-width: 1280px) {
+  html[data-cp-sidebar-collapsed='true'] .rp-doc-layout__sidebar,
+  html[data-cp-sidebar-collapsed='true'] .rp-doc-layout__sidebar-placeholder {
+    display: none !important;
+  }
+}
+
+/* Mirror collapse behaviour for the outline rail. Rspress turns the
+   outline into a fixed overlay drawer at ≤1279px (see
+   `DocLayout/index.css` `@media (width <= 1279px)`), so the
+   collapse-via-display-none only applies above that breakpoint —
+   otherwise opening the drawer via `<CiderpressDocsBar />` would
+   silently no-op. */
+@media (min-width: 1280px) {
+  html[data-cp-outline-collapsed='true'] .rp-doc-layout__outline,
+  html[data-cp-outline-collapsed='true'] .rp-doc-layout__outline-placeholder {
+    display: none !important;
+  }
+}
+
+/* Rspress's mobile nav-screen renders dividers around sections like
+   translations / appearance-toggle / socials. When some of those
+   sections are absent or hidden, two dividers end up adjacent — a
+   pair of stacked empty hairlines. Collapse consecutive dividers and
+   hide a trailing one with no following content. */
+html .rp-nav-screen-divider + .rp-nav-screen-divider,
+html .rp-nav-screen-divider:last-child {
+  display: none;
+}
+
+/* ── Sidebar drawer mode (<=1279px) ─────────────────────────────
+   Rspress ships drawer-base rules natively only at <=768px (its
+   `DocLayout/index.css` `@media (width <= 768px)` sets `position:
+   fixed`, `transform: translate3d(-100%, 0, 0)`, opacity transitions,
+   etc). This block extends that drawer behaviour up to 1279px so the
+   sidebar flips to mobile in lockstep with the Outline rail (which
+   already drawers at <=1279px). Selector chains `html` for higher
+   specificity than Rspress's single-class rules.
+
+   The slide-over overlays the entire viewport (top: 0, full height)
+   so the drawer covers the navbar AND announcement bar — without
+   this they'd stay tappable above an open drawer. Applies to both
+   the doc sidebar and Rspress's nav screen (top-nav slide-over). */
+@media (max-width: 1279px) {
+  html .rp-doc-layout__sidebar {
+    position: fixed;
+    top: 0 !important;
+    left: 0;
+    bottom: 0;
+    width: var(--rp-sidebar-width, 260px);
+    /* Override Rspress's base `height + max-height: calc(100vh -
+       var(--rp-nav-height))` rule (NOT media-scoped, so it caps us
+       even at this breakpoint). Both height and max-height pinned to
+       the full dynamic viewport so the drawer covers navbar +
+       announcement + docs bar. */
+    height: 100dvh !important;
+    max-height: 100dvh !important;
+    margin-top: 0;
+    /* No `padding-bottom` — the sticky `.cp-sidebar-bottom` band pins
+       to the bottom of the content box (padding excluded). Any padding
+       here would shift the band up by the same amount, leaving the
+       promo floating mid-drawer with empty space below it. */
+    background: var(--cp-c-bg-elv);
+    opacity: 0;
+    visibility: hidden;
+    transform: translate3d(-100%, 0, 0);
+    transition:
+      opacity 0.25s,
+      transform 0.5s cubic-bezier(0.19, 1, 0.22, 1),
+      visibility 0s linear 0.5s;
+    z-index: 100 !important;
+    overflow: auto scroll;
+  }
+
+  html .rp-doc-layout__sidebar--open {
+    opacity: 1;
+    visibility: visible;
+    transform: translate3d(0, 0, 0);
+    transition:
+      opacity 0.25s,
+      transform 0.5s cubic-bezier(0.19, 1, 0.22, 1);
+  }
+
+  html .rp-nav-screen {
+    top: 0 !important;
+    height: 100vh !important;
+    height: 100dvh !important;
+    z-index: 100 !important;
+    background: var(--cp-c-bg-elv);
+  }
+}
+
+/* When collapsed: cap the doc reading width and center it within the
+   available space (rail width minus outline). Prevents the prose from
+   stretching edge-to-edge and makes the layout feel intentional. */
+html[data-cp-sidebar-collapsed='true'] .rp-doc-layout__doc {
+  max-width: var(--cp-content-collapsed-max, 1000px) !important;
+  margin: 0 auto !important;
+}
+
+html[data-cp-sidebar-collapsed='true'] .rp-doc-layout__doc-container {
+  max-width: var(--cp-content-collapsed-max, 1000px);
+  margin: 0 auto;
+}

package/dist/theme/components/sidebar/sidebar-toggle.tsx

@@ -0,0 +1,127 @@
+import { match } from 'massaman/match'
+import React, { useCallback, useEffect, useState } from 'react'
+
+import './sidebar-toggle.css'
+
+const STORAGE_KEY = 'ciderpress-sidebar-collapsed'
+const HTML_ATTR = 'cpSidebarCollapsed'
+
+/**
+ * SidebarToggle — small icon button in the topbar to collapse/expand the
+ * docs sidebar on desktop. State persists in localStorage and is applied
+ * via `html[data-cp-sidebar-collapsed='true']` for CSS targeting.
+ *
+ * @returns React element.
+ */
+export function SidebarToggle(): React.ReactElement {
+  const [collapsed, setCollapsed] = useState(() => readCollapsed())
+
+  useEffect(() => {
+    applyState(collapsed)
+  }, [collapsed])
+
+  const handleClick = useCallback(() => {
+    // Below the mobile breakpoint, defer to Rspress's slide-over mobile
+    // menu (its hamburger handler is preserved — we just hide its visual).
+    const isMobile = globalThis.window !== undefined && globalThis.innerWidth < 960
+    if (isMobile) {
+      const rspressBurger = globalThis.document.querySelector(
+        '.rp-nav-hamburger'
+      ) as HTMLButtonElement | null
+      if (rspressBurger !== null) {
+        rspressBurger.click()
+        return
+      }
+    }
+    setCollapsed((prev) => {
+      const next = !prev
+      writeCollapsed(next)
+      return next
+    })
+  }, [])
+
+  const label = match(collapsed)
+    .with(true, () => 'Show sidebar')
+    .otherwise(() => 'Hide sidebar')
+
+  return (
+    <button
+      className="cp-sidebar-toggle"
+      type="button"
+      onClick={handleClick}
+      aria-label={label}
+      title={label}
+    >
+      <svg
+        width="14"
+        height="14"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+      >
+        <line x1="3" y1="6" x2="21" y2="6" />
+        <line x1="3" y1="12" x2="21" y2="12" />
+        <line x1="3" y1="18" x2="21" y2="18" />
+      </svg>
+    </button>
+  )
+}
+
+/**
+ * Read the persisted collapsed state from localStorage.
+ *
+ * @private
+ * @returns true when the sidebar is collapsed.
+ */
+function readCollapsed(): boolean {
+  if (globalThis.window === undefined) {
+    return false
+  }
+  try {
+    return globalThis.localStorage.getItem(STORAGE_KEY) === '1'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Persist the collapsed state to localStorage.
+ *
+ * @private
+ * @param collapsed - true when the sidebar is collapsed.
+ */
+function writeCollapsed(collapsed: boolean): void {
+  if (globalThis.window === undefined) {
+    return
+  }
+  try {
+    if (collapsed) {
+      globalThis.localStorage.setItem(STORAGE_KEY, '1')
+    } else {
+      globalThis.localStorage.removeItem(STORAGE_KEY)
+    }
+  } catch {
+    // ignore — storage may be unavailable
+  }
+}
+
+/**
+ * Apply the collapsed state to the html dataset for CSS targeting.
+ *
+ * @private
+ * @param collapsed - true when the sidebar is collapsed.
+ */
+function applyState(collapsed: boolean): void {
+  if (globalThis.document === undefined) {
+    return
+  }
+  const html = globalThis.document.documentElement
+  match(collapsed)
+    .with(true, () => {
+      html.dataset[HTML_ATTR] = 'true'
+    })
+    .otherwise(() => {
+      delete html.dataset[HTML_ATTR]
+    })
+}