@soybeanjs/shadcn-theme 0.0.11 → 0.2.0

package/README.en_US.md

@@ -1,19 +1,18 @@
 # @soybeanjs/shadcn-theme
 
-A powerful and flexible shadcn/ui theme generator with support for dynamic CSS variable injection, preset color schemes, and light/dark mode switching.
+A powerful and flexible shadcn/ui theme CSS variables generator with preset color schemes, light/dark output, and optional custom preset extension.
 
 [中文 README](README.md)
 
 ## ✨ Features
 
-- 🎨 **Rich Preset Themes** - Multiple base palettes, theme colors, and feedback color presets
-- 🌗 **Light/Dark Mode Support** - Built-in dark mode with automatic dark variant generation
-- 🎯 **Flexible Color Schemes** - Support for both HSL and OKLCH color formats
-- 🔧 **Highly Customizable** - Full control over custom theme color configurations
-- 📦 **Zero Runtime Dependencies** - Only depends on `@soybeanjs/colord` for color processing
-- 🚀 **Plug and Play** - Automatically injects CSS variables into the DOM
-- 🎭 **Extended Palettes** - Theme customization support for sidebars, charts, and more
-- 🌈 **Color Palette Generation** - Automatically generates gradient palettes (50-950) for primary colors
+- 🎨 **Rich Preset Themes** - Built-in base / primary / feedback preset combinations
+- 🌗 **Light/Dark Output** - Supports `.dark` / `@media (prefers-color-scheme: dark)` / custom selector
+- 🎯 **Flexible Color Formats** - Supports `hsl` and `oklch` output
+- 🔧 **Extensible** - Add custom colors via `preset` (including sidebar / chart fields)
+- 🌈 **Palette Variables** - Generates 50-950 palette vars for primary/destructive/success/warning/info/carbon
+- 📦 **Lightweight Dependency** - Only depends on `@soybeanjs/colord`
+- 🧩 **Pure Generator** - Returns CSS strings only; does not automatically mutate the DOM
 
 ## 📦 Installation
 
@@ -28,97 +27,238 @@ pnpm add @soybeanjs/shadcn-theme
 ```typescript
 import { createShadcnTheme } from '@soybeanjs/shadcn-theme';
 
-// Use default presets (slate + indigo + classic)
-createShadcnTheme();
+// Use default presets (gray + indigo + classic + extended)
+const theme = createShadcnTheme();
+const css = theme.getCss();
 
 // Custom preset combination
-createShadcnTheme({
-  presets: {
-    base: 'zinc',      // Base palette: stone | zinc | neutral | gray | slate
-    theme: 'blue',     // Theme color: any Tailwind palette name
-    feedback: 'vivid'  // Feedback color style: classic | vivid | subtle | warm | cool, etc.
-  },
-  radius: '0.5rem',    // Border radius size
-  darkSelector: 'class', // Dark mode selector: 'class' | 'media' | custom
-  format: 'hsl'        // Color format: 'hsl' | 'oklch'
+const custom = createShadcnTheme({
+  base: 'zinc',
+  primary: 'blue',
+  feedback: 'vivid',
+  sidebar: 'extended',
+  radius: '0.5rem',
+  darkSelector: 'class',
+  format: 'hsl'
 });
+
+const customCss = custom.getCss();
+```
+
+### (Optional) Inject into the DOM
+
+This library generates CSS strings. If you want runtime theme switching, you can inject the result yourself:
+
+```ts
+import { createShadcnTheme } from '@soybeanjs/shadcn-theme';
+
+const theme = createShadcnTheme({ primary: 'indigo' });
+
+function applyTheme(cssText: string, styleId = 'SHADCN_THEME_STYLE') {
+  const el = document.getElementById(styleId) ?? document.createElement('style');
+  el.id = styleId;
+  el.textContent = cssText;
+  document.head.appendChild(el);
+}
+
+applyTheme(theme.getCss());
+applyTheme(theme.getCss({ primary: 'emerald' }));
 ```
 
