@ciderpress/ui 1.0.0-rc.1

package/dist/theme/components/shared/accordion.stories.tsx

@@ -0,0 +1,96 @@
+import type { Story } from '@ladle/react'
+
+import { Accordion, AccordionGroup } from './accordion.tsx'
+
+const meta = {
+  title: 'Disclosure / Accordion',
+}
+
+export default meta
+
+/**
+ * Single accordion — collapsed by default.
+ *
+ * @returns Accordion with title and body
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Default: Story = () => (
+  <Accordion title="What is Ciderpress?">
+    <p>
+      Ciderpress is a documentation framework for monorepos. Point it at your existing markdown and
+      get a full site without forcing a layout on the repo.
+    </p>
+  </Accordion>
+)
+
+/**
+ * Accordion with icon and description shown alongside the title.
+ *
+ * @returns Accordion with icon and subtitle
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const WithIconAndDescription: Story = () => (
+  <Accordion
+    title="Theme cascade"
+    description="How --cp-* tokens win over Rspress's --rp-* defaults"
+    icon="pixelarticons:layers"
+  >
+    <p>
+      Each theme palette declares a layer (`mulled`, `honeycrisp`, …) ordered after Rspress's base
+      layer, so brand vars always win.
+    </p>
+  </Accordion>
+)
+
+/**
+ * Accordion that starts expanded.
+ *
+ * @returns Accordion with initial open state
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const InitiallyOpen: Story = () => (
+  <Accordion title="Open by default" icon="pixelarticons:check" defaultOpen>
+    <p>This panel renders expanded on first mount.</p>
+  </Accordion>
+)
+
+/**
+ * Multiple accordions inside a Group — each is independent (multiple
+ * may be open at once).
+ *
+ * @returns Group of independent accordions
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Group: Story = () => (
+  <AccordionGroup>
+    <Accordion title="First section" icon="pixelarticons:flag">
+      <p>Plain content.</p>
+    </Accordion>
+    <Accordion title="Second section" icon="pixelarticons:bulb">
+      <p>More plain content.</p>
+    </Accordion>
+    <Accordion title="Third section" icon="pixelarticons:bookmark">
+      <p>Yet more.</p>
+    </Accordion>
+  </AccordionGroup>
+)
+
+/**
+ * Exclusive group — only one accordion may be open at a time.
+ *
+ * @returns Group with mutex behaviour
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const ExclusiveGroup: Story = () => (
+  <AccordionGroup exclusive>
+    <Accordion title="Step 1 — Install" icon="pixelarticons:download">
+      <p>Run `pnpm add ciderpress` in your repo root.</p>
+    </Accordion>
+    <Accordion title="Step 2 — Configure" icon="pixelarticons:sliders">
+      <p>Create `ciderpress.config.ts` and point it at your docs directory.</p>
+    </Accordion>
+    <Accordion title="Step 3 — Run" icon="pixelarticons:play">
+      <p>Run `pnpm cider dev` and open localhost:3000.</p>
+    </Accordion>
+  </AccordionGroup>
+)

package/dist/theme/components/shared/accordion.tsx

@@ -0,0 +1,191 @@
+import { match, P } from 'massaman/match'
+import type React from 'react'
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react'
+import { Button, Disclosure, DisclosurePanel } from 'react-aria-components'
+
+import { Icon } from './icon'
+
+export interface AccordionGroupProps {
+  /**
+   * When true, only one accordion in the group can be open at a time.
+   */
+  readonly exclusive?: boolean
+  /**
+   * Accordion children to coordinate.
+   */
+  readonly children: React.ReactNode
+}
+
+interface AccordionGroupContextValue {
+  readonly exclusive: boolean
+  readonly openId: string | null
+  readonly setOpenId: (id: string | null) => void
+}
+
+const AccordionGroupContext = createContext<AccordionGroupContextValue | null>(null)
+
+/**
+ * Group container that coordinates multiple Accordion components.
+ * When `exclusive` is true, only one accordion can be open at a time.
+ *
+ * @param props - Group configuration with optional exclusive mode
+ * @returns React element wrapping coordinated accordions
+ */
+export function AccordionGroup({
+  exclusive = false,
+  children,
+}: AccordionGroupProps): React.ReactElement {
+  const [openId, setOpenId] = useState<string | null>(null)
+
+  return (
+    <AccordionGroupContext.Provider value={{ exclusive, openId, setOpenId }}>
+      <div className="cp-accordion-group">{children}</div>
+    </AccordionGroupContext.Provider>
+  )
+}
+
+export interface AccordionProps {
+  /**
+   * Title displayed in the accordion trigger.
+   */
+  readonly title: string
+  /**
+   * Optional description displayed below the title.
+   */
+  readonly description?: string
+  /**
+   * Optional Iconify icon ID rendered before the title.
+   */
+  readonly icon?: string
+  /**
+   * Whether the accordion starts in the expanded state.
+   */
+  readonly defaultOpen?: boolean
+  /**
+   * Custom anchor ID for deep linking. Defaults to a slug of the title.
+   */
+  readonly id?: string
+  /**
+   * Content revealed when the accordion is expanded.
+   */
+  readonly children: React.ReactNode
+}
+
+/**
+ * Expandable section with title, optional description and icon,
+ * URL-hash deep linking, and keyboard-accessible expand/collapse.
+ *
+ * Built on react-aria-components Disclosure for full ARIA support.
+ *
+ * @param props - Accordion configuration
+ * @returns React element with expandable disclosure
+ */
+export function Accordion({
+  title,
+  description,
+  icon,
+  defaultOpen = false,
+  id,
+  children,
+}: AccordionProps): React.ReactElement {
+  const anchorId = id ?? slugify(title)
+  const group = useContext(AccordionGroupContext)
+  const isFirstRender = useRef(true)
+
+  // Determine if this accordion should start open:
+  // 1. URL hash match takes priority
+  // 2. Then defaultOpen prop
+  // 3. Then group exclusive state
+  const hashMatch = globalThis.location !== undefined && globalThis.location.hash === `#${anchorId}`
+  const initialOpen = hashMatch || defaultOpen
+
+  const [isExpanded, setIsExpanded] = useState(initialOpen)
+
+  useEffect(() => {
+    if (group !== null && group.exclusive && group.openId === null && initialOpen) {
+      group.setOpenId(anchorId)
+    }
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps -- seed once on mount
+
+  const expanded = match(group)
+    .with(
+      P.when((g): g is AccordionGroupContextValue => g !== null && g.exclusive),
+      (g) => g.openId === anchorId
+    )
+    .otherwise(() => isExpanded)
+
+  const handleExpandedChange = useCallback(
+    (open: boolean) => {
+      match({ group, exclusive: group !== null && group.exclusive })
+        .with({ group: P.nonNullable, exclusive: true }, ({ group: g }) => {
+          g.setOpenId(
+            match(open)
+              .with(true, () => anchorId)
+              .otherwise(() => null)
+          )
+        })
+        .otherwise(() => {
+          setIsExpanded(open)
+        })
+
+      if (open && globalThis.history !== undefined) {
+        globalThis.history.replaceState(null, '', `#${anchorId}`)
+      }
+    },
+    [group, anchorId]
+  )
+
+  useEffect(() => {
+    if (isFirstRender.current && hashMatch) {
+      isFirstRender.current = false
+      handleExpandedChange(true)
+    }
+  }, [hashMatch, handleExpandedChange])
+
+  const iconEl = match(icon)
+    .with(P.nonNullable, (i) => (
+      <span className="cp-accordion__icon">
+        <Icon icon={i} />
+      </span>
+    ))
+    .otherwise(() => null)
+
+  const descEl = match(description)
+    .with(P.nonNullable, (d) => <span className="cp-accordion__description">{d}</span>)
+    .otherwise(() => null)
+
+  return (
+    <Disclosure
+      id={anchorId}
+      isExpanded={expanded}
+      onExpandedChange={handleExpandedChange}
+      className="cp-accordion"
+    >
+      <Button slot="trigger" className="cp-accordion__trigger">
+        {iconEl}
+        <span className="cp-accordion__header">
+          <span className="cp-accordion__title">{title}</span>
+          {descEl}
+        </span>
+        <span className="cp-accordion__chevron">
+          <Icon icon="pixelarticons:chevron-right" />
+        </span>
+      </Button>
+      <DisclosurePanel className="cp-accordion__panel">{children}</DisclosurePanel>
+    </Disclosure>
+  )
+}
+
+/**
+ * Convert a title string to a URL-safe slug.
+ *
+ * @private
+ * @param text - Title text to slugify
+ * @returns Lowercase hyphenated slug
+ */
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, '-')
+    .replaceAll(/^-|-$/g, '')
+}

