Initial Commit

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

@@ -0,0 +1,102 @@
+# Tasks: enterprise-react-color-picker
+
+**Change ID**: enterprise-react-color-picker
+**Package**: `@suaveplan/react-color-picker`
+**Target path**: `react/forms/react-color-picker`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/react-translate`
+
+---
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## 1. Scaffold
+
+- [ ] Create directory tree per proposal layout.
+- [ ] Write `package.json` at `0.1.0` with `"sideEffects": false`, exports map.
+- [ ] Dependencies: `@suaveplan/error workspace:^`, `@suaveplan/react-translate workspace:^`, `zod catalog:forms`, `tslib catalog:build`.
+- [ ] Write `tsconfig.json`, `vitest.config.ts`, scripts.
+
+---
+
+## 2. Error codes and types
+
+- [ ] Define `ColorPickerError` extending `SuaveplanError`; codes: `COLOR_INVALID_HEX`, `COLOR_INVALID_FORMAT`.
+- [ ] Write `src/types/color.types.ts` (≤150 lines): `ColorFormat` (with alpha variants), `RgbColor`, `HslColor`, `HsvColor`, `RgbaColor`, `HslaColor`, and all component prop interfaces.
+- [ ] Write `ColorValueSchema` Zod schema for hex/rgb/hsl string validation.
+
+---
+
+## 3. Utils (`src/utils/color-utils/`)
+
+- [ ] Implement `hexToRgb(hex): RgbColor | null` — parses 3/4/6/8-char hex; throws `ColorPickerError(COLOR_INVALID_HEX)` on invalid.
+- [ ] Implement `rgbToHex(rgb): string`.
+- [ ] Implement `rgbToHsl(rgb): HslColor`, `hslToRgb(hsl): RgbColor`.
+- [ ] Implement `rgbToHsv(rgb): HsvColor`, `hsvToRgb(hsv): RgbColor`.
+- [ ] Implement `isValidHex(s): boolean`.
+- [ ] Implement `parseColor(s, format?: ColorFormat): RgbColor` — auto-detects format if omitted; throws `ColorPickerError(COLOR_INVALID_FORMAT)` on unrecognised input.
+- [ ] Implement `formatColor(rgb, format: ColorFormat): string`.
+- [ ] All functions handle alpha channel for `hexa`, `rgba`, `hsla` formats.
+- [ ] Write `color-utils.test.ts` (≤500 lines): all functions, round-trip tests (hex→rgb→hex, rgb→hsl→rgb), alpha channel, invalid inputs. `{ timeout: 5000 }`.
+- [ ] Write `color-utils.md`.
+
+---
+
+## 4. Hook — `useColorPicker`
+
+- [ ] Internal representation: `HsvColor` (with alpha). External output: `RgbColor` + formatted string in chosen `ColorFormat`.
+- [ ] Validates input via `ColorValueSchema` on mount / prop change.
+- [ ] Exposes `hue`, `saturation`, `value`, `alpha`, `onChange(partial)`, `setFromString(s)`, `toHex()`, `toRgb()`, `toHsl()`.
+- [ ] Write `use-color-picker.test.ts`: initial value, onChange, setFromString (hex/rgb/hsl), toHex/toRgb/toHsl. `{ timeout: 5000 }`.
+- [ ] Write `use-color-picker.stories.tsx`: playground.
+- [ ] Write `use-color-picker.md`.
+
+---
+
+## 5. Components
+
+### HueSlider
+
+- [ ] Canvas-based hue strip (360° gradient); pointer drag updates `hue`; keyboard (±1°).
+- [ ] `aria-label` from `useTranslation`.
+- [ ] Write test, stories (default, alpha, playground), md.
+
+### SaturationPanel
+
+- [ ] Canvas saturation/value 2D panel; pointer drag updates `saturation`+`value`.
+- [ ] Write test, stories, md.
+
+### ColorSwatch
+
+- [ ] Square/circle swatch showing current color; click opens picker.
+- [ ] Write test, stories, md.
+
+### ColorInput
+
+- [ ] Text input showing current color as string in chosen `ColorFormat`; validates on blur.
+- [ ] Write test, stories, md.
+
+### ColorPicker
+
+- [ ] Composes `HueSlider` + `SaturationPanel` + `ColorSwatch` + `ColorInput` using `useColorPicker`.
+- [ ] Write test, stories (default, compact, alpha-channel, RTL, playground), md.
+
+---
+
+## 6. E2E
+
+- [ ] `e2e/color-picker.spec.ts` — Playwright:
+  - Render `ColorPicker`, drag hue slider, verify hex output changes.
+  - Type `#FF0000` in `ColorInput`, verify swatch updates.
+
+---
+
+## 7. Verify and publish
+
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-color-picker` — green.
+- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-color-picker` — 100%.
+- [ ] `bun scripts/publish.ts --package @suaveplan/react-color-picker`.
+- [ ] Archive change folder.