@ciderpress/ui 1.0.0-rc.1

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@ciderpress/ui",
+  "version": "1.0.0-rc.1",
+  "description": "Rspress plugin, theme components, and styles for ciderpress",
+  "keywords": [
+    "ciderpress",
+    "react",
+    "rspress",
+    "theme",
+    "ui"
+  ],
+  "homepage": "https://github.com/thebytefarm/ciderpress/tree/main/packages/ui#readme",
+  "bugs": "https://github.com/thebytefarm/ciderpress/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thebytefarm/ciderpress.git",
+    "directory": "packages/ui"
+  },
+  "files": [
+    "dist",
+    "src/theme"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.mjs"
+    },
+    "./theme": {
+      "types": "./src/theme/index.tsx",
+      "import": "./src/theme/index.tsx"
+    },
+    "./icons": {
+      "types": "./src/theme/icons/index.ts",
+      "import": "./src/theme/icons/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "dependencies": {
+    "@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.67",
+    "@iconify-json/mdi": "^1.2.3",
+    "@iconify-json/pixelarticons": "^1.2.6",
+    "@iconify-json/simple-icons": "^1.2.86",
+    "@iconify-json/skill-icons": "^1.2.4",
+    "@iconify-json/vscode-icons": "^1.2.55",
+    "@iconify/react": "^6.0.2",
+    "clsx": "^2.1.1",
+    "katex": "^0.17.0",
+    "massaman": "^0.2.0",
+    "mermaid": "^10.9.6",
+    "openapi-sampler": "^1.7.4",
+    "react-aria-components": "^1.18.0",
+    "ts-morph": "^28.0.0",
+    "unist-util-visit": "^5.1.0",
+    "@ciderpress/theme": "1.0.0-rc.1",
+    "@ciderpress/config": "1.0.0-rc.1"
+  },
+  "devDependencies": {
+    "@ladle/react": "^5.1.1",
+    "@rslib/core": "^0.22.0",
+    "@rspress/core": "^2.0.14",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "esbuild": "^0.28.0",
+    "geist": "^1.7.2",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "rspress-plugin-devkit": "^1.0.0",
+    "rspress-plugin-file-tree": "^1.0.5",
+    "rspress-plugin-katex": "^1.0.1",
+    "rspress-plugin-supersub": "^1.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@rspress/core": "^2.0.14",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "postbuild": "node scripts/generate-theme-css.mjs && oxfmt --write src/theme/styles/themes src/head/css/themes && node scripts/minify-head.mjs",
+    "dev": "rslib build --watch --no-clean",
+    "generate:theme-css": "node scripts/generate-theme-css.mjs",
+    "ladle": "ladle serve",
+    "test": "vitest run",
+    "typecheck": "tsgo --noEmit"
+  }
+}

package/src/theme/components/announcement/announcement-bar.css

@@ -0,0 +1,103 @@
+.cp-announce {
+  position: relative;
+  height: var(--cp-announce-h);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 12px;
+  padding: 0 48px;
+  background: linear-gradient(
+    90deg,
+    var(--cp-c-brand-soft) 0%,
+    transparent 50%,
+    var(--cp-c-brand-soft) 100%
+  );
+  border-bottom: 1px solid var(--cp-c-border);
+  font-size: 12.5px;
+  color: var(--cp-c-text-2);
+}
+
+.cp-announce__pulse {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--cp-c-brand-1);
+  animation: cp-announce-pulse 2.4s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+
+@keyframes cp-announce-pulse {
+  0%,
+  100% {
+    box-shadow: 0 0 0 0 var(--cp-c-brand-soft);
+  }
+  50% {
+    box-shadow: 0 0 0 6px transparent;
+  }
+}
+
+.cp-announce__msg {
+  display: inline-flex;
+  flex-wrap: wrap;
+  gap: 4px;
+  align-items: center;
+}
+
+.cp-announce__lead {
+  color: var(--cp-c-text-1);
+  font-style: normal;
+  font-weight: 500;
+}
+
+.cp-announce__cta {
+  color: var(--cp-c-brand-1);
+  font-weight: 500;
+  margin-left: 4px;
+}
+
+.cp-announce__cta:hover {
+  color: var(--cp-c-brand-2);
+}
+
+.cp-announce__close {
+  position: absolute;
+  right: 12px;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 22px;
+  height: 22px;
+  display: grid;
+  place-items: center;
+  background: transparent;
+  border: 0;
+  border-radius: 4px;
+  color: var(--cp-c-text-3);
+  cursor: pointer;
+}
+
+.cp-announce__close:hover {
+  background: var(--cp-c-bg-soft);
+  color: var(--cp-c-text-1);
+}
+
+/* Mobile: shrink padding so the message doesn't wrap weirdly inside a
+   fixed 36px row. Let the bar grow vertically when the message + CTA
+   would otherwise collide with the close button. */
+@media (max-width: 720px) {
+  html .cp-announce {
+    height: auto;
+    min-height: var(--cp-announce-h);
+    padding: 6px 36px 6px 12px;
+    font-size: 12px;
+    line-height: 1.35;
+    text-align: left;
+    justify-content: flex-start;
+  }
+  html .cp-announce__msg {
+    flex: 1;
+    flex-wrap: wrap;
+    row-gap: 2px;
+  }
+  html .cp-announce__close {
+    right: 6px;
+  }
+}