-### Custom Theme Colors
+### Custom Preset
+
+Using the `preset` parameter, you can provide a complete custom color configuration that overrides the built-in base/primary/feedback/sidebar presets. When using a custom preset, you need to provide complete color definitions.
+
+#### 1) When to use custom preset
+
+- Use `preset` to provide a complete custom color configuration when built-in preset combinations cannot meet your design requirements.
+- When using a custom preset, all base/primary/feedback/sidebar related parameters will be ignored, only the `preset` configuration is used.
+
+#### 2) Color values and `format`
+
+- Each color value supports: Tailwind palette reference (e.g. `slate.500`), `hsl(...)`, `oklch(...)`, or the builtin permitted color names (`inherit`, `currentColor`, `transparent`, `black`, `white`).
+- `format: 'hsl'`: outputs `h s l [/ alpha]` (no outer `hsl(...)`); `oklch(...)` inputs are converted to HSL.
+- `format: 'oklch'`: outputs values with the outer `oklch(...)`; `hsl(...)` inputs are converted to OKLCH.
+
+#### Quick example: Complete custom preset
 
 ```typescript
-createShadcnTheme({
-  theme: {
+const theme = createShadcnTheme({
+  preset: {
     light: {
-      background: 'oklch(100% 0 0)',
-      foreground: 'oklch(20% 0 0)',
-      primary: 'oklch(50% 0.2 250)',
-      primaryForeground: 'oklch(100% 0 0)',
-      // ... more color configurations
+      // Base colors
+      background: 'white',
+      foreground: 'slate.950',
+      card: 'white',
+      cardForeground: 'slate.950',
+      popover: 'white',
+      popoverForeground: 'slate.950',
+      primaryForeground: 'slate.50',
+      secondary: 'slate.100',
+      secondaryForeground: 'slate.900',
+      muted: 'slate.100',
+      mutedForeground: 'slate.500',
+      accent: 'slate.100',
+      accentForeground: 'slate.900',
+      destructiveForeground: 'slate.50',
+      successForeground: 'slate.50',
+      warningForeground: 'slate.50',
+      infoForeground: 'slate.50',
+      carbon: 'slate.800',
+      carbonForeground: 'slate.50',
+      border: 'slate.200',
+      input: 'slate.200',
+      // Theme colors
+      primary: 'blue.600',
+      destructive: 'red.500',
+      success: 'green.500',
+      warning: 'amber.500',
+      info: 'blue.500',
+      ring: 'blue.400',
+      // Chart colors
+      chart1: 'orange.600',
+      chart2: 'teal.600',
+      chart3: 'cyan.900',
+      chart4: 'amber.400',
+      chart5: 'amber.500',
+      // Sidebar colors
+      sidebar: 'slate.50',
+      sidebarForeground: 'slate.900',
+      sidebarPrimary: 'blue.600',
+      sidebarPrimaryForeground: 'slate.50',
+      sidebarAccent: 'slate.100',
+      sidebarAccentForeground: 'slate.900',
+      sidebarBorder: 'slate.200',
+      sidebarRing: 'blue.400'
     },
     dark: {
-      // Optional, will automatically generate dark variants if not provided
-      background: 'oklch(20% 0 0)',
-      foreground: 'oklch(100% 0 0)',
-      // ...
+      // Base colors
+      background: 'slate.950',
+      foreground: 'slate.50',
+      card: 'slate.900',
+      cardForeground: 'slate.50',
+      popover: 'slate.900',
+      popoverForeground: 'slate.50',
+      primaryForeground: 'slate.900',
+      secondary: 'slate.800',
+      secondaryForeground: 'slate.50',
+      muted: 'slate.800',
+      mutedForeground: 'slate.400',
+      accent: 'slate.800',
+      accentForeground: 'slate.50',
+      destructiveForeground: 'slate.900',
+      successForeground: 'slate.900',
+      warningForeground: 'slate.900',
+      infoForeground: 'slate.900',
+      carbon: 'slate.100',
+      carbonForeground: 'slate.900',
+      border: 'oklch(100% 0 0 / 0.1)',
+      input: 'oklch(100% 0 0 / 0.15)',
+      // Theme colors
+      primary: 'blue.400',
+      destructive: 'red.400',
+      success: 'green.400',
+      warning: 'amber.400',
+      info: 'blue.400',
+      ring: 'blue.500',
+      // Chart colors
+      chart1: 'orange.500',
+      chart2: 'teal.500',
+      chart3: 'cyan.400',
+      chart4: 'amber.500',
+      chart5: 'amber.600',
+      // Sidebar colors
+      sidebar: 'slate.950',
+      sidebarForeground: 'slate.50',
+      sidebarPrimary: 'blue.400',
+      sidebarPrimaryForeground: 'slate.950',
+      sidebarAccent: 'slate.900',
+      sidebarAccentForeground: 'slate.50',
+      sidebarBorder: 'slate.800',
+      sidebarRing: 'blue.500'
     }
   }
 });
+
+const css = theme.getCss();
 ```
 
