@furystack/shades-common-components 10.0.35 → 11.0.0

package/src/services/css-variable-theme.spec.ts

@@ -0,0 +1,204 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { cssVariableTheme, getCssVariable, setCssVariable, useThemeCssVariables } from './css-variable-theme.js'
+
+describe('css-variable-theme', () => {
+  describe('cssVariableTheme', () => {
+    it('should have a name property', () => {
+      expect(cssVariableTheme.name).toBe('css-variable-theme')
+    })
+
+    it('should have text properties with CSS variable references', () => {
+      expect(cssVariableTheme.text.primary).toBe('var(--shades-theme-text-primary)')
+      expect(cssVariableTheme.text.secondary).toBe('var(--shades-theme-text-secondary)')
+      expect(cssVariableTheme.text.disabled).toBe('var(--shades-theme-text-disabled)')
+    })
+
+    it('should have background properties with CSS variable references', () => {
+      expect(cssVariableTheme.background.default).toBe('var(--shades-theme-background-default)')
+      expect(cssVariableTheme.background.paper).toBe('var(--shades-theme-background-paper)')
+    })
+
+    it('should have palette with color variants', () => {
+      expect(cssVariableTheme.palette.primary.main).toBe('var(--shades-theme-palette-primary-main)')
+      expect(cssVariableTheme.palette.error.main).toBe('var(--shades-theme-palette-error-main)')
+    })
+  })
+
+  describe('setCssVariable', () => {
+    let testElement: HTMLElement
+
+    beforeEach(() => {
+      testElement = document.createElement('div')
+      document.body.appendChild(testElement)
+    })
+
+    afterEach(() => {
+      testElement.remove()
+    })
+
+    it('should set CSS variable on element', () => {
+      setCssVariable('--test-color', 'red', testElement)
+      expect(testElement.style.getPropertyValue('--test-color')).toBe('red')
+    })
+
+    it('should handle var() wrapper in key name', () => {
+      setCssVariable('var(--test-padding)', '10px', testElement)
+      expect(testElement.style.getPropertyValue('--test-padding')).toBe('10px')
+    })
+
+    it('should set multiple CSS variables on same element', () => {
+      setCssVariable('--color-a', 'blue', testElement)
+      setCssVariable('--color-b', 'green', testElement)
+      expect(testElement.style.getPropertyValue('--color-a')).toBe('blue')
+      expect(testElement.style.getPropertyValue('--color-b')).toBe('green')
+    })
+
+    it('should override existing CSS variable', () => {
+      setCssVariable('--test-value', 'first', testElement)
+      setCssVariable('--test-value', 'second', testElement)
+      expect(testElement.style.getPropertyValue('--test-value')).toBe('second')
+    })
+  })
+
+  describe('getCssVariable', () => {
+    let testElement: HTMLElement
+
+    beforeEach(() => {
+      testElement = document.createElement('div')
+      document.body.appendChild(testElement)
+    })
+
+    afterEach(() => {
+      testElement.remove()
+    })
+
+    it('should get CSS variable from element', () => {
+      testElement.style.setProperty('--test-color', 'red')
+      const result = getCssVariable('--test-color', testElement)
+      expect(result).toBe('red')
+    })
+
+    it('should handle var() wrapper in key name', () => {
+      testElement.style.setProperty('--test-padding', '20px')
+      const result = getCssVariable('var(--test-padding)', testElement)
+      expect(result).toBe('20px')
+    })
+
+    it('should return empty string for non-existent variable', () => {
+      const result = getCssVariable('--non-existent', testElement)
+      expect(result).toBe('')
+    })
+  })
+
+  describe('useThemeCssVariables', () => {
+    let root: HTMLElement
+
+    beforeEach(() => {
+      root = document.documentElement
+    })
+
+    afterEach(() => {
+      root.style.cssText = ''
+    })
+
+    it('should set text color CSS variables from theme', () => {
+      useThemeCssVariables({
+        text: {
+          primary: '#ffffff',
+          secondary: '#cccccc',
+        },
+      })
+
+      expect(root.style.getPropertyValue('--shades-theme-text-primary')).toBe('#ffffff')
+      expect(root.style.getPropertyValue('--shades-theme-text-secondary')).toBe('#cccccc')
+    })
+
+    it('should set background CSS variables from theme', () => {
+      useThemeCssVariables({
+        background: {
+          default: '#000000',
+          paper: '#111111',
+        },
+      })
+
+      expect(root.style.getPropertyValue('--shades-theme-background-default')).toBe('#000000')
+      expect(root.style.getPropertyValue('--shades-theme-background-paper')).toBe('#111111')
+    })
+
+    it('should set button CSS variables from theme', () => {
+      useThemeCssVariables({
+        button: {
+          active: '#ff0000',
+          hover: '#00ff00',
+        },
+      })
+
+      expect(root.style.getPropertyValue('--shades-theme-button-active')).toBe('#ff0000')
+      expect(root.style.getPropertyValue('--shades-theme-button-hover')).toBe('#00ff00')
+    })
+
+    it('should set deeply nested palette CSS variables from theme', () => {
+      useThemeCssVariables({
+        palette: {
+          primary: {
+            main: '#1976d2',
+            light: '#42a5f5',
+            dark: '#1565c0',
+          },
+          error: {
+            main: '#d32f2f',
+          },
+        },
+      })
+
+      expect(root.style.getPropertyValue('--shades-theme-palette-primary-main')).toBe('#1976d2')
+      expect(root.style.getPropertyValue('--shades-theme-palette-primary-light')).toBe('#42a5f5')
+      expect(root.style.getPropertyValue('--shades-theme-palette-primary-dark')).toBe('#1565c0')
+      expect(root.style.getPropertyValue('--shades-theme-palette-error-main')).toBe('#d32f2f')
+    })
+
+    it('should set divider CSS variable from theme', () => {
+      useThemeCssVariables({
+        divider: 'rgba(255, 255, 255, 0.12)',
+      })
+
+      expect(root.style.getPropertyValue('--shades-theme-divider')).toBe('rgba(255, 255, 255, 0.12)')
+    })
+
+    it('should handle partial theme with mixed nesting levels', () => {
+      useThemeCssVariables({
+        text: {
+          primary: '#fff',
+        },
+        divider: '#333',
+        palette: {
+          success: {
+            main: '#2e7d32',
+          },
+        },
+      })
+
+      expect(root.style.getPropertyValue('--shades-theme-text-primary')).toBe('#fff')
+      expect(root.style.getPropertyValue('--shades-theme-divider')).toBe('#333')
+      expect(root.style.getPropertyValue('--shades-theme-palette-success-main')).toBe('#2e7d32')
+    })
+
+    it('should allow overriding previously set CSS variables', () => {
+      useThemeCssVariables({
+        text: {
+          primary: '#aaa',
+        },
+      })
+
+      expect(root.style.getPropertyValue('--shades-theme-text-primary')).toBe('#aaa')
+
+      useThemeCssVariables({
+        text: {
+          primary: '#bbb',
+        },
+      })
+
+      expect(root.style.getPropertyValue('--shades-theme-text-primary')).toBe('#bbb')
+    })
+  })
+})

