@hero-design/rn 8.108.1 → 8.108.3-alpha.0

package/src/utils/__tests__/helpers.spec.ts

@@ -1,5 +1,6 @@
 import {
   deepCompareValue,
+  dimHex,
   hexToRgba,
   omit,
   pick,
@@ -256,3 +257,73 @@ describe('hexToRgba', () => {
     });
   });
 });
+
+describe('dimHex', () => {
+  it.each`
+    hex          | surface      | amount | expected
+    ${'#FF0000'} | ${'#FFFFFF'} | ${0.5} | ${'#ff8080'}
+    ${'#000000'} | ${'#FFFFFF'} | ${0.5} | ${'#808080'}
+    ${'#FF0000'} | ${'#FFFFFF'} | ${0}   | ${'#ff0000'}
+    ${'#FF0000'} | ${'#FFFFFF'} | ${1}   | ${'#ffffff'}
+    ${'FF0000'}  | ${'FFFFFF'}  | ${0.5} | ${'#ff8080'}
+    ${'#fff'}    | ${'#000'}    | ${0.5} | ${'#808080'}
+    ${'fff'}     | ${'000'}     | ${0.5} | ${'#808080'}
+  `(
+    'should dim hex "$hex" with surface "$surface" by amount $amount to "$expected"',
+    ({ hex, surface, amount, expected }) => {
+      expect(dimHex(hex, surface, amount)).toBe(expected);
+    }
+  );
+
+  it('should use default parameters', () => {
+    expect(dimHex('#000000', '#ffffff')).toBe('#999999');
+  });
+
+  it('should throw error for invalid input types', () => {
+    // @ts-expect-error: Invalid param type
+    expect(() => dimHex(123, '#fff', 0.5)).toThrow(
+      'dimHex: hex and surface must be strings and amount must be a number'
+    );
+    // @ts-expect-error: Invalid param type
+    expect(() => dimHex('#fff', 123, 0.5)).toThrow(
+      'dimHex: hex and surface must be strings and amount must be a number'
+    );
+    // @ts-expect-error: Invalid param type
+    expect(() => dimHex('#fff', '#fff', '0.5')).toThrow(
+      'dimHex: hex and surface must be strings and amount must be a number'
+    );
+  });
+
+  it('should throw error for amount values outside 0-1 range', () => {
+    expect(() => dimHex('#fff', '#fff', -0.1)).toThrow(
+      'dimHex: amount must be between 0 and 1'
+    );
+    expect(() => dimHex('#fff', '#fff', 1.1)).toThrow(
+      'dimHex: amount must be between 0 and 1'
+    );
+  });
+
+  it('should throw error for invalid hex formats', () => {
+    expect(() => dimHex('invalid', '#fff', 0.5)).toThrow(
+      'dimHex: hex must be a valid 3 or 6 character hex color'
+    );
+    expect(() => dimHex('#gggggg', '#fff', 0.5)).toThrow(
+      'dimHex: hex must be a valid 3 or 6 character hex color'
+    );
+    expect(() => dimHex('#ff', '#fff', 0.5)).toThrow(
+      'dimHex: hex must be a valid 3 or 6 character hex color'
+    );
+  });
+
+  it('should throw error for invalid surface formats', () => {
+    expect(() => dimHex('#fff', 'invalid', 0.5)).toThrow(
+      'dimHex: surface must be a valid 3 or 6 character hex color'
+    );
+    expect(() => dimHex('#fff', '#gggggg', 0.5)).toThrow(
+      'dimHex: surface must be a valid 3 or 6 character hex color'
+    );
+    expect(() => dimHex('#fff', '#ff', 0.5)).toThrow(
+      'dimHex: surface must be a valid 3 or 6 character hex color'
+    );
+  });
+});

package/src/utils/helpers.ts

@@ -68,6 +68,85 @@ export function hexToRgba(hex: string, a: number) {
   return `rgba(${r},${g},${b},${a})`;
 }
 
+/**
+ * Dim a hex color by blending it with a surface color
+ * @param hex - The hex color to dim (3 or 6 characters, with or without #)
+ * @param surface - The surface color to blend with.
+ * @param amount - The amount of dimming (0 = original color, 1 = fully surface color)
+ * @returns The dimmed hex color
+ */
+const DEFAULT_DIM_AMOUNT = 0.6;
+export function dimHex(
+  hex: string,
+  surface: string,
+  amount = DEFAULT_DIM_AMOUNT
+): string {
+  // Validate inputs
+  if (
+    typeof hex !== 'string' ||
+    typeof surface !== 'string' ||
+    typeof amount !== 'number'
+  ) {
+    throw new Error(
+      'dimHex: hex and surface must be strings and amount must be a number'
+    );
+  }
+
+  if (amount < 0 || amount > 1) {
+    throw new Error('dimHex: amount must be between 0 and 1');
+  }
+
+  // Remove # if present and validate hex format
+  const cleanHex = hex.replace(/^#/, '');
+  const cleanSurface = surface.replace(/^#/, '');
+
+  if (!/^[0-9A-Fa-f]{3}$|^[0-9A-Fa-f]{6}$/.test(cleanHex)) {
+    throw new Error('dimHex: hex must be a valid 3 or 6 character hex color');
+  }
+
+  if (!/^[0-9A-Fa-f]{3}$|^[0-9A-Fa-f]{6}$/.test(cleanSurface)) {
+    throw new Error(
+      'dimHex: surface must be a valid 3 or 6 character hex color'
+    );
+  }
+
+  // Handle 3-character hex codes (e.g., #fff -> #ffffff)
+  const normalizedHex =
+    cleanHex.length === 3
+      ? cleanHex
+          .split('')
+          .map((char) => char + char)
+          .join('')
+      : cleanHex;
+
+  const normalizedSurface =
+    cleanSurface.length === 3
+      ? cleanSurface
+          .split('')
+          .map((char) => char + char)
+          .join('')
+      : cleanSurface;
+
+  // Parse hex values
+  const r = parseInt(normalizedHex.substring(0, 2), 16);
+  const g = parseInt(normalizedHex.substring(2, 4), 16);
+  const b = parseInt(normalizedHex.substring(4, 6), 16);
+
+  const sr = parseInt(normalizedSurface.substring(0, 2), 16);
+  const sg = parseInt(normalizedSurface.substring(2, 4), 16);
+  const sb = parseInt(normalizedSurface.substring(4, 6), 16);
+
+  // Linear interpolation between colors
+  const lerp = (c: number, s: number): number =>
+    Math.round(c * (1 - amount) + s * amount);
+
+  const rr = lerp(r, sr).toString(16).padStart(2, '0');
+  const gg = lerp(g, sg).toString(16).padStart(2, '0');
+  const bb = lerp(b, sb).toString(16).padStart(2, '0');
+
+  return `#${rr}${gg}${bb}`;
+}
+
 export const deepCompareValue = <V>(a: V, b: V): boolean => {
   // Handle strict equality first (handles primitives, null, undefined)
   if (a === b) return true;