@ciderpress/ui 1.0.0-rc.1

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

@@ -0,0 +1,100 @@
+import type { Story } from '@ladle/react'
+
+import { Field, FieldGroup } from './field.tsx'
+
+const meta = {
+  title: 'Forms / Field',
+}
+
+export default meta
+
+/**
+ * Required field with a type pill.
+ *
+ * @returns Required field
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Required: Story = () => (
+  <Field name="title" type="string" required>
+    The site title displayed in the navbar and document `&lt;title&gt;`.
+  </Field>
+)
+
+/**
+ * Optional field — default badge state.
+ *
+ * @returns Optional field
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Optional: Story = () => (
+  <Field name="base" type="string">
+    Base path for the deployed site, e.g. `'/docs/'`.
+  </Field>
+)
+
+/**
+ * Deprecated field — name is struck through, badge swaps for
+ * `deprecated`.
+ *
+ * @returns Deprecated field
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Deprecated: Story = () => (
+  <Field name="legacyTheme" type="string" deprecated>
+    Use `theme` instead. Will be removed in 2.0.
+  </Field>
+)
+
+/**
+ * Field with a default value rendered below the header row.
+ *
+ * @returns Field with default value
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const WithDefault: Story = () => (
+  <Field
+    name="theme"
+    type="'mulled' | 'honeycrisp' | 'grannysmith' | 'amber' | 'midnight' | 'arcade'"
+    defaultValue="'mulled'"
+  >
+    Built-in theme palette applied to the site.
+  </Field>
+)
+
+/**
+ * Multiple fields wrapped in a static group (titled section with
+ * bottom border).
+ *
+ * @returns Field group with three fields
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Grouped: Story = () => (
+  <FieldGroup title="Site config">
+    <Field name="title" type="string" required>
+      The site title.
+    </Field>
+    <Field name="description" type="string">
+      Meta description used for SEO and link previews.
+    </Field>
+    <Field name="base" type="string" defaultValue="'/'">
+      Base path for the deployed site.
+    </Field>
+  </FieldGroup>
+)
+
+/**
+ * Expandable group — collapsible panel with chevron trigger.
+ *
+ * @returns Expandable field group
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Expandable: Story = () => (
+  <FieldGroup title="Advanced options" expandable>
+    <Field name="markdown.toc.level" type="number[]" defaultValue="[2, 3]">
+      Heading levels included in the table of contents.
+    </Field>
+    <Field name="search" type="'local' | false" defaultValue="'local'">
+      Search provider. Set to `false` to disable the in-page search panel.
+    </Field>
+  </FieldGroup>
+)

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

@@ -0,0 +1,186 @@
+import { match, P } from 'massaman/match'
+import type React from 'react'
+import { useState } from 'react'
+
+import { Icon } from './icon'
+
+export interface FieldProps {
+  /**
+   * Field name, rendered in monospace bold.
+   */
+  readonly name: string
+  /**
+   * Type annotation shown as a pill badge (e.g. "string", "User[]").
+   */
+  readonly type?: string
+  /**
+   * When true, shows a "required" badge. When false or omitted, shows "optional".
+   * Ignored when `deprecated` is true.
+   */
+  readonly required?: boolean
+  /**
+   * When true, shows a "deprecated" badge and strikes through the name.
+   * Overrides the required/optional badge.
+   */
+  readonly deprecated?: boolean
+  /**
+   * Default value displayed below the header row.
+   */
+  readonly defaultValue?: string
+  /**
+   * Description text and optional nested FieldGroup.
+   */
+  readonly children: React.ReactNode
+}
+
+/**
+ * Individual field documentation block displaying a parameter name,
+ * type badge, required/optional/deprecated badges, default value,
+ * and description body.
+ *
+ * @param props - Field configuration and description children
+ * @returns React element for a single documented field
+ */
+export function Field({
+  name,
+  type,
+  required,
+  deprecated,
+  defaultValue,
+  children,
+}: FieldProps): React.ReactElement {
+  const nameClass = match(deprecated)
+    .with(true, () => 'cp-field__name cp-field__name--deprecated')
+    .otherwise(() => 'cp-field__name')
+
+  const typeEl = match(type)
+    .with(P.nonNullable, (t) => <span className="cp-field__type">{t}</span>)
+    .otherwise(() => null)
+
+  const badgeEl = match(deprecated)
+    .with(true, () => (
+      <span className="cp-field__badge cp-field__badge--deprecated">deprecated</span>
+    ))
+    .otherwise(() =>
+      match(required)
+        .with(true, () => (
+          <span className="cp-field__badge cp-field__badge--required">required</span>
+        ))
+        .otherwise(() => (
+          <span className="cp-field__badge cp-field__badge--optional">optional</span>
+        ))
+    )
+
+  const defaultEl = match(defaultValue)
+    .with(P.nonNullable, (v) => (
+      <div className="cp-field__default">
+        Default: <code>{v}</code>
+      </div>
+    ))
+    .otherwise(() => null)
+
+  return (
+    <div className="cp-field">
+      <div className="cp-field__header">
+        <span className={nameClass}>{name}</span>
+        {typeEl}
+        {badgeEl}
+      </div>
+      {defaultEl}
+      <div className="cp-field__body">{children}</div>
+    </div>
+  )
+}
+
+export interface FieldGroupProps {
+  /**
+   * Group label displayed as a header or trigger text.
+   */
+  readonly title: string
+  /**
+   * When true, renders as a collapsible section with a toggle trigger.
+   */
+  readonly expandable?: boolean
+  /**
+   * Initial expanded state when `expandable` is true.
+   */
+  readonly defaultOpen?: boolean
+  /**
+   * Field children to display within the group.
+   */
+  readonly children: React.ReactNode
+}
+
+/**
+ * Dual-purpose grouping wrapper for Field components.
+ *
+ * In top-level mode (default), renders a titled section with a bottom border.
+ * In expandable mode, renders a collapsible panel with a click-to-toggle
+ * trigger and chevron icon.
+ *
+ * @param props - Group configuration with title and optional expand behavior
+ * @returns React element wrapping grouped fields
+ */
+export function FieldGroup({
+  title,
+  expandable = false,
+  defaultOpen = false,
+  children,
+}: FieldGroupProps): React.ReactElement {
+  return match(expandable)
+    .with(true, () => (
+      <ExpandableFieldGroup title={title} defaultOpen={defaultOpen}>
+        {children}
+      </ExpandableFieldGroup>
+    ))
+    .otherwise(() => (
+      <div className="cp-field-group">
+        <div className="cp-field-group__title">{title}</div>
+        {children}
+      </div>
+    ))
+}
+
+const DATA_OPEN = { 'data-open': '' } as const
+const DATA_CLOSED = {} as const
+
+interface ExpandableFieldGroupInternalProps {
+  readonly title: string
+  readonly defaultOpen: boolean
+  readonly children: React.ReactNode
+}
+
+/**
+ * Internal expandable variant of FieldGroup with toggle state.
+ *
+ * @private
+ * @param props - Title, default open state, and children
+ * @returns React element with collapsible panel
+ */
+function ExpandableFieldGroup({
+  title,
+  defaultOpen,
+  children,
+}: ExpandableFieldGroupInternalProps): React.ReactElement {
+  const [open, setOpen] = useState(defaultOpen)
+
+  const dataAttrs = match(open)
+    .with(true, () => DATA_OPEN)
+    .otherwise(() => DATA_CLOSED)
+
+  return (
+    <div className="cp-field-group--expandable" {...dataAttrs}>
+      <button
+        type="button"
+        className="cp-field-group__trigger"
+        onClick={() => setOpen((prev) => !prev)}
+      >
+        <span className="cp-field-group__chevron">
+          <Icon icon="pixelarticons:chevron-right" />
+        </span>
+        {title}
+      </button>
+      <div className="cp-field-group__panel">{children}</div>
+    </div>
+  )
+}

