# Issue #57 — единый выбор цвета и прозрачности за один клик

- **Issue:** https://github.com/Matysh/houseplan-card/issues/57
- **Статус документа:** принято ревью r1; реализация в `S6-in-progress`
- **Приоритет:** P3
- **Тип:** polish/tech-debt, обычный трек
- **Пользовательское изменение:** да

## 1. Сценарий

Администратор настраивает цвет комнаты, контура, текста, мебели, decor fill либо
Glow в одном из редакторских диалогов. Он нажимает образец цвета и ожидает сразу
получить все относящиеся к значению controls на одной поверхности.

## 2. Что человек увидит до и после

До изменения первый клик открывает строку с нативным color input и прозрачностью,
а второй клик по цвету открывает отдельный системный picker без прозрачности;
после изменения один клик по образцу открывает единый House Plan picker, где цвет
и прозрачность редактируются вместе.

## 3. Проблема

Текущий `hp-color-opacity` уже объединяет swatch и alpha slider внешне, но сам
цвет делегирует `<input type="color">`. Получается вложенный workflow: popover
House Plan → системный picker → возврат к отдельной прозрачности. На touch это
особенно неудобно, а системная поверхность отличается между браузерами и не
следует theme/accessibility contract карточки.

Главное решение владельца: убрать именно эту вложенность. Отдельная сложная
профессиональная палитра, история цветов и второй dialog не нужны.

## 4. Scope

В задачу входят:

- замена нативного nested color input внутри `hp-color-opacity` единым встроенным
  picker UI;
- цветовое поле, hue, точное текстовое значение и alpha на одной поверхности;
- сохранение действующего public API и всех call sites;
- keyboard, screen reader, touch/pointer capture и обе темы;
- общий floating-surface/overlay lifecycle из #68;
- pure color conversion/validation helpers;
- bundle-size отчёт и targeted unit/smoke/golden coverage.

## 5. Не входит в задачу

