vinh-colors-utils 3.1.0

package/README.md

@@ -0,0 +1,83 @@
+# @org/colors
+
+Color conversion and manipulation utilities for TypeScript applications.
+
+## 📦 Package Information
+
+- **Version**: 0.0.1
+- **Publishable**: ✅ Yes
+- **Tag**: `scope:colors`
+- **Module Boundaries**: Can only import from `scope:shared` packages
+
+## 🚀 Features
+
+This package provides comprehensive color utilities:
+
+- **hexToRgb** - Convert hex color codes to RGB values
+- **rgbToHex** - Convert RGB values to hex color codes
+- **lighten** - Make colors lighter by a percentage
+- **darken** - Make colors darker by a percentage
+
+## 📝 Usage Examples
+
+```typescript
+import { hexToRgb, rgbToHex, lighten, darken } from '@org/colors';
+
+// Convert hex to RGB
+hexToRgb('#FF5733');  // { r: 255, g: 87, b: 51 }
+hexToRgb('#000');     // { r: 0, g: 0, b: 0 }
+
+// Convert RGB to hex
+rgbToHex(255, 87, 51);  // '#FF5733'
+rgbToHex(0, 0, 0);      // '#000000'
+
+// Lighten colors
+lighten('#FF5733', 20);  // Returns a 20% lighter shade
+lighten('#000000', 50);  // Returns a 50% lighter shade (gray)
+
+// Darken colors
+darken('#FF5733', 20);   // Returns a 20% darker shade
+darken('#FFFFFF', 30);   // Returns a 30% darker shade
+```
+
+## 🧪 Testing
+
+```bash
+# Run tests for this package
+nx test colors
+
+# Run tests in watch mode
+nx test colors --watch
+```
+
+## 🏗️ Building
+
+```bash
+# Build the package
+nx build colors
+
+# The build output will be in dist/packages/colors
+```
+
+## 📋 Available Commands
+
+```bash
+nx build colors    # Build the package
+nx test colors     # Run tests
+nx lint colors     # Lint the package
+```
+
+## 🔒 Module Boundaries
+
+This package has the tag `scope:colors` and can only import from:
+- `@org/utils` (tagged with `scope:shared`)
+
+Attempting to import from `@org/strings` or `@org/async` will result in a linting error due to module boundary constraints.
+
+## 🎨 Color Format Support
+
+The utilities support various color formats:
+- **Hex**: `#RGB`, `#RRGGBB`
+- **RGB**: Object with `r`, `g`, `b` properties (0-255)
+
+All functions include proper validation and error handling for invalid color formats.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/colors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export * from './lib/colors.js';