package/src/services/css-variable-theme.ts

@@ -21,33 +21,51 @@ export const cssVariableTheme: Theme = {
   palette: {
     primary: {
       light: 'var(--shades-theme-palette-primary-light)',
+      lightContrast: 'var(--shades-theme-palette-primary-light-contrast)',
       main: 'var(--shades-theme-palette-primary-main)',
+      mainContrast: 'var(--shades-theme-palette-primary-main-contrast)',
       dark: 'var(--shades-theme-palette-primary-dark)',
+      darkContrast: 'var(--shades-theme-palette-primary-dark-contrast)',
     },
     secondary: {
       light: 'var(--shades-theme-palette-secondary-light)',
+      lightContrast: 'var(--shades-theme-palette-secondary-light-contrast)',
       main: 'var(--shades-theme-palette-secondary-main)',
+      mainContrast: 'var(--shades-theme-palette-secondary-main-contrast)',
       dark: 'var(--shades-theme-palette-secondary-dark)',
+      darkContrast: 'var(--shades-theme-palette-secondary-dark-contrast)',
     },
     error: {
       light: 'var(--shades-theme-palette-error-light)',
+      lightContrast: 'var(--shades-theme-palette-error-light-contrast)',
       main: 'var(--shades-theme-palette-error-main)',
+      mainContrast: 'var(--shades-theme-palette-error-main-contrast)',
       dark: 'var(--shades-theme-palette-error-dark)',
+      darkContrast: 'var(--shades-theme-palette-error-dark-contrast)',
     },
     warning: {
       light: 'var(--shades-theme-palette-warning-light)',
+      lightContrast: 'var(--shades-theme-palette-warning-light-contrast)',
       main: 'var(--shades-theme-palette-warning-main)',
+      mainContrast: 'var(--shades-theme-palette-warning-main-contrast)',
       dark: 'var(--shades-theme-palette-warning-dark)',
+      darkContrast: 'var(--shades-theme-palette-warning-dark-contrast)',
     },
     info: {
       light: 'var(--shades-theme-palette-info-light)',
+      lightContrast: 'var(--shades-theme-palette-info-light-contrast)',
       main: 'var(--shades-theme-palette-info-main)',
+      mainContrast: 'var(--shades-theme-palette-info-main-contrast)',
       dark: 'var(--shades-theme-palette-info-dark)',
+      darkContrast: 'var(--shades-theme-palette-info-dark-contrast)',
     },
     success: {
       light: 'var(--shades-theme-palette-success-light)',
+      lightContrast: 'var(--shades-theme-palette-success-light-contrast)',
       main: 'var(--shades-theme-palette-success-main)',
+      mainContrast: 'var(--shades-theme-palette-success-main-contrast)',
       dark: 'var(--shades-theme-palette-success-dark)',
+      darkContrast: 'var(--shades-theme-palette-success-dark-contrast)',
     },
   },
   divider: 'var(--shades-theme-divider)',
@@ -69,9 +87,11 @@ const assignValue = <T extends object>(
 ) => {
   const keys = Object.keys(target) as Array<keyof T>
   keys.forEach((key) => {
+    if (source[key] === undefined) {
+      return
+    }
     if (typeof source[key] === 'object' && typeof target[key] === 'object') {
       assignValue(target[key] as object, source[key] as object, root)
-      return
     } else {
       assignFn(target[key] as string, source[key] as string, root)
     }

package/src/services/default-palette.ts

@@ -1,34 +1,56 @@
 import type { Palette } from './theme-provider-service.js'
 
+/**
+ * Default color palette with semantic colors for the application.
+ * Contrast colors are calculated based on WCAG contrast guidelines.
+ */
 export const defaultPalette: Palette = {
   primary: {
     light: '#6573c3',
+    lightContrast: '#ffffff',
     main: '#3f51b5',
+    mainContrast: '#ffffff',
     dark: '#2c387e',
+    darkContrast: '#ffffff',
   },
   secondary: {
     light: '#4aedc4',
+    lightContrast: '#000000',
     main: '#1de9b6',
+    mainContrast: '#000000',
     dark: '#14a37f',
+    darkContrast: '#ffffff',
   },
   error: {
     light: '#e57373',
+    lightContrast: '#000000',
     main: '#f44336',
+    mainContrast: '#ffffff',
     dark: '#a31f1f',
+    darkContrast: '#ffffff',
   },
   warning: {
     light: '#ffb74d',
+    lightContrast: '#000000',
     main: '#ff9800',
+    mainContrast: '#000000',
     dark: '#f57c00',
+    darkContrast: '#000000',
   },
   info: {
     light: '#64b5f6',
+    lightContrast: '#000000',
     main: '#2196f3',
+    mainContrast: '#ffffff',
     dark: '#1976d2',
+    darkContrast: '#ffffff',
   },
   success: {
     light: '#81c784',
+    lightContrast: '#000000',
     main: '#4caf50',
+    mainContrast: '#000000',
     dark: '#388e3c',
+    darkContrast: '#ffffff',
   },
 }

package/src/services/theme-provider-service.spec.ts

@@ -0,0 +1,195 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import { RgbColor, ThemeProviderService } from './theme-provider-service.js'
+
+describe('theme-provider-service', () => {
+  describe('RgbColor', () => {
+    describe('constructor', () => {
+      it('should create RgbColor with r, g, b values', () => {
+        const color = new RgbColor(255, 128, 64)
+        expect(color.r).toBe(255)
+        expect(color.g).toBe(128)
+        expect(color.b).toBe(64)
+        expect(color.a).toBe(1)
+      })
+
+      it('should create RgbColor with alpha value', () => {
+        const color = new RgbColor(255, 128, 64, 0.5)
+        expect(color.r).toBe(255)
+        expect(color.g).toBe(128)
+        expect(color.b).toBe(64)
+        expect(color.a).toBe(0.5)
+      })
+
+      it('should default alpha to 1', () => {
+        const color = new RgbColor(100, 100, 100)
+        expect(color.a).toBe(1)
+      })
+    })
+
+    describe('update', () => {
+      it('should update r value and return self', () => {
+        const color = new RgbColor(100, 100, 100)
+        const result = color.update('r', 200)
+        expect(result).toBe(color)
+        expect(color.r).toBe(200)
+      })
+
+      it('should update g value', () => {
+        const color = new RgbColor(100, 100, 100)
+        color.update('g', 150)
+        expect(color.g).toBe(150)
+      })
+
+      it('should update b value', () => {
+        const color = new RgbColor(100, 100, 100)
+        color.update('b', 50)
+        expect(color.b).toBe(50)
+      })
+
+      it('should update a value', () => {
+        const color = new RgbColor(100, 100, 100, 1)
+        color.update('a', 0.7)
+        expect(color.a).toBe(0.7)
+      })
+
+      it('should allow chained updates', () => {
+        const color = new RgbColor(0, 0, 0)
+        color.update('r', 255).update('g', 128).update('b', 64)
+        expect(color.r).toBe(255)
+        expect(color.g).toBe(128)
+        expect(color.b).toBe(64)
+      })
+    })
+
+    describe('toString', () => {
+      it('should return rgba format string', () => {
+        const color = new RgbColor(255, 128, 64, 0.5)
+        expect(color.toString()).toBe('rgba(255,128,64,0.5)')
+      })
+
+      it('should handle full opacity', () => {
+        const color = new RgbColor(0, 0, 0, 1)
+        expect(color.toString()).toBe('rgba(0,0,0,1)')
+      })
+
+      it('should handle zero alpha', () => {
+        const color = new RgbColor(255, 255, 255, 0)
+        expect(color.toString()).toBe('rgba(255,255,255,0)')
+      })
+    })
+  })
+
+  describe('ThemeProviderService', () => {
+    let service: ThemeProviderService
+
+    beforeEach(() => {
+      service = new ThemeProviderService()
+    })
+
+    describe('getRgbFromColorString', () => {
+      it('should parse 6-digit hex color', () => {
+        const result = service.getRgbFromColorString('#ff8040')
+        expect(result.r).toBe(255)
+        expect(result.g).toBe(128)
+        expect(result.b).toBe(64)
+      })
+
+      it('should parse 6-digit hex color with lowercase', () => {
+        const result = service.getRgbFromColorString('#3f51b5')
+        expect(result.r).toBe(63)
+        expect(result.g).toBe(81)
+        expect(result.b).toBe(181)
+      })
+
+      it('should parse 6-digit hex color with uppercase', () => {
+        const result = service.getRgbFromColorString('#FF0000')
+        expect(result.r).toBe(255)
+        expect(result.g).toBe(0)
+        expect(result.b).toBe(0)
+      })
+
+      it('should parse 3-digit hex color', () => {
+        const result = service.getRgbFromColorString('#f80')
+        expect(result.r).toBe(255)
+        expect(result.g).toBe(136)
+        expect(result.b).toBe(0)
+      })
+
+      it('should parse 3-digit hex white', () => {
+        const result = service.getRgbFromColorString('#fff')
+        expect(result.r).toBe(255)
+        expect(result.g).toBe(255)
+        expect(result.b).toBe(255)
+      })
+
+      it('should parse 3-digit hex black', () => {
+        const result = service.getRgbFromColorString('#000')
+        expect(result.r).toBe(0)
+        expect(result.g).toBe(0)
+        expect(result.b).toBe(0)
+      })
+
+      it('should parse rgba color', () => {
+        const result = service.getRgbFromColorString('rgba(255,128,64,0.5)')
+        expect(result.r).toBe(255)
+        expect(result.g).toBe(128)
+        expect(result.b).toBe(64)
+        expect(result.a).toBe(0)
+      })
+
+      it('should parse rgba color with spaces', () => {
+        const result = service.getRgbFromColorString('rgba(100, 150, 200, 1)')
+        expect(result.r).toBe(100)
+        expect(result.g).toBe(150)
+        expect(result.b).toBe(200)
+        expect(result.a).toBe(1)
+      })
+
+      it('should throw error for unsupported color format', () => {
+        expect(() => service.getRgbFromColorString('red')).toThrow("Color format 'red' is not supported.'")
+      })
+
+      it('should throw error for rgb format without alpha', () => {
+        expect(() => service.getRgbFromColorString('rgb(255, 0, 0)')).toThrow()
+      })
+
+      it('should throw error for invalid hex length', () => {
+        expect(() => service.getRgbFromColorString('#12345')).toThrow()
+      })
+    })
+
+    describe('getTextColor', () => {
+      it('should return dark text for light background', () => {
+        const result = service.getTextColor('#ffffff')
+        expect(result).toBe('#000000')
+      })
+
+      it('should return light text for dark background', () => {
+        const result = service.getTextColor('#000000')
+        expect(result).toBe('#FFFFFF')
+      })
+
+      it('should return custom bright color for light background', () => {
+        const result = service.getTextColor('#ffffff', '#333333', '#eeeeee')
+        expect(result).toBe('#333333')
+      })
+
+      it('should return custom dark color for dark background', () => {
+        const result = service.getTextColor('#000000', '#333333', '#eeeeee')
+        expect(result).toBe('#eeeeee')
+      })
+    })
+
+    describe('theme management', () => {
+      it('should have initial theme assigned', () => {
+        expect(service.getAssignedTheme()).toBeDefined()
+        expect(service.getAssignedTheme().name).toBe('css-variable-theme')
+      })
+
+      it('should expose cssVariableTheme as theme property', () => {
+        expect(service.theme).toBeDefined()
+        expect(service.theme.name).toBe('css-variable-theme')
+      })
+    })
+  })
+})

package/src/services/theme-provider-service.ts

@@ -2,48 +2,106 @@ import { Injectable } from '@furystack/inject'
 import { EventHub, type DeepPartial } from '@furystack/utils'
 import { cssVariableTheme, getCssVariable, useThemeCssVariables } from './css-variable-theme.js'
 
-export type Color = string // `#${string}` | `rgba(${number},${number},${number},${number})` |
+/**
+ * Represents a CSS color value.
+ * Can be a hex color, rgba, or CSS variable reference.
+ * @example '#3f51b5', 'rgba(255, 255, 255, 0.7)', 'var(--my-color)'
+ */
+export type Color = string
 
+/**
+ * Color variants for a palette color with their corresponding contrast text colors.
+ * Each variant (light, main, dark) has an associated contrast color that should be
+ * used for text or icons displayed on top of that variant's background.
+ */
 export type ColorVariants = {
-  main: Color
+  /** The lighter shade of the color */
   light: Color
+  /** Text/icon color that contrasts well with the light variant */
+  lightContrast: Color
+  /** The primary/default shade of the color */
+  main: Color
+  /** Text/icon color that contrasts well with the main variant */
+  mainContrast: Color
+  /** The darker shade of the color */
   dark: Color
+  /** Text/icon color that contrasts well with the dark variant */
+  darkContrast: Color
 }
 
+/**
+ * The color palette containing semantic colors for the application.
+ * Each color has light, main, and dark variants with corresponding contrast colors.
+ */
 export interface Palette {
+  /** Primary brand color, used for main actions and emphasis */
   primary: ColorVariants
+  /** Secondary brand color, used for less prominent actions */
   secondary: ColorVariants
+  /** Color indicating errors or destructive actions */
   error: ColorVariants
+  /** Color indicating warnings or caution */
   warning: ColorVariants
+  /** Color indicating success or positive outcomes */
   success: ColorVariants
+  /** Color for informational content */
   info: ColorVariants
 }
 
+/**
+ * Text color definitions for different emphasis levels.
+ */
 export interface Text {
+  /** High-emphasis text color for important content */
   primary: Color
+  /** Medium-emphasis text color for secondary content */
   secondary: Color
+  /** Low-emphasis text color for disabled or hint text */
   disabled: Color
 }
 
+/**
+ * Button-specific color definitions for various states.
+ */
 export interface ButtonColor {
+  /** Color when button is actively pressed */
   active: Color
+  /** Background color on hover */
   hover: Color
+  /** Background color when selected/checked */
   selected: Color
+  /** Text color when button is disabled */
   disabled: Color
+  /** Background color when button is disabled */
   disabledBackground: Color
 }
 
+/**
+ * Background color definitions for different surface levels.
+ */
 export interface Background {
+  /** Default page/app background color */
   default: Color
+  /** Elevated surface background (cards, dialogs, etc.) */
   paper: Color
 }
 
+/**
+ * Complete theme definition containing all color tokens for the application.
+ * Themes can be switched at runtime to support light/dark modes or custom branding.
+ */
 export interface Theme {
+  /** Unique identifier for the theme */
   name: string
+  /** Semantic color palette */
   palette: Palette
+  /** Text colors for different emphasis levels */
   text: Text
+  /** Button-specific colors */
   button: ButtonColor
+  /** Background colors */
   background: Background
+  /** Color for dividers and borders */
   divider: Color
 }