+#### Notes
+
+- When providing the `preset` parameter, the `base`, `primary`, `feedback`, and `sidebar` parameters will be ignored.
+- The preset must include complete color definitions for both `light` and `dark` modes.
+- It is recommended to start from the structure of built-in presets and modify according to your design needs.
+
 ## 📖 API Documentation
 
 ### `createShadcnTheme(options?: ThemeOptions)`
 
-Main function to create and apply themes.
+Main function to create a theme CSS generator.
+
+Return value:
+
+```ts
+const theme = createShadcnTheme();
+
+theme.getCss(config?: PresetConfig, radius?: string): string
+theme.getColorCss(config: PresetConfig): string
+theme.getRadiusCss(radius?: string): string
+```
 
 #### ThemeOptions
 
-| Parameter | Type | Default | Description |
-|------|------|--------|------|
-| `presets` | `PresetConfig` | - | Preset configuration, takes priority over `theme` |
-| `theme` | `ThemeConfig` | - | Custom theme color configuration |
-| `radius` | `string` | `'0.625rem'` | Global border radius size |
-| `styleId` | `string` | `'SHADCN_THEME_STYLES'` | ID of the injected style tag |
-| `styleTarget` | `'html' \| ':root'` | `':root'` | CSS variable mount target |
-| `darkSelector` | `string` | `'class'` | Dark mode selector |
-| `format` | `'hsl' \| 'oklch'` | `'hsl'` | Color output format |
+| Parameter      | Type                           | Default      | Description                                                                             |
+| -------------- | ------------------------------ | ------------ | --------------------------------------------------------------------------------------- |
+| `base`         | `BuiltinBasePresetKey`         | `'neutral'`  | Base preset key                                                                         |
+| `primary`      | `BuiltinPrimaryPresetKey`      | `'indigo'`   | Primary preset key                                                                      |
+| `feedback`     | `BuiltinFeedbackPresetKey`     | `'classic'`  | Feedback preset key                                                                     |
+| `sidebar`      | `'extended'`                   | `'extended'` | Sidebar mode; `extended` derives from base/primary                                      |
+| `preset`       | `ThemeColorPresetItem`         | -            | Complete custom color preset (when provided, base/primary/feedback/sidebar are ignored) |
+| `radius`       | `string`                       | `'0.625rem'` | Global border radius                                                                    |
+| `styleTarget`  | `'html' \| ':root'`            | `':root'`    | CSS variables mount selector                                                            |
+| `darkSelector` | `'class' \| 'media' \| string` | `'class'`    | Dark mode selector (custom string supported)                                            |
+| `format`       | `'hsl' \| 'oklch'`             | `'hsl'`      | Output color format                                                                     |
 
 ### Preset Configuration (PresetConfig)
 
 ```typescript
 interface PresetConfig {
-  base?: 'stone' | 'zinc' | 'neutral' | 'gray' | 'slate';  // Default: 'slate'
-  theme?: TailwindPaletteKey;  // Any Tailwind palette, default: 'indigo'
-  feedback?: FeedbackPaletteKey;  // Feedback color style, default: 'classic'
+  base?: BuiltinBasePresetKey | 'custom';
+  primary?: BuiltinPrimaryPresetKey | 'custom';
+  feedback?: BuiltinFeedbackPresetKey | 'custom';
+  sidebar?: 'extended' | 'custom';
+  preset?: ThemeColorPresetItem;
 }
 ```
 
+When using the `preset` parameter, other configuration parameters (base/primary/feedback/sidebar) will be ignored.
+
 #### Feedback Palette Key (FeedbackPaletteKey)
 