package/dist/theme/components/shared/brand-logo.stories.tsx

@@ -0,0 +1,49 @@
+import type { Story } from '@ladle/react'
+
+import { CiderpressLogo } from './ciderpress-logo.tsx'
+
+const meta = {
+  title: 'Brand / Logo',
+}
+
+export default meta
+
+/**
+ * Wordmark inheriting the active palette's `--rp-c-brand`.
+ *
+ * @returns Inline SVG wordmark
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Default: Story = () => (
+  <div style={{ width: 'min(640px, 100%)' }}>
+    <CiderpressLogo />
+  </div>
+)
+
+/**
+ * Explicit-size variant — useful for visual diffs against the favicon
+ * mark and footer mark at fixed pixel dimensions.
+ *
+ * @returns SVG wordmark at three explicit sizes
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Sizes: Story = () => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+    <CiderpressLogo width={480} />
+    <CiderpressLogo width={320} />
+    <CiderpressLogo width={200} />
+  </div>
+)
+
+/**
+ * Custom accessible title — replaces the default `"ciderpress"` label
+ * announced to screen readers.
+ *
+ * @returns Wordmark with custom title
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const CustomTitle: Story = () => (
+  <div style={{ width: 480 }}>
+    <CiderpressLogo title="ciderpress — documentation framework" />
+  </div>
+)

package/dist/theme/components/shared/brand-mark.stories.tsx

@@ -0,0 +1,53 @@
+import type { Story } from '@ladle/react'
+
+import { CiderpressMark } from './ciderpress-mark.tsx'
+
+const meta = {
+  title: 'Brand / Mark',
+}
+
+export default meta
+
+/**
+ * Default brand mark — rounded-square chip with `cp` monogram in
+ * the active palette's brand colour.
+ *
+ * @returns SVG mark at 64px
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Default: Story = () => <CiderpressMark size={64} />
+
+/**
+ * Size scale used across nav, footer, and favicon contexts.
+ *
+ * @returns Marks at 16/24/32/48/64/96/128 px
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Sizes: Story = () => (
+  <div style={{ display: 'flex', alignItems: 'flex-end', gap: 16, flexWrap: 'wrap' }}>
+    {[16, 24, 32, 48, 64, 96, 128].map((s) => (
+      <div key={s} style={{ textAlign: 'center' }}>
+        <CiderpressMark size={s} />
+        <div
+          style={{
+            marginTop: 6,
+            fontSize: 11,
+            color: 'var(--cp-c-text-3)',
+            fontFamily: 'ui-monospace, monospace',
+          }}
+        >
+          {s}px
+        </div>
+      </div>
+    ))}
+  </div>
+)
+
+/**
+ * Decorative mark — empty title sets `aria-hidden` so screen readers
+ * skip it. Use this when the surrounding text already conveys meaning.
+ *
+ * @returns Mark hidden from a11y tree
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Decorative: Story = () => <CiderpressMark size={64} title="" />

package/dist/theme/components/shared/browser-window.css

@@ -0,0 +1 @@
+/* Styles moved to desktop-window.css */

