@ciderpress/ui 1.0.0-rc.1

package/dist/theme/components/sidebar/framework-picker.css

@@ -0,0 +1,77 @@
+.cp-fwpicker {
+  padding: 14px 14px 12px;
+  border-bottom: 1px solid var(--cp-c-border);
+}
+
+.cp-fwpicker__head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 6px;
+  gap: 8px;
+}
+
+.cp-fwpicker__head-right {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.cp-fwpicker__label {
+  font-family: var(--cp-font-family-mono);
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--cp-c-text-3);
+}
+
+.cp-fwpicker__version {
+  font-family: var(--cp-font-family-mono);
+  font-size: 10px;
+  color: var(--cp-c-text-3);
+  padding: 1px 6px;
+  border: 1px solid var(--cp-c-border);
+  border-radius: 4px;
+  white-space: nowrap;
+}
+
+.cp-fwpicker__control {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 7px 10px;
+  background: var(--cp-c-bg-alt);
+  border: 1px solid var(--cp-c-border);
+  border-radius: var(--cp-radius-card);
+  font-size: 13px;
+  color: var(--cp-c-text-1);
+  cursor: pointer;
+  transition: border-color 0.15s ease;
+}
+
+.cp-fwpicker__control:hover {
+  border-color: var(--cp-c-border);
+}
+
+.cp-fwpicker__mark {
+  width: 14px;
+  height: 14px;
+  border-radius: 3px;
+  background: linear-gradient(135deg, var(--cp-c-brand-1), var(--cp-c-brand-2));
+  display: grid;
+  place-items: center;
+  color: var(--cp-c-brand-fg);
+  font-size: 9px;
+  font-weight: 700;
+  font-family: var(--cp-font-family-mono);
+  flex-shrink: 0;
+}
+
+.cp-fwpicker__name {
+  flex: 1;
+}
+
+.cp-fwpicker__chev {
+  color: var(--cp-c-text-3);
+  flex-shrink: 0;
+}

package/dist/theme/components/sidebar/framework-picker.tsx

@@ -0,0 +1,78 @@
+import { match } from 'massaman/match'
+import type React from 'react'
+
+import { SidebarToggle } from './sidebar-toggle'
+
+import './framework-picker.css'
+
+export interface FrameworkPickerProps {
+  /**
+   * Eyebrow label above the picker. Defaults to "Framework".
+   */
+  readonly label?: string
+  /**
+   * Currently active framework name shown in the picker.
+   */
+  readonly current: string
+  /**
+   * Optional small mark / icon shown to the left of the framework name.
+   */
+  readonly mark?: React.ReactNode
+  /**
+   * Optional version chip shown next to the eyebrow label.
+   */
+  readonly version?: string
+  /**
+   * When true, render a sidebar collapse toggle in the picker header.
+   */
+  readonly showCollapseToggle?: boolean
+}
+
+/**
+ * FrameworkPicker — top-of-sidebar selector showing the current framework
+ * + an optional version chip + an optional sidebar collapse toggle.
+ * Mirrors the mockup's framework switcher pattern.
+ *
+ * @param props - Picker configuration.
+ * @returns React element.
+ */
+export function FrameworkPicker(props: FrameworkPickerProps): React.ReactElement {
+  const { label = 'Framework', current, mark, version, showCollapseToggle } = props
+
+  return (
+    <div className="cp-fwpicker">
+      <div className="cp-fwpicker__head">
+        <span className="cp-fwpicker__label">{label}</span>
+        <div className="cp-fwpicker__head-right">
+          {match(version)
+            .with(undefined, () => null)
+            .otherwise((v) => (
+              <span className="cp-fwpicker__version">{v}</span>
+            ))}
+          {match(showCollapseToggle)
+            .with(true, () => <SidebarToggle />)
+            .otherwise(() => null)}
+        </div>
+      </div>
+      <div className="cp-fwpicker__control">
+        {match(mark)
+          .with(undefined, () => null)
+          .otherwise((m) => (
+            <span className="cp-fwpicker__mark">{m}</span>
+          ))}
+        <span className="cp-fwpicker__name">{current}</span>
+        <svg
+          className="cp-fwpicker__chev"
+          width="14"
+          height="14"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+        >
+          <polyline points="6 9 12 15 18 9" />
+        </svg>
+      </div>
+    </div>
+  )
+}

package/dist/theme/components/sidebar/sidebar-filter.test.ts

