@zpress/ui 0.1.0

package/src/theme/components/home/feature-card.css

@@ -0,0 +1,89 @@
+/**
+ * Feature Card — layout and typography (base card styles from home-card.css).
+ */
+
+/* ── Feature grid ───────────────────────────────────────────── */
+.feature-grid {
+  --feature-grid-gap: 12px;
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--feature-grid-gap);
+  max-width: 1152px;
+  margin: 0 auto;
+  padding: 0 0 64px;
+}
+
+/* ── Grid item + span system ────────────────────────────────── */
+.feature-card__item {
+  width: 100%;
+  position: relative;
+}
+
+.feature-card__item-wrapper {
+  position: relative;
+  height: 100%;
+}
+
+@media (min-width: 640px) {
+  .feature-card__item--span-2,
+  .feature-card__item--span-4,
+  .feature-card__item--span-6 {
+    width: calc(50% - var(--feature-grid-gap));
+  }
+}
+
+@media (min-width: 768px) {
+  .feature-card__item--span-2,
+  .feature-card__item--span-4 {
+    width: calc(50% - var(--feature-grid-gap));
+  }
+
+  .feature-card__item--span-3,
+  .feature-card__item--span-6 {
+    width: calc((100% - 2 * var(--feature-grid-gap)) / 3);
+  }
+}
+
+@media (min-width: 960px) {
+  .feature-card__item--span-3 {
+    width: calc((100% - 3 * var(--feature-grid-gap)) / 4);
+  }
+
+  .feature-card__item--span-4 {
+    width: calc((100% - 2 * var(--feature-grid-gap)) / 3);
+  }
+
+  .feature-card__item--span-6 {
+    width: calc(50% - var(--feature-grid-gap));
+  }
+}
+
+/* ── Feature card layout ───────────────────────────────────── */
+.feature-card {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  height: 100%;
+}
+
+/* Row 1: icon + title */
+.feature-header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.feature-title {
+  font-family: 'Geist Pixel Square', var(--rp-font-family-base, sans-serif);
+  font-size: 18px;
+  font-weight: 700;
+  color: var(--rp-c-text-1, var(--zp-c-text-1, #fbfbfb));
+  line-height: 1.4;
+}
+
+/* Row 2: description */
+.feature-desc {
+  font-size: 16px;
+  color: var(--rp-c-text-2, var(--zp-c-text-2, rgba(251, 251, 251, 0.72)));
+  line-height: 1.5;
+}

package/src/theme/components/home/feature-card.tsx

@@ -0,0 +1,75 @@
+import type React from 'react'
+import { match, P } from 'ts-pattern'
+
+import './feature-card.css'
+import { Card } from '../shared/card'
+
+/**
+ * Icon color variants matching the design system.
+ */
+export type IconColor = 'purple' | 'blue' | 'green' | 'amber' | 'red' | 'slate' | 'cyan' | 'pink'
+
+export interface FeatureCardProps {
+  readonly title: string
+  readonly description: string
+  readonly href?: string
+  readonly icon?: React.ReactNode
+  readonly iconColor?: IconColor
+  readonly span?: 2 | 3 | 4 | 6
+}
+
+/**
+ * Frontmatter-shaped data for consumers to map from.
+ */
+export interface FeatureItem {
+  readonly title: string
+  readonly details: string
+  readonly link?: string
+  readonly icon?: string
+  readonly iconColor?: IconColor
+  readonly span?: 2 | 3 | 4 | 6
+}
+
+/**
+ * Feature card for landing pages — matches the workspace/section card design.
+ * Renders as `<a>` when `href` is provided, `<div>` otherwise.
+ */
+export function FeatureCard({
+  title,
+  description,
+  href,
+  icon,
+  iconColor = 'purple',
+  span = 4,
+}: FeatureCardProps): React.ReactElement {
+  const iconEl = match(icon)
+    .with(P.nonNullable, (ic) => (
+      <span className={`home-card-icon home-card-icon--${iconColor}`}>{ic}</span>
+    ))
+    .otherwise(() => null)
+
+  return (
+    <div className={`feature-card__item feature-card__item--span-${span}`}>
+      <div className="feature-card__item-wrapper">
+        <Card href={href} className="feature-card">
+          <div className="feature-header">
+            {iconEl}
+            <span className="feature-title">{title}</span>
+          </div>
+          <span className="feature-desc">{description}</span>
+        </Card>
+      </div>
+    </div>
+  )
+}
+
+interface FeatureGridProps {
+  readonly children: React.ReactNode
+}
+
+/**
+ * Flex-wrap layout container for feature cards.
+ */
+export function FeatureGrid({ children }: FeatureGridProps): React.ReactElement {
+  return <div className="feature-grid">{children}</div>
+}

package/src/theme/components/home/feature.tsx

@@ -0,0 +1,53 @@
+import { useFrontmatter } from '@rspress/core/runtime'
+import type React from 'react'
+import { match, P } from 'ts-pattern'
+
+import { Icon } from '../shared/icon'
+import { FeatureCard, FeatureGrid } from './feature-card'
+import type { FeatureItem } from './feature-card'
+
+// ── Helpers ──────────────────────────────────────────────────
+
+/**
+ * Render a single feature as a FeatureCard element.
+ * Accepts the array index from `.map()` to guarantee unique keys.
+ */
+function renderFeature(feature: FeatureItem, index: number): React.ReactElement {
+  const iconEl = match(feature.icon)
+    .with(P.nonNullable, (iconId) => <Icon icon={iconId} />)
+    .otherwise(() => null)
+
+  return (
+    <FeatureCard
+      key={`${feature.title}-${index}`}
+      title={feature.title}
+      description={feature.details}
+      href={feature.link}
+      icon={iconEl}
+      iconColor={feature.iconColor}
+    />
+  )
+}
+
+// ── Component ────────────────────────────────────────────────
+
+/**
+ * Custom HomeFeature override for zpress.
+ * Uses useFrontmatter() hook to read features and renders with FeatureCard/FeatureGrid styling.
+ */
+export function HomeFeature(): React.ReactElement | null {
+  const { frontmatter } = useFrontmatter()
+  // Rspress types frontmatter as its own FrontMatterMeta shape which does not
+  // include zpress-specific `features`. The double cast is necessary because
+  // no shared Zod schema exists for frontmatter validation at runtime.
+  const features = (frontmatter as Record<string, unknown>).features as
+    | readonly FeatureItem[]
+    | undefined
+
+  return match(features)
+    .with(
+      P.when((f): f is readonly FeatureItem[] => Array.isArray(f) && f.length > 0),
+      (items) => <FeatureGrid>{items.map(renderFeature)}</FeatureGrid>
+    )
+    .otherwise(() => null)
+}

package/src/theme/components/home/layout.tsx

@@ -0,0 +1,36 @@
+import { HomeLayout as OriginalHomeLayout } from '@rspress/core/theme-original'
+import type React from 'react'
+
+import { HomeWorkspaces } from './workspaces'
+
+// ── Types ────────────────────────────────────────────────────
+
+interface HomeLayoutProps {
+  readonly beforeHero?: React.ReactNode
+  readonly afterHero?: React.ReactNode
+  readonly beforeFeatures?: React.ReactNode
+  readonly afterFeatures?: React.ReactNode
+  readonly beforeHeroActions?: React.ReactNode
+  readonly afterHeroActions?: React.ReactNode
+}
+
+// ── Component ────────────────────────────────────────────────
+
+/**
+ * Custom HomeLayout override for zpress.
+ * Wraps the original Rspress HomeLayout and injects HomeWorkspaces
+ * into the afterFeatures slot.
+ */
+export function HomeLayout(props: HomeLayoutProps): React.ReactElement {
+  return (
+    <OriginalHomeLayout
+      {...props}
+      afterFeatures={
+        <>
+          {props.afterFeatures}
+          <HomeWorkspaces />
+        </>
+      }
+    />
+  )
+}

package/src/theme/components/home/workspaces.tsx

@@ -0,0 +1,53 @@
+import type React from 'react'
+import { match, P } from 'ts-pattern'
+
+import { useZpress } from '../../hooks/use-zpress'
+import type { WorkspaceGroupData } from '../../hooks/use-zpress'
+import { WorkspaceCard } from '../workspaces/card'
+import { WorkspaceGrid } from '../workspaces/grid'
+
+/**
+ * Smart orchestrator that reads workspace data from themeConfig
+ * and renders workspace groups with the correct card component per type.
+ */
+export function HomeWorkspaces(): React.ReactElement | null {
+  const { workspaces } = useZpress()
+
+  return match(workspaces)
+    .with(
+      P.when((w): w is readonly WorkspaceGroupData[] => Array.isArray(w) && w.length > 0),
+      (groups) => (
+        <div className="workspace-section">
+          <hr className="home-card-divider" />
+          {groups.map(renderGroup)}
+        </div>
+      )
+    )
+    .otherwise(() => null)
+}
+
+// ── Helpers ──────────────────────────────────────────────────
+
+/**
+ * Render a single workspace group.
+ * @private
+ */
+function renderGroup(group: WorkspaceGroupData): React.ReactElement {
+  return (
+    <WorkspaceGrid key={group.heading} heading={group.heading} description={group.description}>
+      {group.cards.map((card, i) => (
+        <WorkspaceCard
+          key={`${card.text}-${i}`}
+          text={card.text}
+          href={card.href}
+          icon={card.icon}
+          iconColor={card.iconColor}
+          scope={card.scope}
+          description={card.description}
+          tags={card.tags}
+          badge={card.badge}
+        />
+      ))}
+    </WorkspaceGrid>
+  )
+}

package/src/theme/components/nav/branch-tag.css

@@ -0,0 +1,54 @@
+/**
+ * Branch tag pill — git branch badge positioned in the nav bar.
+ */
+
+.branch-tag {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  margin-left: 8px;
+  padding: 3px 10px;
+  border-radius: 20px;
+  background: var(--zp-c-bg-soft);
+  border: 1px solid var(--zp-c-divider);
+  color: var(--zp-c-text-3);
+  font-family: var(--zp-font-family-mono);
+  font-size: 11px;
+  font-weight: 600;
+  line-height: 1;
+  white-space: nowrap;
+  max-width: 180px;
+  text-decoration: none !important;
+  transition:
+    border-color 0.2s,
+    color 0.2s;
+}
+
+.branch-tag:hover {
+  border-color: var(--zp-c-brand-1);
+  color: var(--zp-c-brand-1);
+  text-decoration: none !important;
+}
+
+.branch-tag:focus-visible {
+  outline: 2px solid var(--rp-c-brand);
+  outline-offset: 2px;
+}
+
+.branch-tag svg {
+  width: 14px;
+  height: 14px;
+  flex-shrink: 0;
+}
+
+.branch-tag-text {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* ── Responsive ──────────────────────────────────────────── */
+@media (max-width: 768px) {
+  .branch-tag-text {
+    display: none;
+  }
+}

package/src/theme/components/nav/branch-tag.tsx

@@ -0,0 +1,66 @@
+import React, { useEffect, useRef } from 'react'
+
+import './branch-tag.css'
+import { Icon } from '../shared/icon.tsx'
+
+declare const __ZPRESS_GIT_BRANCH__: string | undefined
+
+/**
+ * Resolves the current git branch name from the build-time global,
+ * returning an empty string when undefined.
+ */
+function resolveBranch(): string {
+  if (__ZPRESS_GIT_BRANCH__ !== undefined) {
+    return __ZPRESS_GIT_BRANCH__
+  }
+  return ''
+}
+
+/**
+ * Git branch tag — pill-shaped badge positioned in the nav bar.
+ * Hidden when on `main` (production). Uses the pixelarticons:git-branch icon.
+ */
+export function BranchTag(): React.ReactElement | null {
+  const branch = resolveBranch()
+  const rootRef = useRef<HTMLAnchorElement>(null)
+
+  useEffect(() => {
+    if (!branch || branch === 'main' || !rootRef.current) {
+      return
+    }
+
+    const node = rootRef.current
+
+    // Relocate into the search container so it sits beside the search button.
+    // No Rspress API exists for injecting into the nav bar, so direct DOM
+    // manipulation is the only option for this placement.
+    const searchContainer = document.querySelector('.rspress-nav-search')
+    if (searchContainer) {
+      searchContainer.append(node)
+    }
+
+    return () => {
+      node.remove()
+    }
+  }, [branch])
+
+  if (!branch || branch === 'main') {
+    return null
+  }
+
+  return (
+    <a
+      className="branch-tag"
+      ref={rootRef}
+      href={`https://github.com/joggrdocs/zpress/tree/${branch}`}
+      target="_blank"
+      rel="noopener noreferrer"
+      title={`Branch: ${branch}`}
+    >
+      <Icon icon="pixelarticons:git-branch" width={14} height={14} />
+      <span className="branch-tag-text">{branch}</span>
+    </a>
+  )
+}
+
+export { BranchTag as default }

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

@@ -0,0 +1,27 @@
+import type React from 'react'
+import { match, P } from 'ts-pattern'
+
+// ── Types ────────────────────────────────────────────────────
+
+export interface CardProps {
+  readonly href?: string
+  readonly className?: string
+  readonly children: React.ReactNode
+}
+
+// ── Component ────────────────────────────────────────────────
+
+/**
+ * Shared base card handling link-vs-div rendering.
+ * Renders `<a>` with `home-card--clickable` when `href` is provided,
+ * plain `<div>` otherwise.
+ */
+export function Card({ href, className, children }: CardProps): React.ReactElement {
+  return match(href)
+    .with(P.nonNullable, (h) => (
+      <a className={`home-card home-card--clickable ${className ?? ''}`} href={h}>
+        {children}
+      </a>
+    ))
+    .otherwise(() => <div className={`home-card ${className ?? ''}`}>{children}</div>)
+}

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

@@ -0,0 +1,27 @@
+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
+function cast(v: unknown): Parameters<typeof addCollection>[0] {
+  return v as Parameters<typeof addCollection>[0]
+}
+
+export const pixelarticonsLoaded = addCollection(cast(pixelarticons))
+export const deviconLoaded = addCollection(cast(devicon))
+export const mdiLoaded = addCollection(cast(mdi))
+export const simpleIconsLoaded = addCollection(cast(simpleIcons))
+export const skillIconsLoaded = addCollection(cast(skillIcons))
+export const catppuccinLoaded = addCollection(cast(catppuccin))
+export const logosLoaded = addCollection(cast(logos))
+export const vscodeIconsLoaded = addCollection(cast(vscodeIcons))
+export const materialIconThemeLoaded = addCollection(cast(materialIconTheme))
+
+export { Icon }

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

@@ -0,0 +1,42 @@
+import type React from 'react'
+import { match, P } from 'ts-pattern'
+
+import type { IconColor } from '../home/feature-card'
+import { Card } from './card'
+import { Icon } from './icon'
+
+export interface SectionCardProps {
+  readonly href: string
+  readonly title: string
+  readonly description?: string
+  readonly icon?: string
+  readonly iconColor?: IconColor
+}
+
+/**
+ * Section card — simple icon + title + description link card
+ * used on auto-generated section landing pages.
+ */
+export function SectionCard({
+  href,
+  title,
+  description,
+  icon = 'pixelarticons:file',
+  iconColor = 'purple',
+}: SectionCardProps): React.ReactElement {
+  const descEl = match(description)
+    .with(P.nonNullable, (d) => <span className="section-desc">{d}</span>)
+    .otherwise(() => null)
+
+  return (
+    <Card href={href} className="section-card">
+      <span className={`section-icon section-icon--${iconColor}`}>
+        <Icon icon={icon} />
+      </span>
+      <div className="section-info">
+        <span className="section-title">{title}</span>
+        {descEl}
+      </div>
+    </Card>
+  )
+}

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

@@ -0,0 +1,12 @@
+import type React from 'react'
+
+export interface SectionGridProps {
+  readonly children: React.ReactNode
+}
+
+/**
+ * Grid container for section cards on landing pages.
+ */
+export function SectionGrid({ children }: SectionGridProps): React.ReactElement {
+  return <div className="section-grid">{children}</div>
+}

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

@@ -0,0 +1,68 @@
+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(--zp-c-bg-icon)',
+}
+
+/**
+ * Renders a table of technology icons with tag, label, and identifier columns.
+ * Used in generated icon reference docs.
+ */
+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.tsx

@@ -0,0 +1,28 @@
+import type React from 'react'
+import { match, P } from 'ts-pattern'
+
+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.
+ */
+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="workspace-tag">
+        <Icon icon={e.icon} />
+        {` ${e.label}`}
+      </span>
+    ))
+    .otherwise(() => <span className="workspace-tag">{name}</span>)
+}