Merge branch 'main' into dependabot/npm_and_yarn/tslib-2.8.0

CONTRIBUTING.md

@@ -1,46 +1,37 @@
 # Contributing to Colorus.js 🎉
 
-We welcome contributions to Colorus.js! Whether you're fixing bugs 🐛, improving documentation 📚, or adding new features through plugins ✨, your help is valuable in making this library even better.
+Thank you for considering a contribution to **Colorus.js**! From fixing bugs to improving documentation or expanding functionality with plugins and parsers, every contribution is valuable.
 
-## Future Plans: Mono-repo 📦
+## Design Choice
 
-In the future, we intend to transition the Colorus.js repository into a mono-repo structure. This will allow us to manage the core package and official plugins within a single repository, streamlining development and maintenance.
+The design choice ensures that colors are parsed, transformed, and returned in predictable and reliable ways, even if it means some operations may be slower than highly optimized alternatives.
 
-## Core Functionality: Non-Extensible (Intentional) 🔒
+Despite this focus, **Colorus.js** performs efficiently in most use cases. While the library might not aim to be the absolute fastest, it’s still capable of handling high-demand operations quickly. If you identify areas where optimizations can be made without sacrificing validation, please feel free to propose changes or submit a pull request.
 
-| Core Functionality         | Extensible via Plugins |
-| -------------------------- | ---------------------- |
-| Color creation (`dye`)     | No                     |
-| Color conversions          | No                     |
-| Color adjustments          | No                     |
-| Accessibility calculations | No                     |
+## Core and Extensible Features 🔒
 
-The plugin system provides a powerful and flexible mechanism for adding custom features and behaviors to color objects created by `dye`. We encourage you to leverage this system to enhance the capabilities of Colorus.js without modifying its core. 💪
+| Feature                           | Extensible via Plugins or Parsers             |
+| --------------------------------- | --------------------------------------------- |
+| Color creation (`dye`)            | [Parsers](docs/guide/WORKING_WITH_PARSERS.md) |
+| Color conversions and adjustments | [Plugins](docs/guide/WORKING_WITH_PLUGINS.md) |
 
-## Focus on Performance 🚀
-
-We're always looking for ways to improve the performance of Colorus.js. Contributions that enhance the speed or reduce the bundle size of the library are highly appreciated. If you have ideas for optimizations or performance improvements, please share them with us!
+The plugin and parser systems in version 2.0.0 allow easy extensibility, making it possible to add custom features while preserving the core library’s structure.
 
 ## How to Contribute 🛠️
 
-1. **For complex or significant changes:** Please open an issue first to discuss your proposed changes with the maintainers. This helps ensure alignment with the project's goals and avoids potential conflicts or wasted effort. 💬
-
-2. **For simple fixes (e.g., typos, grammar):** Feel free to directly open a pull request. 👍
-
-3. In either case, follow these steps:
-   - Fork the repository and create a new branch for your feature or bug fix. 🍴
-   - Make your changes and ensure that the code is well-documented and tested. 🧪
-   - Submit a pull request, clearly describing your changes and their benefits. 🚀
+1. **Significant Changes:** Open an issue first to discuss.
+2. **Minor Fixes (e.g., typos):** Open a pull request directly.
+3. **Steps:**
+   - Fork the repository, create a branch, and make your changes.
+   - Ensure documentation and tests accompany your updates.
+   - Submit a pull request with a clear, concise description.
 
 ## Documentation and Type Support 📚
 
-Clear and comprehensive documentation is essential for any library, and Colorus.js is no exception. We strive to provide accurate and up-to-date documentation for all core functions, types, and the plugin system. Contributions that improve the documentation, add examples, or clarify usage are highly valued.
-✍️
-
-### Type Safety and Function Chaining 🔒⛓️
+Complete documentation and robust TypeScript support are priorities for **Colorus.js**. Contributions that improve docs, examples, or types are always welcome.
 
-We place a strong emphasis on type safety. The function chaining mechanism, in particular, relies heavily on TypeScript's type inference to provide a smooth and error-free developer experience. When contributing, pay close attention to maintaining and enhancing the type definitions, especially when modifying or adding new features that interact with the chaining mechanism.
+## Type Safety and Chaining 🔒⛓️
 
-We appreciate your interest in contributing to Colorus.js! Please don't hesitate to reach out if you have any questions or need further guidance. 🙌
+Type safety is critical to **Colorus.js**, particularly in the chaining API. Please ensure typings are preserved or improved when contributing any functions affecting chaining behavior.
 
-**Thank you for your support!** 🙏
+**Thank you for supporting Colorus.js!** 🙏

README.md