@@ -0,0 +1,140 @@
+import type { SidebarData } from '@rspress/core'
+import { describe, expect, it } from 'vitest'
+
+import { belongsToScope, resolveScopedSidebar } from './sidebar-filter'
+
+const gettingStarted: SidebarData[number] = {
+  text: 'Getting Started',
+  link: '/getting-started',
+  collapsible: true,
+  collapsed: true,
+  items: [
+    { text: 'Introduction', link: '/getting-started/introduction' },
+    { text: 'Quick Start', link: '/getting-started/quick-start' },
+  ],
+}
+
+const packages: SidebarData[number] = {
+  text: 'Packages',
+  link: '/packages',
+  collapsible: true,
+  collapsed: true,
+  items: [
+    { text: 'CLI', link: '/packages/cli' },
+    { text: 'Core', link: '/packages/core' },
+  ],
+}
+
+const contributing: SidebarData[number] = {
+  text: 'Contributing',
+  link: '/contributing',
+  collapsible: true,
+  collapsed: true,
+  items: [
+    { text: 'Guides', link: '/contributing/guides' },
+    { text: 'Standards', link: '/contributing/standards' },
+  ],
+}
+
+const groupWithoutLink: SidebarData[number] = {
+  text: 'Nested Group',
+  collapsible: true,
+  collapsed: true,
+  items: [{ text: 'Deep Page', link: '/packages/deep/page' }],
+}
+
+const fullSidebar: SidebarData = [gettingStarted, packages, contributing]
+const scopes: readonly string[] = ['/packages', '/contributing']
+
+describe('resolveScopedSidebar()', () => {
+  it('should return all items when no scopes are defined', () => {
+    const result = resolveScopedSidebar(fullSidebar, '/getting-started', [])
+
+    expect(result).toHaveLength(3)
+  })
+
+  it('should exclude standalone sections on a main page', () => {
+    const result = resolveScopedSidebar(fullSidebar, '/getting-started/introduction', scopes)
+
+    expect(result).toHaveLength(1)
+    expect(result[0]).toMatchObject({ text: 'Getting Started' })
+  })
+
+  it('should show only the matching standalone section on an exact scope path', () => {
+    const result = resolveScopedSidebar(fullSidebar, '/packages', scopes)
+
+    expect(result).toHaveLength(1)
+    expect(result[0]).toMatchObject({ text: 'Packages' })
+  })
+
+  it('should show only the matching standalone section on a nested scope path', () => {
+    const result = resolveScopedSidebar(fullSidebar, '/packages/cli', scopes)
+
+    expect(result).toHaveLength(1)
+    expect(result[0]).toMatchObject({ text: 'Packages' })
+  })
+
+  it('should show only contributing items on the contributing scope', () => {
+    const result = resolveScopedSidebar(fullSidebar, '/contributing/guides', scopes)
+
+    expect(result).toHaveLength(1)
+    expect(result[0]).toMatchObject({ text: 'Contributing' })
+  })
+
+  it('should not mutate the original sidebar data', () => {
+    const original = [...fullSidebar]
+
+    resolveScopedSidebar(fullSidebar, '/packages', scopes)
+
+    expect(fullSidebar).toStrictEqual(original)
+  })
+
+  it('should not match a scope that is only a prefix of the pathname segment', () => {
+    const result = resolveScopedSidebar(fullSidebar, '/packages-extra/foo', scopes)
+
+    expect(result).toHaveLength(1)
+    expect(result[0]).toMatchObject({ text: 'Getting Started' })
+  })
+})
+
+describe('belongsToScope()', () => {
+  it('should match an item whose link equals the scope', () => {
+    expect(belongsToScope(packages, '/packages')).toBe(true)
+  })
+
+  it('should match an item whose link starts with scope/', () => {
+    const item: SidebarData[number] = { text: 'CLI', link: '/packages/cli' }
+
+    expect(belongsToScope(item, '/packages')).toBe(true)
+  })
+
+  it('should not match an item from a different scope', () => {
+    expect(belongsToScope(gettingStarted, '/packages')).toBe(false)
+  })
+
+  it('should not match a partial path segment overlap', () => {
+    const item: SidebarData[number] = { text: 'Extra', link: '/packages-extra' }
+
+    expect(belongsToScope(item, '/packages')).toBe(false)
+  })
+
+  it('should match a group without a link by checking children', () => {
+    expect(belongsToScope(groupWithoutLink, '/packages')).toBe(true)
+  })
+
+  it('should not match a group without a link when children belong to a different scope', () => {
+    expect(belongsToScope(groupWithoutLink, '/contributing')).toBe(false)
+  })
+
+  it('should not match a divider (no link, no items)', () => {
+    const divider: SidebarData[number] = { dividerType: 'solid' }
+
+    expect(belongsToScope(divider, '/packages')).toBe(false)
+  })
+
+  it('should not match a section header (no link, no items)', () => {
+    const header: SidebarData[number] = { sectionHeaderText: 'Header' }
+
+    expect(belongsToScope(header, '/packages')).toBe(false)
+  })
+})