package/src/theme/components/announcement/announcement-bar.tsx

@@ -0,0 +1,173 @@
+import { match } from 'massaman/match'
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+
+import { RouteLink } from '../../lib/route-link.tsx'
+import { safeUrl } from '../../lib/safe-url.ts'
+
+import './announcement-bar.css'
+
+const STORAGE_PREFIX = 'ciderpress-announcement-dismissed:'
+/**
+ * Initial height assumption before the bar mounts and measures itself.
+ * Matches the value Rspress's own `<Banner />` uses (`useState(36)`) so
+ * downstream sticky offsets are roughly correct on the first paint.
+ */
+const INITIAL_HEIGHT = 36
+
+export interface AnnouncementBarProps {
+  /**
+   * Stable ID — when present, dismissal is remembered in localStorage.
+   */
+  readonly id?: string
+  /**
+   * Lead text. Use for the highlighted phrase ("ciderpress 1.0", "NEW:", etc).
+   */
+  readonly lead?: React.ReactNode
+  /**
+   * Body of the announcement.
+   */
+  readonly children: React.ReactNode
+  /**
+   * Optional CTA link rendered after the message.
+   */
+  readonly cta?: { readonly href: string; readonly label: string }
+  /**
+   * Hide the dismiss button.
+   */
+  readonly persistent?: boolean
+}
+
+/**
+ * AnnouncementBar — full-width banner rendered above the topbar via the
+ * Layout `top` slot. Ships with a pulsing accent dot and an optional
+ * dismiss button that persists in localStorage when an `id` is provided.
+ *
+ * @param props - AnnouncementBar configuration.
+ * @returns React element, or null when the bar has been dismissed.
+ */
+export function AnnouncementBar(props: AnnouncementBarProps): React.ReactElement | null {
+  const { id, lead, children, cta, persistent } = props
+  const [dismissed, setDismissed] = useState(() => readDismissed(id))
+  // Track the rendered height so downstream sticky offsets
+  // (`--rp-nav-height` calc + the docs bar's sticky `top`) clear the
+  // announcement bar without anybody hardcoding a number. Mirrors the
+  // pattern Rspress's own `<Banner />` uses: a state value + a
+  // callback ref + a sibling `<style>` tag exposing the value as a
+  // CSS variable.
+  const [height, setHeight] = useState(INITIAL_HEIGHT)
+  const measureRef = useRef<HTMLDivElement | null>(null)
+
+  useEffect(() => {
+    setDismissed(readDismissed(id))
+  }, [id])
+
+  const handleDismiss = useCallback(() => {
+    writeDismissed(id)
+    setDismissed(true)
+  }, [id])
+
+  const setMeasureRef = useCallback((element: HTMLDivElement | null) => {
+    measureRef.current = element
+    if (element !== null && element.offsetHeight > 0) {
+      setHeight(element.offsetHeight)
+    }
+  }, [])
+
+  return match(dismissed)
+    .with(true, () => null)
+    .otherwise(() => (
+      <>
+        <div ref={setMeasureRef} className="cp-announce" role="region" aria-label="Announcement">
+          <span className="cp-announce__pulse" aria-hidden="true" />
+          <span className="cp-announce__msg">
+            {match(lead)
+              .with(undefined, () => null)
+              .otherwise((l) => (
+                <em className="cp-announce__lead">{l}</em>
+              ))}{' '}
+            {children}
+            {match(cta)
+              .with(undefined, () => null)
+              .otherwise((c) => {
+                const href = safeUrl(c.href)
+                if (href === null) {
+                  return null
+                }
+                return (
+                  <RouteLink className="cp-announce__cta" href={href}>
+                    {c.label} →
+                  </RouteLink>
+                )
+              })}
+          </span>
+          {match(persistent === true)
+            .with(true, () => null)
+            .otherwise(() => (
+              <button
+                className="cp-announce__close"
+                type="button"
+                onClick={handleDismiss}
+                aria-label="Dismiss announcement"
+              >
+                <svg
+                  width="12"
+                  height="12"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                >
+                  <line x1="18" y1="6" x2="6" y2="18" />
+                  <line x1="6" y1="6" x2="18" y2="18" />
+                </svg>
+              </button>
+            ))}
+        </div>
+        {/* Expose the measured height as a CSS variable so the docs
+            bar's sticky `top:` and the `--rp-nav-height` calc clear
+            the announcement without anybody hardcoding 36px. Pattern
+            cribbed directly from Rspress's `<Banner />`. */}
+        <style>{`:root { --cp-announcement-height: ${height}px; }`}</style>
+      </>
+    ))
+}
+
+/**
+ * Read the dismissed flag from localStorage.
+ *
+ * @private
+ * @param id - Announcement ID, or undefined.
+ * @returns true when the announcement has been dismissed.
+ */
+function readDismissed(id: string | undefined): boolean {
+  return match(id)
+    .with(undefined, () => false)
+    .otherwise((key) => {
+      if (globalThis.window === undefined) {
+        return false
+      }
+      try {
+        return globalThis.localStorage.getItem(STORAGE_PREFIX + key) === '1'
+      } catch {
+        return false
+      }
+    })
+}
+
+/**
+ * Persist the dismissed flag to localStorage.
+ *
+ * @private
+ * @param id - Announcement ID, or undefined.
+ */
+function writeDismissed(id: string | undefined): void {
+  match(id)
+    .with(undefined, () => {})
+    .otherwise((key) => {
+      try {
+        globalThis.localStorage.setItem(STORAGE_PREFIX + key, '1')
+      } catch {
+        // ignore — storage may be unavailable
+      }
+    })
+}

