react-headless-color-picker 1.0.0 → 1.0.1

package/README.md

@@ -1 +1,252 @@
 # react-headless-color-picker
+
+A lightweight, fully customizable **headless color picker library for React**.
+
+Built for developers who need complete control over styling and layout, `react-headless-color-picker` provides only the core logic and interaction primitives — no forced UI, no opinionated design system.
+
+Inspired by the excellent **react-colorful**, but redesigned with a **headless-first architecture**.
+
+---
+
+## Table of Contents
+
+* Overview
+* Why Use It?
+* Features
+* Installation
+* Quick Start
+* Full Example
+* Custom Pointer Rendering
+* Build Your Own UI
+* API Philosophy
+* Inspiration & Credits
+* NPM Package
+* License
+
+---
+
+## Overview
+
+Most React color pickers ship with predefined styles and component layouts.
+
+That works for simple use cases, but becomes limiting when building:
+
+* Design systems
+* Internal admin tools
+* CMS editors
+* Theme generators
+* GIS / map styling interfaces
+* White-label products
+* Fully branded SaaS dashboards
+
+`react-headless-color-picker` solves that by giving you only the behavior layer, so you can design everything yourself.
+
+---
+
+## Why Use It?
+
+Instead of overriding CSS from a prebuilt component, you get complete freedom:
+
+✅ Use Tailwind, CSS Modules, styled-components, or plain CSS
+✅ Build sliders, panels, popovers, dialogs, sidebars, or floating pickers
+✅ Match your product branding perfectly
+✅ Reuse primitives across projects
+✅ Keep bundle size small
+
+---
+
+## Features
+
+* Headless architecture
+* Fully customizable UI
+* Built specifically for React
+* TypeScript support
+* Lightweight and fast
+* Reusable low-level primitives
+* Flexible composition model
+* Familiar color-picker behavior
+* Inspired by proven UX patterns
+
+---
+
+## Installation
+
+Install using your preferred package manager.
+
+```bash
+npm install react-headless-color-picker
+```
+
+or
+
+```bash
+pnpm add react-headless-color-picker
+```
+
+or
+
+```bash
+yarn add react-headless-color-picker
+```
+
+---
+
+## Full Example
+
+```tsx
+import { useState } from "react";
+import {
+  Alpha,
+  Hue,
+  Saturation,
+  equalHex,
+  hexToHsva,
+  hsvaToHex,
+  useColorManipulation,
+  type ColorModel,
+} from "react-headless-color-picker";
+
+export default function App() {
+  const [hex, setHex] = useState("#3b82f6");
+
+  const hexColorModel: ColorModel<string> = {
+    defaultColor: "#ff0000",
+    toHsva: hexToHsva,
+    fromHsva: hsvaToHex,
+    equal: equalHex,
+  };
+
+  const [hsva, updateHsva] = useColorManipulation(
+    hexColorModel,
+    hex,
+    setHex
+  );
+
+  return (
+    <div>
+      <div className="flex items-center gap-2 mb-3">
+        <span>Selected:</span>
+
+        <div
+          className="w-4 h-4 rounded-sm border"
+          style={{ backgroundColor: hex }}
+        />
+      </div>
+
+      <div className="w-64">
+        <div
+          className="relative w-full"
+          style={{ aspectRatio: "1 / 0.75" }}
+        >
+          <Saturation
+            hsva={hsva}
+            onChange={updateHsva}
+            className="w-full h-full"
+          />
+        </div>
+
+        <div className="mt-3 relative h-3 rounded-full overflow-hidden">
+          <Hue
+            hue={hsva.h}
+            onChange={updateHsva}
+            style={{ width: "100%", height: "100%" }}
+          />
+        </div>
+
+        <div className="mt-3 relative h-3 rounded-full overflow-hidden">
+          <Alpha
+            hsva={hsva}
+            onChange={updateHsva}
+            style={{ width: "100%", height: "100%" }}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Example Result
+
+Customize the UI however you want — modern, minimal, enterprise, branded, playful, or advanced.
+
+![alt text](image.png)
+
+---
+
+## Custom Pointer Rendering
+
+You can customize the pointer/handle used in:
+
+* `Saturation`
+* `Hue`
+* `Alpha`
+
+Use the `renderPointer` prop.
+
+```tsx
+const SaturationPointer = ({
+  left,
+  top,
+}: {
+  left: number;
+  top: number;
+}) => (
+  <Pointer left={left} top={top}>
+    <div className="w-4 h-4 rounded-full border-2 border-white shadow-[0_1px_6px_rgba(0,0,0,0.5)] pointer-events-none" />
+  </Pointer>
+);
+
+<Saturation
+  hsva={hsva}
+  onChange={updateHsva}
+  className="w-full h-full"
+  renderPointer={({ left, top }) => (
+    <SaturationPointer left={left} top={top!} />
+  )}
+/>;
+```
+
+---
+
+## Build Your Own UI
+
+This package is intentionally unstyled.
+
+You can combine primitives to build:
+
+* Popover color pickers
+* Inline editors
+* Theme customization panels
+* Drawing tools
+* Dashboard controls
+* Brand token editors
+* Advanced design system components
+
+---
+
+
+## Inspiration & Credits
+
+This project is heavily inspired by:
+
+**react-colorful**
+[https://github.com/omgovich/react-colorful](https://github.com/omgovich/react-colorful)
+
+The original library demonstrated a clean, elegant, and performant approach to color picking.
+
+`react-headless-color-picker` extends that concept into a **fully headless developer experience**.
+
+---
+
+## NPM Package
+
+[https://www.npmjs.com/package/react-headless-color-picker](https://www.npmjs.com/package/react-headless-color-picker)
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { HTMLAttributes, ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface RgbColor {
     r: number;
@@ -71,29 +71,6 @@ type PointerProps = HTMLAttributes<HTMLDivElement> & {
 };
 declare const Pointer: ({ left, top, children, style, ...rest }: PointerProps) => react_jsx_runtime.JSX.Element;
 
-interface ColorPickerRenderProps {
-    hsva: HsvaColor;
-    updateHsva: (params: Partial<HsvaColor>) => void;
-    Saturation: typeof Saturation;
-    Hue: typeof Hue;
-    Alpha: typeof Alpha;
-    Pointer: typeof Pointer;
-}
-interface ColorPickerProps<T extends AnyColor> extends Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "children" | "color"> {
-    colorModel: ColorModel<T>;
-    color: T;
-    onChange?: (color: T) => void;
-    children?: (renderProps: ColorPickerRenderProps) => ReactNode;
-    renderSaturationPointer?: (args: RenderPointerArgs) => ReactNode;
-    renderHuePointer?: (args: RenderPointerArgs) => ReactNode;
-}
-declare function ColorPicker<T extends AnyColor>({ colorModel, color, onChange, children, renderSaturationPointer, renderHuePointer, ...rest }: ColorPickerProps<T>): react_jsx_runtime.JSX.Element;
-
-interface HexColorPickerProps extends Omit<ColorPickerProps<string>, "colorModel"> {
-}
-declare const hexColorModel: ColorModel<string>;
-declare function HexColorPicker({ color, ...rest }: HexColorPickerProps): react_jsx_runtime.JSX.Element;
-
 type Position = {
     left: number;
     top: number;
@@ -160,4 +137,4 @@ declare const setNonce: (hash: string) => void;
 
 declare const formatClassName: (names: unknown[]) => string;
 
-export { Alpha, type AlphaProps, type AnyColor, type ColorModel, ColorPicker, type ColorPickerProps, type ColorPickerRenderProps, HexColorPicker, type HexColorPickerProps, type HslColor, type HslaColor, type HsvColor, type HsvaColor, Hue, type HueProps, Interactive, type ObjectColor, Pointer, type PointerPosition, type RenderPointerArgs, type RgbColor, type RgbaColor, Saturation, type SaturationProps, clamp, equalColorObjects, equalColorString, equalHex, formatClassName, getNonce, hexColorModel, hexToHsva, hexToRgba, hslStringToHsva, hslaStringToHsva, hslaToHsl, hslaToHsva, hsvStringToHsva, hsvaStringToHsva, hsvaToHex, hsvaToHslString, hsvaToHsla, hsvaToHslaString, hsvaToHsv, hsvaToHsvString, hsvaToHsvaString, hsvaToHueHsl, hsvaToRgbString, hsvaToRgba, hsvaToRgbaString, parseHue, rgbStringToHsva, rgbaStringToHsva, rgbaToHex, rgbaToHsva, rgbaToRgb, round, roundHsva, setNonce, useColorManipulation, useEventCallback, validHex };
+export { Alpha, type AlphaProps, type AnyColor, type ColorModel, type HslColor, type HslaColor, type HsvColor, type HsvaColor, Hue, type HueProps, Interactive, type ObjectColor, Pointer, type PointerPosition, type RenderPointerArgs, type RgbColor, type RgbaColor, Saturation, type SaturationProps, clamp, equalColorObjects, equalColorString, equalHex, formatClassName, getNonce, hexToHsva, hexToRgba, hslStringToHsva, hslaStringToHsva, hslaToHsl, hslaToHsva, hsvStringToHsva, hsvaStringToHsva, hsvaToHex, hsvaToHslString, hsvaToHsla, hsvaToHslaString, hsvaToHsv, hsvaToHsvString, hsvaToHsvaString, hsvaToHueHsl, hsvaToRgbString, hsvaToRgba, hsvaToRgbaString, parseHue, rgbStringToHsva, rgbaStringToHsva, rgbaToHex, rgbaToHsva, rgbaToRgb, round, roundHsva, setNonce, useColorManipulation, useEventCallback, validHex };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { HTMLAttributes, ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface RgbColor {
     r: number;
@@ -71,29 +71,6 @@ type PointerProps = HTMLAttributes<HTMLDivElement> & {
 };
 declare const Pointer: ({ left, top, children, style, ...rest }: PointerProps) => react_jsx_runtime.JSX.Element;
 
-interface ColorPickerRenderProps {
-    hsva: HsvaColor;
-    updateHsva: (params: Partial<HsvaColor>) => void;
-    Saturation: typeof Saturation;
-    Hue: typeof Hue;
-    Alpha: typeof Alpha;
-    Pointer: typeof Pointer;
-}
-interface ColorPickerProps<T extends AnyColor> extends Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "children" | "color"> {
-    colorModel: ColorModel<T>;
-    color: T;
-    onChange?: (color: T) => void;
-    children?: (renderProps: ColorPickerRenderProps) => ReactNode;
-    renderSaturationPointer?: (args: RenderPointerArgs) => ReactNode;
-    renderHuePointer?: (args: RenderPointerArgs) => ReactNode;
-}
-declare function ColorPicker<T extends AnyColor>({ colorModel, color, onChange, children, renderSaturationPointer, renderHuePointer, ...rest }: ColorPickerProps<T>): react_jsx_runtime.JSX.Element;
-
-interface HexColorPickerProps extends Omit<ColorPickerProps<string>, "colorModel"> {
-}
-declare const hexColorModel: ColorModel<string>;
-declare function HexColorPicker({ color, ...rest }: HexColorPickerProps): react_jsx_runtime.JSX.Element;
-
 type Position = {
     left: number;
     top: number;
@@ -160,4 +137,4 @@ declare const setNonce: (hash: string) => void;
 
 declare const formatClassName: (names: unknown[]) => string;
 
-export { Alpha, type AlphaProps, type AnyColor, type ColorModel, ColorPicker, type ColorPickerProps, type ColorPickerRenderProps, HexColorPicker, type HexColorPickerProps, type HslColor, type HslaColor, type HsvColor, type HsvaColor, Hue, type HueProps, Interactive, type ObjectColor, Pointer, type PointerPosition, type RenderPointerArgs, type RgbColor, type RgbaColor, Saturation, type SaturationProps, clamp, equalColorObjects, equalColorString, equalHex, formatClassName, getNonce, hexColorModel, hexToHsva, hexToRgba, hslStringToHsva, hslaStringToHsva, hslaToHsl, hslaToHsva, hsvStringToHsva, hsvaStringToHsva, hsvaToHex, hsvaToHslString, hsvaToHsla, hsvaToHslaString, hsvaToHsv, hsvaToHsvString, hsvaToHsvaString, hsvaToHueHsl, hsvaToRgbString, hsvaToRgba, hsvaToRgbaString, parseHue, rgbStringToHsva, rgbaStringToHsva, rgbaToHex, rgbaToHsva, rgbaToRgb, round, roundHsva, setNonce, useColorManipulation, useEventCallback, validHex };
+export { Alpha, type AlphaProps, type AnyColor, type ColorModel, type HslColor, type HslaColor, type HsvColor, type HsvaColor, Hue, type HueProps, Interactive, type ObjectColor, Pointer, type PointerPosition, type RenderPointerArgs, type RgbColor, type RgbaColor, Saturation, type SaturationProps, clamp, equalColorObjects, equalColorString, equalHex, formatClassName, getNonce, hexToHsva, hexToRgba, hslStringToHsva, hslaStringToHsva, hslaToHsl, hslaToHsva, hsvStringToHsva, hsvaStringToHsva, hsvaToHex, hsvaToHslString, hsvaToHsla, hsvaToHslaString, hsvaToHsv, hsvaToHsvString, hsvaToHsvaString, hsvaToHueHsl, hsvaToRgbString, hsvaToRgba, hsvaToRgbaString, parseHue, rgbStringToHsva, rgbaStringToHsva, rgbaToHex, rgbaToHsva, rgbaToRgb, round, roundHsva, setNonce, useColorManipulation, useEventCallback, validHex };