package/dist/theme/components/sidebar/sidebar-filter.ts

@@ -0,0 +1,79 @@
+/**
+ * Pure sidebar filtering logic for multi-scope support.
+ *
+ * Extracts the runtime filtering from the Sidebar React component so the
+ * logic is independently testable without React rendering.
+ */
+
+import type { SidebarData } from '@rspress/core'
+
+/**
+ * Union element of `SidebarData` — sidebar items may be groups, leaf items,
+ * dividers, or section headers.
+ *
+ * @private
+ */
+type SidebarDataItem = SidebarData[number]
+
+/**
+ * Resolve the sidebar items visible for the current scope.
+ *
+ * When the current pathname matches a standalone scope (e.g. `/packages`),
+ * only that section's sidebar items are returned. For all other paths,
+ * standalone sections are excluded and the remaining sections form a
+ * unified sidebar.
+ *
+ * @param items - Full unified sidebar items
+ * @param pathname - Current decoded URL pathname
+ * @param scopes - Standalone scope paths (e.g. `["/packages", "/contributing"]`)
+ * @returns Filtered sidebar items for the active scope
+ */
+export function resolveScopedSidebar(
+  items: SidebarData,
+  pathname: string,
+  scopes: readonly string[]
+): SidebarData {
+  if (scopes.length === 0) {
+    return [...items]
+  }
+
+  const standaloneMatch = scopes.find(
+    (scope) => pathname === scope || pathname.startsWith(`${scope}/`)
+  )
+
+  const all = [...items]
+
+  if (standaloneMatch) {
+    return all.filter((item) => belongsToScope(item, standaloneMatch))
+  }
+
+  return all.filter((item) => !scopes.some((scope) => belongsToScope(item, scope)))
+}
+
+/**
+ * Check whether a sidebar item belongs to a given scope path.
+ *
+ * Matches when the item's link equals the scope or starts with scope + "/".
+ * For groups without a direct link, recursively checks child items.
+ * Dividers and section headers (no link, no items) are never matched.
+ *
+ * @private
+ * @param item - Sidebar item to check
+ * @param scope - Scope path (e.g. "/packages")
+ * @returns True when the item belongs to the scope
+ */
+export function belongsToScope(item: SidebarDataItem, scope: string): boolean {
+  if (Object.hasOwn(item, 'link')) {
+    const { link } = item as { readonly link?: string }
+    if (link && (link === scope || link.startsWith(`${scope}/`))) {
+      return true
+    }
+  }
+  // Check children — auto-discovered groups from _meta.json may have no
+  // link on the group itself, only on their child items.
+  if (Object.hasOwn(item, 'items')) {
+    const { items } = item as { readonly items: readonly SidebarDataItem[] }
+    return items.some((child) => belongsToScope(child, scope))
+  }
+  return false
+}

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