package/src/theme/components/ask-ai/ask-ai-button.css

@@ -0,0 +1,52 @@
+.cp-ask-ai {
+  position: fixed;
+  bottom: var(--cp-s-20);
+  right: var(--cp-s-20);
+  z-index: var(--cp-z-floating);
+  display: inline-flex;
+  align-items: center;
+  gap: var(--cp-s-8);
+  padding: var(--cp-s-10) var(--cp-s-14);
+  background: var(--cp-c-bg-soft);
+  border: 1px solid var(--cp-c-border);
+  border-radius: var(--cp-radius-pill);
+  color: var(--cp-c-text-1);
+  font-family: var(--cp-font-family-base);
+  font-size: var(--cp-fs-ask-ai);
+  font-weight: 500;
+  cursor: pointer;
+  box-shadow: var(--cp-shadow-ask-ai);
+  backdrop-filter: blur(var(--cp-blur-base));
+  transition: border-color var(--cp-duration-fast) var(--cp-ease-base);
+}
+
+.cp-ask-ai:hover {
+  border-color: var(--cp-c-brand-soft);
+}
+
+.cp-ask-ai__icon {
+  width: var(--cp-size-ask-ai-icon);
+  height: var(--cp-size-ask-ai-icon);
+  border-radius: 50%;
+  background: var(--cp-gradient-brand);
+  display: grid;
+  place-items: center;
+  color: var(--cp-c-brand-fg);
+  font-family: var(--cp-font-family-mono);
+  font-size: var(--cp-fs-ask-ai-mark);
+  font-weight: 700;
+}
+
+.cp-ask-ai__label {
+  white-space: nowrap;
+}
+
+.cp-ask-ai__shortcut {
+  font-family: var(--cp-font-family-mono);
+  font-size: var(--cp-fs-ask-ai-shortcut);
+  color: var(--cp-c-text-3);
+  padding: var(--cp-s-1) var(--cp-s-5);
+  border: 1px solid var(--cp-c-border);
+  border-radius: var(--cp-radius-xs-sm);
+  margin-left: var(--cp-s-4);
+}

