@cdx-ui/styles 0.0.1-beta.8 → 0.0.1-beta.80

package/src/__tests__/generateColorScale.test.ts

@@ -0,0 +1,296 @@
+import { generateColorScale, generatePalettesFromInputs, deriveBaseColorKey } from '../palette';
+
+const PALETTE_STEPS = [
+  '50',
+  '100',
+  '200',
+  '300',
+  '400',
+  '500',
+  '600',
+  '700',
+  '800',
+  '900',
+  '950',
+] as const;
+
+/**
+ * Calculate WCAG 2.x relative luminance from a hex string.
+ * @see https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+ */
+function relativeLuminance(hex: string): number {
+  const r = parseInt(hex.slice(1, 3), 16) / 255;
+  const g = parseInt(hex.slice(3, 5), 16) / 255;
+  const b = parseInt(hex.slice(5, 7), 16) / 255;
+
+  const toLinear = (c: number) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+
+  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+
+/** WCAG 2.x contrast ratio between two hex colours. */
+function contrastRatio(hex1: string, hex2: string): number {
+  const l1 = relativeLuminance(hex1);
+  const l2 = relativeLuminance(hex2);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+// ---------------------------------------------------------------------------
+// generateColorScale
+// ---------------------------------------------------------------------------
+
+describe('generateColorScale', () => {
+  describe('valid hex input → correct 11-step output structure', () => {
+    it('returns all 11 contrast steps plus the input key for brand', () => {
+      const result = generateColorScale('#081728', 'brand');
+
+      for (const step of PALETTE_STEPS) {
+        expect(`color.brand.${step}` in result).toBe(true);
+      }
+      expect('color.brand.input' in result).toBe(true);
+      expect(Object.keys(result)).toHaveLength(12);
+    });
+
+    it('returns all 11 contrast steps plus the input key for accent', () => {
+      const result = generateColorScale('#ffcf23', 'accent');
+
+      for (const step of PALETTE_STEPS) {
+        expect(`color.accent.${step}` in result).toBe(true);
+      }
+      expect('color.accent.input' in result).toBe(true);
+      expect(Object.keys(result)).toHaveLength(12);
+    });
+
+    it('returns all 11 contrast steps plus the input key for base', () => {
+      const result = generateColorScale('#797986', 'base');
+
+      for (const step of PALETTE_STEPS) {
+        expect(`color.base.${step}` in result).toBe(true);
+      }
+      expect('color.base.input' in result).toBe(true);
+      expect(Object.keys(result)).toHaveLength(12);
+    });
+
+    it('all generated values are valid 7-character hex strings', () => {
+      const result = generateColorScale('#0052cc', 'brand');
+
+      for (const value of Object.values(result)) {
+        expect(value).toMatch(/^#[0-9a-f]{6}$/);
+      }
+    });
+  });
+
+  describe('input preservation', () => {
+    it('preserves the original hex (7-char) verbatim in the input key', () => {
+      const result = generateColorScale('#081728', 'brand');
+      expect(result['color.brand.input']).toBe('#081728');
+    });
+
+    it('normalises shorthand hex (#RGB → #RRGGBB) in the input key', () => {
+      const result = generateColorScale('#F00', 'brand');
+      expect(result['color.brand.input']).toBe('#ff0000');
+    });
+
+    it('lowercases the input hex', () => {
+      const result = generateColorScale('#AABBCC', 'accent');
+      expect(result['color.accent.input']).toBe('#aabbcc');
+    });
+  });
+
+  describe('invalid hex handling', () => {
+    it('throws for a string without leading #', () => {
+      expect(() => generateColorScale('081728', 'brand')).toThrow(TypeError);
+      expect(() => generateColorScale('081728', 'brand')).toThrow(/must be a 4-character/);
+    });
+
+    it('throws for wrong-length hex', () => {
+      expect(() => generateColorScale('#0817', 'brand')).toThrow(TypeError);
+      expect(() => generateColorScale('#08172', 'brand')).toThrow(TypeError);
+      expect(() => generateColorScale('#08172800', 'brand')).toThrow(TypeError);
+    });
+
+    it('throws for non-hex characters', () => {
+      expect(() => generateColorScale('#GGHHII', 'brand')).toThrow(TypeError);
+    });
+
+    it('throws for empty string', () => {
+      expect(() => generateColorScale('', 'brand')).toThrow(TypeError);
+    });
+
+    it('throws for non-string input', () => {
+      expect(() => generateColorScale(123 as unknown as string, 'brand')).toThrow(TypeError);
+    });
+  });
+
+  describe('contrast ratio spot-checks', () => {
+    const WHITE = '#ffffff';
+
+    it('brand palette: step 700 meets WCAG AA for normal text (≥ 4.5:1)', () => {
+      const result = generateColorScale('#081728', 'brand');
+      const ratio = contrastRatio(result['color.brand.700'], WHITE);
+      expect(ratio).toBeGreaterThanOrEqual(4.5);
+    });
+
+    it('brand palette: steps are ordered from lightest (50) to darkest (950)', () => {
+      const result = generateColorScale('#081728', 'brand');
+      const luminances = PALETTE_STEPS.map((step) =>
+        relativeLuminance(result[`color.brand.${step}`]),
+      );
+      for (let i = 1; i < luminances.length; i++) {
+        expect(luminances[i]).toBeLessThanOrEqual(luminances[i - 1]);
+      }
+    });
+
+    it('accent palette: step 700 meets WCAG AA for normal text (≥ 4.5:1)', () => {
+      const result = generateColorScale('#ffcf23', 'accent');
+      const ratio = contrastRatio(result['color.accent.700'], WHITE);
+      expect(ratio).toBeGreaterThanOrEqual(4.5);
+    });
+
+    it('accent palette: step 50 has very low contrast against white (< 1.5:1)', () => {
+      const result = generateColorScale('#ffcf23', 'accent');
+      const ratio = contrastRatio(result['color.accent.50'], WHITE);
+      expect(ratio).toBeLessThan(1.5);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// deriveBaseColorKey
+// ---------------------------------------------------------------------------
+
+/** Saturation component (0–1) of a hex color in HSL. */
+function saturation(hex: string): number {
+  const r = parseInt(hex.slice(1, 3), 16) / 255;
+  const g = parseInt(hex.slice(3, 5), 16) / 255;
+  const b = parseInt(hex.slice(5, 7), 16) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  const delta = max - min;
+  if (delta === 0) return 0;
+  return l > 0.5 ? delta / (2 - max - min) : delta / (max + min);
+}
+
+/** Hue component (degrees) of a hex color in HSL. */
+function hue(hex: string): number {
+  const r = parseInt(hex.slice(1, 3), 16) / 255;
+  const g = parseInt(hex.slice(3, 5), 16) / 255;
+  const b = parseInt(hex.slice(5, 7), 16) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const delta = max - min;
+  if (delta === 0) return 0;
+  let h: number;
+  if (max === r) h = (g - b) / delta + (g < b ? 6 : 0);
+  else if (max === g) h = (b - r) / delta + 2;
+  else h = (r - g) / delta + 4;
+  return h * 60;
+}
+
+describe('deriveBaseColorKey', () => {
+  it('returns a normalised 7-character hex string', () => {
+    expect(deriveBaseColorKey('#346099')).toMatch(/^#[0-9a-f]{6}$/);
+  });
+
+  it('lowers saturation to ~5%', () => {
+    // ~5% saturation rounded through 8-bit channels lands close to 0.05.
+    expect(saturation(deriveBaseColorKey('#346099'))).toBeCloseTo(0.05, 2);
+    expect(saturation(deriveBaseColorKey('#ff0000'))).toBeCloseTo(0.05, 2);
+  });
+
+  it('preserves the brand hue (within rounding tolerance)', () => {
+    // At 5% saturation the channels are nearly equal, so 8-bit rounding can
+    // nudge the hue by a couple of degrees — assert a small absolute tolerance.
+    expect(Math.abs(hue(deriveBaseColorKey('#346099')) - hue('#346099'))).toBeLessThan(5);
+  });
+
+  it('accepts shorthand hex and normalises the result', () => {
+    expect(deriveBaseColorKey('#36c')).toMatch(/^#[0-9a-f]{6}$/);
+  });
+
+  it('throws for invalid hex input', () => {
+    expect(() => deriveBaseColorKey('nope')).toThrow(TypeError);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// generatePalettesFromInputs
+// ---------------------------------------------------------------------------
+
+describe('generatePalettesFromInputs', () => {
+  it('generates palettes for both brand and accent colour inputs', () => {
+    const result = generatePalettesFromInputs({
+      brandPrimary: '#0052cc',
+      accentPrimary: '#FF8C42',
+    });
+
+    for (const step of PALETTE_STEPS) {
+      expect(`color.brand.${step}` in result).toBe(true);
+      expect(`color.accent.${step}` in result).toBe(true);
+    }
+    expect(result['color.brand.input']).toBe('#0052cc');
+    expect(result['color.accent.input']).toBe('#ff8c42');
+  });
+
+  it('skips non-colour inputs (e.g. displayFont)', () => {
+    const result = generatePalettesFromInputs({
+      brandPrimary: '#0052cc',
+      displayFont: 'Poppins',
+    });
+
+    expect('color.brand.input' in result).toBe(true);
+    expect(Object.keys(result).every((k) => k.startsWith('color.'))).toBe(true);
+  });
+
+  it('skips colour-input keys with non-string values', () => {
+    const result = generatePalettesFromInputs({
+      brandPrimary: 42 as unknown as string,
+    });
+
+    expect(Object.keys(result)).toHaveLength(0);
+  });
+
+  it('returns an empty object when inputs is empty', () => {
+    const result = generatePalettesFromInputs({});
+    expect(result).toEqual({});
+  });
+
+  it('generates only brand palette when only brandPrimary is provided', () => {
+    const result = generatePalettesFromInputs({
+      brandPrimary: '#081728',
+    });
+
+    expect(Object.keys(result)).toHaveLength(12);
+    for (const key of Object.keys(result)) {
+      expect(key).toMatch(/^color\.brand\./);
+    }
+  });
+
+  it('generates a base palette from a basePrimary input', () => {
+    const result = generatePalettesFromInputs({
+      basePrimary: deriveBaseColorKey('#346099'),
+    });
+
+    for (const step of PALETTE_STEPS) {
+      expect(`color.base.${step}` in result).toBe(true);
+    }
+    expect('color.base.input' in result).toBe(true);
+  });
+
+  it('generates brand, accent, and base palettes together', () => {
+    const result = generatePalettesFromInputs({
+      brandPrimary: '#0052cc',
+      accentPrimary: '#ff8c42',
+      basePrimary: deriveBaseColorKey('#0052cc'),
+    });
+
+    for (const step of PALETTE_STEPS) {
+      expect(`color.brand.${step}` in result).toBe(true);
+      expect(`color.accent.${step}` in result).toBe(true);
+      expect(`color.base.${step}` in result).toBe(true);
+    }
+  });
+});