@@ -0,0 +1,102 @@
+.cp-sidebar-links {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 8px 0;
+}
+
+/* Position modifiers (`--above` / `--below`) used to own their own
+   divider hairlines + spacing, but the `.cp-sidebar-top` and
+   `.cp-sidebar-bottom` wrappers (added in v1) now provide the dividers
+   and edge-to-edge backgrounds. Keep the modifier classes as semantic
+   hooks for downstream consumers, but don't paint extra borders here. */
+
+/* ── Base ───────────────────────────────────────────────── */
+
+.cp-sidebar-link {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 12px;
+  border-radius: 8px;
+  color: var(--rp-c-text-2);
+  font-size: 14px;
+  font-weight: 500;
+  line-height: 24px;
+  text-decoration: none;
+  transition:
+    color 0.15s,
+    background-color 0.15s,
+    border-color 0.15s,
+    opacity 0.15s;
+}
+
+/* ── Ghost (default) — no background, subtle hover ───── */
+
+.cp-sidebar-link--ghost {
+  background-color: transparent;
+}
+
+.cp-sidebar-link--ghost:hover {
+  color: var(--rp-c-text-1);
+  background-color: var(--rp-c-bg-mute);
+}
+
+/* ── Brand — solid brand background ──────────────────── */
+
+.cp-sidebar-link--brand {
+  color: var(--cp-c-on-brand);
+  background: var(--rp-c-brand-darker);
+}
+
+.cp-sidebar-link--brand:hover {
+  background: var(--rp-c-brand-dark);
+}
+
+/* ── Alt — outlined with border ──────────────────────── */
+
+.cp-sidebar-link--alt {
+  border: 1px solid var(--rp-c-gray-light-3);
+  color: var(--rp-c-text-1);
+  background-color: var(--rp-c-bg);
+}
+
+html.dark .cp-sidebar-link--alt {
+  background-color: var(--rp-c-bg-mute);
+  border-color: var(--cp-c-sidebar-alt-border-dark);
+}
+
+.cp-sidebar-link--alt:hover {
+  opacity: 0.8;
+  background-color: var(--rp-c-bg-mute);
+}
+
+/* ── Shapes ──────────────────────────────────────────── */
+
+.cp-sidebar-link--square {
+  border-radius: 8px;
+}
+
+.cp-sidebar-link--rounded {
+  border-radius: 9999px;
+}
+
+.cp-sidebar-link--circle {
+  border-radius: 50%;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  padding: 0;
+}
+
+.cp-sidebar-link-icon {
+  flex-shrink: 0;
+  width: 16px;
+  height: 16px;
+}
+
+.cp-sidebar-link-text {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}

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

@@ -0,0 +1,122 @@
+import { Link } from '@rspress/core/runtime'
+import { match, P } from 'massaman/match'
+import type React from 'react'
+
+import { safeUrl } from '../../lib/safe-url.ts'
+import { Icon } from '../shared/icon'
+
+import './sidebar-links.css'
+
+interface SidebarLinkItem {
+  readonly text: string
+  readonly link: string
+  readonly icon?: string | { readonly id: string; readonly color: string }
+  readonly style?: 'brand' | 'alt' | 'ghost'
+  readonly shape?: 'square' | 'rounded' | 'circle'
+}
+
+interface SidebarLinksProps {
+  readonly items: readonly SidebarLinkItem[]
+  readonly position: 'above' | 'below'
+}
+
+/**
+ * Render a group of sidebar navigation links above or below the main sidebar.
+ *
+ * @param props - Sidebar links props with items and position
+ * @returns React element with sidebar links or null
+ */
+export function SidebarLinks(props: SidebarLinksProps): React.ReactElement | null {
+  return match(props.items.length > 0)
+    .with(true, () => (
+      <nav
+        className={`cp-sidebar-links cp-sidebar-links--${props.position}`}
+        aria-label={`Sidebar links ${props.position}`}
+      >
+        {props.items.map((item) => (
+          <SidebarLinkEntry key={item.link} item={item} />
+        ))}
+      </nav>
+    ))
+    .otherwise(() => null)
+}
+
+/**
+ * Render an icon from a sidebar link item's icon configuration.
+ *
+ * @private
+ * @param icon - Icon string or object with id/color
+ * @returns Icon element or null
+ */
+function renderIcon(icon: SidebarLinkItem['icon']): React.ReactElement | null {
+  return match(icon)
+    .with(P.string, (id) => <Icon icon={id} className="cp-sidebar-link-icon" />)
+    .with({ id: P.string, color: P.string }, (i) => (
+      <Icon icon={i.id} className="cp-sidebar-link-icon" style={{ color: i.color }} />
+    ))
+    .otherwise(() => null)
+}
+
+/**
+ * Check whether a URL points to an external origin.
+ *
+ * @private
+ * @param link - Link URL to check
+ * @returns True when the link is absolute http(s)
+ */
+function isExternal(link: string): boolean {
+  return link.startsWith('http://') || link.startsWith('https://')
+}
+
+/**
+ * Render a single sidebar link entry with optional icon.
+ * Uses client-side `Link` for internal routes, `<a>` for external URLs.
+ *
+ * @private
+ * @param props - Props with sidebar link item
+ * @returns Sidebar link element
+ */
+function SidebarLinkEntry({ item }: { readonly item: SidebarLinkItem }): React.ReactElement | null {
+  const isCircle = item.shape === 'circle'
+  const content = (
+    <>
+      {renderIcon(item.icon)}
+      {match(isCircle)
+        .with(true, () => null)
+        .otherwise(() => (
+          <span className="cp-sidebar-link-text">{item.text}</span>
+        ))}
+    </>
+  )
+
+  const variant = item.style ?? 'ghost'
+  const shape = item.shape ?? 'square'
+  const cls = `cp-sidebar-link cp-sidebar-link--${variant} cp-sidebar-link--${shape}`
+  /* oxlint-disable unicorn/no-useless-undefined -- React aria-label expects undefined, not null */
+  const ariaLabel = match(isCircle)
+    .with(true, () => item.text)
+    .otherwise(() => undefined)
+  /* oxlint-enable unicorn/no-useless-undefined */
+
+  const safeLink = safeUrl(item.link)
+  if (safeLink === null) {
+    return null
+  }
+  return match(isExternal(safeLink))
+    .with(true, () => (
+      <a
+        href={safeLink}
+        className={cls}
+        target="_blank"
+        rel="noopener noreferrer"
+        aria-label={ariaLabel}
+      >
+        {content}
+      </a>
+    ))
+    .otherwise(() => (
+      <Link to={safeLink} className={cls} aria-label={ariaLabel}>
+        {content}
+      </Link>
+    ))
+}

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

