@zpress/core 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -69,12 +69,22 @@ export declare interface CardConfig {
     };
 }
 
+/**
+ * All valid color modes — used for validation.
+ */
+export declare const COLOR_MODES: readonly ColorMode[];
+
+/**
+ * How dark/light mode is controlled.
+ */
+export declare type ColorMode = 'dark' | 'light' | 'toggle';
+
 /**
  * Error produced during config validation in `defineConfig`.
  */
 export declare interface ConfigError {
     readonly _tag: 'ConfigError';
-    readonly type: 'empty_sections' | 'missing_field' | 'duplicate_prefix' | 'invalid_icon' | 'invalid_entry';
+    readonly type: 'empty_sections' | 'missing_field' | 'duplicate_prefix' | 'invalid_icon' | 'invalid_entry' | 'invalid_theme';
     readonly message: string;
 }
 
@@ -513,6 +523,14 @@ export declare interface Paths {
     readonly cacheDir: string;
 }
 
+/**
+ * Resolve the default color mode for a given theme name.
+ *
+ * @param theme - Built-in theme identifier
+ * @returns The theme's natural color mode
+ */
+export declare function resolveDefaultColorMode(theme: ThemeName): ColorMode;
+
 /**
  * Internal resolved node — produced by the resolver, consumed by copy + sidebar/nav generators.
  */
@@ -750,6 +768,73 @@ export declare interface SyncResult {
     readonly elapsed: number;
 }
 
+/**
+ * All valid theme names — used for validation.
+ */
+export declare const THEME_NAMES: readonly ThemeName[];
+
+/**
+ * Optional color overrides keyed to CSS custom properties.
+ *
+ * Each key maps to one or more `--zp-c-*` / `--rp-c-*` variables.
+ * Values must be valid CSS color strings (hex or rgba).
+ */
+export declare interface ThemeColors {
+    readonly brand?: string;
+    readonly brandLight?: string;
+    readonly brandDark?: string;
+    readonly brandSoft?: string;
+    readonly bg?: string;
+    readonly bgAlt?: string;
+    readonly bgElv?: string;
+    readonly bgSoft?: string;
+    readonly text1?: string;
+    readonly text2?: string;
+    readonly text3?: string;
+    readonly divider?: string;
+    readonly border?: string;
+    readonly homeBg?: string;
+}
+
+/**
+ * Top-level theme configuration for `zpress.config.ts`.
+ */
+export declare interface ThemeConfig {
+    /**
+     * Built-in theme to use.
+     * @default 'base'
+     */
+    readonly name?: ThemeName;
+    /**
+     * Color mode behavior. Defaults to the theme's natural mode.
+     */
+    readonly colorMode?: ColorMode;
+    /**
+     * Show the theme switcher dropdown in the nav bar.
+     * @default false
+     */
+    readonly switcher?: boolean;
+    /**
+     * Partial color overrides applied in light mode (or base mode).
+     */
+    readonly colors?: ThemeColors;
+    /**
+     * Partial color overrides applied only in dark mode.
+     */
+    readonly darkColors?: ThemeColors;
+}
+
+/**
+ * Theme types and default resolution.
+ *
+ * Defines the built-in theme palette system: theme names, color modes,
+ * per-theme color overrides, and the top-level ThemeConfig shape.
+ */
+/**
+ * Built-in theme identifiers.
+ */
+export declare type ThemeName = 'base' | 'midnight' | 'arcade';
+
 /**
  * URL path (e.g. `"/guides/add-api-route"`)
  */
