@zc-ui/theme 1.0.0

package/dist/types/presets.d.ts

@@ -0,0 +1,185 @@
+import { PaletteInput } from './color-generator';
+/**
+ * A collection of CSS variable key-value pairs.
+ * Keys are CSS custom property names (e.g. '--color-zc-primary-500').
+ */
+export interface ThemeVariables {
+    [cssVarName: string]: string;
+}
+/**
+ * Component-level override token map.
+ * Each key is a component name (e.g. 'Button'), and the value is
+ * a set of CSS variables scoped to that component.
+ *
+ * Supports two key formats:
+ * 1. **CSS variable names** (prefixed with `--`): `'--zc-button-border-radius': '8px'`
+ * 2. **CamelCase shorthand** (auto-prefixed): `'borderRadius': '8px'`
+ *
+ * @example
+ * ```ts
+ * {
+ *   Button: {
+ *     '--zc-button-border-radius': '8px',
+ *     '--zc-button-font-weight': '600',
+ *   },
+ *   Input: {
+ *     '--zc-input-border-color': '#d9d9d9',
+*   },
+  * }
+* ```
+ */
+export interface ComponentThemeOverrides {
+    [componentName: string]: ThemeVariables;
+}
+/**
+ * Shorthand component override map using camelCase keys.
+ * Each key is converted to `--zc-{componentName}-{kebab-case-key}`.
+ *
+ * @example
+ * ```ts
+ * {
+ *   button: { bgColor: 'red', textColor: '#fff' },
+ *   input: { borderColor: '#d9d9d9' },
+ * }
+ * // Generates:
+ * // Button: { '--zc-button-bg-color': 'red', '--zc-button-text-color': '#fff' }
+ * // Input:  { '--zc-input-border-color': '#d9d9d9' }
+ * ```
+ */
+export type ComponentShorthandOverrides = {
+    [componentName: string]: Record<string, string>;
+};
+/**
+ * A complete theme preset.
+ */
+export interface ThemePreset {
+    /** Unique name for identification */
+    name: string;
+    /** 'light' or 'dark' — determines base background and text colors */
+    mode: 'light' | 'dark';
+    /** Global CSS variables (colors, spacing, typography, etc.) */
+    variables: ThemeVariables;
+    /** Per-component CSS variable overrides */
+    componentOverrides?: ComponentThemeOverrides;
+    /** Optional metadata */
+    meta?: {
+        author?: string;
+        version?: string;
+        description?: string;
+    };
+}
+/**
+ * Options for creating a custom theme preset.
+ */
+export interface CreateThemeOptions {
+    /** Theme name */
+    name?: string;
+    /** Color mode (default: 'light') */
+    mode?: 'light' | 'dark';
+    /**
+     * Brand colors — generates full 50–950 scales automatically.
+     * Any omitted color keeps the default.
+     */
+    brandColors?: PaletteInput;
+    /** Additional CSS variables to set or override */
+    variables?: ThemeVariables;
+    /**
+    * Per-component overrides using full CSS variable names.
+    * @example
+    * ```ts
+    * componentOverrides: {
+    *   Button: { '--zc-button-border-radius': '8px' },
+  * }
+     * ```
+     */
+    componentOverrides?: ComponentThemeOverrides;
+    /**
+     * Per-component overrides using camelCase shorthand.
+     * Each key is auto-converted to `--zc-{component}-{kebab-case-key}`.
+     *
+     * @example
+     * ```ts
+     * components: {
+     *   button: { bgColor: 'red', textColor: '#fff' },
+     * }
+     * // Generates: --zc-button-bg-color: red; --zc-button-text-color: #fff;
+     * ```
+     */
+    components?: ComponentShorthandOverrides;
+    /** Base on an existing preset (default: lightTheme) */
+    extends?: ThemePreset;
+    /** Metadata */
+    meta?: ThemePreset['meta'];
+}
+/**
+ * Convert a shorthand component override map to full CSS variable names.
+ *
+ * Keys that already start with `--` are kept as-is.
+ * CamelCase keys are converted to `--zc-{component}-{kebab-case}`.
+ *
+ * @example
+ * ```ts
+ * componentShorthandToCssVars('button', { bgColor: 'red', '--zc-button-font-size': '16px' })
+ * // => { '--zc-button-bg-color': 'red', '--zc-button-font-size': '16px' }
+ * ```
+ */
+export declare function componentShorthandToCssVars(componentName: string, shorthand: Record<string, string>): ThemeVariables;
+/**
+ * The built-in light theme preset.
+ * Contains all default color scales, semantic tokens, and design tokens.
+ *
+ * Accessing this returns a cached instance — do not mutate it directly.
+ * Use `createTheme({ extends: lightTheme, ... })` to customize.
+ */
+export declare const lightTheme: ThemePreset;
+/**
+ * The built-in dark theme preset.
+ * Contains dark-adapted color scales and semantic tokens.
+ */
+export declare const darkTheme: ThemePreset;
+/**
+ * Create a custom theme preset.
+ *
+ * This function lets you build a theme from brand colors with automatic
+ * color scale generation, while also supporting fine-grained overrides.
+ *
+ * @example
+ * ```ts
+ * const purpleTheme = createTheme({
+ *   name: 'purple-brand',
+ *   brandColors: { primary: '#722ed1' },
+ *   componentOverrides: {
+ *     Button: { '--zc-button-border-radius': '8px' },
+ *   },
+ * })
+ * ```
+ */
+export declare function createTheme(options?: CreateThemeOptions): ThemePreset;
+/**
+ * Merge multiple theme presets into one.
+ * Later presets take precedence over earlier ones.
+ *
+ * @example
+ * ```ts
+ * const customDark = mergeThemes(darkTheme, brandOverride)
+ * ```
+ */
+export declare function mergeThemes(...presets: ThemePreset[]): ThemePreset;
+/**
+ * Get a specific component's override variables from a theme preset.
+ *
+ * @example
+ * ```ts
+ * const buttonVars = getComponentOverrides(theme, 'Button')
+ * ```
+ */
+export declare function getComponentOverrides(theme: ThemePreset, componentName: string): ThemeVariables;
+/**
+ * Convert a theme preset's global variables to a CSS string.
+ *
+ * @param theme The theme preset
+ * @param selector CSS selector (default: ':root')
+ * @returns CSS text with variable declarations
+ */
+export declare function themeToCssText(theme: ThemePreset, selector?: string): string;
+//# sourceMappingURL=presets.d.ts.map

