@ciderpress/ui 1.0.0-rc.1

package/dist/theme/components/shared/tech-tag.tsx

@@ -0,0 +1,31 @@
+import { match, P } from 'massaman/match'
+import type React from 'react'
+
+import { TECH_ICONS } from '../../icons/index.ts'
+import { Icon } from './icon'
+
+export interface TechTagProps {
+  readonly name: string
+}
+
+/**
+ * Technology tag — resolves a tech name to icon + label using the tech map.
+ * Falls back to raw name string if not in map.
+ *
+ * @param props - Props with the technology name to resolve
+ * @returns React element with icon and label, or the raw name as fallback
+ */
+export function TechTag({ name }: TechTagProps): React.ReactElement {
+  const entry = (TECH_ICONS as Record<string, { readonly icon: string; readonly label: string }>)[
+    name
+  ]
+
+  return match(entry)
+    .with(P.nonNullable, (e) => (
+      <span className="cp-tag">
+        <Icon icon={e.icon} />
+        {` ${e.label}`}
+      </span>
+    ))
+    .otherwise(() => <span className="cp-tag">{name}</span>)
+}

package/dist/theme/components/shared/theme-color-palette.css

@@ -0,0 +1,80 @@
+/**
+ * ThemeColorPalette — grouped swatch grid rendered inside an Accordion.
+ */
+
+.cp-theme-color-palette {
+  display: flex;
+  flex-direction: column;
+  gap: var(--cp-s-16);
+  padding-top: var(--cp-s-4);
+}
+
+.cp-theme-color-palette__variants {
+  display: inline-flex;
+  align-self: flex-start;
+  padding: var(--cp-s-4);
+  border: 1px solid var(--cp-c-border);
+  border-radius: var(--rp-radius);
+  background: var(--cp-c-bg);
+  gap: var(--cp-s-4);
+}
+
+.cp-theme-color-palette__variant {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--cp-s-6);
+  padding: var(--cp-s-4) var(--cp-s-10);
+  border: none;
+  border-radius: var(--rp-radius);
+  background: transparent;
+  color: var(--cp-c-text-2);
+  font-family: var(--cp-font-family-base);
+  font-size: var(--cp-fs-color-name);
+  font-weight: 600;
+  cursor: pointer;
+  transition:
+    background var(--cp-duration-base),
+    color var(--cp-duration-base);
+}
+
+.cp-theme-color-palette__variant:hover {
+  color: var(--cp-c-text-1);
+  background: var(--cp-c-bg-soft);
+}
+
+.cp-theme-color-palette__variant:focus-visible {
+  outline: var(--cp-size-focus-ring) solid var(--cp-c-brand-1);
+  outline-offset: var(--cp-size-focus-ring-offset);
+}
+
+.cp-theme-color-palette__variant[data-active='true'] {
+  background: var(--cp-c-brand-soft);
+  color: var(--cp-c-brand-1);
+}
+
+.cp-theme-color-palette__variant svg {
+  display: block;
+  width: 14px;
+  height: 14px;
+}
+
+.cp-theme-color-palette__group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--cp-s-8);
+}
+
+.cp-theme-color-palette__heading {
+  margin: 0;
+  font-size: var(--cp-fs-color-name);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--cp-c-text-3);
+}
+
+.cp-theme-color-palette__grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+  gap: var(--cp-s-8);
+}

package/dist/theme/components/shared/theme-color-palette.stories.tsx

