@ciderpress/ui 1.0.0-rc.1

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

@@ -0,0 +1,44 @@
+import { match, P } from 'massaman/match'
+import type React from 'react'
+
+import { Card } from './card'
+import { Icon } from './icon'
+import { resolveCardIcon } from './resolve-card-icon'
+
+export interface SectionCardProps {
+  readonly href: string
+  readonly title: string
+  readonly description?: string
+  readonly icon?: string | { readonly id: string; readonly color: string }
+}
+
+/**
+ * Section card — simple icon + title + description link card
+ * used on auto-generated section landing pages.
+ *
+ * @param props - Props with href, title, optional description and icon
+ * @returns React element with a linked section card
+ */
+export function SectionCard({
+  href,
+  title,
+  description,
+  icon = 'pixelarticons:file',
+}: SectionCardProps): React.ReactElement {
+  const resolved = resolveCardIcon(icon) ?? { id: 'pixelarticons:file', color: 'purple' }
+  const descEl = match(description)
+    .with(P.nonNullable, (d) => <span className="cp-section-card__desc">{d}</span>)
+    .otherwise(() => null)
+
+  return (
+    <Card href={href} className="cp-section-card">
+      <div className="cp-section-card__header">
+        <span className={`cp-section-card__icon cp-section-card__icon--${resolved.color}`}>
+          <Icon icon={resolved.id} />
+        </span>
+        <span className="cp-section-card__title">{title}</span>
+      </div>
+      {descEl}
+    </Card>
+  )
+}

package/src/theme/components/shared/section-grid.stories.tsx

@@ -0,0 +1,46 @@
+import type { Story } from '@ladle/react'
+
+import { SectionCard } from './section-card.tsx'
+import { SectionGrid } from './section-grid.tsx'
+
+const meta = {
+  title: 'Layout / Section Grid',
+}
+
+export default meta
+
+/**
+ * Section grid populated with the same SectionCards used on auto-
+ * generated landing pages.
+ *
+ * @returns Grid wrapping four section cards
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Default: Story = () => (
+  <SectionGrid>
+    <SectionCard
+      href="/guides/getting-started"
+      title="Getting started"
+      description="Spin up a docs site against your existing markdown."
+      icon={{ id: 'pixelarticons:flag', color: 'purple' }}
+    />
+    <SectionCard
+      href="/concepts"
+      title="Concepts"
+      description="How the sync engine and theme cascade fit together."
+      icon={{ id: 'pixelarticons:bulb', color: 'amber' }}
+    />
+    <SectionCard
+      href="/references/cli"
+      title="CLI reference"
+      description="Every command, flag, and config option."
+      icon={{ id: 'pixelarticons:command', color: 'blue' }}
+    />
+    <SectionCard
+      href="/examples"
+      title="Examples"
+      description="Real-world Ciderpress sites you can copy from."
+      icon={{ id: 'pixelarticons:layout', color: 'green' }}
+    />
+  </SectionGrid>
+)

package/src/theme/components/shared/section-grid.tsx

@@ -0,0 +1,15 @@
+import type React from 'react'
+
+export interface SectionGridProps {
+  readonly children: React.ReactNode
+}
+
+/**
+ * Grid container for section cards on landing pages.
+ *
+ * @param props - Props with children to render inside the grid
+ * @returns React element wrapping children in a section grid
+ */
+export function SectionGrid({ children }: SectionGridProps): React.ReactElement {
+  return <div className="cp-section-grid">{children}</div>
+}

package/src/theme/components/shared/status-badge.css

