hcg-color-picker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hcg-color-picker contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,367 @@
+# Google Chrome Style Color Picker
+
+A lightweight, dependency-free color picker widget inspired by Google Chrome's built-in color picker. Supports multiple instances, alpha control, touch input, and the EyeDropper API.
+
+---
+
+## Features
+
+- **No dependencies** - pure vanilla JavaScript, no libraries required
+- **Multiple instances** - attach a picker to any number of buttons, each remembers its own color
+- **Single shared UI** - one picker element is reused across all instances, keeping memory usage minimal
+- **Three color modes** - switch between HEX, RGBA, and HSLA input formats
+- **Alpha / opacity control** - full transparency support, can be enabled or disabled per instance
+- **EyeDropper API** - pick any color from the screen (supported browsers only)
+- **Touch support** - works on mobile and tablet devices
+- **Color preview swatch** - live preview inside the picker
+- **Keyboard accessible** - color text inputs are fully keyboard navigable
+- **`data-color` attribute** - current color is always available on the trigger element via `element.dataset.color`
+- **Event system** - subscribe and unsubscribe to color change events
+- **Programmatic API** - set color, enable/disable, and destroy instances at runtime
+
+---
+
+## Installation
+
+Include the script in your HTML file:
+
+```html
+<script src="hcg-color.js"></script>
+```
+
+---
+
+## Basic Usage
+
+```html
+<button id="my-color-btn">Pick Color</button>
+
+<script>
+    const picker = new hcgColor(
+        document.getElementById('my-color-btn'),
+        '#ff0000'
+    );
+
+    picker.on('change', function (colors) {
+        console.log(colors.hex);
+    });
+</script>
+```
+
+---
+
+## Constructor
+
+```js
+new hcgColor(element, color, onChange, options)
+```
+
+| Parameter  | Type          | Required | Description                                      |
+|------------|---------------|----------|--------------------------------------------------|
+| `element`  | `HTMLElement` | ✅        | The trigger button element                       |
+| `color`    | `string`      | ✅        | Initial color - supports HEX, RGB, HSL formats  |
+| `onChange` | `function`    | ❌        | Shorthand change callback (same as `.on()`)     |
+| `options`  | `object`      | ❌        | Configuration options (see below)                |
+
+---
+
+## Options
+
+| Option  | Type      | Default | Description                          |
+|---------|-----------|---------|--------------------------------------|
+| `alpha` | `boolean` | `true`  | Set to `false` to disable alpha control |
+
+```js
+const picker = new hcgColor(element, '#ff0000', null, { alpha: false });
+```
+
+---
+
+## Initial Color Formats
+
+The `color` parameter accepts any of the following formats:
+
+```js
+new hcgColor(el, '#ff0000');              // 6-digit HEX
+new hcgColor(el, '#ff0000ff');            // 8-digit HEX with alpha
+new hcgColor(el, '#f00');                 // 3-digit HEX shorthand
+new hcgColor(el, 'rgb(255, 0, 0)');       // RGB
+new hcgColor(el, 'rgba(255, 0, 0, 0.5)'); // RGBA
+new hcgColor(el, 'hsl(0, 100%, 50%)');    // HSL
+new hcgColor(el, 'hsla(0, 100%, 50%, 1)');// HSLA
+```
+
+---
+
+## Instance Methods
+
+### `.on(event, callback)`
+Subscribe to an event.
+```js
+picker.on('change', function (colors) {
+    console.log(colors.hex);   // "#ff0000"
+    console.log(colors.rgb);   // "rgb(255, 0, 0)"
+    console.log(colors.rgba);  // "rgba(255, 0, 0, 1)"
+    console.log(colors.hsl);   // "hsl(0, 100%, 50%)"
+    console.log(colors.hsla);  // "hsla(0, 100%, 50%, 1)"
+});
+```
+
+### `.off(event, callback)`
+Unsubscribe a specific listener.
+```js
+function onChange(colors) { console.log(colors.hex); }
+
+picker.on('change', onChange);
+picker.off('change', onChange);
+```
+
+### `.setColor(color)`
+Programmatically set the color. Fires the `change` event.
+```js
+picker.setColor('#00ff00');
+picker.setColor('rgb(0, 255, 0)');
+```
+
+### `.getColor()`
+Returns the current color as an 8-digit or 6-digit HEX string.
+```js
+const hex = picker.getColor(); // "#ff0000"
+```
+
+### `.setAlphaEnabled(boolean)`
+Enable or disable the alpha slider at runtime.
+```js
+picker.setAlphaEnabled(false); // hide alpha controls
+picker.setAlphaEnabled(true);  // show alpha controls
+```
+
+### `.disable()`
+Disable the picker - prevents the picker from opening on click.
+```js
+picker.disable();
+```
+
+### `.enable()`
+Re-enable a previously disabled picker.
+```js
+picker.enable();
+```
+
+### `.destroy()`
+Fully remove the picker instance - cleans up event listeners, clears state, and removes the color from the element.
+```js
+picker.destroy();
+```
+
+---
+
+## Static Methods
+
+### `hcgColor.eyeDropper()`
+Opens the EyeDropper tool and applies the picked color to the currently active picker instance.
+```js
+hcgColor.eyeDropper();
+```
+
+---
+
+## Events
+
+| Event    | Callback data | Description                        |
+|----------|---------------|------------------------------------|
+| `change` | `colors`      | Fired every time the color changes |
+
+### `colors` object
+
+```js
+{
+    hex:  "#ff0000",
+    hexa: "#ff0000",
+    rgb:  "rgb(255, 0, 0)",
+    rgba: "rgba(255, 0, 0, 1)",
+    hsl:  "hsl(0, 100%, 50%)",
+    hsla: "hsla(0, 100%, 50%, 1)"
+}
+```
+
+---
+
+## Multiple Instances
+
+Each instance is independent - they share one picker UI but each stores its own color state.
+
+```js
+const picker1 = new hcgColor(document.getElementById('btn1'), '#ff0000');
+const picker2 = new hcgColor(document.getElementById('btn2'), '#0000ff');
+const picker3 = new hcgColor(document.getElementById('btn3'), '#00ff00', null, { alpha: false });
+
+picker1.on('change', colors => console.log('Picker 1:', colors.hex));
+picker2.on('change', colors => console.log('Picker 2:', colors.hex));
+```
+
+---
+
+## Reading Color Without an Instance Reference
+
+The current color is always stored on the trigger element via `data-color`, so you can read it anywhere without keeping a reference to the picker instance:
+
+```js
+// On form submit, collect all picker colors
+document.querySelectorAll('.color-btn').forEach(btn => {
+    console.log(btn.dataset.color); // "#ff0000"
+});
+```
+
+---
+
+## Usage in React
+
+A dedicated React component is available as a separate package.
+
+### Installation
+
+```bash
+npm install hcg-color-picker-react
+```
+
+### Import
+
+```jsx
+import ColorPicker from 'hcg-color-picker-react';
+import 'hcg-color-picker-react/ColorPicker.css';
+```
+
+> `createPortal` is used internally and imported from `react-dom` - no extra setup needed.
+
+---
+
+### Props
+
+| Prop       | Type       | Default     | Description                              |
+|------------|------------|-------------|------------------------------------------|
+| `color`    | `string`   | `'#ff0000'` | Initial color - HEX, RGB, HSL formats   |
+| `onChange` | `function` | -           | Called every time the color changes      |
+| `alpha`    | `boolean`  | `true`      | Set to `false` to disable alpha control  |
+| `disabled` | `boolean`  | `false`     | Prevents the picker from opening         |
+| `className`| `string`   | -           | CSS class applied to the trigger button  |
+| `style`    | `object`   | -           | Inline styles for the trigger button     |
+
+---
+
+### Basic usage
+
+```jsx
+import ColorPicker from 'hcg-color-picker-react';
+import 'hcg-color-picker-react/ColorPicker.css';
+
+function App() {
+    function handleChange(colors) {
+        console.log(colors.hex);   // "#ff0000"
+        console.log(colors.rgba);  // "rgba(255, 0, 0, 1)"
+        console.log(colors.hsla);  // "hsla(0, 100%, 50%, 1)"
+    }
+
+    return (
+        <div>
+            {/* Basic */}
+            <ColorPicker color="#ff0000" onChange={handleChange} />
+
+            {/* No alpha */}
+            <ColorPicker color="#0000ff" alpha={false} onChange={handleChange} />
+
+            {/* Disabled */}
+            <ColorPicker color="#00ff00" disabled={true} />
+        </div>
+    );
+}
+
+export default App;
+```
+
+---
+
+### Programmatic API via `ref`
+
+Use `ref` to call methods directly from a parent component:
+
+```jsx
+import { useRef } from 'react';
+import ColorPicker from 'hcg-color-picker-react';
+import 'hcg-color-picker-react/ColorPicker.css';
+
+function App() {
+    const pickerRef = useRef(null);
+
+    return (
+        <div>
+            <ColorPicker
+                ref={pickerRef}
+                color="#ff9800"
+                onChange={colors => console.log(colors.hex)}
+            />
+
+            <button onClick={() => pickerRef.current.setColor('#e91e63')}>Set Pink</button>
+            <button onClick={() => alert(pickerRef.current.getColor())}>Get Color</button>
+            <button onClick={() => pickerRef.current.setAlphaEnabled(false)}>Disable Alpha</button>
+        </div>
+    );
+}
+
+export default App;
+```
+
+### Ref methods
+
+| Method                    | Description                              |
+|---------------------------|------------------------------------------|
+| `.setColor(color)`        | Programmatically set the color           |
+| `.getColor()`             | Returns current color as HEX string      |
+| `.setAlphaEnabled(bool)`  | Show or hide the alpha slider at runtime |
+| `.enable()`               | Enable the picker                        |
+| `.disable()`              | Disable the picker                       |
+
+---
+
+### Multiple instances
+
+Each `<ColorPicker>` is a fully independent instance - no shared state between them:
+
+```jsx
+function App() {
+    return (
+        <div>
+            <ColorPicker color="#f44336" onChange={c => console.log('Red picker:', c.hex)} />
+            <ColorPicker color="#4caf50" onChange={c => console.log('Green picker:', c.hex)} />
+            <ColorPicker color="#2196f3" alpha={false} onChange={c => console.log('Blue picker:', c.hex)} />
+        </div>
+    );
+}
+```
+
+---
+
+### React - Key notes
+
+| | Reason |
+|---|---|
+| `forwardRef` | Allows parent components to access ref methods |
+| `useImperativeHandle` | Exposes `setColor`, `getColor` etc. via ref |
+| `createPortal` (from `react-dom`) | Renders picker popup at `document.body` level to avoid overflow/z-index issues |
+| Unique SVG IDs per instance | Each picker generates unique gradient IDs - no conflicts with multiple instances |
+
+---
+
+## Browser Support
+
+| Feature          | Support                          |
+|------------------|----------------------------------|
+| Color picker UI  | All modern browsers              |
+| Touch events     | iOS Safari, Android Chrome       |
+| EyeDropper API   | Chrome 95+, Edge 95+ (not Firefox/Safari) |
+
+---
+
+## License
+
+MIT