package/dist/theme/components/shared/browser-window.stories.tsx

@@ -0,0 +1,100 @@
+import type { Story } from '@ladle/react'
+
+import {
+  BrowserWindow,
+  Command,
+  IDEWindow,
+  Line,
+  Output,
+  TerminalWindow,
+} from './desktop-window.tsx'
+
+const meta = {
+  title: 'Windows',
+}
+
+export default meta
+
+/**
+ * BrowserWindow with a URL bar and inline body content.
+ *
+ * @returns Rendered browser chrome
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Browser: Story = () => (
+  <BrowserWindow url="https://ciderpress.dev/guides/themes" tab={{ title: 'Ciderpress · Themes' }}>
+    <div style={{ padding: 24 }}>
+      <h1 style={{ marginTop: 0 }}>Theme palettes</h1>
+      <p>Switch the palette in the toolbar above to preview the cascade.</p>
+    </div>
+  </BrowserWindow>
+)
+
+/**
+ * BrowserWindow rendering an image as its body — common pattern in docs
+ * for screenshots / hero captures.
+ *
+ * @returns Browser chrome wrapping an image
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const BrowserWithImage: Story = () => (
+  <BrowserWindow
+    url="https://ciderpress.dev"
+    tab={{ title: 'Ciderpress' }}
+    image="https://picsum.photos/seed/ciderpress/1200/600"
+  />
+)
+
+/**
+ * TerminalWindow with composed command/output children including coloured
+ * inline `<Line>` runs.
+ *
+ * @returns Terminal chrome
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Terminal: Story = () => (
+  <TerminalWindow title="zsh">
+    <Command>pnpm install ciderpress</Command>
+    <Output>
+      <Line color="muted">resolved 142 packages in 1.4s</Line>
+    </Output>
+    <Output>
+      <Line color="success" bold>
+        +
+      </Line>{' '}
+      <Line color="muted">ciderpress 1.0.0-rc.0</Line>
+    </Output>
+    <Command>pnpm cider dev</Command>
+    <Output>
+      <Line color="info">→</Line> <Line>http://localhost:3000</Line>
+    </Output>
+  </TerminalWindow>
+)
+
+const IDE_SAMPLE_CODE = `import { defineConfig } from 'ciderpress'
+
+export default defineConfig({
+  title: 'My Docs',
+  theme: 'mulled',
+  base: '/',
+})
+`
+
+/**
+ * IDE-style window with file tabs and a syntax-highlighted code block
+ * rendered via the stubbed `CodeBlockRuntime`.
+ *
+ * @returns IDE chrome with sample TypeScript code
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const IDE: Story = () => (
+  <IDEWindow
+    files={[
+      { name: 'ciderpress.config.ts', active: true },
+      { name: 'package.json' },
+      { name: 'README.md' },
+    ]}
+    code={IDE_SAMPLE_CODE}
+    lang="ts"
+  />
+)

package/dist/theme/components/shared/browser-window.tsx

@@ -0,0 +1,2 @@
+export { BrowserWindow } from './desktop-window'
+export type { BrowserWindowProps, BrowserTab } from './desktop-window'

package/dist/theme/components/shared/card.stories.tsx

@@ -0,0 +1,50 @@
+import type { Story } from '@ladle/react'
+
+import { Card } from './card.tsx'
+
+const meta = {
+  title: 'Surface / Card',
+}
+
+export default meta
+
+/**
+ * Plain card without a link target — renders as `<div>`.
+ *
+ * @returns Static card
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Static: Story = () => (
+  <Card>
+    <h3 style={{ marginTop: 0 }}>Static card</h3>
+    <p>No href supplied — the surface renders as a plain div.</p>
+  </Card>
+)
+
+/**
+ * Card with a safe URL — renders as the stubbed Rspress `<Link>`.
+ *
+ * @returns Clickable card
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Clickable: Story = () => (
+  <Card href="/guides/getting-started">
+    <h3 style={{ marginTop: 0 }}>Clickable card</h3>
+    <p>href passes safeUrl validation, so the card becomes an anchor.</p>
+  </Card>
+)
+
+/**
+ * Card with an unsafe `javascript:` href — `safeUrl()` rejects it and the
+ * card falls back to `<div>`. Visually identical to `Static`.
+ *
+ * @returns Card with stripped href
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const RejectedHref: Story = () => (
+  // oxlint-disable-next-line no-script-url -- testing safeUrl() rejection
+  <Card href={'javascript:alert(1)'}>
+    <h3 style={{ marginTop: 0 }}>Rejected href</h3>
+    <p>Falls back to a div — XSS sink defused.</p>
+  </Card>
+)

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

@@ -0,0 +1,35 @@
+import { Link } from '@rspress/core/runtime'
+import { match, P } from 'massaman/match'
+import type React from 'react'
+
+import { safeUrl } from '../../lib/safe-url.ts'
+
+export interface CardProps {
+  readonly href?: string
+  readonly className?: string
+  readonly children: React.ReactNode
+}
+
+/**
+ * Shared base card handling link-vs-div rendering.
+ *
+ * Renders `<a>` with `cp-card--clickable` when `href` is provided AND
+ * passes `safeUrl()` validation. When `href` is omitted or fails
+ * validation, falls back to a plain `<div>` so the card surface stays
+ * visible without becoming a script-execution sink.
+ *
+ * @param props - Props with optional href, optional className, and children
+ * @returns React element rendered as an anchor or div
+ */
+export function Card({ href, className, children }: CardProps): React.ReactElement {
+  const safeHref = match(href)
+    .with(P.nullish, () => null)
+    .otherwise((h) => safeUrl(h))
+  return match(safeHref)
+    .with(P.nonNullable, (h) => (
+      <Link className={`cp-card cp-card--clickable ${className ?? ''}`} to={h}>
+        {children}
+      </Link>
+    ))
+    .otherwise(() => <div className={`cp-card ${className ?? ''}`}>{children}</div>)
+}

