@djangocfg/ui-core 2.1.209 → 2.1.210

package/README.md

@@ -65,35 +65,58 @@ pnpm add @djangocfg/ui-core
 
 ## Theme Palette Hooks
 
-Hooks for accessing theme colors from CSS variables (useful for charts, diagrams, etc.):
+Hooks for accessing theme colors from CSS variables (useful for Canvas, SVG, charts, diagrams, etc.):
 
-| Hook | Description |
-|------|-------------|
-| `useThemePalette()` | Full color palette from CSS variables |
-| `useStylePresets()` | Pre-built style configs for diagrams |
-| `useBoxColors()` | Colors for boxes/containers |
+| Hook / Util | Description |
+|-------------|-------------|
+| `useThemePalette()` | Full hex color palette from CSS variables |
+| `useThemeColor(var, opacity?)` | Single color by CSS var name — lighter alternative |
+| `useStylePresets()` | Pre-built `{ fill, stroke, color }` configs for diagrams |
+| `useBoxColors()` | Semi-transparent RGBA colors for boxes/containers |
+| `alpha(hex, opacity)` | Convert hex color to `rgba()` string |
 
 ```tsx
-import { useStylePresets, useBoxColors } from '@djangocfg/ui-core/styles/palette';
+import {
+  useThemePalette,
+  useThemeColor,
+  useStylePresets,
+  useBoxColors,
+  alpha,
+} from '@djangocfg/ui-core/styles/palette';
+
+function MyCanvas() {
+  const palette = useThemePalette();
+
+  // Use in Canvas / inline styles
+  ctx.fillStyle = palette.primary;            // '#a855f7' (theme-aware)
+  ctx.fillStyle = alpha(palette.primary, 0.3); // 'rgba(168, 85, 247, 0.3)'
+}
+
+function MyWaveform() {
+  // Lighter: only subscribes to 'primary', not the entire palette
+  const primary         = useThemeColor('primary');        // '#a855f7'
+  const primaryFaded    = useThemeColor('primary', 0.3);   // 'rgba(168, 85, 247, 0.3)'
+  const errorBackground = useThemeColor('destructive', 0.1);
+}
 
 function MyChart() {
   const presets = useStylePresets();
-  // presets.success = { fill: '#22c55e', stroke: '#16a34a', color: '#ffffff' }
-  // presets.warning = { fill: '#f59e0b', stroke: '#d97706', color: '#000000' }
-  // presets.danger = { fill: '#ef4444', stroke: '#dc2626', color: '#ffffff' }
-  // presets.info = { fill: '#3b82f6', stroke: '#2563eb', color: '#ffffff' }
-  // presets.primary = { fill: '#...', stroke: '#...', color: '#...' }
+  // presets.primary = { fill: '#a855f7', stroke: '#a855f7', color: '#fff' }
+  // presets.success = { fill: '#22c55e', stroke: '#22c55e', color: '#fff' }
+  // presets.danger  = { fill: '#ef4444', stroke: '#ef4444', color: '#fff' }
+  // presets.warning = { fill: '#f59e0b', stroke: '#f59e0b', color: '#fff' }
+  // presets.info    = { fill: '#3b82f6', stroke: '#3b82f6', color: '#fff' }
 
   const boxes = useBoxColors();
-  // boxes.primary = 'rgba(59, 130, 246, 0.2)'
-  // boxes.success = 'rgba(34, 197, 94, 0.2)'
+  // boxes.primary = 'rgba(168, 85, 247, 0.15)'  (0.3 in dark mode)
+  // boxes.success = 'rgba(34, 197, 94, 0.15)'
   // etc.
 
   return <Chart colors={[presets.success.fill, presets.warning.fill]} />;
 }
 ```
 
-### Color Utilities
+### Color Utilities (HSL conversion)
 
 ```tsx
 import { hslToHex, hslToRgbString, hslToRgba } from '@djangocfg/ui-core/styles/palette';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.209",
+  "version": "2.1.210",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -81,7 +81,7 @@
     "playground": "playground dev"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.209",
+    "@djangocfg/i18n": "^2.1.210",
     "react-device-detect": "^2.2.3",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -143,9 +143,9 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.209",
+    "@djangocfg/i18n": "^2.1.210",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.209",
+    "@djangocfg/typescript-config": "^2.1.210",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/styles/README.md

@@ -11,6 +11,11 @@ styles/
 ├── base.css         # Base element styles
 ├── utilities.css    # Custom utility classes
 ├── sources.css      # Source detection for Tailwind v4 monorepo
+├── palette/         # Theme palette hooks & utilities
+│   ├── index.ts     # Exports
+│   ├── types.ts     # ThemePalette, StylePresets, BoxColors interfaces
+│   ├── useThemePalette.ts  # useThemePalette, useStylePresets, useBoxColors, alpha
+│   └── utils.ts     # hslToHex, hslToRgbString, hslToRgba
 └── theme/
     ├── tokens.css   # @theme block with CSS custom properties
     ├── light.css    # Light theme variables
@@ -204,6 +209,51 @@ Z-index utilities (`z-50`, `z-100`) require `--z-index-*` variables:
 <div className="aspect-square rounded-full overflow-hidden w-10 h-10">
 ```
 
