@bornova/colorpicker 1.0.0

package/dist/types/colors.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Converts HSVA color values to RGBA.
+ * @param {HSVA} hsva
+ * @returns {RGBA}
+ */
+export function HSVAtoRGBA(hsva: HSVA): RGBA;
+/**
+ * Converts HSVA color values to HSLA.
+ * @param {HSVA} hsva
+ * @returns {HSLA}
+ */
+export function HSVAtoHSLA(hsva: HSVA): HSLA;
+/**
+ * Converts RGBA color values to HSVA.
+ * @param {RGBA} rgba
+ * @returns {HSVA}
+ */
+export function RGBAtoHSVA(rgba: RGBA): HSVA;
+/**
+ * Parses any valid CSS color string and returns its RGBA components.
+ * @param {string} str - Any valid CSS color string.
+ * @returns {RGBA}
+ */
+export function strToRGBA(str: string): RGBA;
+/**
+ * Converts RGBA color values to a CSS hex color string.
+ * @param {RGBA} rgba
+ * @returns {string} Hex color string (e.g. `#rrggbb` or `#rrggbbaa`).
+ */
+export function RGBAToHex(rgba: RGBA): string;
+/**
+ * Converts RGBA color values to a CSS `rgb()` or `rgba()` string.
+ * @param {RGBA} rgba
+ * @returns {string}
+ */
+export function RGBAToStr(rgba: RGBA): string;
+/**
+ * Converts HSLA color values to a CSS `hsl()` or `hsla()` string.
+ * @param {HSLA} hsla
+ * @returns {string}
+ */
+export function HSLAToStr(hsla: HSLA): string;
+export type RGBA = {
+    /**
+     * - Red channel (0–255)
+     */
+    r: number;
+    /**
+     * - Green channel (0–255)
+     */
+    g: number;
+    /**
+     * - Blue channel (0–255)
+     */
+    b: number;
+    /**
+     * - Alpha channel (0–1)
+     */
+    a: number;
+};
+export type HSVA = {
+    /**
+     * - Hue (0–360)
+     */
+    h: number;
+    /**
+     * - Saturation (0–100)
+     */
+    s: number;
+    /**
+     * - Value/brightness (0–100)
+     */
+    v: number;
+    /**
+     * - Alpha channel (0–1)
+     */
+    a: number;
+};
+export type HSLA = {
+    /**
+     * - Hue (0–360)
+     */
+    h: number;
+    /**
+     * - Saturation (0–100)
+     */
+    s: number;
+    /**
+     * - Lightness (0–100)
+     */
+    l: number;
+    /**
+     * - Alpha channel (0–1)
+     */
+    a: number;
+};

package/dist/types/dom.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Returns the element with the given ID.
+ * @param {string} id
+ * @returns {HTMLElement | null}
+ */
+export function getEl(id: string): HTMLElement | null;
+/**
+ * Attaches an event listener to an element, with optional CSS selector delegation.
+ * @param {EventTarget} context - The element to attach the listener to.
+ * @param {string} type - The event type.
+ * @param {string | EventListener} selector - A CSS selector for event delegation, or a direct event handler.
+ * @param {EventListener} [fn] - Event handler (required when `selector` is a string).
+ * @returns {void}
+ */
+export function addListener(context: EventTarget, type: string, selector: string | EventListener, fn?: EventListener): void;
+/**
+ * Calls `fn` immediately if the DOM is ready, otherwise defers until `DOMContentLoaded`.
+ * @param {Function} fn - The function to call.
+ * @param {any[]} [args] - Arguments to pass to `fn`.
+ * @returns {void}
+ */
+export function DOMReady(fn: Function, args?: any[]): void;

package/dist/types/index.d.ts

@@ -0,0 +1,18 @@
+export default ColorPicker;
+/**
+ * Initializes the color picker, binding it to matching fields or applying global options.
+ * @param {string | ColorPickerOptions} [options] - A CSS selector string to bind matching fields, or an options object.
+ * @returns {void}
+ */
+declare function ColorPicker(options?: string | ColorPickerOptions): void;
+declare namespace ColorPicker {
+    export function set(arg0: ColorPickerOptions): void;
+    export function wrap(arg0: string | HTMLElement | HTMLElement[]): void;
+    export function close(arg0?: boolean | undefined): void;
+    export function setInstance(arg0: string, arg1: ColorPickerOptions): void;
+    export function removeInstance(arg0: string): void;
+    export function updatePosition(): void;
+    export { DOMReady as ready };
+}
+import type { ColorPickerOptions } from './settings.js';
+import { DOMReady } from './dom.js';