package/dist/theme/components/shared/ciderpress-logo.tsx

@@ -0,0 +1,93 @@
+import { BRAND_COLORS, DEFAULT_THEME_NAME } from '@ciderpress/theme'
+import type React from 'react'
+
+const FONT_STACK = "'SF Mono', 'Fira Code', 'JetBrains Mono', Consolas, monospace"
+/**
+ * ViewBox cropped to the measured glyph bounding box plus a 1px border
+ * on every side. With `translate(0, 14)` below, the first line's
+ * ascender sits at y≈0 and the sixth line's descender bottoms out at
+ * y≈99, so the whole wordmark fills the box edge-to-edge instead of
+ * floating in extra empty space.
+ */
+const LOGO_VIEWBOX = '-1 -1 588 101'
+const LOGO_FALLBACK_COLOR = BRAND_COLORS[DEFAULT_THEME_NAME].primary
+const FONT_SIZE = 13
+const LINE_HEIGHT = 16
+const X_OFFSET = 0
+const Y_OFFSET = 14
+
+const CIDERPRESS_ART: readonly string[] = Object.freeze([
+  ' ██████╗██╗██████╗ ███████╗██████╗ ██████╗ ██████╗ ███████╗███████╗███████╗',
+  '██╔════╝██║██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔════╝██╔════╝██╔════╝',
+  '██║     ██║██║  ██║█████╗  ██████╔╝██████╔╝██████╔╝█████╗  ███████╗███████╗',
+  '██║     ██║██║  ██║██╔══╝  ██╔══██╗██╔═══╝ ██╔══██╗██╔══╝  ╚════██║╚════██║',
+  '╚██████╗██║██████╔╝███████╗██║  ██║██║     ██║  ██║███████╗███████║███████║',
+  ' ╚═════╝╚═╝╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝',
+])
+
+export interface CiderpressLogoProps {
+  /**
+   * Optional className applied to the root `<svg>` element.
+   */
+  readonly className?: string
+  /**
+   * Accessible label rendered into an SVG `<title>` element. Defaults to
+   * `"ciderpress"` so the logo is always announced by screen readers.
+   */
+  readonly title?: string
+  /**
+   * Explicit `width` attribute. Omit to let CSS / containing element
+   * control sizing via the SVG's `viewBox`.
+   */
+  readonly width?: number | string
+  /**
+   * Explicit `height` attribute. Omit to let CSS / containing element
+   * control sizing via the SVG's `viewBox`.
+   */
+  readonly height?: number | string
+}
+
+/**
+ * Inline `<svg>` ciderpress wordmark logo that auto-themes to the active theme.
+ *
+ * Renders the FIGlet "ciderpress" wordmark using `fill="currentColor"` so the
+ * glyphs inherit color from the wrapping `<svg>`. The wrapper sets `color`
+ * to `var(--rp-c-brand)` — the canonical brand variable maintained by
+ * `ThemeProvider` — so the logo tints to whichever theme (and variant) is
+ * active without any JS re-renders or theme subscriptions.
+ *
+ * Falls back to the default theme's primary brand color when
+ * `--rp-c-brand` is not defined (e.g. when rendered outside the
+ * ciderpress theme context).
+ *
+ * @param props - Optional className, title, and explicit size overrides
+ * @returns Inline SVG element
+ */
+export function CiderpressLogo(props: CiderpressLogoProps): React.ReactElement {
+  const title = props.title ?? 'ciderpress'
+
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox={LOGO_VIEWBOX}
+      className={props.className}
+      width={props.width}
+      height={props.height}
+      style={{ color: `var(--rp-c-brand, ${LOGO_FALLBACK_COLOR})` }}
+      role="img"
+    >
+      <title>{title}</title>
+      <g
+        transform={`translate(${X_OFFSET}, ${Y_OFFSET})`}
+        fontFamily={FONT_STACK}
+        fill="currentColor"
+      >
+        {CIDERPRESS_ART.map((line, i) => (
+          <text key={line} fontSize={FONT_SIZE} y={i * LINE_HEIGHT} xmlSpace="preserve">
+            {line}
+          </text>
+        ))}
+      </g>
+    </svg>
+  )
+}