@zpress/ui 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export declare function createRspressConfig(options: CreateRspressConfigOptions)
 declare interface CreateRspressConfigOptions {
     readonly config: ZpressConfig;
     readonly paths: Paths;
+    readonly logLevel?: 'info' | 'warn' | 'error' | 'silent';
 }
 
 /**
@@ -21,6 +22,8 @@ declare interface CreateRspressConfigOptions {
  * CSS import — not through the plugin globalStyles property.
  * Nav-level components (e.g. BranchTag) are injected via layout
  * slot props in the custom Layout component, not globalUIComponents.
+ * ThemeProvider is registered as a globalUIComponent to configure
+ * the active theme on every page.
  */
 export declare function zpressPlugin(): RspressPlugin;
 

package/dist/index.mjs

@@ -1,9 +1,14 @@
 import { execSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import node_path from "node:path";
+import { resolveDefaultColorMode } from "@zpress/core";
 function zpressPlugin() {
+    const componentsDir = node_path.resolve(import.meta.dirname, 'theme', 'components');
     return {
-        name: 'zpress'
+        name: 'zpress',
+        globalUIComponents: [
+            node_path.resolve(componentsDir, 'theme-provider.tsx')
+        ]
     };
 }
 function loadGenerated(contentDir, name, fallback) {
@@ -24,12 +29,37 @@ function detectGitBranch() {
         return '';
     }
 }
+function resolveThemeName(config) {
+    if (config.theme && config.theme.name) return config.theme.name;
+    return 'base';
+}
+function resolveColorMode(config, themeName) {
+    if (config.theme && config.theme.colorMode) return config.theme.colorMode;
+    return resolveDefaultColorMode(themeName);
+}
+function resolveThemeSwitcher(config) {
+    if (config.theme && config.theme.switcher) return config.theme.switcher;
+    return false;
+}
+function resolveThemeColors(config) {
+    if (config.theme && config.theme.colors) return config.theme.colors;
+    return {};
+}
+function resolveThemeDarkColors(config) {
+    if (config.theme && config.theme.darkColors) return config.theme.darkColors;
+    return {};
+}
 function createRspressConfig(options) {
-    const { config, paths } = options;
+    const { config, paths, logLevel } = 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();
+    const themeName = resolveThemeName(config);
+    const colorMode = resolveColorMode(config, themeName);
+    const themeSwitcher = resolveThemeSwitcher(config);
+    const themeColors = resolveThemeColors(config);
+    const themeDarkColors = resolveThemeDarkColors(config);
     return {
         root: paths.contentDir,
         outDir: paths.distDir,
@@ -47,6 +77,12 @@ function createRspressConfig(options) {
             zpressPlugin()
         ],
         builderConfig: {
+            ...(()=>{
+                if (logLevel) return {
+                    logLevel
+                };
+                return {};
+            })(),
             resolve: {
                 alias: {
                     '@zpress/ui/theme': node_path.resolve(import.meta.dirname, 'theme', 'index.tsx')
@@ -54,7 +90,12 @@ function createRspressConfig(options) {
             },
             source: {
                 define: {
-                    __ZPRESS_GIT_BRANCH__: JSON.stringify(gitBranch)
+                    __ZPRESS_GIT_BRANCH__: JSON.stringify(gitBranch),
+                    __ZPRESS_THEME_NAME__: JSON.stringify(themeName),
+                    __ZPRESS_COLOR_MODE__: JSON.stringify(colorMode),
+                    __ZPRESS_THEME_COLORS__: JSON.stringify(JSON.stringify(themeColors)),
+                    __ZPRESS_THEME_DARK_COLORS__: JSON.stringify(JSON.stringify(themeDarkColors)),
+                    __ZPRESS_THEME_SWITCHER__: JSON.stringify(themeSwitcher)
                 }
             },
             output: {
@@ -66,7 +107,7 @@ function createRspressConfig(options) {
         themeConfig: {
             sidebar,
             nav,
-            darkMode: true,
+            darkMode: 'toggle' === colorMode,
             search: true,
             workspaces
         }

package/dist/theme/components/nav/layout.tsx

@@ -2,13 +2,13 @@ import { Layout as OriginalLayout } from '@rspress/core/theme-original'
 import type React from 'react'
 
 import { BranchTag } from './branch-tag'
+import { ThemeSwitcher } from './theme-switcher'
 
 /**
  * Custom Layout override for zpress.
- * Wraps the original Rspress Layout and injects the BranchTag
- * into the `beforeNavMenu` slot so it renders before the search
- * bar in the navbar on all page types.
+ * Wraps the original Rspress Layout and injects BranchTag
+ * into `beforeNavMenu` and ThemeSwitcher into `afterNavMenu`.
  */
 export function Layout(): React.ReactElement {
-  return <OriginalLayout beforeNavMenu={<BranchTag />} />
+  return <OriginalLayout beforeNavMenu={<BranchTag />} afterNavMenu={<ThemeSwitcher />} />
 }

package/dist/theme/components/nav/theme-switcher.css

@@ -0,0 +1,92 @@
+/**
+ * Theme switcher dropdown styles.
+ */
+
+.theme-switcher {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  margin-left: 8px;
+}
+
+.theme-switcher-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  border: 1px solid var(--zp-c-border);
+  border-radius: var(--rp-radius);
+  background: var(--zp-c-bg);
+  color: var(--zp-c-text-2);
+  cursor: pointer;
+  transition:
+    color 0.2s,
+    border-color 0.2s;
+}
+
+.theme-switcher-btn:hover {
+  color: var(--zp-c-text-1);
+  border-color: var(--zp-c-brand-1);
+}
+
+.theme-switcher-dropdown {
+  position: absolute;
+  top: calc(100% + 8px);
+  right: 0;
+  z-index: 100;
+  min-width: 160px;
+  padding: 4px;
+  border: 1px solid var(--zp-c-border);
+  border-radius: var(--rp-radius);
+  background: var(--zp-c-bg-elv);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+}
+
+.theme-switcher-option {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  padding: 8px 12px;
+  border: none;
+  border-radius: var(--rp-radius-small);
+  background: none;
+  color: var(--zp-c-text-2);
+  font-size: 13px;
+  font-family: var(--zp-font-family-base);
+  cursor: pointer;
+  transition:
+    background 0.15s,
+    color 0.15s;
+}
+
+.theme-switcher-option:hover {
+  background: var(--zp-c-bg-soft);
+  color: var(--zp-c-text-1);
+}
+
+.theme-switcher-option--active {
+  color: var(--zp-c-brand-1);
+}
+
+.theme-switcher-swatch {
+  display: inline-block;
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+  border: 1px solid var(--zp-c-border);
+  flex-shrink: 0;
+}
+
+.theme-switcher-check {
+  margin-left: auto;
+  font-size: 11px;
+  opacity: 0.7;
+}
+
+.theme-switcher-name {
+  flex: 1;
+  text-align: left;
+}

package/dist/theme/components/nav/theme-switcher.tsx

@@ -0,0 +1,135 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+
+import { Icon } from '../shared/icon.tsx'
+
+import './theme-switcher.css'
+
+declare const __ZPRESS_THEME_SWITCHER__: boolean
+
+interface ThemeOption {
+  readonly name: string
+  readonly label: string
+  readonly swatch: string
+  readonly defaultColorMode: 'dark' | 'light' | 'toggle'
+}
+
+const THEME_OPTIONS: readonly ThemeOption[] = [
+  { name: 'base', label: 'Base', swatch: '#a78bfa', defaultColorMode: 'toggle' },
+  { name: 'midnight', label: 'Midnight', swatch: '#60a5fa', defaultColorMode: 'dark' },
+  { name: 'arcade', label: 'Arcade', swatch: '#00ff88', defaultColorMode: 'dark' },
+]
+
+/**
+ * Build the className string for a theme option button.
+ */
+function optionClassName(isActive: boolean): string {
+  if (isActive) {
+    return 'theme-switcher-option theme-switcher-option--active'
+  }
+  return 'theme-switcher-option'
+}
+
+/**
+ * Apply a theme by updating the DOM and persisting to localStorage.
+ */
+function applyTheme(theme: ThemeOption): void {
+  const html = document.documentElement
+  html.dataset.zpTheme = theme.name
+  localStorage.setItem('zpress-theme', theme.name)
+
+  if (theme.defaultColorMode === 'dark') {
+    html.classList.add('rp-dark')
+    html.dataset.dark = 'true'
+    localStorage.setItem('rspress-theme', 'dark')
+  } else if (theme.defaultColorMode === 'light') {
+    html.classList.remove('rp-dark')
+    html.dataset.dark = 'false'
+    localStorage.setItem('rspress-theme', 'light')
+  }
+}
+
+/**
+ * ThemeSwitcher — dropdown button for switching between built-in themes.
+ * Only renders when `__ZPRESS_THEME_SWITCHER__` build-time define is true.
+ */
+export function ThemeSwitcher(): React.ReactElement | null {
+  const [isOpen, setIsOpen] = useState(false)
+  const [activeTheme, setActiveTheme] = useState(() => {
+    if (typeof globalThis === 'undefined') {
+      return 'base'
+    }
+    try {
+      return localStorage.getItem('zpress-theme') || 'base'
+    } catch {
+      return 'base'
+    }
+  })
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  const handleToggle = useCallback(() => {
+    setIsOpen((prev) => !prev)
+  }, [])
+
+  const handleSelect = useCallback((theme: ThemeOption) => {
+    setActiveTheme(theme.name)
+    applyTheme(theme)
+    setIsOpen(false)
+  }, [])
+
+  useEffect(() => {
+    function handleClickOutside(event: MouseEvent): void {
+      if (containerRef.current && !containerRef.current.contains(event.target as Node)) {
+        setIsOpen(false)
+      }
+    }
+
+    function handleEscape(event: KeyboardEvent): void {
+      if (event.key === 'Escape') {
+        setIsOpen(false)
+      }
+    }
+
+    document.addEventListener('mousedown', handleClickOutside)
+    document.addEventListener('keydown', handleEscape)
+
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside)
+      document.removeEventListener('keydown', handleEscape)
+    }
+  }, [])
+
+  if (!__ZPRESS_THEME_SWITCHER__) {
+    return null
+  }
+
+  return (
+    <div className="theme-switcher" ref={containerRef}>
+      <button
+        className="theme-switcher-btn"
+        onClick={handleToggle}
+        aria-label="Switch theme"
+        type="button"
+      >
+        <Icon icon="pixelarticons:paint-bucket" width={16} height={16} />
+      </button>
+      {isOpen && (
+        <div className="theme-switcher-dropdown">
+          {THEME_OPTIONS.map((theme) => (
+            <button
+              key={theme.name}
+              className={optionClassName(activeTheme === theme.name)}
+              onClick={() => handleSelect(theme)}
+              type="button"
+            >
+              <span className="theme-switcher-swatch" style={{ backgroundColor: theme.swatch }} />
+              <span className="theme-switcher-name">{theme.label}</span>
+              {activeTheme === theme.name && (
+                <span className="theme-switcher-check">{'\u2713'}</span>
+              )}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}

package/dist/theme/components/shared/browser-window.css

@@ -0,0 +1,61 @@
+.browser-window {
+  border: 1px solid var(--zp-c-border);
+  border-radius: 8px;
+  overflow: hidden;
+  background: var(--zp-c-bg-soft);
+}
+
+.browser-window__titlebar {
+  display: flex;
+  align-items: center;
+  padding: 8px 12px;
+  gap: 8px;
+  background: var(--zp-c-bg-elv);
+  border-bottom: 1px solid var(--zp-c-border);
+}
+
+.browser-window__dots {
+  display: flex;
+  gap: 6px;
+}
+
+.browser-window__dot {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+}
+
+.browser-window__dot--close {
+  background: #ff5f57;
+}
+
+.browser-window__dot--minimize {
+  background: #febc2e;
+}
+
+.browser-window__dot--maximize {
+  background: #28c840;
+}
+
+.browser-window__url {
+  flex: 1;
+  text-align: center;
+  font-size: 11px;
+  color: var(--zp-c-text-3);
+  background: var(--zp-c-bg-soft);
+  border-radius: 4px;
+  padding: 2px 8px;
+}
+
+.browser-window__content p {
+  margin: 0;
+  padding: 0;
+  line-height: 0;
+}
+
+.browser-window__content img {
+  width: 100%;
+  display: block;
+  margin: 0;
+  padding: 0;
+}

package/dist/theme/components/shared/browser-window.tsx

@@ -0,0 +1,35 @@
+import type React from 'react'
+import { match, P } from 'ts-pattern'
+
+import './browser-window.css'
+
+// ── Types ────────────────────────────────────────────────────
+
+export interface BrowserWindowProps {
+  readonly url?: string
+  readonly children: React.ReactNode
+}
+
+// ── Component ────────────────────────────────────────────────
+
+/**
+ * Fake browser window chrome that wraps content in a title bar
+ * with traffic-light dots and an optional URL pill.
+ */
+export function BrowserWindow({ url, children }: BrowserWindowProps): React.ReactElement {
+  return (
+    <div className="browser-window">
+      <div className="browser-window__titlebar">
+        <div className="browser-window__dots">
+          <span className="browser-window__dot browser-window__dot--close" />
+          <span className="browser-window__dot browser-window__dot--minimize" />
+          <span className="browser-window__dot browser-window__dot--maximize" />
+        </div>
+        {match(url)
+          .with(P.nonNullable, (u) => <span className="browser-window__url">{u}</span>)
+          .otherwise(() => null)}
+      </div>
+      <div className="browser-window__content">{children}</div>
+    </div>
+  )
+}

package/dist/theme/components/theme-provider.tsx

@@ -0,0 +1,159 @@
+import { useEffect } from 'react'
+import type React from 'react'
+
+declare const __ZPRESS_THEME_NAME__: string
+declare const __ZPRESS_COLOR_MODE__: string
+declare const __ZPRESS_THEME_COLORS__: string
+declare const __ZPRESS_THEME_DARK_COLORS__: string
+
+const COLOR_VAR_MAP: Record<string, readonly string[]> = {
+  brand: ['--zp-c-brand-1', '--rp-c-brand'],
+  brandLight: ['--rp-c-brand-light'],
+  brandDark: ['--zp-c-brand-2', '--rp-c-brand-dark'],
+  brandSoft: ['--zp-c-brand-soft', '--rp-c-brand-tint'],
+  bg: ['--zp-c-bg', '--rp-c-bg'],
+  bgAlt: ['--zp-c-bg-alt'],
+  bgElv: ['--zp-c-bg-elv'],
+  bgSoft: ['--zp-c-bg-soft', '--rp-c-bg-soft'],
+  text1: ['--zp-c-text-1', '--rp-c-text-1'],
+  text2: ['--zp-c-text-2', '--rp-c-text-2'],
+  text3: ['--zp-c-text-3', '--rp-c-text-3'],
+  divider: ['--zp-c-divider', '--rp-c-divider'],
+  border: ['--zp-c-border'],
+  homeBg: ['--rp-home-background-bg'],
+}
+
+/**
+ * Build a flat list of [cssVar, value] pairs from a color overrides object.
+ */
+function resolveColorPairs(colors: Record<string, string>): readonly (readonly [string, string])[] {
+  return Object.entries(colors).flatMap(([key, value]) => {
+    const vars = COLOR_VAR_MAP[key]
+    if (!vars) {
+      return []
+    }
+    return vars.map((cssVar) => [cssVar, value] as const)
+  })
+}
+
+/**
+ * Apply a ThemeColors object as inline CSS custom properties on <html>.
+ */
+function applyColorOverrides(html: HTMLElement, colors: Record<string, string>): void {
+  const pairs = resolveColorPairs(colors)
+  // oxlint-disable-next-line unicorn/no-array-for-each -- DOM side effect; for-loops also banned
+  pairs.forEach(([cssVar, value]) => {
+    html.style.setProperty(cssVar, value)
+  })
+}
+
+/**
+ * Collect all CSS variable names from the color map.
+ */
+const ALL_CSS_VARS: readonly string[] = Object.values(COLOR_VAR_MAP).flat()
+
+/**
+ * Remove all color overrides previously set as inline styles.
+ */
+function clearColorOverrides(html: HTMLElement): void {
+  // oxlint-disable-next-line unicorn/no-array-for-each -- DOM side effect; for-loops also banned
+  ALL_CSS_VARS.forEach((cssVar) => {
+    html.style.removeProperty(cssVar)
+  })
+}
+
+/**
+ * Safe localStorage read — returns null if storage is unavailable.
+ */
+function safeGetItem(key: string): string | null {
+  try {
+    return localStorage.getItem(key)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Parse a JSON build-time define, returning an empty object on failure.
+ */
+function parseColors(raw: string): Record<string, string> {
+  if (!raw || raw === '""' || raw === 'undefined') {
+    return {}
+  }
+  try {
+    return JSON.parse(raw) as Record<string, string>
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * ThemeProvider — global UI component that configures the active theme.
+ *
+ * Sets `data-zp-theme` attribute, forces color mode, and applies
+ * inline CSS custom property overrides from build-time defines.
+ */
+export function ThemeProvider(): React.ReactElement | null {
+  useEffect(() => {
+    const html = document.documentElement
+    const themeName = safeGetItem('zpress-theme') || __ZPRESS_THEME_NAME__
+    const colorMode = __ZPRESS_COLOR_MODE__
+    const colors = parseColors(__ZPRESS_THEME_COLORS__)
+    const darkColors = parseColors(__ZPRESS_THEME_DARK_COLORS__)
+    const hasColors = Object.keys(colors).length > 0
+    const hasDarkColors = Object.keys(darkColors).length > 0
+
+    // 1. Set theme attribute
+    html.dataset.zpTheme = themeName
+
+    // 2. Force color mode if not toggle
+    if (colorMode === 'dark') {
+      html.classList.add('rp-dark')
+      html.dataset.dark = 'true'
+      localStorage.setItem('rspress-theme', 'dark')
+    } else if (colorMode === 'light') {
+      html.classList.remove('rp-dark')
+      html.dataset.dark = 'false'
+      localStorage.setItem('rspress-theme', 'light')
+    }
+
+    // 3. Apply base color overrides
+    if (hasColors) {
+      applyColorOverrides(html, colors)
+    }
+
+    // 4. Observe dark mode changes for dark-specific overrides
+    if (hasDarkColors) {
+      const isDark = html.classList.contains('rp-dark')
+      if (isDark) {
+        applyColorOverrides(html, darkColors)
+      }
+
+      const observer = new MutationObserver((mutations) => {
+        const classChanged = mutations.some((m) => m.attributeName === 'class')
+        if (classChanged) {
+          const nowDark = html.classList.contains('rp-dark')
+          clearColorOverrides(html)
+          if (hasColors) {
+            applyColorOverrides(html, colors)
+          }
+          if (nowDark && hasDarkColors) {
+            applyColorOverrides(html, darkColors)
+          }
+        }
+      })
+
+      observer.observe(html, { attributes: true, attributeFilter: ['class'] })
+
+      return () => {
+        observer.disconnect()
+      }
+    }
+
+    // no cleanup needed when dark color overrides are absent
+  }, [])
+
+  return null
+}
+
+export { ThemeProvider as default }

package/dist/theme/index.tsx

@@ -12,6 +12,11 @@
 import './styles/overrides/fonts.css'
 import './styles/overrides/tokens.css'
 import './styles/overrides/rspress.css'
+// Theme color palettes — scoped via [data-zp-theme] selectors
+import './styles/themes/base.css'
+import './styles/themes/midnight.css'
+import './styles/themes/arcade.css'
+import './styles/themes/arcade-fx.css'
 import './styles/overrides/details.css'
 import './styles/overrides/scrollbar.css'
 import './styles/overrides/sidebar.css'
@@ -43,6 +48,8 @@ export type { TechTagProps } from './components/shared/tech-tag'
 export { TechIconTable } from './components/shared/tech-icon-table'
 export type { TechIconEntry, TechIconTableProps } from './components/shared/tech-icon-table'
 export { Icon } from './components/shared/icon'
+export { BrowserWindow } from './components/shared/browser-window'
+export type { BrowserWindowProps } from './components/shared/browser-window'
 
 // Home page overrides — shadow the wildcard re-exports from theme-original
 export { HomeFeature } from './components/home/feature'