package/dist/theme/components/shared/frame.css

@@ -0,0 +1,39 @@
+/**
+ * Frame — media wrapper with caption and hint.
+ */
+
+.cp-frame {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  margin: 16px 0;
+  padding: 0;
+}
+
+.cp-frame__hint {
+  display: block;
+  font-size: 12px;
+  color: var(--cp-c-text-3);
+  text-align: center;
+}
+
+.cp-frame__content {
+  border: 1px solid var(--cp-c-border);
+  border-radius: var(--rp-radius-large);
+  overflow: hidden;
+  background: var(--cp-c-bg-soft);
+}
+
+.cp-frame__content img,
+.cp-frame__content video {
+  display: block;
+  width: 100%;
+  height: auto;
+}
+
+.cp-frame__caption {
+  font-size: 13px;
+  color: var(--cp-c-text-2);
+  text-align: center;
+  line-height: 1.5;
+}

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

@@ -0,0 +1,49 @@
+import type { Story } from '@ladle/react'
+
+import { Frame } from './frame.tsx'
+
+const meta = {
+  title: 'Layout / Frame',
+}
+
+export default meta
+
+const IMAGE_URL = 'https://picsum.photos/seed/ciderpress-frame/1200/600'
+
+/**
+ * Bare frame — image wrapped in a `<figure>` with the standard border
+ * treatment.
+ *
+ * @returns Frame around an image
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Default: Story = () => (
+  <Frame>
+    <img src={IMAGE_URL} alt="Sample" />
+  </Frame>
+)
+
+/**
+ * Frame with a caption rendered below the content.
+ *
+ * @returns Frame with caption
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const WithCaption: Story = () => (
+  <Frame caption="Figure 1. Default Ciderpress landing page.">
+    <img src={IMAGE_URL} alt="Sample" />
+  </Frame>
+)
+
+/**
+ * Frame with a hint rendered above the content — useful for callouts
+ * like "Source: …" or "Live preview".
+ *
+ * @returns Frame with hint and caption
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const WithHint: Story = () => (
+  <Frame hint="Live preview" caption="Theme: mulled · variant: dark">
+    <img src={IMAGE_URL} alt="Sample" />
+  </Frame>
+)

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

@@ -0,0 +1,76 @@
+import { match, P } from 'massaman/match'
+import React from 'react'
+
+export interface FrameProps {
+  /**
+   * Caption text displayed below the content.
+   * Rendered as-is (MDX children handle markdown processing).
+   */
+  readonly caption?: string
+  /**
+   * Hint text displayed above the content.
+   */
+  readonly hint?: string
+  /**
+   * Image, video, or other visual content to frame.
+   */
+  readonly children: React.ReactNode
+}
+
+/**
+ * Media wrapper that adds consistent border styling, optional caption,
+ * and hint text to images and videos.
+ *
+ * When a video child has `autoPlay`, the Frame automatically injects
+ * `playsInline`, `loop`, and `muted` attributes.
+ *
+ * @param props - Frame configuration with optional caption and hint
+ * @returns React element with semantic figure/figcaption markup
+ */
+export function Frame({ caption, hint, children }: FrameProps): React.ReactElement {
+  const hintEl = match(hint)
+    .with(P.nonNullable, (h) => <span className="cp-frame__hint">{h}</span>)
+    .otherwise(() => null)
+
+  const captionEl = match(caption)
+    .with(P.nonNullable, (c) => <figcaption className="cp-frame__caption">{c}</figcaption>)
+    .otherwise(() => null)
+
+  const enhancedChildren = React.Children.map(children, enhanceVideoChild)
+
+  return (
+    <figure className="cp-frame">
+      {hintEl}
+      <div className="cp-frame__content">{enhancedChildren}</div>
+      {captionEl}
+    </figure>
+  )
+}
+
+/**
+ * Clone video elements with autoPlay to inject playsInline, loop, and muted.
+ *
+ * @private
+ * @param child - React child element
+ * @returns Original child or enhanced video clone
+ */
+function enhanceVideoChild(child: React.ReactNode): React.ReactNode {
+  if (!React.isValidElement(child)) {
+    return child
+  }
+
+  const props = child.props as Record<string, unknown>
+
+  if (child.type === 'video' && props['autoPlay'] === true) {
+    return React.cloneElement(
+      child as React.ReactElement<React.VideoHTMLAttributes<HTMLVideoElement>>,
+      {
+        playsInline: true,
+        loop: true,
+        muted: true,
+      }
+    )
+  }
+
+  return child
+}

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