package/dist/types/picker.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Applies configuration options to the color picker.
+ * @param {ColorPickerOptions} options
+ * @returns {void}
+ */
+export function configure(options: ColorPickerOptions): void;
+/**
+ * Registers a virtual instance that applies custom options to fields matching a CSS selector.
+ * @param {string} selector - CSS selector identifying the target field(s).
+ * @param {ColorPickerOptions} options - Options to apply when the picker opens for a matching field.
+ * @returns {void}
+ */
+export function setVirtualInstance(selector: string, options: ColorPickerOptions): void;
+/**
+ * Removes a previously registered virtual instance.
+ * @param {string} selector - The CSS selector of the instance to remove.
+ * @returns {void}
+ */
+export function removeVirtualInstance(selector: string): void;
+/**
+ * Binds the color picker to one or more input fields.
+ * @param {string | HTMLElement | HTMLElement[]} selector - A CSS selector string, a single element, or an array of elements.
+ * @returns {void}
+ */
+export function bindFields(selector: string | HTMLElement | HTMLElement[]): void;
+/**
+ * Recalculates and applies the picker's position relative to the active input field.
+ * @returns {void}
+ */
+export function updatePickerPosition(): void;
+/**
+ * Wraps one or more color input fields in a `.clr-field` container with a preview button.
+ * @param {string | HTMLElement | HTMLElement[]} selector - A CSS selector string, a single element, or an array of elements.
+ * @returns {void}
+ */
+export function wrapFields(selector: string | HTMLElement | HTMLElement[]): void;
+/**
+ * Closes the color picker, optionally reverting the color to its pre-open value.
+ * @param {boolean} [revert] - If `true`, restores the field value to what it was when the picker opened.
+ * @returns {void}
+ */
+export function closePicker(revert?: boolean): void;
+/**
+ * Creates the picker DOM, appends it to the document, and binds all event listeners.
+ * @returns {void}
+ */
+export function init(): void;
+import type { ColorPickerOptions } from './settings.js';