@@ -0,0 +1,37 @@
+/**
+ * Badge — inline labels with semantic variants and custom colors.
+ */
+
+.cp-badge {
+  display: inline-flex;
+  align-items: center;
+  padding: var(--cp-s-1) var(--cp-s-8);
+  border-radius: var(--cp-radius-pill);
+  font-size: var(--cp-fs-badge);
+  font-weight: 600;
+  line-height: var(--cp-lh-relaxed);
+  letter-spacing: var(--cp-letter-wide);
+  text-transform: uppercase;
+  white-space: nowrap;
+  vertical-align: middle;
+}
+
+.cp-badge--info {
+  background: var(--cp-c-badge-info-bg);
+  color: var(--cp-c-badge-info-fg);
+}
+
+.cp-badge--success {
+  background: var(--cp-c-badge-success-bg);
+  color: var(--cp-c-badge-success-fg);
+}
+
+.cp-badge--warning {
+  background: var(--cp-c-badge-warning-bg);
+  color: var(--cp-c-badge-warning-fg);
+}
+
+.cp-badge--error {
+  background: var(--cp-c-badge-error-bg);
+  color: var(--cp-c-badge-error-fg);
+}

package/src/theme/components/shared/status-badge.stories.tsx

@@ -0,0 +1,61 @@
+import type { Story } from '@ladle/react'
+
+import { Badge } from './status-badge.tsx'
+import type { BadgeProps } from './status-badge.tsx'
+
+const meta = {
+  title: 'Data Display / Status Badge',
+}
+
+export default meta
+
+/**
+ * Default badge — info variant.
+ *
+ * @param args - Badge props driven by Ladle controls
+ * @returns Rendered badge
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Default: Story<BadgeProps> = (args) => <Badge {...args}>{args.children}</Badge>
+
+Default.args = {
+  children: 'Beta',
+  variant: 'info',
+}
+
+Default.argTypes = {
+  variant: {
+    control: { type: 'radio' },
+    options: ['info', 'success', 'warning', 'error'],
+    defaultValue: 'info',
+  },
+}
+
+/**
+ * One badge per semantic variant for at-a-glance review.
+ *
+ * @returns Variant gallery
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Variants: Story = () => (
+  <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
+    <Badge variant="info">Info</Badge>
+    <Badge variant="success">Success</Badge>
+    <Badge variant="warning">Warning</Badge>
+    <Badge variant="error">Error</Badge>
+  </div>
+)
+
+/**
+ * Badge driven by a free-form custom color.
+ *
+ * @returns Custom-colored badge
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const CustomColor: Story = () => (
+  <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
+    <Badge color="#7c3aed">Violet</Badge>
+    <Badge color="#0ea5e9">Sky</Badge>
+    <Badge color="#f472b6">Pink</Badge>
+  </div>
+)

package/src/theme/components/shared/status-badge.tsx

@@ -0,0 +1,74 @@
+import { match, P } from 'massaman/match'
+import type React from 'react'
+
+export type BadgeVariant = 'info' | 'success' | 'warning' | 'error'
+
+export interface BadgeProps {
+  /**
+   * Semantic variant controlling color. Defaults to 'info'.
+   * Ignored when `color` is provided.
+   */
+  readonly variant?: BadgeVariant
+  /**
+   * Custom color (hex, rgb, hsl). Overrides `variant` when set.
+   * Used as the text color with a 12% opacity background tint.
+   */
+  readonly color?: string
+  /**
+   * Badge label text.
+   */
+  readonly children: React.ReactNode
+}
+
+/**
+ * Inline badge for labeling features, endpoints, or sections.
+ * Supports semantic variants (info, success, warning, error) and
+ * arbitrary custom colors.
+ *
+ * @param props - Badge variant or custom color and label content
+ * @returns React element with styled inline badge
+ */
+export function Badge({ variant = 'info', color, children }: BadgeProps): React.ReactElement {
+  return match(color)
+    .with(P.nonNullable, (c) => (
+      <span className="cp-badge" style={{ color: c, backgroundColor: hexToTint(c) }}>
+        {children}
+      </span>
+    ))
+    .otherwise(() => {
+      const className = match(variant)
+        .with('info', () => 'cp-badge cp-badge--info')
+        .with('success', () => 'cp-badge cp-badge--success')
+        .with('warning', () => 'cp-badge cp-badge--warning')
+        .with('error', () => 'cp-badge cp-badge--error')
+        .exhaustive()
+
+      return <span className={className}>{children}</span>
+    })
+}
+
+/**
+ * Convert a hex color to an rgba tint at 12% opacity for the badge background.
+ * Falls back to a simple rgba wrapper for non-hex values.
+ *
+ * @private
+ * @param color - CSS color value
+ * @returns rgba string at 12% opacity
+ */
+function hexToTint(color: string): string {
+  const hex = color.replaceAll('#', '')
+
+  if (hex.length !== 6 && hex.length !== 3) {
+    return `color-mix(in srgb, ${color} 12%, transparent)`
+  }
+
+  const fullHex = match(hex.length)
+    .with(3, () => [...hex].map((c) => `${c}${c}`).join(''))
+    .otherwise(() => hex)
+
+  const r = Number.parseInt(fullHex.slice(0, 2), 16)
+  const g = Number.parseInt(fullHex.slice(2, 4), 16)
+  const b = Number.parseInt(fullHex.slice(4, 6), 16)
+
+  return `rgba(${String(r)}, ${String(g)}, ${String(b)}, 0.12)`
+}