package/src/theme/components/ask-ai/ask-ai-button.tsx

@@ -0,0 +1,56 @@
+import { match } from 'massaman/match'
+import React, { useCallback } from 'react'
+
+import './ask-ai-button.css'
+
+export interface AskAIButtonProps {
+  /**
+   * Click handler. When omitted, the button does nothing.
+   */
+  readonly onClick?: () => void
+  /**
+   * Visible label. Defaults to "Ask AI".
+   */
+  readonly label?: string
+  /**
+   * Optional shortcut hint (e.g. "⌘J").
+   */
+  readonly shortcut?: string
+  /**
+   * Pre-positioned glyph for the badge (default: ★).
+   */
+  readonly badge?: React.ReactNode
+}
+
+/**
+ * AskAIButton — floating CTA pill anchored bottom-right of the viewport.
+ * Visual sibling of the page chrome; pairs with AI-search integrations.
+ *
+ * @param props - AskAIButton configuration.
+ * @returns React element.
+ */
+export function AskAIButton(props: AskAIButtonProps): React.ReactElement {
+  const { onClick, label = 'Ask AI', shortcut, badge = '★' } = props
+
+  const handleClick = useCallback(() => {
+    match(onClick)
+      .with(undefined, () => {})
+      .otherwise((fn) => {
+        fn()
+      })
+  }, [onClick])
+
+  return (
+    <button className="cp-ask-ai" type="button" onClick={handleClick} aria-label={label}>
+      <span className="cp-ask-ai__icon" aria-hidden="true">
+        {badge}
+      </span>
+      <span className="cp-ask-ai__label">{label}</span>
+      {match(shortcut)
+        .with(undefined, () => null)
+        .otherwise((s) => (
+          <span className="cp-ask-ai__shortcut">{s}</span>
+        ))}
+    </button>
+  )
+}

package/src/theme/components/content-footer/content-footer-portal.tsx

@@ -0,0 +1,70 @@
+import React, { useEffect, useState } from 'react'
+import { createPortal } from 'react-dom'
+
+export interface ContentFooterPortalProps {
+  /**
+   * Children to portal into the in-rail doc footer slot.
+   */
+  readonly children: React.ReactNode
+}
+
+const HOST_ATTR = 'data-cp-content-footer-host'
+
+/**
+ * ContentFooterPortal — portals its children into Rspress's `.rp-doc-footer`
+ * so the content lives INSIDE the doc rail (at the reading width) rather
+ * than at body level (where the `afterDoc` slot otherwise lands).
+ *
+ * Inserts a sentinel div as the FIRST child of `.rp-doc-footer` so the
+ * portalled content appears above Rspress's built-in `.rp-prev-next-page`
+ * pager. Watches DOM mutations so the portal re-attaches on client-side
+ * route changes (Rspress re-renders the doc-footer per page).
+ *
+ * @param props - Portal configuration.
+ * @returns React element.
+ */
+export function ContentFooterPortal(props: ContentFooterPortalProps): React.ReactElement | null {
+  const [host, setHost] = useState<HTMLElement | null>(null)
+
+  useEffect(() => {
+    function ensureHost(): HTMLElement | null {
+      const docFooter = globalThis.document.querySelector('.rp-doc-footer')
+      if (docFooter === null) {
+        return null
+      }
+      const existing = docFooter.querySelector(`[${HOST_ATTR}]`) as HTMLElement | null
+      if (existing !== null) {
+        return existing
+      }
+      const node = globalThis.document.createElement('div')
+      node.setAttribute(HOST_ATTR, '')
+      const first = docFooter.firstChild
+      if (first === null) {
+        docFooter.append(node)
+      } else {
+        first.before(node)
+      }
+      return node
+    }
+
+    setHost(ensureHost())
+
+    const observer = new globalThis.MutationObserver(() => {
+      const next = ensureHost()
+      setHost((prev) => {
+        if (prev !== null && prev.isConnected) {
+          return prev
+        }
+        return next
+      })
+    })
+    observer.observe(globalThis.document.body, { childList: true, subtree: true })
+
+    return () => observer.disconnect()
+  }, [])
+
+  if (host === null) {
+    return null
+  }
+  return createPortal(<div className="cp-content-footer">{props.children}</div>, host)
+}

