Initial Commit
This commit is contained in:
91
openspec/changes/enterprise-react-color-picker/proposal.md
Normal file
91
openspec/changes/enterprise-react-color-picker/proposal.md
Normal file
@@ -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
|
||||
```
|
||||
102
openspec/changes/enterprise-react-color-picker/tasks.md
Normal file
102
openspec/changes/enterprise-react-color-picker/tasks.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user