@zpress/core 0.3.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;
 }
 
@@ -98,21 +108,15 @@ export declare type ConfigResult<T> = readonly [ConfigError, null] | readonly [n
 export declare function createPaths(dir: string): Paths;
 
 /**
- * Type-safe config helper with validation.
- *
- * Validates the config structure and exits with a clear error message
- * if any issues are found. This is the primary entry point for user-
- * provided config — validation happens at the boundary.
+ * Type-safe config helper for user config files.
  *
- * `defineConfig` is called in user config files (e.g. `zpress.config.ts`)
- * where the return value is consumed by the c12 config loader, which
- * expects a plain `ZpressConfig` object — not a `Result` tuple.
- * Because this is the outermost user-facing boundary (not a library
- * function), `process.exit(1)` is acceptable here: the user must fix
- * their config before any downstream code can run.
+ * This is a passthrough that provides type safety and editor
+ * autocompletion in `zpress.config.ts`. Validation is deferred to
+ * `loadConfig` at CLI runtime, so errors surface with structured
+ * feedback rather than a raw `process.exit`.
  *
  * @param config - Raw zpress config object
- * @returns The validated config (unchanged)
+ * @returns The config (unchanged)
  */
 export declare function defineConfig(config: ZpressConfig): ZpressConfig;
 
@@ -251,6 +255,11 @@ export declare interface Entry {
      * @default "overview"
      */
     readonly indexFile?: string;
+    /**
+     * Iconify icon identifier (e.g. `"pixelarticons:speed-fast"`).
+     * Used on home page feature cards when auto-generated from sections.
+     */
+    readonly icon?: string;
     /**
      * Card display metadata for the parent section's auto-generated landing page.
      *
@@ -395,10 +404,14 @@ declare type GlobPattern = string;
 export declare function hasGlobChars(s: string): boolean;
 
 /**
- * Load zpress config at runtime via c12.
+ * Load and validate zpress config at runtime via c12.
+ *
+ * Returns a `ConfigResult` tuple — the CLI boundary is responsible for
+ * surfacing any error and exiting. Validation runs here (not in
+ * `defineConfig`) so every consumer gets structured error feedback.
  *
- * Returns a `ConfigResult` tuple instead of calling `process.exit` — the
- * CLI boundary is responsible for surfacing the error and exiting.
+ * @param dir - Repository root directory to search for `zpress.config.*`
+ * @returns A `ConfigResult` tuple — `[null, config]` on success or `[ConfigError, null]` on failure
  */
 export declare function loadConfig(dir: string): Promise<ConfigResult<ZpressConfig>>;
 
@@ -510,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.
  */
@@ -747,11 +768,86 @@ 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"`)
  */
 declare type UrlPath = string;
 
+/**
+ * Validate the entire config, returning the first error found.
+ *
+ * @param config - Raw zpress config object to validate
+ * @returns A `ConfigResult` tuple — `[null, config]` on success or `[ConfigError, null]` on failure
+ */
+export declare function validateConfig(config: ZpressConfig): ConfigResult<ZpressConfig>;
+
 /**
  * A named group of workspace items for custom workspace categories.
  *
@@ -906,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,12 +47,20 @@ 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) {
-    const [err] = validateConfig(config);
-    if (err) {
-        process.stderr.write(`[zpress] ${err.message}\n`);
-        process.exit(1);
-    }
     return config;
 }
 function validateConfig(config) {
@@ -90,6 +98,11 @@ function validateConfig(config) {
         featErr,
         null
     ];
+    const [themeErr] = validateTheme(config.theme);
+    if (themeErr) return [
+        themeErr,
+        null
+    ];
     return [
         null,
         config
@@ -222,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,
@@ -235,10 +313,7 @@ async function config_loadConfig(dir) {
         configError('empty_sections', 'Failed to load zpress.config — no sections found'),
         null
     ];
-    return [
-        null,
-        config
-    ];
+    return validateConfig(config);
 }
 const FIGLET_CHARS = Object.freeze({
     A: [
@@ -1429,7 +1504,7 @@ function buildFeatures(sections, repoRoot) {
     return Promise.all(sections.slice(0, 3).map(async (section, index)=>{
         const link = section.link ?? findFirstChildLink(section);
         const details = await extractSectionDescription(section, repoRoot);
-        const iconId = null;
+        const iconId = section.icon ?? null;
         const iconColor = ICON_COLORS[index % ICON_COLORS.length];
         return {
             title: section.text,
@@ -2839,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 };
+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.3.0",
+  "version": "0.5.0",
   "description": "Config loading, sync engine, and asset utilities for zpress",
   "keywords": [
     "config",