@furystack/shades-common-components 12.7.0 → 13.0.0

package/src/services/get-rgb-from-color-string.ts

@@ -0,0 +1,96 @@
+import { getCssVariable } from './css-variable-theme.js'
+import { RgbColor } from './rgb-color.js'
+
+const NAMED_COLORS: Record<string, [r: number, g: number, b: number]> = {
+  aqua: [0, 255, 255],
+  black: [0, 0, 0],
+  blue: [0, 0, 255],
+  brown: [165, 42, 42],
+  coral: [255, 127, 80],
+  crimson: [220, 20, 60],
+  cyan: [0, 255, 255],
+  darkblue: [0, 0, 139],
+  darkgray: [169, 169, 169],
+  darkgreen: [0, 100, 0],
+  darkgrey: [169, 169, 169],
+  darkred: [139, 0, 0],
+  deeppink: [255, 20, 147],
+  dodgerblue: [30, 144, 255],
+  fuchsia: [255, 0, 255],
+  gold: [255, 215, 0],
+  gray: [128, 128, 128],
+  green: [0, 128, 0],
+  grey: [128, 128, 128],
+  hotpink: [255, 105, 180],
+  indigo: [75, 0, 130],
+  ivory: [255, 255, 240],
+  khaki: [240, 230, 140],
+  lavender: [230, 230, 250],
+  lime: [0, 255, 0],
+  limegreen: [50, 205, 50],
+  magenta: [255, 0, 255],
+  maroon: [128, 0, 0],
+  navy: [0, 0, 128],
+  olive: [128, 128, 0],
+  orange: [255, 165, 0],
+  orangered: [255, 69, 0],
+  pink: [255, 192, 203],
+  purple: [128, 0, 128],
+  red: [255, 0, 0],
+  royalblue: [65, 105, 225],
+  salmon: [250, 128, 114],
+  silver: [192, 192, 192],
+  skyblue: [135, 206, 235],
+  steelblue: [70, 130, 180],
+  teal: [0, 128, 128],
+  tomato: [255, 99, 71],
+  turquoise: [64, 224, 208],
+  violet: [238, 130, 238],
+  white: [255, 255, 255],
+  yellow: [255, 255, 0],
+}
+
+/**
+ * Parses a CSS color string and returns its RGBA representation.
+ * Supports hex (#rgb, #rrggbb), rgb(), rgba(), CSS variables (var(--…)),
+ * and common named colors.
+ * @param color The color string to parse
+ * @returns The parsed RGBA values
+ */
+export const getRgbFromColorString = (color: string): RgbColor => {
+  if (color.startsWith('var(--')) {
+    return getRgbFromColorString(getCssVariable(color))
+  }
+
+  if (color.startsWith('#')) {
+    if (color.length === 7) {
+      const r = parseInt(color.substring(1, 3), 16)
+      const g = parseInt(color.substring(3, 5), 16)
+      const b = parseInt(color.substring(5, 7), 16)
+      return new RgbColor(r, g, b)
+    }
+    if (color.length === 4) {
+      const r = parseInt(color[1] + color[1], 16)
+      const g = parseInt(color[2] + color[2], 16)
+      const b = parseInt(color[3] + color[3], 16)
+      return new RgbColor(r, g, b)
+    }
+  }
+
+  const rgbaMatch = /^rgba?\(\s*(?<red>\d+),\s*(?<green>\d+),\s*(?<blue>\d+)(?:,\s*(?<alpha>[\d.]+))?\s*\)$/.exec(color)
+  if (rgbaMatch?.groups) {
+    return new RgbColor(
+      parseInt(rgbaMatch.groups.red, 10),
+      parseInt(rgbaMatch.groups.green, 10),
+      parseInt(rgbaMatch.groups.blue, 10),
+      rgbaMatch.groups.alpha !== undefined ? parseFloat(rgbaMatch.groups.alpha) : 1,
+    )
+  }
+
+  const named = NAMED_COLORS[color.toLowerCase()]
+  if (named) {
+    return new RgbColor(named[0], named[1], named[2])
+  }
+
+  throw Error(`Color format '${color}' is not supported.`)
+}

package/src/services/get-text-color.spec.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { getTextColor } from './get-text-color.js'
+
+describe('getTextColor', () => {
+  it('should return dark text for light background', () => {
+    expect(getTextColor('#ffffff')).toBe('#000000')
+  })
+
+  it('should return light text for dark background', () => {
+    expect(getTextColor('#000000')).toBe('#FFFFFF')
+  })
+
+  it('should return custom bright color for light background', () => {
+    expect(getTextColor('#ffffff', '#333333', '#eeeeee')).toBe('#333333')
+  })
+
+  it('should return custom dark color for dark background', () => {
+    expect(getTextColor('#000000', '#333333', '#eeeeee')).toBe('#eeeeee')
+  })
+
+  it('should work with named colors', () => {
+    expect(getTextColor('white')).toBe('#000000')
+    expect(getTextColor('black')).toBe('#FFFFFF')
+  })
+})