-| Style | Description | Use Cases |
-|------|------|----------|
-| `classic` | Classic Standard | Most common combination, suitable for most scenarios |
-| `vivid` | Vivid & Energetic | High saturation, suitable for youth-oriented products and creative applications |
-| `subtle` | Soft & Elegant | Low contrast, suitable for premium brands and elegant interfaces |
-| `warm` | Warm & Welcoming | Warm color tones, creates a friendly and warm atmosphere |
-| `cool` | Cool & Professional | Cool color tones, suitable for tech and professional applications |
-| `nature` | Natural & Fresh | Natural colors, suitable for eco-friendly and health products |
-| `modern` | Modern & Minimalist | Strong modern feel, suitable for tech products and SaaS applications |
-| `vibrant` | Vibrant & Dynamic | High-energy colors, suitable for sports and gaming applications |
-| `professional` | Business Professional | Stable and dignified, suitable for enterprise applications and B2B products |
-| `soft` | Dreamy & Soft | Soft tones, suitable for design tools and creative platforms |
-| `bold` | Bold & Eye-catching | High contrast, suitable for scenarios requiring strong visual impact |
-| `calm` | Calm & Soothing | Low saturation, suitable for long-term use applications |
-| `candy` | Candy Colors | Bright and cute, suitable for children's products and fun applications |
-| `deep` | Deep & Mysterious | Deep tones, suitable for dark themes and mysterious styles |
-| `light` | Fresh & Light | Light tones, suitable for clean and refreshing interfaces |
+| Style          | Description           | Use Cases                                                                       |
+| -------------- | --------------------- | ------------------------------------------------------------------------------- |
+| `classic`      | Classic Standard      | Most common combination, suitable for most scenarios                            |
+| `vivid`        | Vivid & Energetic     | High saturation, suitable for youth-oriented products and creative applications |
+| `subtle`       | Soft & Elegant        | Low contrast, suitable for premium brands and elegant interfaces                |
+| `warm`         | Warm & Welcoming      | Warm color tones, creates a friendly and warm atmosphere                        |
+| `cool`         | Cool & Professional   | Cool color tones, suitable for tech and professional applications               |
+| `nature`       | Natural & Fresh       | Natural colors, suitable for eco-friendly and health products                   |
+| `modern`       | Modern & Minimalist   | Strong modern feel, suitable for tech products and SaaS applications            |
+| `vibrant`      | Vibrant & Dynamic     | High-energy colors, suitable for sports and gaming applications                 |
+| `professional` | Business Professional | Stable and dignified, suitable for enterprise applications and B2B products     |
+| `soft`         | Dreamy & Soft         | Soft tones, suitable for design tools and creative platforms                    |
+| `bold`         | Bold & Eye-catching   | High contrast, suitable for scenarios requiring strong visual impact            |
+| `calm`         | Calm & Soothing       | Low saturation, suitable for long-term use applications                         |
+| `candy`        | Candy Colors          | Bright and cute, suitable for children's products and fun applications          |
+| `deep`         | Deep & Mysterious     | Deep tones, suitable for dark themes and mysterious styles                      |
+| `light`        | Fresh & Light         | Light tones, suitable for clean and refreshing interfaces                       |
 
 ### Theme Color Configuration (ThemeColors)
 
 Supports configuration of the following color variables:
 
 #### Base Colors
+
 - `background` - Background color
 - `foreground` - Foreground color (text)
 - `card` - Card background
@@ -140,12 +280,14 @@ Supports configuration of the following color variables:
 - `ring` - Focus ring color
 
 #### Extended Colors
+
 - `success` / `successForeground` - Success state
 - `warning` / `warningForeground` - Warning state
 - `info` / `infoForeground` - Info state
 - `carbon` / `carbonForeground` - Carbon color (additional dark scheme)
 
 #### Sidebar Colors
+
 - `sidebar` - Sidebar background
 - `sidebarForeground` - Sidebar foreground
 - `sidebarPrimary` - Sidebar primary color
@@ -156,6 +298,7 @@ Supports configuration of the following color variables:
 - `sidebarRing` - Sidebar focus ring
 
 #### Chart Colors
+
 - `chart1` ~ `chart5` - Chart colors
 
 ### Color Value Format (ColorValue)
