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

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.