# 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.