@@ -0,0 +1,42 @@
+.cp-sidebar-promo {
+  margin: 12px 8px;
+  border: 1px solid var(--cp-c-border);
+  border-radius: var(--cp-radius-card);
+  padding: 14px;
+  background: var(--cp-c-bg-soft);
+}
+
+.cp-sidebar-promo__title {
+  font-size: 13px;
+  font-weight: 500;
+  margin: 0 0 4px;
+  color: var(--cp-c-text-1);
+}
+
+.cp-sidebar-promo__body {
+  font-size: 12px;
+  color: var(--cp-c-text-2);
+  line-height: 1.5;
+  margin: 0 0 10px;
+}
+
+.cp-sidebar-promo__cta {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  padding: 6px 12px;
+  font-size: 12px;
+  font-weight: 600;
+  border-radius: var(--cp-radius-pill);
+  background: var(--cp-c-brand-1);
+  color: var(--cp-c-brand-fg);
+  text-decoration: none;
+  transition: background 0.15s ease;
+}
+
+.cp-sidebar-promo__cta:hover {
+  background: var(--cp-c-brand-2);
+  color: var(--cp-c-brand-fg);
+  text-decoration: none;
+}

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

@@ -0,0 +1,52 @@
+import type React from 'react'
+
+import { RouteLink } from '../../lib/route-link.tsx'
+import { safeUrl } from '../../lib/safe-url.ts'
+
+import './sidebar-promo.css'
+
+export interface SidebarPromoProps {
+  /**
+   * Headline of the promo card.
+   */
+  readonly title: string
+  /**
+   * Body copy beneath the headline.
+   */
+  readonly body: string
+  /**
+   * CTA button label.
+   */
+  readonly ctaText: string
+  /**
+   * CTA destination URL.
+   */
+  readonly ctaHref: string
+}
+
+/**
+ * SidebarPromo — bordered promo card pinned at the bottom of the docs
+ * sidebar. Mirrors the mockup's "Ship docs that stay in sync" pattern.
+ *
+ * Renders `null` when `ctaHref` fails `safeUrl()` validation — the entire
+ * promo card disappears rather than rendering a card whose CTA goes
+ * nowhere safe.
+ *
+ * @param props - Promo card configuration.
+ * @returns React element, or `null` when the CTA href fails URL validation.
+ */
+export function SidebarPromo(props: SidebarPromoProps): React.ReactElement | null {
+  const ctaHref = safeUrl(props.ctaHref)
+  if (ctaHref === null) {
+    return null
+  }
+  return (
+    <div className="cp-sidebar-promo">
+      <p className="cp-sidebar-promo__title">{props.title}</p>
+      <p className="cp-sidebar-promo__body">{props.body}</p>
+      <RouteLink className="cp-sidebar-promo__cta" href={ctaHref}>
+        {props.ctaText}
+      </RouteLink>
+    </div>
+  )
+}