Initial Commit

openspec/changes/enterprise-react-color-picker/proposal.md

@@ -0,0 +1,91 @@
+# OpenSpec Change: enterprise-react-color-picker
+
+- **Change ID**: enterprise-react-color-picker
+- **Package**: `@suaveplan/react-color-picker`
+- **Category**: react
+- **Target path**: `react/forms/react-color-picker`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-color-picker.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-color-picker` on genesis from scratch at enterprise quality. A React color-picking UI kit: composed `ColorPicker` (hue slider + saturation/value panel + swatch + text input), lower-level components (`HueSlider`, `SaturationPanel`, `ColorSwatch`, `ColorInput`), `useColorPicker` hook, and conversion utilities (hex/RGB/HSL/HSV round-trip). Genesis splits the over-long `color.types.ts` (312 lines → type file + utils file), adds Storybook stories, Playwright E2E, and 100% coverage.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `ColorPickerError` |
+| `@suaveplan/react-translate` (`workspace:^`) | i18n for labels |
+| `zod` (`catalog:forms`) | Color value schemas |
+
+External: `tslib catalog:build`. React 18 peer.
+
+---
+
+## Preserved public API surface
+
+```ts
+// Components
+ColorPicker, HueSlider, SaturationPanel, ColorSwatch, ColorInput
+
+// Hook
+useColorPicker (+ UseColorPickerOptions, UseColorPickerReturn)
+
+// Types
+ColorFormat, HslColor, HsvColor, RgbColor, ColorPickerProps,
+ColorInputProps, ColorSwatchProps, HueSliderProps, SaturationPanelProps
+
+// Utils (≤60 lines each, split from types file)
+hexToRgb, rgbToHex, rgbToHsl, hslToRgb, rgbToHsv, hsvToRgb,
+isValidHex, parseColor, formatColor
+```
+
+---
+
+## New additions for genesis
+
+1. **File size fix** — `color.types.ts` split: types in `color.types.ts` (≤150 lines) + conversions in `color-utils.ts` (≤150 lines).
+2. **`ColorPickerError`** — codes: `COLOR_INVALID_HEX`, `COLOR_INVALID_FORMAT`.
+3. **Zod `ColorValueSchema`** — validates hex/rgb/hsl strings at the `useColorPicker` boundary.
+4. **Alpha channel support** — `ColorFormat` gains `'hexa' | 'rgba' | 'hsla'`; all conversion utils handle alpha.
+5. **Stories** — `ColorPicker` (default, compact, alpha, RTL), `HueSlider`, `SaturationPanel`, `ColorSwatch`, `ColorInput`, `useColorPicker` playground.
+6. **Playwright E2E** — open picker, drag hue slider, verify output hex.
+
+---
+
+## File layout
+
+```text
+react/forms/react-color-picker/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    components/
+      color-picker/ (tsx + types + md + test + stories + index)
+      hue-slider/ (tsx + types + md + test + stories + index)
+      saturation-panel/ (tsx + types + md + test + stories + index)
+      color-swatch/ (tsx + types + md + test + stories + index)
+      color-input/ (tsx + types + md + test + stories + index)
+    hooks/
+      use-color-picker/ (ts + types + md + test + stories + index)
+    types/
+      color.types.ts (≤150 lines)
+    utils/
+      color-utils/ (ts + md + test + index)
+  e2e/
+    color-picker.spec.ts
+```