package/src/services/get-text-color.ts

@@ -0,0 +1,15 @@
+import { getRgbFromColorString } from './get-rgb-from-color-string.js'
+
+/**
+ * Returns a contrasting text color (bright or dark) for a given background color.
+ * Uses the YIQ luminance formula to determine whether the background is light or dark.
+ * @param color The background color string
+ * @param bright The color to return for light backgrounds (defaults to '#000000')
+ * @param dark The color to return for dark backgrounds (defaults to '#FFFFFF')
+ * @returns The bright or dark color that best contrasts the background
+ */
+export const getTextColor = (color: string, bright = '#000000', dark = '#FFFFFF'): string => {
+  const { r, g, b } = getRgbFromColorString(color)
+  const yiq = (r * 299 + g * 587 + b * 114) / 1000
+  return yiq >= 128 ? bright : dark
+}

package/src/services/index.ts

@@ -1,13 +1,16 @@
 export * from './click-away-service.js'
 export * from './collection-service.js'
 export * from './css-variable-theme.js'
-export * from './default-dark-palette.js'
-export * from './default-dark-theme.js'
-export * from './default-light-theme.js'
-export * from './default-palette.js'
+export * from '../themes/default-dark-palette.js'
+export * from '../themes/default-dark-theme.js'
+export * from '../themes/default-light-theme.js'
+export * from '../themes/default-palette.js'
+export * from './get-rgb-from-color-string.js'
+export * from './get-text-color.js'
 export * from './layout-service.js'
 export * from './list-service.js'
 export * from './noty-service.js'
 export * from './palette-css-vars.js'
+export * from './rgb-color.js'
 export * from './theme-provider-service.js'
 export * from './tree-service.js'

package/src/services/rgb-color.spec.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import { RgbColor } from './rgb-color.js'
+
+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)')
+    })
+  })
+})

package/src/services/rgb-color.ts

@@ -0,0 +1,20 @@
+/**
+ * Represents an RGBA color with mutable channels.
+ */
+export class RgbColor {
+  constructor(
+    public r: number,
+    public g: number,
+    public b: number,
+    public a: number = 1,
+  ) {}
+
+  public update(key: 'r' | 'g' | 'b' | 'a', value: number): RgbColor {
+    this[key] = value
+    return this
+  }
+
+  public toString(): string {
+    return `rgba(${this.r},${this.g},${this.b},${this.a})`
+  }
+}

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

@@ -1,195 +1,22 @@
 import { beforeEach, describe, expect, it } from 'vitest'
-import { RgbColor, ThemeProviderService } from './theme-provider-service.js'
+import { 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)
-      })
+describe('ThemeProviderService', () => {
+  let service: ThemeProviderService
 
-      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)')
-      })
-    })
+  beforeEach(() => {
+    service = new ThemeProviderService()
   })
 