package/dist/lib/colors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * RGB color representation
+ */
+export interface RgbColor {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * HSL color representation
+ */
+export interface HslColor {
+    h: number;
+    s: number;
+    l: number;
+}
+/**
+ * Convert hex color to RGB
+ */
+export declare function hexToRgb(hex: string): RgbColor;
+/**
+ * Convert RGB to hex color
+ */
+export declare function rgbToHex(r: number, g: number, b: number): string;
+export declare function rgbToHex(rgb: RgbColor): string;
+/**
+ * Darken a color by percentage
+ */
+export declare function darken(color: string, percent: number): string;
+/**
+ * Lighten a color by percentage
+ */
+export declare function lighten(color: string, percent: number): string;
+/**
+ * Validate hex color code
+ */
+export declare function isValidHex(color: unknown): color is string;
+/**
+ * Validate RGB values
+ */
+export declare function isValidRgb(r: number, g: number, b: number): boolean;
+export declare function isValidRgb(rgb: Partial<RgbColor>): boolean;
+/**
+ * Get contrast ratio between two colors
+ */
+export declare function getContrastRatio(color1: string, color2: string): number;
+/**
+ * Generate a random hex color
+ */
+export declare function randomHex(): string;
+/**
+ * Convert RGB to HSL
+ */
+export declare function rgbToHsl(r: number, g: number, b: number): HslColor;
+export declare function rgbToHsl(rgb: RgbColor): HslColor;
+//# sourceMappingURL=colors.d.ts.map

package/dist/lib/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../../src/lib/colors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,QAAQ;IACrB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACrB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAoB9C;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;AAClE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAAC;AA4BhD;;GAEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAgB7D;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAgB9D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAG1D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;AACrE,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC;AAoB5D;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAuBvE;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAGlC;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;AACpE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,GAAG,QAAQ,CAAC"}

package/dist/lib/colors.js

@@ -0,0 +1,154 @@
+/**
+ * Convert hex color to RGB
+ */
+export function hexToRgb(hex) {
+    if (!isValidHex(hex)) {
+        throw new Error('Invalid hex color');
+    }
+    // Remove # if present
+    const cleanHex = hex.replace('#', '');
+    // Handle 3-digit hex
+    const fullHex = cleanHex.length === 3
+        ? cleanHex.split('').map(char => char + char).join('')
+        : cleanHex;
+    const bigint = parseInt(fullHex, 16);
+    return {
+        r: (bigint >> 16) & 255,
+        g: (bigint >> 8) & 255,
+        b: bigint & 255
+    };
+}
+export function rgbToHex(rOrRgb, g, b) {
+    let r;
+    if (typeof rOrRgb === 'object') {
+        ({ r, g, b } = rOrRgb);
+    }
+    else {
+        r = rOrRgb;
+        g = g;
+        b = b;
+    }
+    if (!isValidRgb(r, g, b)) {
+        throw new Error('Invalid RGB values. Must be between 0-255');
+    }
+    const toHex = (n) => {
+        const hex = n.toString(16);
+        return hex.length === 1 ? '0' + hex : hex;
+    };
+    return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+/**
+ * Darken a color by percentage
+ */
+export function darken(color, percent) {
+    if (!isValidHex(color)) {
+        throw new Error('Invalid hex color');
+    }
+    if (percent < 0 || percent > 100) {
+        throw new Error('Percent must be between 0 and 100');
+    }
+    const rgb = hexToRgb(color);
+    const factor = 1 - (percent / 100);
+    return rgbToHex(Math.round(rgb.r * factor), Math.round(rgb.g * factor), Math.round(rgb.b * factor));
+}
+/**
+ * Lighten a color by percentage
+ */
+export function lighten(color, percent) {
+    if (!isValidHex(color)) {
+        throw new Error('Invalid hex color');
+    }
+    if (percent < 0 || percent > 100) {
+        throw new Error('Percent must be between 0 and 100');
+    }
+    const rgb = hexToRgb(color);
+    const factor = percent / 100;
+    return rgbToHex(Math.round(rgb.r + (255 - rgb.r) * factor), Math.round(rgb.g + (255 - rgb.g) * factor), Math.round(rgb.b + (255 - rgb.b) * factor));
+}
+/**
+ * Validate hex color code
+ */
+export function isValidHex(color) {
+    if (typeof color !== 'string')
+        return false;
+    return /^#?([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/.test(color);
+}
+export function isValidRgb(rOrRgb, g, b) {
+    let r;
+    if (typeof rOrRgb === 'object') {
+        ({ r, g, b } = rOrRgb);
+    }
+    else {
+        r = rOrRgb;
+    }
+    const isValid = (n) => n !== undefined && Number.isInteger(n) && n >= 0 && n <= 255;
+    return isValid(r) && isValid(g) && isValid(b);
+}
+/**
+ * Get contrast ratio between two colors
+ */
+export function getContrastRatio(color1, color2) {
+    const getLuminance = (rgb) => {
+        const toLinear = (val) => {
+            const normalized = val / 255;
+            return normalized <= 0.03928
+                ? normalized / 12.92
+                : Math.pow((normalized + 0.055) / 1.055, 2.4);
+        };
+        const r = toLinear(rgb.r);
+        const g = toLinear(rgb.g);
+        const b = toLinear(rgb.b);
+        return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    };
+    const lum1 = getLuminance(hexToRgb(color1));
+    const lum2 = getLuminance(hexToRgb(color2));
+    const lighter = Math.max(lum1, lum2);
+    const darker = Math.min(lum1, lum2);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+/**
+ * Generate a random hex color
+ */
+export function randomHex() {
+    const random = () => Math.floor(Math.random() * 256);
+    return rgbToHex(random(), random(), random());
+}
+export function rgbToHsl(rOrRgb, g, b) {
+    let r;
+    if (typeof rOrRgb === 'object') {
+        ({ r, g, b } = rOrRgb);
+    }
+    else {
+        r = rOrRgb;
+        g = g;
+        b = b;
+    }
+    r /= 255;
+    g /= 255;
+    b /= 255;
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    let h = 0;
+    let s = 0;
+    const l = (max + min) / 2;
+    if (max !== min) {
+        const d = max - min;
+        s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+        switch (max) {
+            case r:
+                h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+                break;
+            case g:
+                h = ((b - r) / d + 2) / 6;
+                break;
+            case b:
+                h = ((r - g) / d + 4) / 6;
+                break;
+        }
+    }
+    return {
+        h: Math.round(h * 360),
+        s: Math.round(s * 100),
+        l: Math.round(l * 100)
+    };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "vinh-colors-utils",
+  "version": "3.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@org/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "nx": {
+    "tags": [
+      "scope:colors"
+    ]
+  }
+}