package/src/theme/components/shared/steps.css

@@ -0,0 +1,88 @@
+/**
+ * Steps — vertical timeline stepper with numbered circles and connecting lines.
+ */
+
+.cp-steps {
+  display: flex;
+  flex-direction: column;
+  padding: 0;
+  margin: 16px 0;
+}
+
+.cp-step {
+  display: flex;
+  gap: 16px;
+}
+
+.cp-step__rail {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+.cp-step__indicator {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  border-radius: 50%;
+  border: 1px solid var(--cp-c-border);
+  background: var(--cp-c-bg-soft);
+  color: var(--cp-c-text-1);
+  font-size: 12px;
+  font-weight: 600;
+  line-height: 1;
+  flex-shrink: 0;
+}
+
+.cp-step__connector {
+  margin-top: 4px;
+  margin-bottom: 4px;
+  width: 2px;
+  flex: 1;
+  background: var(--cp-c-border);
+  min-height: 16px;
+}
+
+.cp-step:last-child .cp-step__connector {
+  background: linear-gradient(to bottom, var(--cp-c-border) 50%, transparent);
+}
+
+.cp-step__body {
+  padding-bottom: 24px;
+  min-width: 0;
+  flex: 1;
+}
+
+.cp-step:last-child .cp-step__body {
+  padding-bottom: 0;
+}
+
+.cp-step__title {
+  margin-top: 0 !important;
+  font-size: 16px;
+  font-weight: 600;
+  line-height: 24px;
+  color: var(--cp-c-text-1);
+}
+
+h2.cp-step__title {
+  font-size: 20px;
+  line-height: 24px;
+}
+
+p.cp-step__title {
+  font-size: 14px;
+  font-weight: 500;
+  line-height: 24px;
+}
+
+.cp-step__content {
+  margin-top: 8px;
+}
+
+.cp-step__content:empty {
+  display: none;
+}

package/src/theme/components/shared/steps.stories.tsx

@@ -0,0 +1,68 @@
+import type { Story } from '@ladle/react'
+
+import { Step, Steps } from './steps.tsx'
+
+const meta = {
+  title: 'Data Display / Steps',
+}
+
+export default meta
+
+/**
+ * Default — three numbered steps in the standard h3 title size.
+ *
+ * @returns Steps with numbered indicators
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Default: Story = () => (
+  <Steps>
+    <Step title="Install">
+      <p>Add Ciderpress to your monorepo:</p>
+      <code>pnpm add ciderpress</code>
+    </Step>
+    <Step title="Configure">
+      <p>Create `ciderpress.config.ts` at the repo root and point it at your docs directory.</p>
+    </Step>
+    <Step title="Run">
+      <p>Start the dev server and open the printed URL.</p>
+    </Step>
+  </Steps>
+)
+
+/**
+ * Icon indicators — each step's circle is replaced with the supplied
+ * Iconify icon instead of a number.
+ *
+ * @returns Steps with icon indicators
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const WithIcons: Story = () => (
+  <Steps>
+    <Step title="Author" icon="pixelarticons:edit">
+      <p>Write your docs as plain markdown — no special directives required.</p>
+    </Step>
+    <Step title="Sync" icon="pixelarticons:sync">
+      <p>The sync engine mirrors your structure into the Rspress-expected layout.</p>
+    </Step>
+    <Step title="Ship" icon="pixelarticons:cloud-upload">
+      <p>`pnpm cider build` produces a static site ready to deploy anywhere.</p>
+    </Step>
+  </Steps>
+)
+
+/**
+ * Smaller title size — useful for nested steps or sidebar callouts.
+ *
+ * @returns Steps with paragraph-sized titles
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const ParagraphTitles: Story = () => (
+  <Steps titleSize="p">
+    <Step title="First check">
+      <p>Verify Node 24+ is installed.</p>
+    </Step>
+    <Step title="Second check">
+      <p>Confirm pnpm is on a recent version.</p>
+    </Step>
+  </Steps>
+)

package/src/theme/components/shared/steps.tsx

@@ -0,0 +1,100 @@
+import { match, P } from 'massaman/match'
+import React from 'react'
+
+import { Icon } from './icon'
+
+export interface StepsProps {
+  /**
+   * Heading level for step titles.
+   */
+  readonly titleSize?: 'h2' | 'h3' | 'p'
+  /**
+   * Step children to render in a vertical timeline.
+   */
+  readonly children: React.ReactNode
+}
+
+/**
+ * Vertical timeline stepper that renders numbered Step children
+ * with connecting lines between them.
+ *
+ * @param props - Steps configuration with optional title size
+ * @returns React element wrapping Step children in a timeline layout
+ */
+export function Steps({ titleSize = 'h3', children }: StepsProps): React.ReactElement {
+  const mapped = React.Children.map(children, (child, index) =>
+    match(child)
+      .with(
+        P.when((c): c is React.ReactElement => React.isValidElement(c)),
+        (el) => React.cloneElement(el, { stepNumber: index + 1, titleSize } as Partial<StepProps>)
+      )
+      .otherwise(() => child)
+  )
+
+  return <div className="cp-steps">{mapped}</div>
+}
+
+export interface StepProps {
+  /**
+   * Title displayed next to the step indicator.
+   */
+  readonly title: string
+  /**
+   * Optional Iconify icon ID that replaces the step number in the circle.
+   */
+  readonly icon?: string
+  /**
+   * Explicit step number override. Injected automatically by Steps.
+   */
+  readonly stepNumber?: number
+  /**
+   * Heading level for the title. Injected automatically by Steps.
+   */
+  readonly titleSize?: 'h2' | 'h3' | 'p'
+  /**
+   * Arbitrary MDX content for this step.
+   */
+  readonly children: React.ReactNode
+}
+
+/**
+ * Individual step within a Steps timeline, rendering a numbered circle
+ * indicator (or icon), connecting line, title, and body content.
+ *
+ * @param props - Step configuration with title, optional icon, and content
+ * @returns React element for a single timeline step
+ */
+export function Step({
+  title,
+  icon,
+  stepNumber = 1,
+  titleSize = 'h3',
+  children,
+}: StepProps): React.ReactElement {
+  const indicator = match(icon)
+    .with(P.nonNullable, (i) => (
+      <span className="cp-step__indicator">
+        <Icon icon={i} />
+      </span>
+    ))
+    .otherwise(() => <span className="cp-step__indicator">{stepNumber}</span>)
+
+  const titleEl = match(titleSize)
+    .with('h2', () => <h2 className="cp-step__title">{title}</h2>)
+    .with('h3', () => <h3 className="cp-step__title">{title}</h3>)
+    .with('p', () => <p className="cp-step__title">{title}</p>)
+    .exhaustive()
+
+  return (
+    <div className="cp-step">
+      <div className="cp-step__rail">
+        {indicator}
+        <div className="cp-step__connector" />
+      </div>
+      <div className="cp-step__body">
+        {titleEl}
+        <div className="cp-step__content">{children}</div>
+      </div>
+    </div>
+  )
+}