-  describe('ThemeProviderService', () => {
-    let service: ThemeProviderService
-
-    beforeEach(() => {
-      service = new ThemeProviderService()
+  describe('theme management', () => {
+    it('should have initial theme assigned', () => {
+      expect(service.getAssignedTheme()).toBeDefined()
+      expect(service.getAssignedTheme().name).toBe('css-variable-theme')
     })
 
-    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')
-      })
+    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

@@ -1,6 +1,7 @@
 import { Injectable } from '@furystack/inject'
 import { EventHub, type DeepPartial } from '@furystack/utils'
-import { cssVariableTheme, getCssVariable, useThemeCssVariables } from './css-variable-theme.js'
+
+import { cssVariableTheme, useThemeCssVariables } from './css-variable-theme.js'
 
 /**
  * Represents a CSS color value.
@@ -84,6 +85,8 @@ export interface Background {
   default: Color
   /** Elevated surface background (cards, dialogs, etc.) */
   paper: Color
+  /** Optional CSS background-image for paper surfaces (e.g. a tiled texture) */
+  paperImage?: string
 }
 
 /**
@@ -128,6 +131,8 @@ export type BorderRadiusScale = {
 export type Shape = {
   /** Border radius scale */
   borderRadius: BorderRadiusScale
+  /** Border width for surface components (paper, card, etc.). Defaults to 0. */
+  borderWidth?: string
 }
 
 /**
@@ -226,6 +231,8 @@ export type ThemeTypography = {
   lineHeight: LineHeightScale
   /** Letter spacing scale */
   letterSpacing?: LetterSpacingScale
+  /** CSS text-shadow value applied globally to text */
+  textShadow?: string
 }
 
 /**
@@ -356,82 +363,11 @@ export interface Theme {
   effects?: Effects
 }
 
-export class RgbColor {
-  constructor(
-    public r: number,
-    public g: number,
-    public b: number,
-    public a: number = 1,
-  ) {}
-
-  public update(key: 'r' | 'g' | 'b' | 'a', value: number): RgbColor {
-    this[key] = value
-    return this
-  }
-
-  public toString(): string {
-    return `rgba(${this.r},${this.g},${this.b},${this.a})`
-  }
-}
-
 /**
  * Service class for theme-related operations
  */
 @Injectable({ lifetime: 'singleton' })
 export class ThemeProviderService extends EventHub<{ themeChanged: DeepPartial<Theme> }> {
-  /**
-   * @deprecated does not respect CSS vars
-   * @param color The background color
-   * @param bright The Bright color
-   * @param dark The Dark color
-   * @returns The bright or dark color variant that fits the background color
-   */
-  public getTextColor(color: string, bright = '#000000', dark = '#FFFFFF') {
-    const { r, g, b } = this.getRgbFromColorString(color)
-    const yiq = (r * 299 + g * 587 + b * 114) / 1000
-    return yiq >= 128 ? bright : dark
-  }
-
-  /**
-   * Parses a color string and returns RGB values
-   * @param color The color string
-   * @returns The parsed R,G,B, A values
-   */
-  public getRgbFromColorString(color: string): RgbColor {
-    if (color.startsWith('var(--')) {
-      return this.getRgbFromColorString(getCssVariable(color))
-    }
-
-    if (color.startsWith('#')) {
-      if (color.length === 7) {
-        const r = parseInt(color.substr(1, 2), 16)
-        const g = parseInt(color.substr(3, 2), 16)
-        const b = parseInt(color.substr(5, 2), 16)
-        return new RgbColor(r, g, b)
-      }
-      if (color.length === 4) {
-        const r = parseInt(color.substr(1, 1) + color.substr(1, 1), 16)
-        const g = parseInt(color.substr(2, 1) + color.substr(2, 1), 16)
-        const b = parseInt(color.substr(3, 1) + color.substr(3, 1), 16)
-        return new RgbColor(r, g, b)
-      }
-    }
-    if (color.startsWith('rgba(')) {
-      const result = new RegExp(
-        /^rgba[(](?<red>[\d]+)[,][\s]?(?<green>[\d]+)[,][\s]?(?<blue>[\d]+)[,][\s]?(?<alpha>[\d|.]+)[)]/gm,
-      ).exec(color)
-      if (result && result.groups) {
-        return new RgbColor(
-          parseInt(result.groups.red, 10),
-          parseInt(result.groups.green, 10),
-          parseInt(result.groups.blue, 10),
-          parseInt(result.groups.alpha, 10),
-        )
-      }
-    }
-    throw Error(`Color format '${color}' is not supported.'`)
-  }
-
   public readonly theme = cssVariableTheme
 
   private _assignedTheme: DeepPartial<Theme> = cssVariableTheme

package/src/themes/architect-palette.ts

@@ -0,0 +1,57 @@
+import type { Palette } from '../services/theme-provider-service.js'
+
+/**
+ * Color palette inspired by The Matrix.
+ * Digital green primary, white secondary,
+ * with monochrome-green tones for semantic colors.
+ */
+export const architectPalette: Palette = {
+  primary: {
+    light: '#50ff70',
+    lightContrast: '#000000',
+    main: '#00ff41',
+    mainContrast: '#000000',
+    dark: '#00c430',
+    darkContrast: '#000000',
+  },
+  secondary: {
+    light: '#e0e0e0',
+    lightContrast: '#000000',
+    main: '#c0c0c0',
+    mainContrast: '#000000',
+    dark: '#909090',
+    darkContrast: '#000000',
+  },
+  error: {
+    light: '#ff5050',
+    lightContrast: '#000000',
+    main: '#e02020',
+    mainContrast: '#000000',
+    dark: '#a81818',
+    darkContrast: '#ffffff',
+  },
+  warning: {
+    light: '#e0c040',
+    lightContrast: '#000000',
+    main: '#c4a020',
+    mainContrast: '#000000',
+    dark: '#948018',
+    darkContrast: '#ffffff',
+  },
+  success: {
+    light: '#40e060',
+    lightContrast: '#000000',
+    main: '#20c040',
+    mainContrast: '#000000',
+    dark: '#109028',
+    darkContrast: '#ffffff',
+  },
+  info: {
+    light: '#40c0e0',
+    lightContrast: '#000000',
+    main: '#20a0c0',
+    mainContrast: '#000000',
+    dark: '#108090',
+    darkContrast: '#ffffff',
+  },
+}