- palette history, eyedropper, gradients, RGB/CMYK/Lab panels;
- сохранённые пользовательские presets или синхронизация между карточками;
- отдельная полноэкранная/mobile страница;
- runtime dependency либо загрузка кода/палитры по сети;
- изменение формата сохраняемого цвета/opacity;
- массовый redesign диалогов и editor touch parity;
- добавление alpha в consumers, где `showOpacity=false` имеет предметный смысл.
- параллельные native color inputs для ripple и палитры «Общих настроек» —
  вынесены ревьюером в [#180](https://github.com/Matysh/houseplan-card/issues/180).

## 6. Технический выбор

Внутри существующего `hp-color-opacity` реализуется небольшой in-repo HSV picker:

- saturation/value field;
- отдельный hue range;
- alpha range + точное значение в процентах, если `showOpacity=true`;
- редактируемое hex-поле `#RRGGBB`;
- preview swatch на checkerboard.

Почему выбран этот путь:

| Вариант | Итог |
| --- | --- |
| Нативный `<input type=color>` | отклонён: сохраняет второй вложенный picker и не объединяет alpha |
| Vendored `iro.js`/`vanilla-picker`/аналог | отклонён по умолчанию: чужой lifecycle/theme/a11y и риск превысить budget ради малого surface |
| In-repo HSV controls | принят: сохраняет API, использует native ranges/floating controller и добавляет только нужный контракт |

Новых runtime dependencies в `package.json` нет. Production minified+gzip bundle
delta этой функции не превышает 15 KiB; в handoff публикуются raw и gzip значения
до/после на exact build.

Если автор докажет, что vendored dependency меньше и лучше выполняет все AC, это
допустимая техническая замена только при: локально vendored source/license,
нулевых runtime fetch, том же API, ≤15 KiB gzip delta и полном тестовом контракте.
Продуктовая поверхность от выбора реализации не меняется.

## 7. Единый interaction contract

Один click/tap/Enter/Space по swatch открывает одну surface. В момент первого
paint на ней одновременно доступны:

- saturation/value field;
- hue;
- hex value;
- opacity slider и процент для opacity-capable consumer.

Ни один control внутри не открывает системный color dialog. Изменения применяются
к draft в реальном времени через существующее событие
`hp-color-opacity-change`; сохранение/отмена принадлежит родительскому диалогу и
остаётся прежним.

Повторное нажатие trigger, click/tap вне поверхности, Escape, открытие другой
exclusive transient surface, закрытие родительского диалога, mode change или
disconnect закрывают picker. Escape сначала закрывает picker и не закрывает
dialog; второй Escape работает по обычному контракту `hp-dialog`.

Открытие не меняет высоту/scroll родительского dialog. Popover API, portal
fallback, flip/shift, visual viewport, resize/orientation и focus traversal
переиспользуют `FloatingSurfaceController`/`hp-dialog.registerOverlay` из #68.

## 8. Значения и преобразования

- Canonical external color остаётся lowercase либо normalized `#RRGGBB` по
  действующему `safeStoredColor` contract.
- Opacity наружу остаётся числом `[0,1]`; UI показывает целые `0–100%`.
- HSV существует только как transient representation и не сохраняется.
- Hex input принимает `RGB`, `RRGGBB`, с необязательным `#`; после commit
  нормализуется в `#rrggbb`/действующий canonical case.
- Невалидный незавершённый hex остаётся draft до blur/Enter и не отправляет
  испорченное значение. На commit восстанавливается последнее валидное значение.
- Изменение hue у achromatic цвета сохраняет transient hue в открытой session,
  чтобы последующее повышение saturation давало выбранный hue.
- Все conversions конечны, clamped и имеют round-trip tolerance ≤1 RGB channel.

`showOpacity=false` полностью скрывает alpha row, не меняет входной opacity и
эмитит его существующее значение вместе с новым цветом для API compatibility.

## 9. Pointer и touch

- Touch по saturation/value field использует Pointer Events и capture; движение
  за пределами поля продолжает текущую drag-session до up/cancel.
- Второй pointer отменяет изменение первого либо игнорируется безопасно; pinch
  родительского canvas не начинается через открытую picker surface.
- Touch targets hue/alpha/close-independent controls не меньше 40×40 CSS px.
- `touch-action` задаётся только интерактивному полю/slider, не всему dialog.
- `pointercancel`/lost capture сохраняют последнее уже эмитированное валидное
  draft, очищают drag state и не создают дополнительное событие.
- Compatibility mouse после tap не открывает/закрывает surface второй раз.

Сам picker получает явную touch-поддержку. Остальные операции редакторов остаются
best effort согласно `docs/TOUCH-SUPPORT.md`.

**Touch editor: supported для самого picker;** остальные операции родительских
редакторов остаются best effort по `docs/TOUCH-SUPPORT.md`.

## 10. Keyboard и accessibility

- Trigger остаётся настоящей кнопкой с `aria-haspopup="dialog"` и
  `aria-expanded`.
- Surface имеет локализованное accessible name и участвует в composed focus trap.
- Hue, saturation, value и opacity доступны как отдельные native range inputs
  либо эквивалентные sliders с `aria-valuemin/max/now/text`.
- Pointer-only saturation/value field не является единственным способом: рядом
  существуют keyboard-доступные saturation и value controls.
- Arrow меняет значение на 1, `Shift+Arrow` — на 10; Home/End устанавливают
  границы, где это соответствует native range semantics.
- Hex — подписанный text input с сообщаемой validation ошибкой без live-region
  spam на каждый символ.
- Focus-visible не смешивается с hover; при закрытии Escape focus возвращается
  на trigger, при outside click не переносится.
- При 200% zoom и viewport 390 CSS px поверхность не имеет горизонтального
  overflow; допустим внутренний вертикальный scroll.

## 11. Theme и visual contract

- Surface использует HA/House Plan theme tokens, не hardcoded light palette.
- Saturation/value и hue tracks остаются читаемыми в light/dark themes.
- Checkerboard явно показывает opacity, включая 0%.
- Trigger продолжает показывать итоговую пару color+opacity.
- Disabled component не открывается и не меняет draft.
- `prefers-reduced-motion` отключает только open/close transition; color drag
  остаётся немедленным.

## 12. API, модель данных и migration

Сохраняется существующий contract:

```ts
color: string
opacity: number
showOpacity: boolean
disabled: boolean
hp-color-opacity-change: { color: string; opacity: number }
```

Существующие call sites не получают адаптеров и охватывают как минимум decor
stroke/fill/text/furniture, room/space custom fill и marker Glow override.
Config schema, backend, storage и migration не меняются; старые colors/alpha
открываются и сохраняются losslessly в прежнем формате.

## 13. i18n

Добавляются пары en/ru для общих controls: Color picker, Hue, Saturation, Value/
Brightness, Hex color и Opacity (существующий `space.opacity` можно переиспользовать
только если семантика и scanner допускают это без связности с space dialog).

`hp-color-opacity` остаётся presentation-only и получает уже локализованные labels
properties от House Plan; он не читает глобальный словарь или `hass.locale`.
Две карточки с разными `config.language` не влияют друг на друга.

## 14. Acceptance criteria

1. **AC1 — один уровень.** Первый click/tap/keyboard activation открывает surface,
   где сразу доступны color и opacity; внутри нет `<input type=color>` или второго
   picker dialog. **Доказательство:** DOM unit + desktop/touch smoke.
2. **AC2 — все consumers.** Existing call sites продолжают работать через тот же
   API; `showOpacity=false` скрывает только alpha. **Доказательство:** source-contract
   unit + smoke matrix.
3. **AC3 — точные значения.** HSV/RGB, hex и alpha round-trip без повреждения,
   invalid draft не эмитится. **Доказательство:** table/property unit tests.
4. **AC4 — touch.** Drag поля/hue/alpha, cancel и multi-touch безопасны на 390px
   viewport; nested/system picker не появляется. **Доказательство:** real-touch smoke.
5. **AC5 — keyboard/a11y.** Все четыре dimensions и hex доступны с клавиатуры,
   labels/roles/values корректны, Escape/focus trap работают. **Доказательство:**
   accessibility/browser smoke.
6. **AC6 — floating lifecycle.** Native/fallback surface не обрезается, корректно
   flip/shift-ится и конкурирует с `hp-help` по #68. **Доказательство:** forced-
   fallback smoke.
7. **AC7 — visual parity.** Light/dark/200% zoom читаемы, checkerboard отражает
   alpha, dialog layout не прыгает. **Доказательство:** reviewed golden.
8. **AC8 — budget.** Нет runtime dependency/fetch; minified+gzip delta ≤15 KiB,
   raw/gzip числа записаны. **Доказательство:** exact production build artifact.
9. **AC9 — compatibility.** Config/backend schema и serialized values не меняются.
   **Доказательство:** round-trip unit + code review.

## 15. План автотестов

### Unit

- RGB↔HSV round trips, hue wrap, grayscale remembered hue;
- safe hex parsing/commit/cancel and alpha clamping;
- single event payload and no event for invalid draft;
- `showOpacity`, disabled and existing property/event API;
- source scan prohibits native `input[type=color]` in component;
- en/ru key parity and presentation-only labels.

### Browser smoke

- each representative consumer: decor stroke/fill, room fill, Glow color-only;
- pointer field/hue/alpha/hex, live draft and parent Cancel/Save;
- keyboard traversal/ranges/hex/Escape and dialog focus wrap;
- real touch, multi-touch/pointercancel, 390px/200% zoom;
- native Popover and forced portal fallback, viewport edges/rotation;
- `hp-help` exclusive overlay interaction and two-card language isolation.

### Golden

- open picker in light/dark desktop;
- mobile 390px with non-100% alpha checkerboard;
- color-only Glow variant without alpha row;
- golden baseline updates only from reviewed full Linux artifact.

### Performance and size

- production build size before/after: raw and gzip;
- pointermove updates only local component/draft, without parent full render per
  raw event (rAF/coalescing allowed);
- no new long task in targeted editor smoke.

## 16. Затронутые поверхности

- `src/hp-color-opacity.ts`, `src/color.ts` либо новый small pure color helper;
- `src/houseplan-card.ts` only for localized properties/call-site parity;
- `src/i18n/en.json`, `src/i18n/ru.json`;
- component unit tests, dialog/touch smoke and golden fixtures;
- `docs/USER-GUIDE.ru.md`, `docs/TESTING.md`.

## 17. Риски и откат

| Риск | Мера |
| --- | --- |
| Custom field недоступен keyboard | отдельные native range alternatives |
| Pointer drag перегружает render | local state + rAF/coalesced emission |
| Цвет round-trip дрейфует | property/table tests и canonical external RGB |
| Surface обрезается dialog | общий floating controller #68 |
| Bundle непропорционально растёт | ≤15 KiB gzip hard budget |

Откат возвращает прежнее внутреннее содержимое `hp-color-opacity`; public API и
сохранённые данные не меняются, поэтому migration rollback не нужен.

## 18. Release-артефакты

Implementation commit имеет `User-Visible: yes` и одновременно обновляет:

- `docs/CHANGELOG.md` и `docs/CHANGELOG.ru.md`;
- `docs/USER-GUIDE.ru.md` — единый one-click color+opacity workflow;
- `docs/TESTING.md` — component/touch/fallback/keyboard coverage.

Нужны reviewed desktop/mobile golden artifacts, targeted smoke report и bundle
size note с exact build SHA. Новые i18n keys добавляются синхронно en+ru.

## 19. Принятые технические предположения

- базовый implementation — in-repo HSV field + native ranges, без dependency;
- external model остаётся `#RRGGBB` + opacity `[0,1]`;
- live change API сохраняется, Save/Cancel принадлежит parent dialog;
- pointer field дополняется, а не заменяет keyboard-доступные ranges;
- exact easing/layout допустимо уточнять на реализации без изменения one-click
  и accessibility contracts.