+## Theme Palette (Programmatic Color Access)
+
+For Canvas, SVG, Mermaid, and other contexts that don't support CSS variables, use the palette hooks:
+
+```tsx
+import {
+  useThemePalette,
+  useStylePresets,
+  useBoxColors,
+  alpha,
+} from '@djangocfg/ui-core/styles/palette';
+
+// Hex colors from CSS variables (updates on theme switch)
+const palette = useThemePalette();
+ctx.fillStyle = palette.primary;              // '#a855f7'
+ctx.fillStyle = alpha(palette.primary, 0.3); // 'rgba(168, 85, 247, 0.3)'
+
+// Pre-built { fill, stroke, color } for diagrams
+const presets = useStylePresets();
+presets.success // { fill: '#22c55e', stroke: '#22c55e', color: '#fff' }
+presets.danger  // { fill: '#ef4444', stroke: '#ef4444', color: '#fff' }
+
+// Semi-transparent backgrounds (adapts opacity to light/dark)
+const boxes = useBoxColors();
+boxes.primary // 'rgba(168, 85, 247, 0.15)' in light, 0.3 in dark
+```
+
+### `alpha(hex, opacity)`
+
+Convert any hex color to `rgba()` — works with any value from `ThemePalette`:
+
+```tsx
+alpha(palette.primary, 0.3)    // 'rgba(168, 85, 247, 0.3)'
+alpha(palette.destructive, 0.1) // useful for error backgrounds
+```
+
+### Raw HSL Utilities
+
+```tsx
+import { hslToHex, hslToRgbString, hslToRgba } from '@djangocfg/ui-core/styles/palette';
+
+hslToHex('265 89% 78%')        // '#c084fc'
+hslToRgba('265 89% 78%', 0.2) // 'rgba(192, 132, 252, 0.2)'
+```
+
 ## What to Avoid
 
 - Custom utilities like: `section-padding`, `animate-*`, `shadow-brand`

package/src/styles/palette/index.ts

@@ -45,6 +45,8 @@ export {
   useThemePalette,
   useStylePresets,
   useBoxColors,
+  useThemeColor,
+  alpha,
 } from './useThemePalette';
 
 // Utils (for advanced use)

package/src/styles/palette/useThemePalette.ts

@@ -11,19 +11,53 @@
 
 import { useMemo } from 'react';
 import { useResolvedTheme } from '../../hooks/useResolvedTheme';