@@ -0,0 +1,52 @@
+import type { Story } from '@ladle/react'
+
+import { ThemeColorPalette } from './theme-color-palette.tsx'
+
+const meta = {
+  title: 'Data Display / Theme Color Palette',
+}
+
+export default meta
+
+/**
+ * Single palette — collapsed by default.
+ *
+ * @returns Mulled dark palette inside the accordion
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Default: Story = () => <ThemeColorPalette theme="mulled" />
+
+/**
+ * Palette pinned open on mount.
+ *
+ * @returns Honeycrisp dark palette, expanded
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const InitiallyOpen: Story = () => <ThemeColorPalette theme="honeycrisp" defaultOpen />
+
+/**
+ * Explicit variant — light token tree for a multi-variant theme.
+ *
+ * @returns Honeycrisp light palette
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const LightVariant: Story = () => (
+  <ThemeColorPalette theme="honeycrisp" variant="light" defaultOpen />
+)
+
+/**
+ * All six built-in themes stacked, default variants, all expanded.
+ *
+ * @returns Stack of palette accordions
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const AllBuiltIns: Story = () => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+    <ThemeColorPalette theme="mulled" defaultOpen />
+    <ThemeColorPalette theme="honeycrisp" />
+    <ThemeColorPalette theme="grannysmith" />
+    <ThemeColorPalette theme="amber" />
+    <ThemeColorPalette theme="midnight" />
+    <ThemeColorPalette theme="arcade" />
+  </div>
+)

package/dist/theme/components/shared/theme-color-palette.tsx

@@ -0,0 +1,275 @@
+import {
+  BUILT_IN_THEMES,
+  isBuiltInTheme,
+  resolveDefaultVariant,
+  resolveThemeVariants,
+} from '@ciderpress/theme'
+import type { BuiltInThemeName, ThemeVariant } from '@ciderpress/theme'
+import { match, P } from 'massaman/match'
+import { useState } from 'react'
+import type React from 'react'
+
+import { Accordion } from './accordion.tsx'
+import { Color } from './color.tsx'
+import { Icon } from './icon.tsx'
+
+export interface ThemeColorPaletteProps {
+  /**
+   * Built-in theme to render. Accepts any name in `BUILT_IN_THEMES`.
+   */
+  readonly theme: BuiltInThemeName
+  /**
+   * Initial variant to render. Defaults to the theme's `defaultVariant`.
+   * If the requested variant is not declared by the theme, falls back to
+   * the default.
+   */
+  readonly variant?: ThemeVariant
+  /**
+   * Title shown on the accordion trigger. Defaults to the theme name.
+   */
+  readonly title?: string
+  /**
+   * Description shown below the trigger title.
+   */
+  readonly description?: string
+  /**
+   * Whether the palette accordion starts expanded.
+   */
+  readonly defaultOpen?: boolean
+}
+
+interface ColorEntry {
+  readonly name: string
+  readonly value: string
+}
+
+interface ColorGroup {
+  readonly heading: string
+  readonly colors: readonly ColorEntry[]
+}
+
+const VARIANT_LABEL: Readonly<Record<ThemeVariant, string>> = Object.freeze({
+  dark: 'Dark',
+  light: 'Light',
+})
+
+const VARIANT_ICON: Readonly<Record<ThemeVariant, string>> = Object.freeze({
+  dark: 'pixelarticons:moon',
+  light: 'pixelarticons:sun',
+})
+
+/**
+ * Collapsible palette display for a built-in theme. Renders every brand,
+ * surface, text, border, and semantic color token as a copy-on-click
+ * {@link Color} swatch, grouped under a single {@link Accordion}. When the
+ * theme declares both `dark` and `light` variants, a sun/moon segmented
+ * control inside the panel switches between them in place.
+ *
+ * @param props - Theme palette configuration
+ * @returns React element with the collapsible palette
+ */
+export function ThemeColorPalette({
+  theme,
+  variant,
+  title,
+  description,
+  defaultOpen = false,
+}: ThemeColorPaletteProps): React.ReactElement | null {
+  const themeEntry = match(isBuiltInTheme(theme))
+    .with(true, () => BUILT_IN_THEMES[theme])
+    .otherwise(() => null)
+  if (themeEntry === null) {
+    return null
+  }
+
+  const variants = resolveThemeVariants(theme)
+  const initialVariant = resolveVariant(theme, variant)
+  const [activeVariant, setActiveVariant] = useState<ThemeVariant>(initialVariant)
+
+  const tokens = themeEntry.variants[activeVariant]
+  if (tokens === undefined) {
+    return null
+  }
+
+  const groups = buildGroups(tokens)
+  const headingText = title ?? theme
+  const subtitle =
+    description ?? `Brand, surface, text, border, and semantic tokens for the ${theme} theme.`
+
+  const showToggle = variants.length > 1
+
+  return (
+    <Accordion
+      id={`theme-palette-${theme}`}
+      title={headingText}
+      description={subtitle}
+      icon="pixelarticons:eyedropper"
+      defaultOpen={defaultOpen}
+    >
+      <div className="cp-theme-color-palette">
+        {match(showToggle)
+          .with(true, () => (
+            <div
+              className="cp-theme-color-palette__variants"
+              role="radiogroup"
+              aria-label="Variant"
+            >
+              {variants.map((v) => {
+                const selected = v === activeVariant
+                return (
+                  <button
+                    key={v}
+                    type="button"
+                    role="radio"
+                    aria-checked={selected}
+                    className="cp-theme-color-palette__variant"
+                    data-active={selected}
+                    onClick={() => setActiveVariant(v)}
+                  >
+                    <Icon icon={VARIANT_ICON[v]} />
+                    <span>{VARIANT_LABEL[v]}</span>
+                  </button>
+                )
+              })}
+            </div>
+          ))
+          .otherwise(() => null)}
+        {groups.map((group) => (
+          <section key={group.heading} className="cp-theme-color-palette__group">
+            <h4 className="cp-theme-color-palette__heading">{group.heading}</h4>
+            <div className="cp-theme-color-palette__grid">
+              {group.colors.map((c) => (
+                <Color key={c.name} value={c.value} name={c.name} />
+              ))}
+            </div>
+          </section>
+        ))}
+      </div>
+    </Accordion>
+  )
+}
+
+/**
+ * Resolve a variant for the requested theme — falls back to the theme's
+ * default when the requested variant is unavailable.
+ *
+ * @private
+ * @param theme - Built-in theme identifier
+ * @param requested - Variant supplied by the caller (optional)
+ * @returns Variant guaranteed to exist on the theme
+ */
+function resolveVariant(
+  theme: BuiltInThemeName,
+  requested: ThemeVariant | undefined
+): ThemeVariant {
+  const fallback = resolveDefaultVariant(theme)
+  return match(requested)
+    .with(P.nullish, () => fallback)
+    .with(P.string, (v) => {
+      const exists = BUILT_IN_THEMES[theme].variants[v] !== undefined
+      return match(exists)
+        .with(true, () => v)
+        .otherwise(() => fallback)
+    })
+    .exhaustive()
+}
+
+/**
+ * Project a parsed token tree into the grouped layout rendered by the
+ * palette accordion.
+ *
+ * @private
+ * @param tokens - Token tree from `BUILT_IN_THEMES[theme].variants[variant]`
+ * @returns Ordered list of groups suitable for the swatch grid
+ */
+function buildGroups(tokens: {
+  readonly colors: {
+    readonly brand: {
+      readonly primary: string
+      readonly hover: string
+      readonly active: string
+      readonly soft: string
+      readonly fg: string
+      readonly light: string
+      readonly lighter: string
+    }
+    readonly surface: {
+      readonly bg: string
+      readonly bgAlt: string
+      readonly bgElv: string
+      readonly bgSoft: string
+      readonly homeBg: string
+      readonly gutter: string
+      readonly codeBlockBg: string
+    }
+    readonly text: {
+      readonly text1: string
+      readonly text2: string
+      readonly text3: string
+    }
+    readonly border: {
+      readonly border: string
+      readonly divider: string
+    }
+    readonly semantic: {
+      readonly success: string
+      readonly error: string
+      readonly warn: string
+      readonly info: string
+      readonly muted: string
+    }
+  }
+}): readonly ColorGroup[] {
+  const { brand, surface, text, border, semantic } = tokens.colors
+  return [
+    {
+      heading: 'Brand',
+      colors: [
+        { name: 'primary', value: brand.primary },
+        { name: 'hover', value: brand.hover },
+        { name: 'active', value: brand.active },
+        { name: 'soft', value: brand.soft },
+        { name: 'fg (on-brand)', value: brand.fg },
+        { name: 'light', value: brand.light },
+        { name: 'lighter', value: brand.lighter },
+      ],
+    },
+    {
+      heading: 'Surface',
+      colors: [
+        { name: 'bg', value: surface.bg },
+        { name: 'bgAlt', value: surface.bgAlt },
+        { name: 'bgElv', value: surface.bgElv },
+        { name: 'bgSoft', value: surface.bgSoft },
+        { name: 'homeBg', value: surface.homeBg },
+        { name: 'gutter', value: surface.gutter },
+        { name: 'codeBlockBg', value: surface.codeBlockBg },
+      ],
+    },
+    {
+      heading: 'Text',
+      colors: [
+        { name: 'text1', value: text.text1 },
+        { name: 'text2', value: text.text2 },
+        { name: 'text3', value: text.text3 },
+      ],
+    },
+    {
+      heading: 'Border',
+      colors: [
+        { name: 'border', value: border.border },
+        { name: 'divider', value: border.divider },
+      ],
+    },
+    {
+      heading: 'Semantic',
+      colors: [
+        { name: 'success', value: semantic.success },
+        { name: 'error', value: semantic.error },
+        { name: 'warn', value: semantic.warn },
+        { name: 'info', value: semantic.info },
+        { name: 'muted', value: semantic.muted },
+      ],
+    },
+  ]
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Tooltip — hover-to-reveal definitions.
+ */
+
+.cp-tooltip__trigger {
+  display: inline;
+  padding: 0;
+  border: none;
+  background: none;
+  color: inherit;
+  font: inherit;
+  cursor: help;
+  text-decoration: underline;
+  text-decoration-style: dotted;
+  text-decoration-color: var(--cp-c-text-3);
+  text-underline-offset: var(--cp-s-3);
+}
+
+.cp-tooltip__trigger:focus-visible {
+  outline: var(--cp-size-focus-ring) solid var(--cp-c-brand-1);
+  outline-offset: var(--cp-size-focus-ring-offset);
+  border-radius: var(--cp-radius-xs);
+}
+
+.cp-tooltip__overlay {
+  max-width: var(--cp-size-tooltip-max);
+  padding: var(--cp-s-10) var(--cp-s-14);
+  background: var(--cp-c-bg-elv);
+  border: 1px solid var(--cp-c-border);
+  border-radius: var(--rp-radius-large);
+  box-shadow: var(--cp-shadow-tooltip);
+  font-size: var(--cp-fs-tooltip);
+  line-height: var(--cp-lh-base);
+  color: var(--cp-c-text-1);
+  z-index: var(--cp-z-tooltip);
+}
+
+.cp-tooltip__arrow svg {
+  display: block;
+}
+
+.cp-tooltip__body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--cp-s-4);
+}
+
+.cp-tooltip__headline {
+  font-size: var(--cp-fs-tooltip-headline);
+  font-weight: 600;
+  color: var(--cp-c-text-1);
+}
+
+.cp-tooltip__tip {
+  color: var(--cp-c-text-2);
+}
+
+.cp-tooltip__cta {
+  display: inline-block;
+  margin-top: var(--cp-s-4);
+  font-size: var(--cp-fs-tooltip-cta);
+  font-weight: 500;
+  color: var(--cp-c-brand-1);
+  text-decoration: none;
+}
+
+.cp-tooltip__cta:hover {
+  text-decoration: underline;
+}

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