@@ -163,22 +306,25 @@ Supports configuration of the following color variables:
 Supports three color value formats:
 
 1. **HSL Format**
+
 ```typescript
-'hsl(0 0% 100%)'
-'hsl(0 0% 100% / 0.5)' // with opacity
+'hsl(0 0% 100%)';
+'hsl(0 0% 100% / 0.5)'; // with opacity
 ```
 
 2. **OKLCH Format**
+
 ```typescript
-'oklch(100% 0 0)'
-'oklch(100% 0 0 / 0.5)' // with opacity
+'oklch(100% 0 0)';
+'oklch(100% 0 0 / 0.5)'; // with opacity
 ```
 
 3. **Tailwind Palette Reference**
+
 ```typescript
-'slate.500'
-'blue.600'
-'red.50'
+'slate.500';
+'blue.600';
+'red.50';
 ```
 
 ## 🎨 Usage Examples
@@ -186,78 +332,75 @@ Supports three color value formats:
 ### Example 1: Classic Blue Theme
 
 ```typescript
-createShadcnTheme({
-  presets: {
-    base: 'slate',
-    theme: 'blue',
-    feedback: 'classic'
-  },
+const theme = createShadcnTheme({
+  base: 'slate',
+  primary: 'blue',
+  feedback: 'classic',
   radius: '0.5rem',
   darkSelector: 'class'
 });
+
+const css = theme.getCss();
 ```
 
 ### Example 2: Modern Purple Theme
 
 ```typescript
-createShadcnTheme({
-  presets: {
-    base: 'zinc',
-    theme: 'violet',
-    feedback: 'modern'
-  },
+const theme = createShadcnTheme({
+  base: 'zinc',
+  primary: 'violet',
+  feedback: 'modern',
   radius: '0.75rem',
   darkSelector: 'class',
   format: 'oklch'
 });
+
+const css = theme.getCss();
 ```
 
-### Example 3: Custom Brand Colors
+### Example 3: Override Per Generation
 
 ```typescript
-createShadcnTheme({
-  theme: {
-    light: {
-      background: 'oklch(100% 0 0)',
-      foreground: 'oklch(20% 0 0)',
-      primary: 'oklch(50% 0.25 280)', // Custom brand purple
-      primaryForeground: 'oklch(100% 0 0)',
-      secondary: 'oklch(95% 0.01 280)',
-      secondaryForeground: 'oklch(30% 0 0)',
-      // ... other colors
-    }
-    // dark is optional, will be auto-generated if not provided
-  }
-});
+const theme = createShadcnTheme({ base: 'slate', primary: 'indigo', feedback: 'classic' });
+
+const css1 = theme.getCss();
+const css2 = theme.getCss({ primary: 'emerald', feedback: 'vivid' });
 ```
 
 ### Example 4: Media Query Dark Mode
 
 ```typescript
-createShadcnTheme({
-  presets: {
-    base: 'slate',
-    theme: 'indigo'
-  },
+const theme = createShadcnTheme({
+  base: 'slate',
+  primary: 'indigo',
   darkSelector: 'media' // Use system preference
 });
+
+const css = theme.getCss();
 ```
 
 ### Example 5: Custom Dark Mode Selector
 
 ```typescript
-createShadcnTheme({
-  presets: {
-    base: 'slate',
-    theme: 'emerald'
-  },
+const theme = createShadcnTheme({
+  base: 'slate',
+  primary: 'emerald',
   darkSelector: '[data-theme="dark"]' // Custom selector
 });
+
+const css = theme.getCss();
 ```
 
 ## 🎯 Generated CSS Variables
 