-import { hslToHex, hslToRgba } from './utils';
+import { hslToHex } from './utils';
 import type { ThemePalette, StylePresets, BoxColors } from './types';
 
 /**
- * Read a CSS variable from document and convert to hex
+ * SSR-safe fallback palette (light theme defaults).
+ * Used when document is not available (server-side rendering).
+ */
+const SSR_FALLBACK: Record<string, string> = {
+  'background':           '#f5f5f5',
+  'foreground':           '#171717',
+  'card':                 '#ffffff',
+  'card-foreground':      '#171717',
+  'popover':              '#ffffff',
+  'popover-foreground':   '#171717',
+  'muted':                '#e5e5e5',
+  'muted-foreground':     '#737373',
+  'border':               '#e5e5e5',
+  'input':                '#e5e5e5',
+  'ring':                 '#3b82f6',
+  'primary':              '#3b82f6',
+  'primary-foreground':   '#ffffff',
+  'secondary':            '#f5f5f5',
+  'secondary-foreground': '#171717',
+  'accent':               '#f5f5f5',
+  'accent-foreground':    '#171717',
+  'destructive':          '#ef4444',
+  'destructive-foreground': '#ffffff',
+  'chart-1':              '#3b82f6',
+  'chart-2':              '#22c55e',
+  'chart-3':              '#8b5cf6',
+  'chart-4':              '#f59e0b',
+  'chart-5':              '#ef4444',
+};
+
+/**
+ * Read a CSS variable from document and convert to hex.
+ * Falls back to SSR_FALLBACK on the server.
  */
 function getCssColorAsHex(varName: string): string {
-  if (typeof document === 'undefined') return '#000000';
+  if (typeof document === 'undefined') {
+    return SSR_FALLBACK[varName] ?? '#000000';
+  }
 
   const style = getComputedStyle(document.documentElement);
   const value = style.getPropertyValue(`--${varName}`).trim();
 
-  if (!value) return '#000000';
+  if (!value) return SSR_FALLBACK[varName] ?? '#000000';
 
   // If already hex, return as-is
   if (value.startsWith('#')) return value;
@@ -32,35 +66,31 @@ function getCssColorAsHex(varName: string): string {
   return hslToHex(value);
 }
 
+
 /**
- * Read a CSS variable from document and convert to rgba with opacity
+ * Convert a hex color to rgba string with given opacity.
+ * Works with any hex returned from ThemePalette.
+ *
+ * @example
+ * const palette = useThemePalette();
+ * ctx.fillStyle = alpha(palette.primary, 0.3);
  */
-function getCssColorAsRgba(varName: string, alpha: number): string {
-  if (typeof document === 'undefined') return `rgba(0, 0, 0, ${alpha})`;
-
-  const style = getComputedStyle(document.documentElement);
-  const value = style.getPropertyValue(`--${varName}`).trim();
-
-  if (!value) return `rgba(0, 0, 0, ${alpha})`;
-
-  return hslToRgba(value, alpha);
+export function alpha(hexColor: string, opacity: number): string {
+  const hex = hexColor.replace('#', '');
+  const r = parseInt(hex.substring(0, 2), 16);
+  const g = parseInt(hex.substring(2, 4), 16);
+  const b = parseInt(hex.substring(4, 6), 16);
+  return `rgba(${r}, ${g}, ${b}, ${opacity})`;
 }
 
 /**
- * Hook to get the full theme palette from CSS variables
+ * Hook to get the full theme palette from CSS variables.
+ * Returns hex colors for use in Canvas, SVG, Mermaid, and inline styles.
  *
  * @example
- * ```tsx
- * function MyComponent() {
- *   const palette = useThemePalette();
- *
- *   // Use in canvas
- *   ctx.fillStyle = palette.primary;
- *
- *   // Use in inline styles
- *   <div style={{ backgroundColor: palette.success }} />
- * }
- * ```
+ * const palette = useThemePalette();
+ * ctx.fillStyle = palette.primary;
+ * ctx.fillStyle = alpha(palette.primary, 0.3);
  */
 export function useThemePalette(): ThemePalette {
   const theme = useResolvedTheme();
@@ -216,18 +246,43 @@ export function useStylePresets(): StylePresets {
  */
 export function useBoxColors(): BoxColors {
   const theme = useResolvedTheme();
+  const palette = useThemePalette();
 
   return useMemo(() => {
-    // Semi-transparent backgrounds for boxes
-    const alpha = theme === 'dark' ? 0.3 : 0.15;
+    const opacity = theme === 'dark' ? 0.3 : 0.15;
 
     return {
-      primary: getCssColorAsRgba('primary', alpha),
-      success: getCssColorAsRgba('chart-2', alpha),
-      warning: getCssColorAsRgba('chart-4', alpha),
-      danger: getCssColorAsRgba('destructive', alpha),
-      info: getCssColorAsRgba('chart-3', alpha),
-      muted: getCssColorAsRgba('muted', alpha),
+      primary: alpha(palette.primary, opacity),
+      success: alpha(palette.success, opacity),
+      warning: alpha(palette.warning, opacity),
+      danger: alpha(palette.destructive, opacity),
+      info: alpha(palette.info, opacity),
+      muted: alpha(palette.muted, opacity),
     };
-  }, [theme]);
+  }, [theme, palette]);
+}
+
+/**
+ * Hook to get a single theme color by CSS variable name.
+ * Lighter alternative to useThemePalette() when you only need 1-3 colors.
+ *
+ * @param varName - CSS variable name without `--` prefix (e.g. 'primary', 'card-foreground')
+ * @param opacity - Optional opacity 0-1. If provided, returns rgba() string instead of hex.
+ *
+ * @example
+ * // Hex color
+ * const primary = useThemeColor('primary');           // '#a855f7'
+ *
+ * // With opacity
+ * const wave = useThemeColor('primary', 0.3);         // 'rgba(168, 85, 247, 0.3)'
+ * const bg   = useThemeColor('destructive', 0.1);     // useful for error backgrounds
+ */
+export function useThemeColor(varName: string, opacity?: number): string {
+  const theme = useResolvedTheme();
+
+  return useMemo(() => {
+    const hex = getCssColorAsHex(varName);
+    return opacity !== undefined ? alpha(hex, opacity) : hex;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [theme, varName, opacity]);
 }