@@ -1,60 +1,65 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/supitsdu/colorus-js/main/favicon.svg" width="256">
-<p>
-
 # Colorus.js
 
-[![NPM](https://img.shields.io/badge/NPM-%23CB3837.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=black&color=black)](https://www.npmjs.com/package/colorus-js)
-[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white&labelColor=black&color=black)](https://www.typescriptlang.org/)
-[![GitHub stars](https://img.shields.io/github/stars/supitsdu/colorus-js?style=for-the-badge&logo=Github&logoColor=white&labelColor=black&color=black)](https://github.com/supitsdu/colorus-js)
-
-A versatile and powerful color manipulation library for JavaScript.
+**Colorus.js** is a flexible color manipulation library with multi-format support and TypeScript compatibility.
 
 ## Features
 
-- **Intuitive API:** Work with colors effortlessly using a simple and expressive function-based API.
-- **Multiple Color Models:** Supports various color models, including RGB, HSL, HSV, and CMYK.
-- **Flexible Input/Output:** Accepts color inputs in different formats (hex, rgb, hsl, etc.) and provides various output options.
-- **Color Conversions:** Easily convert between different color models and formats.
-- **Color Adjustments:** Perform common color adjustments like lightening, darkening, saturating, desaturating, and more.
-- **Accessibility:** Calculate relative luminance and contrast ratios for improved accessibility.
-- **Extensible:** Extend the core functionality with custom plugins.
-- **TypeScript Support:** Provides full TypeScript support for enhanced type safety and developer experience.
+- 🌈 **Model-Agnostic Design** – Supports HEX, RGB, HSL, HSV, CMYK, and is extendable to any color model.
+- ⚡️ **Effortless Chaining** – Chain transformations with seamless TypeScript support for clarity and reliability.
+- 🧩 **Extensible by Design** – Add custom parsers and plugins to unlock new models and functions.
+- 🔒 **Solid Type Safety** – Robust TypeScript types deliver consistent, predictable color transformations.
 
-### Usage
+## Quick Start
 
 ```javascript
 import { dye } from "colorus-js"
 
-const color = dye("#ff0000") // Create a color from a hex code
+const color = dye("rgb(255 0 0)")
+
+console.log(color.hsl) // { h: 0, s: 100, l: 50, a: 1 }
+console.log(color.luminance) // 0.21
+console.log(color.source.isValid) // true
+console.log(color.source.model) // "rgb"
+```
+
+### Multi-Format Support
+
+```javascript
+import { dye, hslParser } from "colorus-js"
 
-console.log(color.rgb) // Output: { r: 255, g: 0, b: 0, a: 1 }
-console.log(color.toHsl()) // Output: hsl(0, 100%, 50%)
+const color = dye("hsl(120deg 50% 30%)", { parsers: [hslParser] })
 
-const lighterColor = color.lighten(0.2) // Lighten the color by 20%
-console.log(lighterColor.toHex()) // Output: #ff6666
+console.log(color.luminance) // 0.13
+console.log(color.rgb) // { r: 38.25, g: 114.75, b: 38.25, a: 1 }
 ```
 
-### Plugins
+**Built-in Parsers:** `cmykParser`, `hexParser`, `hslParser`, `hsvParser`, `rgbParser` (default)
 
-Extend the `dye` function with custom methods using plugins.
+### Custom Plugins
 
 ```javascript
-const colorWithPlugin = dye("#0000ff", {
-  plugins: {
-    isBlue() {
-      return this.rgb.b > 200
-    }
-  }
+import { createPlugin, dye } from "colorus-js"
+
+// Custom grayscale plugin definition
+const grayscale = createPlugin("grayscale", function () {
+  const avg = (this.rgb.r + this.rgb.g + this.rgb.b) / 3
+  return dye({ r: avg, g: avg, b: avg, a: this.rgb.a }, this.options)
 })
 
-console.log(colorWithPlugin.isBlue()) // Output: true
+// Usage
+const color = dye("rgb(255, 0, 0)", { plugins: { grayscale } })
+
+console.log(color.grayscale().rgb) // { r: 85, g: 85, b: 85, a: 1 }
 ```
 
-For more information see [Working with Plugins Guide](docs/WORKING_WITH_PLUGINS.md).
+**Built-in Plugins:** `invert`, `lighten`, `darken`, `saturate`, `desaturate`, `toCmyk`, `toHex`, `toHsl`, `toHsv`, `toRgb`
 
-## Contributing
+## Further Reading
+
+- [API Reference](docs/API.md)
+- [Working with Plugins](docs/guide/WORKING_WITH_PLUGINS.md)
+- [Working with Parsers](docs/guide/WORKING_WITH_PARSERS.md)
 
-Contributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md).
+## Contributing
 
-[**Leave a star and help spread the hues! 🎨⭐**](https://github.com/supitsdu/colorus-js)
+Contributions are welcome! See the [Contributing Guide](CONTRIBUTING.md).

biome.json

@@ -1,7 +1,15 @@
 {
 	"files": {
-		"ignore": ["node_modules", "coverage", "docs", ".github", "_test"],
-		"include": ["src/*.ts", "test/*.ts"]
+		"ignore": [
+			"node_modules",
+			"coverage",
+			"docs",
+			".github",
+			"_test",
+			"build",
+			"dist"
+		],
+		"include": ["src/*.ts", "test/*.ts", "rollup.config.js", "jest.config.js"]
 	},
 	"organizeImports": { "enabled": true },
 	"formatter": {
@@ -31,18 +39,25 @@
 		"enabled": true,
 		"rules": {
 			"complexity": {
-				"noStaticOnlyClass": "warn"
+				"noStaticOnlyClass": "warn",
+				"noForEach": "off"
 			},
 			"suspicious": {
 				"noDebugger": "off",
-				"noConsoleLog": "info",
+				"noConsoleLog": "warn",
 				"noExplicitAny": "off",
 				"noConfusingVoidType": "off"
 			},
 			"style": {
 				"noShoutyConstants": "warn",
 				"useNamingConvention": "error",
-				"noNonNullAssertion": "off"
+				"noNonNullAssertion": "off",
+				"noInferrableTypes": "off",
+				"useNumberNamespace": "off"
+			},
+			"correctness": {
+				"noUnusedVariables": "warn",
+				"noUnusedImports": "warn"
 			}
 		}
 	}

docs/API.md

@@ -0,0 +1,68 @@
+# API Reference
+
+Detailed information about the core functionalities, methods, and types available in the library.
+
+## Core Method
+
+### `dye(input: Colors.Input, options?: Dye.Options): Dye.Instance`
+
+The primary function for creating a color instance.
+
+**Parameters:**
+
+- `input`: A color input, which can be either a color string (e.g., `"#FF5733"`, `"rgb(255, 0, 0)"`, `"hsl(120, 100%, 50%)"`, etc.) or an object representing RGB values.
+- `options`: An optional configuration object to customize parsing and plugin behavior.
+  - `plugins`: An object containing custom plugins to extend functionality.
+  - `parsers`: An array of `ColorParser` instances to use for the input.
+  - `formatOptions`: Options for output formatting.
+
+**Returns:** An instance of `Dye.Instance` with methods for color manipulation.
+
+**Example:**
+
+```javascript
+import { dye } from "colorus-js"
+
+const color = dye("rgb(255, 0, 0)")
+console.log(color.hsl) // { h: 0, s: 100, l: 50, a: 1 }
+```
+
+## Color Types
+
+Colorus.js supports various color representations defined as follows:
+
+- **`Colors.Rgb`**: Represents colors in RGB format as `{ r: number, g: number, b: number, a: number }`.
+- **`Colors.Hsl`**: Represents colors in HSL format as `{ h: number, s: number, l: number, a: number }`.
+- **`Colors.Hsv`**: Represents colors in HSV format as `{ h: number, s: number, v: number, a: number }`.
+- **`Colors.Cmyk`**: Represents colors in CMYK format as `{ c: number, m: number, y: number, k: number, a: number }`.
+
+All these formats maintain an alpha channel for transparency, represented as a number (0 to 1).
+
+## Color Properties
+
+Each `Dye.Instance` provides access to various color properties calculated based on the initial input:
+
+- `rgb`: Returns the RGB representation.
+- `hsl`: Returns the HSL representation.
+- `hsv`: Returns the HSV representation.
+- `cmyk`: Returns the CMYK representation.
+- `luminance`: Calculates and returns the luminance value.
+- `alpha`: Returns the alpha (transparency) value.
+- `hue`: Returns the hue value.
+- `source`: Metadata and validity.
+- `error`: Returns the error message, if any.
+
+**Example:**
+
+```javascript
+const color = dye("hsl(120, 100%, 50%)")
+console.log(color.rgb) // { r: 0, g: 255, b: 0, a: 1 }
+```
+
+## Built-in Parsers
+
+For detailed information about the built-in parsers available in Colorus.js, please refer to the [Working with Parsers](/docs/guide/WORKING_WITH_PARSERS.md).
+
+## Built-in Plugins
+
+For detailed information about the built-in plugins available in Colorus.js, please refer to the [Working with Plugins](/docs/guide/WORKING_WITH_PLUGINS.md).