@@ -0,0 +1,90 @@
+import type { Story } from '@ladle/react'
+
+import { Icon } from './icon'
+
+const meta = {
+  title: 'Icons / Icon',
+}
+
+export default meta
+
+/**
+ * Default — Iconify icon at default size (inherits text color via
+ * `currentColor`).
+ *
+ * @returns Single icon
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Default: Story = () => (
+  <div style={{ fontSize: 32 }}>
+    <Icon icon="pixelarticons:sparkles" />
+  </div>
+)
+
+/**
+ * One icon per registered Iconify library so reviewers can verify each
+ * collection loaded.
+ *
+ * @returns Grid of icons across libraries
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Libraries: Story = () => {
+  const samples = [
+    { id: 'pixelarticons:flag', label: 'pixelarticons' },
+    { id: 'devicon:typescript', label: 'devicon' },
+    { id: 'mdi:database', label: 'mdi' },
+    { id: 'simple-icons:vercel', label: 'simple-icons' },
+    { id: 'skill-icons:rust', label: 'skill-icons' },
+    { id: 'catppuccin:typescript', label: 'catppuccin' },
+    { id: 'logos:github-icon', label: 'logos' },
+    { id: 'vscode-icons:file-type-typescript', label: 'vscode-icons' },
+    { id: 'material-icon-theme:typescript', label: 'material-icon-theme' },
+  ]
+  return (
+    <div
+      style={{
+        display: 'grid',
+        gridTemplateColumns: 'repeat(auto-fit, minmax(160px, 1fr))',
+        gap: 12,
+      }}
+    >
+      {samples.map((s) => (
+        <div
+          key={s.id}
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            gap: 6,
+            padding: 12,
+            border: '1px solid var(--cp-c-border)',
+            borderRadius: 8,
+            background: 'var(--cp-c-bg-soft)',
+            fontFamily: 'ui-monospace, monospace',
+            fontSize: 11,
+          }}
+        >
+          <div style={{ fontSize: 28 }}>
+            <Icon icon={s.id} />
+          </div>
+          <code style={{ color: 'var(--cp-c-text-3)' }}>{s.label}</code>
+          <code style={{ color: 'var(--cp-c-text-2)' }}>{s.id}</code>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+/**
+ * Explicit size — width/height props bypass the inherited font-size.
+ *
+ * @returns Three icons at 16/32/64px
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Sizes: Story = () => (
+  <div style={{ display: 'flex', alignItems: 'center', gap: 24 }}>
+    <Icon icon="pixelarticons:sparkles" width={16} height={16} />
+    <Icon icon="pixelarticons:sparkles" width={32} height={32} />
+    <Icon icon="pixelarticons:sparkles" width={64} height={64} />
+  </div>
+)

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

@@ -0,0 +1,41 @@
+import catppuccin from '@iconify-json/catppuccin/icons.json' with { type: 'json' }
+import devicon from '@iconify-json/devicon/icons.json' with { type: 'json' }
+import logos from '@iconify-json/logos/icons.json' with { type: 'json' }
+import materialIconTheme from '@iconify-json/material-icon-theme/icons.json' with { type: 'json' }
+import mdi from '@iconify-json/mdi/icons.json' with { type: 'json' }
+import pixelarticons from '@iconify-json/pixelarticons/icons.json' with { type: 'json' }
+import simpleIcons from '@iconify-json/simple-icons/icons.json' with { type: 'json' }
+import skillIcons from '@iconify-json/skill-icons/icons.json' with { type: 'json' }
+import vscodeIcons from '@iconify-json/vscode-icons/icons.json' with { type: 'json' }
+import { addCollection, Icon } from '@iconify/react'
+
+// Register all icon collections for offline Iconify resolution.
+// `addCollection` is called purely for its side effect of mutating
+// Iconify's internal registry. Holding the return values in a
+// throwaway `const` keeps the call list a single expression statement
+// rather than nine misleading named exports.
+// oxlint-disable-next-line no-unused-vars
+const _iconCollectionsLoaded = [
+  addCollection(cast(pixelarticons)),
+  addCollection(cast(devicon)),
+  addCollection(cast(mdi)),
+  addCollection(cast(simpleIcons)),
+  addCollection(cast(skillIcons)),
+  addCollection(cast(catppuccin)),
+  addCollection(cast(logos)),
+  addCollection(cast(vscodeIcons)),
+  addCollection(cast(materialIconTheme)),
+] as const
+
+export { Icon }
+
+/**
+ * Cast an icon JSON import to the type expected by `addCollection`.
+ *
+ * @private
+ * @param v - Raw icon JSON import
+ * @returns Value cast to the addCollection parameter type
+ */
+function cast(v: unknown): Parameters<typeof addCollection>[0] {
+  return v as Parameters<typeof addCollection>[0]
+}