package/dist/types/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../src/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAqC,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAOxF;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,uBAAuB;IACtC,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc,CAAA;CACxC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChD,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,IAAI,EAAE,OAAO,GAAG,MAAM,CAAA;IACtB,+DAA+D;IAC/D,SAAS,EAAE,cAAc,CAAA;IACzB,2CAA2C;IAC3C,kBAAkB,CAAC,EAAE,uBAAuB,CAAA;IAC5C,wBAAwB;IACxB,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,CAAA;CACF;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iBAAiB;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,oCAAoC;IACpC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,YAAY,CAAA;IAC1B,kDAAkD;IAClD,SAAS,CAAC,EAAE,cAAc,CAAA;IAC1B;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,uBAAuB,CAAA;IAC5C;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,2BAA2B,CAAA;IACxC,uDAAuD;IACvD,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,eAAe;IACf,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAC3B;AAyBD;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,cAAc,CAgBhB;AAwJD;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,EAAE,WAWxB,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,WAWvB,CAAA;AAkCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CA4CzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,OAAO,EAAE,WAAW,EAAE,GAAG,WAAW,CAuBlE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,MAAM,GACpB,cAAc,CAEhB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,EAClB,QAAQ,SAAU,GACjB,MAAM,CAMR"}

package/dist/types/runtime-theme.d.ts

