@ciderpress/ui 1.0.0-rc.1

package/dist/theme/components/workspaces/card.css

@@ -0,0 +1,151 @@
+/**
+ * Workspace grid, card layout, deploy badge, and tech tags.
+ * Base card styles (container, hover, icons) from home-card.css.
+ */
+
+/* ── Workspace section ───────────────────────────────────── */
+.cp-workspace-section {
+  max-width: 1152px;
+  margin: 0 auto;
+  padding-bottom: 64px;
+}
+
+.cp-workspace-section h2 {
+  font-size: 18px;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  margin-bottom: 4px;
+  color: var(--cp-c-text-2);
+}
+
+.cp-workspace-section__desc {
+  margin: 0 0 16px;
+  font-size: 14px;
+  color: var(--cp-c-text-3);
+  line-height: 1.5;
+}
+
+.cp-workspace-grid {
+  display: grid;
+  grid-template-columns: repeat(var(--cp-workspace-cols, 2), 1fr);
+  gap: 12px;
+  margin-bottom: 40px;
+}
+
+/* ── Workspace card layout ───────────────────────────────── */
+.cp-workspace-card {
+  display: flex;
+  flex-direction: column;
+}
+
+.cp-workspace-card__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 10px;
+}
+
+.cp-workspace-card__identity {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.cp-workspace-card__title {
+  display: flex;
+  flex-direction: column;
+  line-height: 1.2;
+}
+
+.cp-workspace-card__scope {
+  font-family: var(--cp-font-family-mono);
+  font-size: 11px;
+  color: var(--cp-c-text-3);
+}
+
+.cp-workspace-card__name {
+  font-family: var(--cp-font-family-mono);
+  font-size: 15px;
+  font-weight: 700;
+  color: var(--cp-c-text-1);
+}
+
+.cp-workspace-card__desc {
+  font-size: 13px;
+  color: var(--cp-c-text-2);
+  line-height: 1.5;
+  flex: 1;
+}
+
+/* ── Truncation ─────────────────────────────────────────── */
+.cp-workspace-card__name.cp-clamp,
+.cp-workspace-card__desc.cp-clamp {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* ── Deploy badge ────────────────────────────────────────── */
+.cp-workspace-card__badge {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 4px 6px;
+  border-radius: 6px;
+  background: var(--cp-c-bg);
+  border: 1px solid var(--cp-c-divider);
+}
+
+.cp-workspace-card__badge-logo {
+  height: 16px;
+  width: auto;
+  opacity: 0.75;
+  transition: opacity 0.2s;
+}
+
+.cp-card:hover .cp-workspace-card__badge-logo {
+  opacity: 1;
+}
+
+/* ── Tech tags ───────────────────────────────────────────── */
+.cp-workspace-card__tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-top: 10px;
+}
+
+.cp-tag {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-family: var(--cp-font-family-mono);
+  font-size: 11px;
+  padding: 2px 8px;
+  border-radius: var(--rp-radius-small);
+  background: var(--cp-c-bg);
+  color: var(--cp-c-text-3);
+  border: 1px solid var(--cp-c-divider);
+}
+
+.cp-tag svg {
+  width: 14px;
+  height: 14px;
+  flex-shrink: 0;
+}
+
+/* ── Responsive ──────────────────────────────────────────── */
+@media (max-width: 1184px) {
+  .cp-workspace-section {
+    padding-left: 16px;
+    padding-right: 16px;
+  }
+}
+
+@media (max-width: 768px) {
+  .cp-workspace-grid {
+    grid-template-columns: 1fr;
+  }
+}

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

@@ -0,0 +1,166 @@
+import { match, P } from 'massaman/match'
+import type React from 'react'
+
+import { Card } from '../shared/card'
+import { Icon } from '../shared/icon'
+import { resolveCardIcon } from '../shared/resolve-card-icon'
+import { TechTag } from '../shared/tech-tag'
+
+export interface WorkspaceCardProps {
+  /**
+   * Display name for the card header.
+   */
+  readonly title: string
+  /**
+   * Link target (e.g. "/apps/api").
+   */
+  readonly href: string
+  /**
+   * Icon config — Iconify identifier string or `{ id, color }` object.
+   */
+  readonly icon?: string | { readonly id: string; readonly color: string }
+  /**
+   * Scope prefix shown above the name (e.g. "apps/").
+   */
+  readonly scope?: string
+  /**
+   * Short description rendered below the header.
+   */
+  readonly description?: string
+  /**
+   * Technology tag names resolved via the tech map.
+   */
+  readonly tags?: readonly string[]
+  /**
+   * Deploy badge image for the card header.
+   */
+  readonly badge?: { readonly src: string; readonly alt: string }
+  /**
+   * Max lines for the title before ellipsis truncation.
+   */
+  readonly titleLines?: number
+  /**
+   * Max lines for the description before ellipsis truncation.
+   */
+  readonly descriptionLines?: number
+}
+
+/**
+ * Workspace card — renders a clickable link card with icon, name,
+ * description, tech tags, and optional deploy badge.
+ *
+ * @param props - Props with title, href, and optional icon, scope, description, tags, badge, titleLines, descriptionLines
+ * @returns React element with a workspace link card
+ */
+export function WorkspaceCard({
+  title,
+  href,
+  icon,
+  scope,
+  description,
+  tags,
+  badge,
+  titleLines,
+  descriptionLines,
+}: WorkspaceCardProps): React.ReactElement {
+  const name = title.toLowerCase()
+  const resolved = resolveCardIcon(icon)
+
+  const iconEl = match(resolved)
+    .with(P.nonNullable, (r) => <Icon icon={r.id} />)
+    .otherwise(() => null)
+
+  const iconColor = match(resolved)
+    .with(P.nonNullable, (r) => r.color)
+    .otherwise(() => 'purple')
+
+  const scopeEl = match(scope)
+    .with(
+      P.when((s): s is string => s !== undefined && s.length > 0),
+      (s) => <span className="cp-workspace-card__scope">{s}</span>
+    )
+    .otherwise(() => null)
+
+  const badgeEl = match(badge)
+    .with(P.nonNullable, (b) => (
+      <span className="cp-workspace-card__badge" title={`Deployed on ${b.alt}`}>
+        <img src={b.src} alt={b.alt} className="cp-workspace-card__badge-logo" />
+      </span>
+    ))
+    .otherwise(() => null)
+
+  const descEl = match(description)
+    .with(P.nonNullable, (d) => (
+      <span
+        className={clampClass('cp-workspace-card__desc', descriptionLines)}
+        style={clampStyle(descriptionLines)}
+      >
+        {d}
+      </span>
+    ))
+    .otherwise(() => null)
+
+  const tagsEl = match(tags)
+    .with(
+      P.when((t): t is readonly string[] => t !== undefined && t.length > 0),
+      (t) => (
+        <div className="cp-workspace-card__tags">
+          {t.map((tag) => (
+            <TechTag key={tag} name={tag} />
+          ))}
+        </div>
+      )
+    )
+    .otherwise(() => null)
+
+  return (
+    <Card href={href} className="cp-workspace-card">
+      <div className="cp-workspace-card__header">
+        <div className="cp-workspace-card__identity">
+          <span className={`cp-card__icon cp-card__icon--${iconColor}`}>{iconEl}</span>
+          <div className="cp-workspace-card__title">
+            {scopeEl}
+            <span
+              className={clampClass('cp-workspace-card__name', titleLines)}
+              style={clampStyle(titleLines)}
+            >
+              {name}
+            </span>
+          </div>
+        </div>
+        {badgeEl}
+      </div>
+      {descEl}
+      {tagsEl}
+    </Card>
+  )
+}
+
+/**
+ * Build a className string with optional `cp-clamp` suffix.
+ *
+ * @private
+ * @param base - Base CSS class name
+ * @param lines - Optional line clamp value
+ * @returns Class string with or without cp-clamp
+ */
+function clampClass(base: string, lines: number | undefined): string {
+  if (lines) {
+    return `${base} cp-clamp`
+  }
+  return base
+}
+
+/**
+ * Build an inline style object for line clamping.
+ *
+ * @private
+ * @param lines - Optional line clamp value
+ * @returns Style object with WebkitLineClamp or undefined
+ */
+function clampStyle(lines: number | undefined): React.CSSProperties | undefined {
+  if (lines) {
+    return { WebkitLineClamp: lines }
+  }
+  return undefined
+}

package/dist/theme/components/workspaces/grid.tsx

@@ -0,0 +1,62 @@
+import type React from 'react'
+
+import './card.css'
+
+export interface WorkspaceGridProps {
+  /**
+   * Section heading (e.g. "Apps", "Packages").
+   */
+  readonly heading: string
+  /**
+   * Brief description rendered below the heading.
+   */
+  readonly description: string
+  /**
+   * Number of grid columns.
+   */
+  readonly columns?: number
+  /**
+   * WorkspaceCard elements.
+   */
+  readonly children: React.ReactNode
+}
+
+/**
+ * Grid container for workspace cards — renders a heading, description,
+ * and a CSS grid wrapping its children.
+ *
+ * @param props - Props with heading, description, columns, and children workspace cards
+ * @returns React element with heading, description, and grid layout
+ */
+export function WorkspaceGrid({
+  heading,
+  description,
+  columns,
+  children,
+}: WorkspaceGridProps): React.ReactElement {
+  const style = columnsStyle(columns)
+
+  return (
+    <>
+      <h2>{heading}</h2>
+      <p className="cp-workspace-section__desc">{description}</p>
+      <div className="cp-workspace-grid" style={style}>
+        {children}
+      </div>
+    </>
+  )
+}
+
+/**
+ * Build an inline style object for the workspace grid column count.
+ *
+ * @private
+ * @param columns - Optional column count
+ * @returns Style object with CSS variable or undefined
+ */
+function columnsStyle(columns: number | undefined): React.CSSProperties | undefined {
+  if (columns !== undefined) {
+    return { '--cp-workspace-cols': String(columns) } as React.CSSProperties
+  }
+  return undefined
+}

package/dist/theme/css.d.ts

@@ -0,0 +1 @@
+declare module '*.css' {}

package/dist/theme/env.d.ts

@@ -0,0 +1,12 @@
+interface ImportMetaEnv {
+  /**
+   * Set to `true` by Rspress during the SSG-MD rendering pass
+   * (the build step that generates per-page `.md` files and `llms.txt`).
+   * Always `false` during normal browser and HTML SSR rendering.
+   */
+  readonly SSG_MD: boolean
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

package/dist/theme/hooks/use-ciderpress.ts

@@ -0,0 +1,61 @@
+import type { FooterConfig, HomeConfig, SiteConfig } from '@ciderpress/config'
+import { useSite } from '@rspress/core/runtime'
+
+export interface CiderpressSidebarItem {
+  readonly text?: string
+  readonly link?: string
+  readonly icon?: string
+  readonly items?: readonly CiderpressSidebarItem[]
+}
+
+export interface CiderpressSidebarLink {
+  readonly text: string
+  readonly link: string
+  readonly icon?: string | { readonly id: string; readonly color: string }
+  readonly style?: 'brand' | 'alt' | 'ghost'
+  readonly shape?: 'square' | 'rounded' | 'circle'
+}
+
+export interface WorkspaceCardData {
+  readonly title: string
+  readonly href: string
+  readonly icon: string | { readonly id: string; readonly color: string } | undefined
+  readonly scope: string | undefined
+  readonly description: string | undefined
+  readonly tags: readonly string[]
+  readonly badge: { readonly src: string; readonly alt: string } | undefined
+}
+
+export interface WorkspaceGroupData {
+  readonly type: 'apps' | 'packages' | 'workspaces'
+  readonly heading: string
+  readonly description: string
+  readonly cards: readonly WorkspaceCardData[]
+}
+
+interface CiderpressThemeConfig {
+  readonly sidebar: Record<string, readonly CiderpressSidebarItem[]>
+  readonly sidebarAbove: readonly CiderpressSidebarLink[] | undefined
+  readonly sidebarBelow: readonly CiderpressSidebarLink[] | undefined
+  readonly workspaces: readonly WorkspaceGroupData[] | undefined
+  readonly standaloneScopePaths: readonly string[] | undefined
+  readonly home: HomeConfig | undefined
+  readonly ciderpressFooter: FooterConfig | undefined
+  readonly site: SiteConfig | undefined
+}
+
+/**
+ * Typed wrapper around Rspress `useSite()` that exposes
+ * ciderpress-specific themeConfig fields.
+ *
+ * The double cast is necessary because Rspress types `themeConfig` as
+ * `NormalizedThemeConfig`, but ciderpress injects custom fields (sidebar,
+ * workspaces) via spread at build time. No Zod schema exists for runtime
+ * validation yet.
+ *
+ * @returns ciderpress theme config with sidebar and workspace data.
+ */
+export function useCiderpress(): CiderpressThemeConfig {
+  const { site } = useSite()
+  return site.themeConfig as unknown as CiderpressThemeConfig
+}

package/dist/theme/hooks/use-nav-items.ts

@@ -0,0 +1,76 @@
+import { useEffect, useState } from 'react'
+
+import type { CiderpressNavMenuItem } from '../components/nav/ciderpress-nav-menu'
+
+/**
+ * Hook that yields the primary nav items.
+ *
+ * Rspress's `site` object doesn't surface its top-level `nav` field on
+ * the public typings reachable from a custom layout. We fall back to
+ * scraping the items off Rspress's auto-rendered `.rp-nav-menu` (which
+ * is mounted but visually hidden by `<CiderpressHeader />`). A
+ * `MutationObserver` retries if the items haven't been written into
+ * the DOM by first paint.
+ *
+ * @returns Live array of `{ text, link }` items; empty until Rspress mounts
+ */
+export function useNavItems(): readonly CiderpressNavMenuItem[] {
+  const [items, setItems] = useState<readonly CiderpressNavMenuItem[]>([])
+
+  useEffect(() => {
+    const initial = scrapeNavItems()
+    if (initial.length > 0) {
+      setItems(initial)
+      return
+    }
+
+    const observer = new MutationObserver(() => {
+      const next = scrapeNavItems()
+      if (next.length > 0) {
+        setItems(next)
+        observer.disconnect()
+      }
+    })
+    observer.observe(document.body, { childList: true, subtree: true })
+    return () => {
+      observer.disconnect()
+    }
+  }, [])
+
+  return items
+}
+
+/**
+ * Read every anchor under Rspress's hidden `.rp-nav-menu` and project
+ * it into a `{ text, link }` item. Anchors with empty text or `href`
+ * are dropped so we never surface a placeholder entry.
+ *
+ * @private
+ * @returns Nav items currently in the DOM (empty array when not mounted).
+ */
+function scrapeNavItems(): readonly CiderpressNavMenuItem[] {
+  const anchors = document.querySelectorAll<HTMLAnchorElement>('.rp-nav-menu .rp-nav-menu__item a')
+  return [...anchors]
+    .map((anchor) => ({
+      text: readAnchorText(anchor),
+      link: anchor.getAttribute('href') ?? '',
+    }))
+    .filter((item) => item.text !== '' && item.link !== '')
+}
+
+/**
+ * Pull the trimmed text content from an anchor. Returns an empty
+ * string when `textContent` is missing — callers treat empty as "skip
+ * this anchor".
+ *
+ * @private
+ * @param anchor - Anchor element to read.
+ * @returns Trimmed inner text, or empty string when absent.
+ */
+function readAnchorText(anchor: HTMLAnchorElement): string {
+  const text = anchor.textContent
+  if (text === null) {
+    return ''
+  }
+  return text.trim()
+}

package/dist/theme/icons/index.ts

@@ -0,0 +1,2 @@
+export { TECH_ICONS } from './tech-map.ts'
+export type { TechName } from './tech-map.ts'