@zpress/ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joggr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.mjs

@@ -0,0 +1,75 @@
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import node_path from "node:path";
+function zpressPlugin() {
+    const componentsDir = node_path.resolve(import.meta.dirname, 'theme', 'components');
+    return {
+        name: 'zpress',
+        globalUIComponents: [
+            node_path.resolve(componentsDir, 'nav', 'branch-tag.tsx')
+        ]
+    };
+}
+function loadGenerated(contentDir, name, fallback) {
+    const p = node_path.resolve(contentDir, '.generated', name);
+    if (!existsSync(p)) {
+        process.stderr.write(`[zpress] Generated file not found: ${name} — run "zpress sync" first\n`);
+        return fallback;
+    }
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+function detectGitBranch() {
+    try {
+        return execSync('git rev-parse --abbrev-ref HEAD', {
+            encoding: 'utf8',
+            stdio: 'pipe'
+        }).trim();
+    } catch  {
+        return '';
+    }
+}
+function createRspressConfig(options) {
+    const { config, paths } = options;
+    const sidebar = loadGenerated(paths.contentDir, 'sidebar.json', {});
+    const nav = loadGenerated(paths.contentDir, 'nav.json', []);
+    const workspaces = loadGenerated(paths.contentDir, 'workspaces.json', []);
+    const gitBranch = detectGitBranch();
+    return {
+        root: paths.contentDir,
+        outDir: paths.distDir,
+        llms: true,
+        title: config.title ?? 'zpress',
+        description: config.description ?? 'Documentation',
+        logo: '/logo.svg',
+        logoText: '',
+        themeDir: node_path.resolve(import.meta.dirname, 'theme'),
+        plugins: [
+            zpressPlugin()
+        ],
+        builderConfig: {
+            resolve: {
+                alias: {
+                    '@zpress/ui/theme': node_path.resolve(import.meta.dirname, 'theme', 'index.tsx')
+                }
+            },
+            source: {
+                define: {
+                    __ZPRESS_GIT_BRANCH__: JSON.stringify(gitBranch)
+                }
+            },
+            output: {
+                distPath: {
+                    root: paths.distDir
+                }
+            }
+        },
+        themeConfig: {
+            sidebar,
+            nav,
+            darkMode: true,
+            search: true,
+            workspaces
+        }
+    };
+}
+export { createRspressConfig, zpressPlugin };

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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>
+}