@@ -0,0 +1,162 @@
+import { PaletteInput } from './color-generator';
+import { ColorName } from './colors';
+import { ThemePreset, ThemeVariables } from './presets';
+/** Options for runtime theme application */
+export interface ApplyThemeOptions {
+    /** Element to apply variables to (default: document.documentElement) */
+    target?: HTMLElement | null;
+    /** CSS variable prefix (default: '--color-zc') */
+    prefix?: string;
+}
+/**
+ * Register a theme preset by name for later use with `switchTheme()`.
+ *
+ * @example
+ * ```ts
+ * registerTheme('brand', createTheme({ brandColors: { primary: '#722ed1' } }))
+ * registerTheme('dark', darkTheme)
+ *
+ * // Later...
+ * switchTheme('brand')
+ * switchTheme('dark')
+ * ```
+ */
+export declare function registerTheme(name: string, preset: ThemePreset): void;
+/**
+ * Unregister a theme preset.
+ */
+export declare function unregisterTheme(name: string): void;
+/**
+ * Get a registered theme preset by name.
+ */
+export declare function getRegisteredTheme(name: string): ThemePreset | undefined;
+/**
+ * List all registered theme names.
+ */
+export declare function listRegisteredThemes(): string[];
+/**
+ * Switch to a previously registered theme by name.
+ *
+ * @throws Error if the theme is not registered
+ */
+export declare function switchTheme(name: string, options?: ApplyThemeOptions): void;
+/**
+ * Get the name of the currently applied theme (if set via switchTheme).
+ */
+export declare function getCurrentThemeName(): string | null;
+/**
+ * Apply a complete theme preset to the document.
+ *
+ * Sets all CSS variables from the preset on the target element
+ * and toggles the dark mode class.
+ *
+ * @example
+ * ```ts
+ * import { applyTheme, darkTheme } from '@zc-ui/theme'
+ * applyTheme(darkTheme)
+ * ```
+ */
+export declare function applyTheme(preset: ThemePreset, options?: ApplyThemeOptions): void;
+/**
+ * Set a single brand color at runtime.
+ * Automatically generates the full 50–950 color scale.
+ *
+ * @example
+ * ```ts
+ * setBrandColor('primary', '#722ed1')
+ * setBrandColor('danger', '#ff4d4f')
+ * ```
+ */
+export declare function setBrandColor(name: ColorName, hex: string, options?: ApplyThemeOptions): void;
+/**
+ * Set multiple brand colors at runtime.
+ *
+ * @example
+ * ```ts
+ * setBrandColors({
+ *   primary: '#722ed1',
+ *   success: '#52c41a',
+ *   danger: '#ff4d4f',
+ * })
+ * ```
+ */
+export declare function setBrandColors(palette: PaletteInput, options?: ApplyThemeOptions): void;
+/**
+ * Set or update a single CSS variable at runtime.
+ *
+ * @example
+ * ```ts
+ * setThemeVariable('--color-zc-primary-500', '#722ed1')
+ * setThemeVariable('--radius-zc-base', '8px')
+ * ```
+ */
+export declare function setThemeVariable(name: string, value: string, options?: ApplyThemeOptions): void;
+/**
+ * Remove a CSS variable that was set at runtime.
+ */
+export declare function removeThemeVariable(name: string, options?: ApplyThemeOptions): void;
+/**
+ * Apply or remove the dark mode class on an element.
+ *
+ * @param isDark Whether to enable dark mode
+ * @param target Target element (default: document.documentElement)
+ */
+export declare function applyDarkMode(isDark: boolean, target?: HTMLElement | null): void;
+/**
+ * Remove all runtime theme overrides from an element.
+ * Cleans up any CSS variables with the specified prefix.
+ *
+ * @example
+ * ```ts
+ * clearThemeOverrides() // removes all --color-zc-* inline overrides
+ * ```
+ */
+export declare function clearThemeOverrides(options?: ApplyThemeOptions & {
+    prefix?: string;
+}): void;
+/**
+ * Apply a component-level override to a specific element.
+ *
+ * This is used internally by ConfigProvider to scope overrides,
+ * but can also be called directly.
+ *
+ * @example
+ * ```ts
+ * applyComponentOverrides(document.querySelector('.my-section'), 'Button', {
+ *   '--zc-button-border-radius': '8px',
+ * })
+ * ```
+ */
+export declare function applyComponentOverrides(element: HTMLElement, componentName: string, overrides: ThemeVariables): void;
+/**
+ * Remove component-level overrides from an element.
+ */
+export declare function removeComponentOverrides(element: HTMLElement, componentName: string, overrides: ThemeVariables): void;
+/**
+ * Create a reactive theme controller.
+ * Useful for Vue components that need reactive theme switching.
+ *
+ * @example
+ * ```ts
+ * const controller = createThemeController()
+ * controller.apply(darkTheme)
+ * controller.toggleDark()
+ * controller.setBrandColor('primary', '#722ed1')
+ */
+export declare function createThemeController(options?: ApplyThemeOptions): {
+    /** Get the currently applied preset (null if none) */
+    readonly current: ThemePreset | null;
+    /** Apply a full theme preset */
+    apply(preset: ThemePreset): void;
+    /** Set a single brand color */
+    setBrandColor(name: ColorName, hex: string): void;
+    /** Set multiple brand colors */
+    setBrandColors(palette: PaletteInput): void;
+    /** Set a single CSS variable */
+    setVariable(name: string, value: string): void;
+    /** Toggle dark mode */
+    toggleDark(): boolean;
+    /** Clear all runtime overrides */
+    clear(): void;
+};
+//# sourceMappingURL=runtime-theme.d.ts.map

package/dist/types/runtime-theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-theme.d.ts","sourceRoot":"","sources":["../../src/runtime-theme.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@zc-ui/theme",
+  "version": "1.0.0",
+  "description": "ZC UI theme tokens and design variables",
+  "license": "MIT",
+  "author": "ZC UI Team",
+  "homepage": "https://zc-ui.github.io/zc-ui",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zc-ui/zc-ui.git",
+    "directory": "packages/theme"
+  },
+  "bugs": {
+    "url": "https://github.com/zc-ui/zc-ui/issues"
+  },
+  "keywords": [
+    "vue",
+    "ui",
+    "theme",
+    "design-tokens",
+    "css-variables",
+    "zc-ui"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./styles": "./src/styles.css"
+  },
+  "files": [
+    "dist",
+    "src/styles.css"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json"
+  }
+}