package/src/theme/components/content-footer/feedback.css

@@ -0,0 +1,47 @@
+.cp-feedback {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 14px 16px;
+  border: 1px solid var(--cp-c-border);
+  border-radius: var(--cp-radius-card);
+  margin-bottom: 24px;
+  background: var(--cp-c-bg-soft);
+}
+
+.cp-feedback__q {
+  font-size: 13px;
+  color: var(--cp-c-text-1);
+}
+
+.cp-feedback__actions {
+  display: flex;
+  gap: 6px;
+}
+
+.cp-feedback__btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 12px;
+  font-size: 12px;
+  font-weight: 500;
+  font-family: inherit;
+  border-radius: var(--cp-radius-pill);
+  border: 1px solid var(--cp-c-border);
+  background: transparent;
+  color: var(--cp-c-text-1);
+  cursor: pointer;
+  transition: all 0.15s ease;
+  white-space: nowrap;
+}
+
+.cp-feedback__btn:hover {
+  background: var(--cp-c-bg-elv);
+  border-color: var(--cp-c-border);
+}
+
+.cp-feedback__thanks {
+  font-size: 13px;
+  color: var(--cp-c-text-2);
+}

package/src/theme/components/content-footer/feedback.tsx

@@ -0,0 +1,96 @@
+import { match } from 'massaman/match'
+import React, { useCallback, useState } from 'react'
+
+import './feedback.css'
+
+export interface FeedbackProps {
+  /**
+   * Question shown to the reader. Defaults to "Was this page helpful?".
+   */
+  readonly question?: string
+  /**
+   * Optional callback invoked with the user's answer.
+   */
+  readonly onSubmit?: (answer: 'yes' | 'no') => void
+}
+
+type FeedbackState = 'idle' | 'yes' | 'no'
+
+/**
+ * Feedback — yes/no widget rendered at the bottom of doc pages.
+ * Submitting hides the buttons and shows a thank-you message.
+ *
+ * @param props - Feedback configuration.
+ * @returns React element.
+ */
+export function Feedback(props: FeedbackProps): React.ReactElement {
+  const { question = 'Was this page helpful?', onSubmit } = props
+  const [state, setState] = useState<FeedbackState>('idle')
+
+  const handleClick = useCallback(
+    (answer: 'yes' | 'no') => () => {
+      setState(answer)
+      match(onSubmit)
+        .with(undefined, () => {})
+        .otherwise((fn) => {
+          fn(answer)
+        })
+    },
+    [onSubmit]
+  )
+
+  return (
+    <div className="cp-feedback">
+      {match(state)
+        .with('idle', () => (
+          <>
+            <span className="cp-feedback__q">{question}</span>
+            <div className="cp-feedback__actions">
+              <button className="cp-feedback__btn" type="button" onClick={handleClick('yes')}>
+                <ThumbIcon />
+                Yes
+              </button>
+              <button className="cp-feedback__btn" type="button" onClick={handleClick('no')}>
+                <ThumbIcon flipped />
+                No
+              </button>
+            </div>
+          </>
+        ))
+        .otherwise(() => (
+          <span className="cp-feedback__thanks">Thanks for the feedback.</span>
+        ))}
+    </div>
+  )
+}
+
+interface ThumbIconProps {
+  readonly flipped?: boolean
+}
+
+/**
+ * Thumb icon used in feedback buttons.
+ *
+ * @private
+ * @param props - Whether to flip the icon (for thumbs-down).
+ * @returns SVG element.
+ */
+function ThumbIcon(props: ThumbIconProps): React.ReactElement {
+  const transform = match(props.flipped === true)
+    .with(true, () => 'rotate(180deg)')
+    .otherwise(() => 'none')
+
+  return (
+    <svg
+      width="11"
+      height="11"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      style={{ transform }}
+    >
+      <path d="M14 9V5a3 3 0 0 0-3-3l-4 9v11h11.28a2 2 0 0 0 2-1.7l1.38-9a2 2 0 0 0-2-2.3zM7 22H4a2 2 0 0 1-2-2v-7a2 2 0 0 1 2-2h3" />
+    </svg>
+  )
+}