package/src/theme/components/shared/tech-icon-table.stories.tsx

@@ -0,0 +1,29 @@
+import type { Story } from '@ladle/react'
+
+import { TechIconTable } from './tech-icon-table.tsx'
+
+const meta = {
+  title: 'Icons / Tech Icon Table',
+}
+
+export default meta
+
+/**
+ * Default — table of language icons matching what auto-generated
+ * reference docs render.
+ *
+ * @returns Tech-icon table with 6 entries
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Default: Story = () => (
+  <TechIconTable
+    entries={[
+      { tag: 'typescript', icon: 'devicon:typescript', label: 'TypeScript' },
+      { tag: 'javascript', icon: 'devicon:javascript', label: 'JavaScript' },
+      { tag: 'python', icon: 'devicon:python', label: 'Python' },
+      { tag: 'rust', icon: 'devicon:rust', label: 'Rust' },
+      { tag: 'go', icon: 'devicon:go', label: 'Go' },
+      { tag: 'java', icon: 'devicon:java', label: 'Java' },
+    ]}
+  />
+)

package/src/theme/components/shared/tech-icon-table.tsx

@@ -0,0 +1,71 @@
+import type React from 'react'
+
+import { Icon } from './icon'
+
+export interface TechIconEntry {
+  readonly tag: string
+  readonly icon: string
+  readonly label: string
+}
+
+export interface TechIconTableProps {
+  readonly entries: readonly TechIconEntry[]
+}
+
+const tableStyle: React.CSSProperties = {
+  width: '100%',
+}
+
+const iconCellStyle: React.CSSProperties = {
+  width: 48,
+  textAlign: 'center' as const,
+}
+
+const iconWrapperStyle: React.CSSProperties = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  width: 36,
+  height: 36,
+  background: 'var(--cp-c-bg-icon)',
+}
+
+/**
+ * Renders a table of technology icons with tag, label, and identifier columns.
+ * Used in generated icon reference docs.
+ *
+ * @param props - Props with an array of tech icon entries to render
+ * @returns React element with an icon reference table
+ */
+export function TechIconTable({ entries }: TechIconTableProps): React.ReactElement {
+  return (
+    <table style={tableStyle}>
+      <thead>
+        <tr>
+          <th style={iconCellStyle} />
+          <th>Tag</th>
+          <th>Label</th>
+          <th>Identifier</th>
+        </tr>
+      </thead>
+      <tbody>
+        {entries.map((entry) => (
+          <tr key={entry.tag}>
+            <td style={iconCellStyle}>
+              <div style={iconWrapperStyle}>
+                <Icon icon={entry.icon} width={20} height={20} />
+              </div>
+            </td>
+            <td>
+              <code>{entry.tag}</code>
+            </td>
+            <td>{entry.label}</td>
+            <td>
+              <code>{entry.icon}</code>
+            </td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  )
+}

package/src/theme/components/shared/tech-tag.stories.tsx

@@ -0,0 +1,40 @@
+import type { Story } from '@ladle/react'
+
+import { TechTag } from './tech-tag.tsx'
+
+const meta = {
+  title: 'Icons / Tech Tag',
+}
+
+export default meta
+
+/**
+ * Default — resolves `typescript` against the TECH_ICONS map and
+ * renders the icon + label pair.
+ *
+ * @returns Single tech tag
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Default: Story = () => <TechTag name="typescript" />
+
+/**
+ * Several common language tags laid out inline.
+ *
+ * @returns Inline list of tags
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Languages: Story = () => (
+  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
+    {['typescript', 'javascript', 'python', 'rust', 'go', 'java', 'ruby', 'php'].map((n) => (
+      <TechTag key={n} name={n} />
+    ))}
+  </div>
+)
+
+/**
+ * Unknown tag — falls back to the raw name without an icon.
+ *
+ * @returns Tag without an icon
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Fallback: Story = () => <TechTag name="not-a-real-tech-name" />