pretty-color-picker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pretty 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,67 @@
+# Pretty Color Picker
+
+A perceptually accurate color picker for the modern web. Colors are stored internally as **OKLCH** (`picker.color`); Hex, RGB, HSL, and OKLCH are edit/display formats. The 2D plane is a classic **saturation × value** slice at the current hue (the layout every color picker uses), not an OKLCH chroma × lightness plane.
+
+Native **Web Component**. Works in any framework or plain HTML.
+
+**[Live demo](https://colors.kiira.in)** · **[GitHub](https://github.com/kiiradesign/pretty-color-picker)**
+
+The design and interactions are inspired by [DialKit](https://joshpuckett.me/dialkit). I'm considering contributing this component upstream.
+
+## Features
+
+Saturation × value color plane with hue and alpha sliders, format tabs (Hex / RGB / HSL / OKLCH), Last Used history, label scrubbing, **popover** mode (anchored to a trigger), draggable panel header, light / dark / system themes, Shadow DOM.
+
+## Install
+
+```bash
+npm install pretty-color-picker
+```
+
+## Usage
+
+```ts
+import 'pretty-color-picker'
+```
+
+```html
+<pretty-color-picker value="#6366f1" theme="system" header-action="close"></pretty-color-picker>
+
+<!-- Popover anchored to a trigger (click outside or Escape to close) -->
+<button type="button" id="color-btn">Pick color</button>
+<pretty-color-picker
+  value="#6366f1"
+  mode="popover"
+  anchor="#color-btn"
+  header-action="close"
+></pretty-color-picker>
+
+<!-- Centered floating panel (demo-style) -->
+<pretty-color-picker value="#6366f1" movable header-action="close"></pretty-color-picker>
+
+<!-- Without Last Used history -->
+<pretty-color-picker value="#6366f1" history="false"></pretty-color-picker>
+```
+
+
+| Attribute       | Values                      | Description                                      |
+| --------------- | --------------------------- | ------------------------------------------------ |
+| `value`         | CSS color                   | Initial color                                    |
+| `theme`         | `light` \| `dark` \| `system` | Chrome theme                                     |
+| `header-action` | `close` \| `theme` \| `none` | Close button, theme toggle, or no header button |
+| `mode`          | `inline` \| `popover`       | `popover` = floating panel anchored to `anchor` |
+| `anchor`        | CSS selector                | Trigger for popover mode (e.g. `#color-btn`)     |
+| `open`          | present when visible        | Popover visibility (also `show()` / `hide()`)    |
+| `movable`       | present to enable           | Draggable header (enabled by default in popover mode) |
+| `history`       | `false` to hide             | Last Used swatch grid (on by default; hidden until the first color is committed) |
+
+
+**Events:** `change` (`detail.color`, `detail.css`, `detail.hex`) fires while dragging sliders or scrubbing labels; field inputs commit on Enter/blur. Not fired on mount. `close` when the panel closes (`header-action="close"` or popover dismiss). `themechange` when the user clicks the built-in theme toggle (`header-action="theme"`).
+
+**API:** `picker.value`, `picker.color` (OKLCH), `picker.theme`, `picker.headerAction`, `picker.mode`, `picker.anchor`, `picker.open`, `picker.show()`, `picker.hide()`, `picker.toggle()`, `picker.movable`, `picker.history`.
+
+TypeScript types exported from `pretty-color-picker`.
+
+## License
+
+MIT. See [LICENSE](LICENSE). Icons from [Phosphor](https://phosphoricons.com) (MIT).

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+export declare interface ColorChangeDetail {
+    color: OklchColor;
+    css: string;
+    hex: string;
+}
+
+export declare type ColorFormat = 'hex' | 'rgb' | 'hsl' | 'oklch';
+
+export declare const DEFAULT_COLOR: OklchColor;
+
+export declare interface FormatField {
+    key: string;
+    label: string;
+    value: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** Label-scrub sensitivity (value units per pixel). */
+    scrubStep?: number;
+    suffix?: string;
+}
+
+export declare function formatFieldsFor(color: OklchColor, format: ColorFormat): FormatField[];
+
+export declare function normalizeOklch(color: Partial<OklchColor>): OklchColor;
+
+/** Internal color representation — always OKLCH (L, C, H, alpha). */
+export declare interface OklchColor {
+    l: number;
+    c: number;
+    h: number;
+    alpha: number;
+}
+
+export declare function oklchFromCss(input: string): OklchColor | null;
+
+export declare function oklchToCss(color: OklchColor): string;
+
+export declare function oklchToHex(color: OklchColor): string;
+
+export declare function oklchToRgbString(color: OklchColor): string;
+
+export declare function parseFormatFields(format: ColorFormat, fields: Record<string, string>, current: OklchColor): OklchColor | null;
+
+export declare type PickerHeaderAction = 'close' | 'theme' | 'none';
+
+export declare type PickerTheme = 'dark' | 'light' | 'system';
+
+export declare class PrettyColorPicker extends HTMLElement {
+    #private;
+    static get observedAttributes(): string[];
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    get value(): string;
+    set value(v: string);
+    get color(): OklchColor;
+    set color(c: OklchColor);
+    get theme(): PickerTheme;
+    set theme(value: PickerTheme);
+    get headerAction(): PickerHeaderAction;
+    set headerAction(value: PickerHeaderAction);
+    get movable(): boolean;
+    set movable(value: boolean);
+    /** `inline` (default) or `popover` for a floating panel anchored to `anchor`. */
+    get mode(): 'inline' | 'popover';
+    set mode(value: 'inline' | 'popover');
+    get popoverMode(): boolean;
+    /** CSS selector or element id for the popover trigger (e.g. `#btn` or `.trigger`). */
+    get anchor(): string | null;
+    set anchor(value: string | null);
+    get open(): boolean;
+    set open(value: boolean);
+    show(): void;
+    hide(): void;
+    toggle(): void;
+    /** Last Used swatch grid — on by default; set `history="false"` to hide. */
+    get history(): boolean;
+    set history(value: boolean);
+}
+
+export declare interface ThemeChangeDetail {
+    theme: 'dark' | 'light';
+}
+
+export { }