@@ -0,0 +1,72 @@
+import type { Story } from '@ladle/react'
+
+import { Tooltip } from './tooltip.tsx'
+
+const meta = {
+  title: 'Disclosure / Tooltip',
+}
+
+export default meta
+
+/**
+ * Bare tooltip — hover the trigger to reveal a tip with no headline
+ * or call to action.
+ *
+ * @returns Sentence with an inline tooltip trigger
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const Default: Story = () => (
+  <p style={{ lineHeight: 2 }}>
+    Hover{' '}
+    <Tooltip tip="A small package of design tokens applied as CSS custom properties to <html>.">
+      <span style={{ borderBottom: '1px dashed var(--cp-c-brand-1)', cursor: 'help' }}>
+        the theme cascade
+      </span>
+    </Tooltip>{' '}
+    to see the explanation pop in.
+  </p>
+)
+
+/**
+ * Tooltip with a bold headline above the tip.
+ *
+ * @returns Tooltip with headline + tip
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const WithHeadline: Story = () => (
+  <p style={{ lineHeight: 2 }}>
+    Read about the{' '}
+    <Tooltip
+      headline="Sync engine"
+      tip="Watches your source markdown and mirrors structure into Rspress's expected layout."
+    >
+      <span style={{ borderBottom: '1px dashed var(--cp-c-brand-1)', cursor: 'help' }}>
+        sync engine
+      </span>
+    </Tooltip>{' '}
+    in the architecture docs.
+  </p>
+)
+
+/**
+ * Tooltip with a call-to-action link in the overlay — routed through
+ * the stubbed Rspress `<Link>` so external/internal handling matches
+ * production.
+ *
+ * @returns Tooltip with headline, tip, and CTA
+ */
+// oxlint-disable-next-line func-style -- Ladle stories use `export const`
+export const WithCta: Story = () => (
+  <p style={{ lineHeight: 2 }}>
+    Try the{' '}
+    <Tooltip
+      headline="Mulled palette"
+      tip="The default Ciderpress palette — deep red brand on near-black surfaces."
+      cta="See the full palette →"
+      href="/guides/themes/mulled"
+    >
+      <span style={{ borderBottom: '1px dashed var(--cp-c-brand-1)', cursor: 'help' }}>Mulled</span>
+    </Tooltip>{' '}
+    palette.
+  </p>
+)

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

