@ciderpress/ui 1.0.0-rc.1

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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>
+  )
+}

package/dist/theme/components/content-footer/meta-actions.css

@@ -0,0 +1,25 @@
+.cp-meta-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 16px;
+  font-family: var(--cp-font-family-mono);
+  font-size: 12px;
+  color: var(--cp-c-text-3);
+  margin-bottom: 24px;
+}
+
+.cp-meta-actions__item {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--cp-c-text-2);
+  transition: color 0.15s ease;
+}
+
+.cp-meta-actions__item:hover {
+  color: var(--cp-c-text-1);
+}
+
+.cp-meta-actions__icon {
+  display: inline-flex;
+}

package/dist/theme/components/content-footer/meta-actions.tsx

@@ -0,0 +1,57 @@
+import { match } from 'massaman/match'
+import React from 'react'
+
+import { safeUrl } from '../../lib/safe-url.ts'
+
+import './meta-actions.css'
+
+export interface MetaAction {
+  readonly href: string
+  readonly label: string
+  readonly icon?: React.ReactNode
+}
+
+export interface MetaActionsProps {
+  /**
+   * List of actions to render — typically Edit on GitHub, Report issue, Discuss.
+   */
+  readonly actions: readonly MetaAction[]
+}
+
+/**
+ * MetaActions — horizontal row of mono-styled links rendered below the
+ * feedback widget on doc pages. Each action is an external/internal link
+ * with an optional leading icon.
+ *
+ * @param props - Actions to render.
+ * @returns React element, or null when no actions are provided.
+ */
+export function MetaActions(props: MetaActionsProps): React.ReactElement | null {
+  const safeActions = props.actions.flatMap((action) => {
+    const href = safeUrl(action.href)
+    if (href === null) {
+      return []
+    }
+    return [{ ...action, href }]
+  })
+  return match(safeActions.length === 0)
+    .with(true, () => null)
+    .otherwise(() => (
+      <div className="cp-meta-actions">
+        {safeActions.map((action) => (
+          <a
+            key={`${action.label}:${action.href}`}
+            className="cp-meta-actions__item"
+            href={action.href}
+          >
+            {match(action.icon)
+              .with(undefined, () => null)
+              .otherwise((icon) => (
+                <span className="cp-meta-actions__icon">{icon}</span>
+              ))}
+            <span>{action.label}</span>
+          </a>
+        ))}
+      </div>
+    ))
+}