package/dist/types/settings.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @typedef {Object} A11yLabels
+ * @property {string} open
+ * @property {string} close
+ * @property {string} clear
+ * @property {string} marker
+ * @property {string} hueSlider
+ * @property {string} alphaSlider
+ * @property {string} input
+ * @property {string} format
+ * @property {string} swatch
+ * @property {string} instruction
+ */
+/**
+ * @typedef {Object} ColorPickerOptions
+ * @property {string|HTMLElement|HTMLElement[]} [el]
+ * @property {string|HTMLElement} [parent]
+ * @property {string} [theme]
+ * @property {'light'|'dark'|'auto'} [themeMode]
+ * @property {boolean} [rtl]
+ * @property {boolean} [wrap]
+ * @property {number} [margin]
+ * @property {'hex'|'rgb'|'hsl'|'auto'|'mixed'} [format]
+ * @property {boolean} [formatToggle]
+ * @property {string[]} [swatches]
+ * @property {boolean} [swatchesOnly]
+ * @property {boolean} [alpha]
+ * @property {boolean} [forceAlpha]
+ * @property {boolean} [focusInput]
+ * @property {boolean} [selectInput]
+ * @property {boolean} [inline]
+ * @property {string} [defaultColor]
+ * @property {boolean|{show: boolean, label: string}} [clearButton]
+ * @property {string} [clearLabel]
+ * @property {boolean} [closeButton]
+ * @property {string} [closeLabel]
+ * @property {function(string, HTMLElement=): void} [onChange]
+ * @property {Partial<A11yLabels>} [a11y]
+ */
+/**
+ * @typedef {Object} Settings
+ * @property {string} el
+ * @property {string} parent
+ * @property {string} theme
+ * @property {string} themeMode
+ * @property {boolean} rtl
+ * @property {boolean} wrap
+ * @property {number} margin
+ * @property {string} format
+ * @property {boolean} formatToggle
+ * @property {string[]} swatches
+ * @property {boolean} swatchesOnly
+ * @property {boolean} alpha
+ * @property {boolean} forceAlpha
+ * @property {boolean} focusInput
+ * @property {boolean} selectInput
+ * @property {boolean} inline
+ * @property {string} defaultColor
+ * @property {boolean} clearButton
+ * @property {string} clearLabel
+ * @property {boolean} closeButton
+ * @property {string} closeLabel
+ * @property {function(string, HTMLElement=): void} onChange
+ * @property {A11yLabels} a11y
+ */
+/** @type {Settings} */
+export const settings: Settings;
+export type A11yLabels = {
+    open: string;
+    close: string;
+    clear: string;
+    marker: string;
+    hueSlider: string;
+    alphaSlider: string;
+    input: string;
+    format: string;
+    swatch: string;
+    instruction: string;
+};
+export type ColorPickerOptions = {
+    el?: string | HTMLElement | HTMLElement[] | undefined;
+    parent?: string | HTMLElement | undefined;
+    theme?: string | undefined;
+    themeMode?: "auto" | "light" | "dark" | undefined;
+    rtl?: boolean | undefined;
+    wrap?: boolean | undefined;
+    margin?: number | undefined;
+    format?: "auto" | "rgb" | "hex" | "hsl" | "mixed" | undefined;
+    formatToggle?: boolean | undefined;
+    swatches?: string[] | undefined;
+    swatchesOnly?: boolean | undefined;
+    alpha?: boolean | undefined;
+    forceAlpha?: boolean | undefined;
+    focusInput?: boolean | undefined;
+    selectInput?: boolean | undefined;
+    inline?: boolean | undefined;
+    defaultColor?: string | undefined;
+    clearButton?: boolean | {
+        show: boolean;
+        label: string;
+    } | undefined;
+    clearLabel?: string | undefined;
+    closeButton?: boolean | undefined;
+    closeLabel?: string | undefined;
+    onChange?: ((arg0: string, arg1?: HTMLElement | undefined) => void) | undefined;
+    a11y?: Partial<A11yLabels> | undefined;
+};
+export type Settings = {
+    el: string;
+    parent: string;
+    theme: string;
+    themeMode: string;
+    rtl: boolean;
+    wrap: boolean;
+    margin: number;
+    format: string;
+    formatToggle: boolean;
+    swatches: string[];
+    swatchesOnly: boolean;
+    alpha: boolean;
+    forceAlpha: boolean;
+    focusInput: boolean;
+    selectInput: boolean;
+    inline: boolean;
+    defaultColor: string;
+    clearButton: boolean;
+    clearLabel: string;
+    closeButton: boolean;
+    closeLabel: string;
+    onChange: (arg0: string, arg1: HTMLElement | undefined) => void;
+    a11y: A11yLabels;
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@bornova/colorpicker",
+  "version": "1.0.0",
+  "description": "A lightweight and elegant JavaScript color picker written in vanilla JavaScript. Zero dependencies.",
+  "keywords": [
+    "color",
+    "picker",
+    "javascript"
+  ],
+  "homepage": "https://github.com/bornova/ColorPicker#readme",
+  "bugs": {
+    "url": "https://github.com/bornova/ColorPicker/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bornova/ColorPicker.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/colorpicker.js"
+    }
+  },
+  "jsdelivr": "./dist/browser/colorpicker.min.js",
+  "unpkg": "./dist/browser/colorpicker.min.js",
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prebuild": "npm run lint && npm run prettier",
+    "build": "rollup -c && npm run types",
+    "format": "npm run prettier:fix && npm run lint:fix",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "prettier": "prettier --check .",
+    "prettier:fix": "prettier --write .",
+    "types": "tsc"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@rollup/plugin-terser": "^1.0.0",
+    "eslint": "^10.4.0",
+    "globals": "^17.6.0",
+    "prettier": "^3.8.3",
+    "rollup": "^4.60.4",
+    "typescript": "^6.0.3"
+  }
+}