@@ -0,0 +1,77 @@
+import { match, P } from 'massaman/match'
+import type React from 'react'
+import { Button, OverlayArrow, Tooltip as AriaTooltip, TooltipTrigger } from 'react-aria-components'
+
+import { RouteLink } from '../../lib/route-link.tsx'
+import { safeUrl } from '../../lib/safe-url.ts'
+
+export interface TooltipProps {
+  /**
+   * Main tooltip text displayed on hover.
+   */
+  readonly tip: string
+  /**
+   * Optional bold headline displayed above the tip.
+   */
+  readonly headline?: string
+  /**
+   * Optional call-to-action link label.
+   */
+  readonly cta?: string
+  /**
+   * URL for the call-to-action link. Required when `cta` is provided.
+   */
+  readonly href?: string
+  /**
+   * Inline content that triggers the tooltip on hover.
+   */
+  readonly children: React.ReactNode
+}
+
+/**
+ * Hover-to-reveal tooltip for definitions, glossary terms,
+ * and inline contextual help.
+ *
+ * Built on react-aria-components for full accessibility,
+ * keyboard support, and automatic repositioning.
+ *
+ * @param props - Tooltip configuration with tip text and optional CTA
+ * @returns React element with tooltip trigger and overlay
+ */
+export function Tooltip({ tip, headline, cta, href, children }: TooltipProps): React.ReactElement {
+  const headlineEl = match(headline)
+    .with(P.nonNullable, (h) => <strong className="cp-tooltip__headline">{h}</strong>)
+    .otherwise(() => null)
+
+  const ctaEl = match({ cta, href })
+    .with({ cta: P.nonNullable, href: P.nonNullable }, ({ cta: label, href: url }) => {
+      const safeHref = safeUrl(url)
+      if (safeHref === null) {
+        return null
+      }
+      return (
+        <RouteLink className="cp-tooltip__cta" href={safeHref}>
+          {label}
+        </RouteLink>
+      )
+    })
+    .otherwise(() => null)
+
+  return (
+    <TooltipTrigger delay={300}>
+      <Button className="cp-tooltip__trigger">{children}</Button>
+      <AriaTooltip className="cp-tooltip__overlay" offset={8}>
+        <OverlayArrow className="cp-tooltip__arrow">
+          <svg width="12" height="6" viewBox="0 0 12 6">
+            <path d="M0 6L6 0L12 6" fill="var(--cp-c-bg-elv)" stroke="var(--cp-c-border)" />
+          </svg>
+        </OverlayArrow>
+        <div className="cp-tooltip__body">
+          {headlineEl}
+          <span className="cp-tooltip__tip">{tip}</span>
+          {ctaEl}
+        </div>
+      </AriaTooltip>
+    </TooltipTrigger>
+  )
+}