@ciderpress/ui 1.0.0-rc.6 → 1.0.0-rc.7

package/dist/theme/components/shared/section-card.tsx

@@ -1,6 +1,9 @@
+import type { BadgeConfig } from '@ciderpress/config'
 import { match, P } from 'massaman/match'
 import type React from 'react'
 
+import { useCiderpress } from '../../hooks/use-ciderpress'
+import { BadgeChips } from '../sidebar/sidebar-badge'
 import { Card } from './card'
 import { CardIcon } from './card-icon'
 import type { CardIconInput } from './resolve-card-icon'
@@ -26,6 +29,8 @@ export function SectionCard({
   description,
   icon = 'pixelarticons:file',
 }: SectionCardProps): React.ReactElement {
+  const { pageBadges } = useCiderpress()
+  const badges = lookupBadges({ pageBadges, href })
   const resolved = resolveCardIcon(icon) ?? {
     kind: 'iconify' as const,
     id: 'pixelarticons:file',
@@ -40,8 +45,31 @@ export function SectionCard({
       <div className="cp-section-card__header">
         <CardIcon resolved={resolved} className="cp-section-card__icon" />
         <span className="cp-section-card__title">{title}</span>
+        {badges.length > 0 && (
+          <span className="cp-section-card__badges">
+            <BadgeChips badges={badges} />
+          </span>
+        )}
       </div>
       {descEl}
     </Card>
   )
 }
+
+/**
+ * Look up a page's badges from the route→badges map by its href.
+ *
+ * @private
+ * @param params - The route→badges map (if present) and card destination.
+ * @returns The page's badges, or an empty array when none apply
+ */
+function lookupBadges(params: {
+  readonly pageBadges: Record<string, readonly BadgeConfig[]> | undefined
+  readonly href: string
+}): readonly BadgeConfig[] {
+  const { pageBadges, href } = params
+  if (pageBadges === undefined) {
+    return []
+  }
+  return pageBadges[href] ?? []
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Sidebar badge chips — small uppercase labels (ALPHA, WIP, …) rendered
+ * in a sidebar item's right slot via the `Tag` override.
+ */
+
+@layer ciderpress.overrides {
+  .cp-sbadge {
+    display: inline-flex;
+    align-items: center;
+    padding: 1px 5px;
+    border-radius: var(--cp-radius-pill, 9999px);
+    font-family: var(--cp-font-family-mono, inherit);
+    font-size: 9px;
+    font-weight: 600;
+    line-height: 1.4;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    white-space: nowrap;
+    vertical-align: middle;
+  }
+
+  .cp-sbadge + .cp-sbadge {
+    margin-left: 4px;
+  }
+
+  .cp-sbadge--info {
+    background: var(--cp-c-badge-info-bg);
+    color: var(--cp-c-badge-info-fg);
+  }
+
+  .cp-sbadge--success {
+    background: var(--cp-c-badge-success-bg);
+    color: var(--cp-c-badge-success-fg);
+  }
+
+  .cp-sbadge--warning {
+    background: var(--cp-c-badge-warning-bg);
+    color: var(--cp-c-badge-warning-fg);
+  }
+
+  .cp-sbadge--danger {
+    background: var(--cp-c-badge-error-bg);
+    color: var(--cp-c-badge-error-fg);
+  }
+
+  .cp-sbadge--neutral {
+    background: var(--rp-c-bg-mute);
+    color: var(--rp-c-text-2);
+  }
+}

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

@@ -0,0 +1,153 @@
+/**
+ * Sidebar badge rendering — overrides Rspress's `Tag` component.
+ *
+ * Rspress renders `<Tag tag={...} />` inside every sidebar item. Ciderpress
+ * encodes page badges (label + variant + tooltip) into that `tag` string via
+ * `@ciderpress/config`'s `encodeBadges`. This override decodes ciderpress
+ * badges and renders styled chips; any other tag falls through to Rspress's
+ * native `Tag` so existing tag behavior (images, keyword badges) is preserved.
+ */
+
+import { decodeBadges } from '@ciderpress/config'
+import type { BadgeConfig, BadgeVariant } from '@ciderpress/config'
+import { Tag as RspressTag } from '@rspress/core/theme-original'
+import { match, P } from 'massaman/match'
+import type React from 'react'
+
+/**
+ * Props mirror Rspress's `Tag` — a single (optional) tag string.
+ *
+ * @private
+ */
+interface TagProps {
+  readonly tag?: string
+}
+
+/**
+ * Sidebar tag renderer. Renders ciderpress badge chips for encoded tags,
+ * delegating everything else to Rspress's native `Tag`.
+ *
+ * @param props - The sidebar item's tag string
+ * @returns Badge chips, a native tag, or `null` when there is no tag
+ */
+export function Tag({ tag }: TagProps): React.ReactElement | null {
+  const badges = decodeTag(tag)
+  if (badges === null) {
+    return <RspressTag tag={tag} />
+  }
+  return <BadgeChips badges={badges} />
+}
+
+/**
+ * Props for {@link BadgeChips}.
+ */
+export interface BadgeChipsProps {
+  readonly badges: readonly BadgeConfig[]
+}
+
+/**
+ * Render a list of badge chips (variant color, custom-color tint, hover
+ * tooltip). Used by the sidebar `Tag` override and the breadcrumb bar.
+ *
+ * @param props - The badges to render
+ * @returns Chip elements, or `null` when there are no badges
+ */
+export function BadgeChips({ badges }: BadgeChipsProps): React.ReactElement | null {
+  if (badges.length === 0) {
+    return null
+  }
+  return (
+    <>
+      {badges.map((badge, index) => (
+        <SidebarBadge key={`${badge.text}-${String(index)}`} badge={badge} />
+      ))}
+    </>
+  )
+}
+
+/**
+ * Decode a tag string into ciderpress badges, or `null` when the tag is
+ * absent or not ciderpress-encoded.
+ *
+ * @private
+ * @param tag - Raw tag string from the sidebar item
+ * @returns Decoded badges, or `null` to signal native fallback
+ */
+function decodeTag(tag: string | undefined): readonly BadgeConfig[] | null {
+  if (tag === undefined) {
+    return null
+  }
+  return decodeBadges(tag)
+}
+
+/**
+ * A single sidebar badge chip.
+ *
+ * @private
+ */
+interface SidebarBadgeProps {
+  readonly badge: BadgeConfig
+}
+
+/**
+ * Render one badge chip with variant color (or a custom color tint) and a
+ * hover tooltip.
+ *
+ * @private
+ * @param props - The badge to render
+ * @returns A styled badge chip element
+ */
+function SidebarBadge({ badge }: SidebarBadgeProps): React.ReactElement {
+  const tooltip = resolveTooltip(badge)
+  return match(badge.color)
+    .with(P.string, (color) => (
+      <span className="cp-sbadge" style={{ color, backgroundColor: tint(color) }} title={tooltip}>
+        {badge.text}
+      </span>
+    ))
+    .otherwise(() => (
+      <span className={variantClass(badge.variant)} title={tooltip}>
+        {badge.text}
+      </span>
+    ))
+}
+
+/**
+ * Resolve the hover tooltip for a badge, defaulting to its label text.
+ *
+ * @private
+ * @param badge - The badge to resolve a tooltip for
+ * @returns The tooltip string
+ */
+function resolveTooltip(badge: BadgeConfig): string {
+  return badge.tooltip ?? badge.text
+}
+
+/**
+ * Map a badge variant to its chip class, defaulting to `neutral`.
+ *
+ * @private
+ * @param variant - The badge variant, if any
+ * @returns The full class string for the chip
+ */
+function variantClass(variant: BadgeVariant | undefined): string {
+  return match(variant)
+    .with('info', () => 'cp-sbadge cp-sbadge--info')
+    .with('success', () => 'cp-sbadge cp-sbadge--success')
+    .with('warning', () => 'cp-sbadge cp-sbadge--warning')
+    .with('danger', () => 'cp-sbadge cp-sbadge--danger')
+    .with('neutral', () => 'cp-sbadge cp-sbadge--neutral')
+    .with(undefined, () => 'cp-sbadge cp-sbadge--neutral')
+    .exhaustive()
+}
+
+/**
+ * Build a subtle background tint from a custom color.
+ *
+ * @private
+ * @param color - CSS color value
+ * @returns A `color-mix` background at low opacity
+ */
+function tint(color: string): string {
+  return `color-mix(in srgb, ${color} 14%, transparent)`
+}

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

@@ -14,7 +14,7 @@ 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 { useEffect, useLayoutEffect, useMemo, useState } from 'react'
 
 import { useCiderpress } from '../../hooks/use-ciderpress'
 import { resolveScopedSidebar } from './sidebar-filter'
@@ -59,9 +59,32 @@ export function Sidebar(): React.ReactElement {
     setSidebarData(initializeCollapsed(filteredData, activeMatcher))
   }, [activeMatcher, filteredData])
 
+  useEffect(() => {
+    decorateOverflowTitles()
+  }, [sidebarData])
+
   return <SidebarList sidebarData={sidebarData} setSidebarData={setSidebarData} />
 }
 
+/**
+ * Add a `title` attribute to sidebar labels that overflow their column so
+ * the full text shows on hover; clear it when the label fits. Runs after
+ * render because overflow is a measured, layout-dependent property.
+ *
+ * @private
+ */
+function decorateOverflowTitles(): void {
+  const labels = [...document.querySelectorAll<HTMLElement>('.rp-sidebar-item__left > .rp-doc')]
+  labels.reduce<null>((_, label) => {
+    if (label.scrollWidth > label.clientWidth) {
+      label.setAttribute('title', label.textContent ?? '')
+    } else {
+      label.removeAttribute('title')
+    }
+    return null
+  }, null)
+}
+
 /**
  * Walk the sidebar tree and uncollapse groups that contain the active path.
  *

package/dist/theme/hooks/use-ciderpress.ts

@@ -1,4 +1,4 @@
-import type { FooterConfig, HomeConfig, SerializedIcon } from '@ciderpress/config'
+import type { BadgeConfig, FooterConfig, HomeConfig, SerializedIcon } from '@ciderpress/config'
 import { useSite } from '@rspress/core/runtime'
 
 export interface CiderpressSidebarItem {
@@ -86,6 +86,10 @@ export interface CiderpressSiteBlock {
         readonly brandMark?: string
       }
     | undefined
+  readonly feedback: {
+    readonly enabled: boolean
+    readonly question: string | undefined
+  }
 }
 
 interface CiderpressThemeConfig {
@@ -97,6 +101,7 @@ interface CiderpressThemeConfig {
   readonly home: HomeConfig | undefined
   readonly ciderpressFooter: FooterConfig | undefined
   readonly site: CiderpressSiteBlock | undefined
+  readonly pageBadges: Record<string, readonly BadgeConfig[]> | undefined
 }
 
 /**

package/dist/theme/hooks/use-nav-items.ts

@@ -1,3 +1,4 @@
+import { removeBase } from '@rspress/core/runtime'
 import { useEffect, useState } from 'react'
 
 import type { CiderpressNavMenuItem } from '../components/nav/ciderpress-nav-menu'
@@ -41,34 +42,104 @@ export function useNavItems(): readonly CiderpressNavMenuItem[] {
 }
 
 /**
- * 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.
+ * Reconstruct the primary nav from Rspress's hidden `.rp-nav-menu`,
+ * preserving dropdowns. Each top-level `.rp-nav-menu__item` is either a
+ * leaf (its container is an anchor) or a dropdown parent (it wraps a
+ * `.rp-hover-group` of child links). Items with empty text, or dropdown
+ * parents with no usable children, are dropped.
  *
  * @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 navMenuRoots()
+    .map(scrapeNavItem)
+    .filter((item): item is CiderpressNavMenuItem => item !== null)
+}
+
+/**
+ * Collect the top-level `.rp-nav-menu__item` `<li>`s to scrape. Rspress
+ * renders separate left and right nav `<ul>`s; the ciderpress topbar is
+ * right-aligned, so we read the right menu and only fall back to the
+ * unscoped selector when it isn't present.
+ *
+ * @private
+ * @returns Top-level nav item elements.
+ */
+function navMenuRoots(): readonly HTMLElement[] {
+  const right = document.querySelectorAll<HTMLElement>('.rp-nav-menu--right > .rp-nav-menu__item')
+  if (right.length > 0) {
+    return [...right]
+  }
+  return [...document.querySelectorAll<HTMLElement>('.rp-nav-menu > .rp-nav-menu__item')]
+}
+
+/**
+ * Project a single top-level `.rp-nav-menu__item` element into a nav
+ * item, recursing one level into its `.rp-hover-group` dropdown when
+ * present.
+ *
+ * @private
+ * @param root - Top-level nav `<li>` element.
+ * @returns Parsed nav item, or `null` when unusable.
+ */
+function scrapeNavItem(root: HTMLElement): CiderpressNavMenuItem | null {
+  const container = root.querySelector(':scope > .rp-nav-menu__item__container')
+  if (container === null) {
+    return null
+  }
+  const text = readElementText(container)
+  if (text === '') {
+    return null
+  }
+  const group = root.querySelector(':scope > .rp-hover-group')
+  if (group !== null) {
+    const items = scrapeGroupItems(group)
+    if (items.length === 0) {
+      return null
+    }
+    return { text, items }
+  }
+  const href = container.getAttribute('href')
+  if (href === null || href === '') {
+    return null
+  }
+  // Un-base the scraped href so `<Link>` re-applies the site `base` once
+  // rather than doubling the mount prefix on subpath deploys.
+  return { text, link: removeBase(href) }
+}
+
+/**
+ * Read the child links out of a Rspress `.rp-hover-group` dropdown.
+ *
+ * @private
+ * @param group - The `.rp-hover-group` element.
+ * @returns Child nav items with text + link (empties dropped).
+ */
+function scrapeGroupItems(group: Element): readonly CiderpressNavMenuItem[] {
+  const anchors = group.querySelectorAll<HTMLAnchorElement>('.rp-hover-group__item__link')
   return [...anchors]
     .map((anchor) => ({
-      text: readAnchorText(anchor),
-      link: anchor.getAttribute('href') ?? '',
+      text: readElementText(anchor),
+      // Rspress's rendered hrefs already include the site `base`; strip it so
+      // the consuming `<Link>` re-applies it once instead of doubling the mount
+      // prefix on subpath deploys (the `/examples/<slug>/examples/<slug>/…` 404).
+      link: removeBase(anchor.getAttribute('href') ?? ''),
     }))
     .filter((item) => item.text !== '' && item.link !== '')
 }
 
 /**
- * Pull the trimmed text content from an anchor. Returns an empty
+ * Pull the trimmed text content from an element. Returns an empty
  * string when `textContent` is missing — callers treat empty as "skip
- * this anchor".
+ * this element".
  *
  * @private
- * @param anchor - Anchor element to read.
+ * @param element - Element to read.
  * @returns Trimmed inner text, or empty string when absent.
  */
-function readAnchorText(anchor: HTMLAnchorElement): string {
-  const text = anchor.textContent
+function readElementText(element: Element): string {
+  const text = element.textContent
   if (text === null) {
     return ''
   }

package/dist/theme/index.tsx

@@ -53,6 +53,7 @@ import './components/content-footer/feedback.css'
 import './components/content-footer/meta-actions.css'
 import './components/content-footer/page-pager.css'
 import './components/sidebar/framework-picker.css'
+import './components/sidebar/sidebar-badge.css'
 import './components/sidebar/sidebar-promo.css'
 import './components/sidebar/sidebar-toggle.css'
 import './components/home/page-rail.css'
@@ -89,6 +90,8 @@ export { HomeFeature } from './components/home/feature'
 export { HomeLayout } from './components/home/layout'
 /** @internal Sidebar override — multi-scope filtering for standalone sections */
 export { Sidebar } from './components/sidebar/sidebar-scope'
+/** @internal Tag override — renders ciderpress sidebar badges, delegates other tags to Rspress */
+export { Tag } from './components/sidebar/sidebar-badge'
 
 export { FeatureCard, FeatureGrid } from './components/home/feature-card'
 export type { FeatureCardProps, FeatureItem } from './components/home/feature-card'

package/dist/theme/styles/overrides/rail.css

@@ -145,18 +145,22 @@ html .rp-doc-layout__sidebar > :first-child:not(.cp-sidebar-top) {
 }
 
 html .cp-sidebar-bottom {
-  /* Grow to fill the remaining sidebar space so the nav tree stacks
-     from the top and this band occupies everything below it. When the
-     nav tree is short, the band is tall and its content (promo +
-     below-links) sits at its bottom via `justify-content: flex-end`. */
-  flex: 1 0 auto;
+  /* Size to content and sit directly under the nav tree. `flex: 0 0 auto`
+     (no grow) is deliberate: growing to fill (`1 0 auto`) stretched the
+     band across all leftover sidebar height, and a short nav tree left a
+     tall empty band with its content (promo + below-links) stranded at the
+     bottom. With no grow the band is exactly as tall as its content and
+     the promo/links hug the last nav item. */
+  flex: 0 0 auto;
   display: flex;
   flex-direction: column;
-  justify-content: flex-end;
-  /* When the sidebar scrolls (nav tree taller than viewport), this band
-     stays glued to the viewport bottom so the promo is always visible.
-     `z-index: 3` so the band paints above the thin overlay scrollbar
-     thumb so it doesn't appear to "go through" the band region. */
+  /* When the nav tree overflows the viewport the sidebar scrolls; this
+     band stays glued to the viewport bottom (`sticky bottom: 0`) so the
+     promo/links remain visible while the tree scrolls behind them. With a
+     short (non-scrolling) nav tree the sticky offset is never engaged, so
+     the band simply flows under the last nav item. `z-index: 3` paints it
+     above the thin overlay scrollbar thumb so it doesn't appear to "go
+     through" the band region. */
   position: sticky;
   bottom: 0;
   z-index: 3;
@@ -189,6 +193,19 @@ html .rp-outline__title {
   display: none;
 }
 
+/* "On this page" outline — truncate long headings to a single line with
+   an ellipsis instead of wrapping. Rspress already sets a native `title`
+   on each `.rp-toc-item` anchor, so hovering a truncated heading reveals
+   the full text. Targets `.rp-toc-item__text`, shared by the desktop
+   rail and the mobile outline dropdown. */
+html .rp-toc-item__text {
+  display: block;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 html .rp-doc-layout__doc {
   background: var(--cp-c-bg);
 }

package/dist/theme/styles/overrides/section-card.css

@@ -31,6 +31,15 @@
   gap: 10px;
 }
 
+/* Page badges pinned to the right of the card title row. */
+.cp-section-card__badges {
+  margin-left: auto;
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  flex: 0 0 auto;
+}
+
 .cp-section-card:hover {
   border-color: var(--cp-c-brand-1);
   background: var(--cp-c-bg-elv);

package/dist/theme/styles/overrides/sidebar.css

@@ -24,6 +24,28 @@
     }
   }
 
+  /* ── Long titles — single-line ellipsis, badge stays pinned ──── */
+  /* The item's left slot holds the label; constrain it so the label
+     truncates instead of pushing the badge (right slot) out of view.
+     A `title` attribute is added by the Sidebar effect on overflow. */
+  html .rp-sidebar-item__left {
+    min-width: 0;
+    flex: 1 1 auto;
+    overflow: hidden;
+  }
+
+  html .rp-sidebar-item__left > .rp-doc {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  html .rp-sidebar-item__right {
+    flex: 0 0 auto;
+    margin-left: 6px;
+  }
+
   /* ── Group section headers — mono ALL CAPS (mockup pattern) ──── */
   html .rp-sidebar-section-header {
     font-family: var(--cp-font-family-mono);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ciderpress/ui",
-  "version": "1.0.0-rc.6",
+  "version": "1.0.0-rc.7",
   "description": "Rspress plugin, theme components, and styles for ciderpress",
   "keywords": [
     "ciderpress",
@@ -48,28 +48,29 @@
     "@iconify-json/catppuccin": "^1.2.17",
     "@iconify-json/devicon": "^1.2.62",
     "@iconify-json/logos": "^1.2.11",
-    "@iconify-json/material-icon-theme": "^1.2.68",
+    "@iconify-json/material-icon-theme": "^1.2.69",
     "@iconify-json/mdi": "^1.2.3",
-    "@iconify-json/pixelarticons": "^1.2.6",
-    "@iconify-json/simple-icons": "^1.2.87",
+    "@iconify-json/pixel": "^1.2.2",
+    "@iconify-json/pixelarticons": "^1.2.7",
+    "@iconify-json/simple-icons": "^1.2.89",
     "@iconify-json/skill-icons": "^1.2.4",
-    "@iconify-json/vscode-icons": "^1.2.62",
+    "@iconify-json/vscode-icons": "^1.2.65",
     "@iconify/react": "^6.0.2",
     "clsx": "^2.1.1",
     "katex": "^0.17.0",
     "massaman": "^0.3.0",
-    "mermaid": "^10.9.6",
+    "mermaid": "^11.16.0",
     "openapi-sampler": "^1.7.4",
     "react-aria-components": "^1.19.0",
     "ts-morph": "^28.0.0",
     "unist-util-visit": "^5.1.0",
-    "@ciderpress/config": "1.0.0-rc.5",
-    "@ciderpress/theme": "1.0.0-rc.3"
+    "@ciderpress/config": "1.0.0-rc.6",
+    "@ciderpress/theme": "1.0.0-rc.4"
   },
   "devDependencies": {
     "@ladle/react": "^5.1.1",
-    "@rslib/core": "^0.23.1",
-    "@rspress/core": "^2.0.15",
+    "@rslib/core": "0.23.1",
+    "@rspress/core": "^2.0.16",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "esbuild": "^0.28.1",
@@ -81,10 +82,10 @@
     "rspress-plugin-katex": "^1.0.1",
     "rspress-plugin-supersub": "^1.0.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "@rspress/core": "^2.0.15",
+    "@rspress/core": "^2.0.16",
     "react": "^19.2.5",
     "react-dom": "^19.2.5"
   },

package/src/theme/components/nav/ciderpress-docs-bar.css

@@ -90,11 +90,21 @@
   display: flex;
   align-items: center;
   gap: 6px;
-  flex: 1 1 auto;
+  /* Shrink-to-content (not grow) so page badges sit snug to the right of
+     the trail; long trails still truncate via `overflow: hidden`. */
+  flex: 0 1 auto;
   min-width: 0;
   overflow: hidden;
 }
 
+/* Page badges (ALPHA / WIP …) immediately right of the breadcrumb trail. */
+.cp-docs-bar__badges {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  flex: 0 0 auto;
+}
+
 .cp-docs-bar__crumb-wrap {
   display: inline-flex;
   align-items: center;
@@ -358,6 +368,8 @@ html[data-cp-outline-collapsed='true'] .cp-docs-bar__chev {
    `styles/overrides/rspress.css`. ──────────────────────────────── */
 .cp-docs-bar__llms {
   flex-shrink: 0;
+  /* Crumbs no longer grow, so push the LLMs cluster to the far right. */
+  margin-left: auto;
 }
 
 .cp-docs-bar__llms .rp-llms-container {