-After calling `createShadcnTheme()`, a `<style>` tag containing the following variables will be automatically injected into `<head>`:
+`getCss()` returns a CSS string containing variables like the following.
+
+When `format: 'hsl'`, variable values are `h s l [/ alpha]` (without the outer `hsl(...)` wrapper):
+
+Notes:
+
+- When `format: 'hsl'` and the color key is `border`, `input`, or `sidebarBorder`, if the value includes opacity (e.g. `hsl(... / 0.1)` or `oklch(... / 0.1)`), the library also emits alpha variables: `--border-alpha`, `--input-alpha`, `--sidebar-border-alpha`. Meanwhile `--border` / `--input` / `--sidebar-border` keep only the `h s l` part (without the `/ alpha`).
+- It generates 11 palette variables (50-950) for `primary`, `destructive`, `success`, `warning`, `info`, and `carbon`: `50/100/200/300/400/500/600/700/800/900/950`.
 
 ```css
 :root {
@@ -265,9 +408,13 @@ After calling `createShadcnTheme()`, a `<style>` tag containing the following va
   --background: 0 0% 100%;
   --foreground: 222.2 84% 4.9%;
   --primary: 221.2 83.2% 53.3%;
+
+  /* In hsl mode: border/input/sidebarBorder also output alpha vars */
+  --border: 214.3 31.8% 91.4%;
+  --border-alpha: 0.1;
   /* ... more variables */
 
-  /* Auto-generated palettes */
+  /* Auto-generated palettes (11 levels: 50-950) */
   --primary-50: 239 84% 97%;
   --primary-100: 237 84% 94%;
   /* ... primary-200 to primary-950 */
@@ -287,23 +434,36 @@ After calling `createShadcnTheme()`, a `<style>` tag containing the following va
 }
 ```
 
+When `format: 'oklch'`, variable values include the outer `oklch(...)` wrapper:
+
+```css
+:root {
+  --background: oklch(100% 0 0);
+  --foreground: oklch(20% 0 0);
+  --border: oklch(100% 0 0 / 0.1);
+}
+```
+
 ## 💡 Advanced Usage
 
 ### Dynamic Theme Switching
 
 ```typescript
-// Switch to light theme
-createShadcnTheme({
-  presets: { base: 'slate', theme: 'blue' }
-});
+const theme = createShadcnTheme();
+
+function apply(cssText: string) {
+  const id = 'SHADCN_THEME_STYLE';
+  const el = document.getElementById(id) ?? document.createElement('style');
+  el.id = id;
+  el.textContent = cssText;
+  document.head.appendChild(el);
+}
 
-// Runtime switch to dark theme (by toggling class)
-document.documentElement.classList.add('dark');
+apply(theme.getCss());
+apply(theme.getCss({ base: 'zinc', primary: 'purple' }));
 
-// Switch to another theme
-createShadcnTheme({
-  presets: { base: 'zinc', theme: 'purple' }
-});
+// Dark mode switching is controlled by your darkSelector (e.g. default is adding .dark)
+document.documentElement.classList.add('dark');
 ```
 
 ### Using with Tailwind CSS
@@ -321,19 +481,42 @@ module.exports = {
           DEFAULT: 'hsl(var(--primary))',
           foreground: 'hsl(var(--primary-foreground))',
           50: 'hsl(var(--primary-50))',
-          100: 'hsl(var(--primary-100))',
+          100: 'hsl(var(--primary-100))'
           // ... more shades
-        },
+        }
         // ... other colors
       },
       borderRadius: {
         lg: 'var(--radius)',
         md: 'calc(var(--radius) - 2px)',
-        sm: 'calc(var(--radius) - 4px)',
+        sm: 'calc(var(--radius) - 4px)'
       }
     }
   }
-}
+};
+```
+
+When you use `format: 'hsl'`, opacity must be handled separately, especially for `border` / `input` / `sidebarBorder`:
+
+- These variables output `h s l` (without `/ alpha`). If opacity is present, the library also emits `--border-alpha` / `--input-alpha` / `--sidebar-border-alpha`.
+- In Tailwind, you can compose them using the slash syntax:
+
+```js
+// Use the generated alpha value
+border: 'hsl(var(--border) / var(--border-alpha))';
+```
+
+If you want Tailwind opacity modifiers to work (e.g. `border-border/50`), use the `<alpha-value>` placeholder (in this case you typically don't use `--border-alpha`):
+
+```js
+// Let Tailwind inject opacity
+border: 'hsl(var(--border) / <alpha-value>)';
+```
+
+If you use `format: 'oklch'`, since the variable value already contains `oklch(...)`, use `var(--xxx)` directly in Tailwind (no extra `oklch(...)` wrapper needed):
+
+```js
+background: 'var(--background)';
 ```
 
 ### Using in CSS