@@ -917,6 +1002,11 @@ export declare interface ZpressConfig {
      * Site meta description. Used as the hero headline on the home page.
      */
     readonly description?: string;
+    /**
+     * Theme configuration.
+     * Controls the visual theme, color mode, and optional color overrides.
+     */
+    readonly theme?: ThemeConfig;
     /**
      * Path to a custom favicon file served from `.zpress/public/`.
      * When omitted, defaults to the auto-generated `/icon.svg`.

package/dist/index.mjs

@@ -1,8 +1,8 @@
+import { P, match } from "ts-pattern";
 import { loadConfig } from "c12";
 import promises from "node:fs/promises";
 import node_path from "node:path";
 import { log } from "@clack/prompts";
-import { P, match } from "ts-pattern";
 import { capitalize, groupBy, isUndefined, omitBy, range, words } from "es-toolkit";
 import { createHash } from "node:crypto";
 import gray_matter from "gray-matter";
@@ -47,6 +47,19 @@ function collectResults(results) {
         []
     ]);
 }
+const THEME_NAMES = [
+    'base',
+    'midnight',
+    'arcade'
+];
+const COLOR_MODES = [
+    'dark',
+    'light',
+    'toggle'
+];
+function resolveDefaultColorMode(theme) {
+    return match(theme).with('base', ()=>'toggle').with('midnight', ()=>'dark').with('arcade', ()=>'dark').exhaustive();
+}
 function defineConfig(config) {
     return config;
 }
@@ -85,6 +98,11 @@ function validateConfig(config) {
         featErr,
         null
     ];
+    const [themeErr] = validateTheme(config.theme);
+    if (themeErr) return [
+        themeErr,
+        null
+    ];
     return [
         null,
         config
@@ -217,6 +235,71 @@ function validateFeature(feature) {
     if (feature.icon && !feature.icon.includes(':')) return configError('invalid_icon', `Feature "${feature.text}": icon must be an Iconify identifier (e.g. "pixelarticons:speed-fast")`);
     return null;
 }
+function validateThemeColors(colors, label) {
+    const colorPattern = /^(?:#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})|rgba?\([^)]*\))$/;
+    const keys = [
+        'brand',
+        'brandLight',
+        'brandDark',
+        'brandSoft',
+        'bg',
+        'bgAlt',
+        'bgElv',
+        'bgSoft',
+        'text1',
+        'text2',
+        'text3',
+        'divider',
+        'border',
+        'homeBg'
+    ];
+    const firstError = keys.reduce((acc, key)=>{
+        if (acc) return acc;
+        const value = colors[key];
+        if (void 0 !== value && !colorPattern.test(value)) return configError('invalid_theme', `theme.${label}.${key}: "${value}" is not a valid color (use hex #xxx/#xxxxxx or rgba())`);
+        return null;
+    }, null);
+    if (firstError) return [
+        firstError,
+        null
+    ];
+    return [
+        null,
+        true
+    ];
+}
+function validateTheme(theme) {
+    if (void 0 === theme) return [
+        null,
+        true
+    ];
+    if (void 0 !== theme.name && !THEME_NAMES.includes(theme.name)) return [
+        configError('invalid_theme', `theme.name: "${theme.name}" is not a valid theme (use ${THEME_NAMES.map((n)=>`"${n}"`).join(', ')})`),
+        null
+    ];
+    if (void 0 !== theme.colorMode && !COLOR_MODES.includes(theme.colorMode)) return [
+        configError('invalid_theme', `theme.colorMode: "${theme.colorMode}" is not valid (use ${COLOR_MODES.map((m)=>`"${m}"`).join(', ')})`),
+        null
+    ];
+    if (theme.colors) {
+        const [colorsErr] = validateThemeColors(theme.colors, 'colors');
+        if (colorsErr) return [
+            colorsErr,
+            null
+        ];
+    }
+    if (theme.darkColors) {
+        const [darkErr] = validateThemeColors(theme.darkColors, 'darkColors');
+        if (darkErr) return [
+            darkErr,
+            null
+        ];
+    }
+    return [
+        null,
+        true
+    ];
+}
 async function config_loadConfig(dir) {
     const { config } = await loadConfig({
         cwd: dir,
@@ -2831,4 +2914,4 @@ function createPaths(dir) {
         cacheDir: node_path.resolve(outputRoot, 'cache')
     };
 }
-export { configError, config_loadConfig as loadConfig, createPaths, defineConfig, generateAssets, generateBannerSvg, generateIconSvg, generateLogoSvg, hasGlobChars, loadManifest, resolveEntries, sync, syncError, validateConfig };
+export { COLOR_MODES, THEME_NAMES, configError, config_loadConfig as loadConfig, createPaths, defineConfig, generateAssets, generateBannerSvg, generateIconSvg, generateLogoSvg, hasGlobChars, loadManifest, resolveDefaultColorMode, resolveEntries, sync, syncError, validateConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zpress/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Config loading, sync engine, and asset utilities for zpress",
   "keywords": [
     "config",