houseplan-card/docs/specs/381-no-op-tap-action.md

Issue #381 — действие по нажатию «Ничего не делать»

• Issue: https://github.com/Matysh/houseplan-card/issues/381
• Статус документа: утверждено, реализовано, готово к code review
• Приоритет / тип: P2 · feature / polish
• Область: marker config, Редактор устройств, View/киоск, frontend action projection, backend validation, i18n, документация и QA
• Связи: #94 (универсальный Toggle), #178 (точная Toggle-сущность)
• Ревизия: 2 (2026-08-30)

Сценарий

Администратор дома размещает на плане датчик или виртуальный маркер, который должен только показывать место и состояние. В Редакторе устройств он выбирает для маркера действие «Ничего не делать» и сохраняет настройки. После этого член семьи, гость или киоск может коротко нажать маркер, не открывая карточку и не отправляя команду устройству. Долгое нажатие и правый клик сохраняют свои отдельные информационные действия.

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

До: короткое нажатие всегда открывает информационную поверхность либо пытается выполнить команду. После: в селекторе появляется явный вариант «Ничего не делать», и короткое нажатие выбранного маркера не даёт никакого результата, пока сам маркер продолжает показывать состояние на плане.

Проблема

TAP_ACTIONS предлагает только info, more-info, toggle и run. projectedTapAction() проецирует неизвестный сохранённый токен в info, а _clickDevice() после известных команд открывает локальную карточку. Backend MARKER_SCHEMA также принимает только эти четыре значения, legacy cover и null. Поэтому строка в селекторе без сквозного контракта либо будет отклонена сервером, либо после reload превратится в открытие карточки.

Использовать неработоспособный toggle как замену нельзя: это зависимый от текущей привязки safe no-op с диагностикой, который может начать отправлять команду после восстановления цели. Здесь требуется явное и стабильное намерение пользователя.

Скоуп

• Новая строка «Ничего не делать» в селекторе «Действие по нажатию» для существующих и новых реальных/виртуальных маркеров.
• Канонический persisted literal marker.tap_action: "none".
• Одинаковый no-op для короткого mouse click, touch tap и keyboard activation Enter/Space в View и киоске.
• Сквозное чтение, preview, запись, backend validation, full/space export/import и downgrade-описание нового literal.
• Паритет переводов EN/RU/DE/FR и обновление пользовательской документации.
• Регресс-проверки остальных действий и default-проекции.

Не-скоуп

• Изменение долгого нажатия, правого клика или жестов редактора.
• Отдельная настройка hold/right-click action.
• Изменение hit area, hover/focus, внешнего вида, состояния, pulse, Glow, LQI, value badge, room aggregates или доступности маркера.
• Изменение defaults: свет без явного значения по-прежнему получает Toggle, остальные устройства — карточку House Plan.
• Изменение семантики info, more-info, toggle, run и legacy cover.
• Новая HA service/WebSocket-команда, подтверждение или toast для none.
• Интерактивность houseplan-space-card, которая остаётся отдельной статической поверхностью по своему существующему контракту.

Контракт поведения

1. Выбор и сохранение

1. TAP_ACTIONS содержит канонический none; селектор показывает его строкой «Ничего не делать» после существующих четырёх действий.
2. Выбор none немедленно меняет draft/effective action диалога. Toggle- и Run-зависимые поля скрываются по тем же правилам, что для info и more-info; блок controls остаётся доступен, поскольку он участвует также в light/presentation graph.
3. Save записывает точный literal tap_action: "none". Повторное открытие диалога и reload сохраняют выбранную строку.
4. Cancel не меняет конфиг. Простое Open → Save маркера с отсутствующим, legacy либо неизвестным tap_action сохраняет прежний lossless-контракт и не материализует none.
5. none не равен null, отсутствию или пустой строке. Только явный literal отключает короткое действие; прежняя light/non-light default-проекция не меняется.

2. Короткое нажатие

1. projectedTapAction("none", domain) возвращает none для любого domain и binding kind. Неизвестные токены по-прежнему fail closed в info.
2. В View/киоске _clickDevice() после разрешения актуального marker по id и до binding/service веток завершает none как quiet no-op.
3. No-op означает одновременно: не открывать карточку House Plan или HA more-info, не создавать confirmation, не показывать toast, не вызывать HA service/WebSocket, не запускать press feedback/activity и не менять локальное/серверное состояние.
4. Click/tap по маркеру остаётся поглощённым маркером и не превращается в клик по комнате, pan либо другому объекту под ним.
5. Enter и Space идут тем же _clickDevice()-путём, предотвращают браузерный default как сейчас и также завершаются без побочного действия.

3. Независимые жесты и presentation

• Long press 600 ms по-прежнему открывает внутреннюю карточку House Plan.
• Правый клик по-прежнему открывает HA more-info основной сущности либо существующий fallback для marker без primary.
• В Редакторе устройств короткий клик по маркеру по-прежнему открывает его настройки; tap_action относится только к View/киоску.
• Marker остаётся видимым, focusable и получает прежние hover/focus стили, tooltip, state, pulse, badge, Glow и LQI. Отдельного disabled-вида нет.
• Preview диалога меняет только effective action; рисунок маркера не меняется.

UX и i18n

Добавить одинаковый ключ tap.none в четыре словаря:

• RU: Ничего не делать;
• EN: Do nothing;
• DE: Nichts tun;
• FR: Ne rien faire.

Новая строка находится в существующем native select после Run; новая подсказка, иконка либо секция диалога не нужны. Toggle-hint, target chooser и confirmation checkbox при none не показываются. Live region Toggle не анонсирует цель.

Модель данных, миграция и совместимость

Frontend

• Возвращаемый тип projectedTapAction() и все effective-action consumers расширяются literal none.
• Marker.tap_action остаётся forward-compatible string | null; отдельная миграция типа или model/store version не требуется.
• devices fingerprint уже включает исходный tap_action, поэтому смена на none инвалидирует presentation/action snapshot без нового cache key.

Backend

MARKER_SCHEMA принимает none рядом с текущими canonical literals. Значение не несёт target/ref и не требует semantic validator. Cross-language parity test обязан доказать, что backend принимает каждый literal из frontend TAP_ACTIONS, включая none, и продолжает отдельно принимать legacy cover.

Import/export и downgrade

• Full и space export/import сохраняют none штатным копированием marker; remap ссылок не требуется.
• Виртуализация duplicate marker при space import продолжает удалять tap_action вместе с HA-dependent marker fields по существующему правилу.
• Старый frontend прочитает неизвестный ему none как info; старый backend отклонит попытку записать изменённый marker с новым literal. Это известная граница downgrade для нового enum value, а не основание маскировать none под отсутствующее значение.
• Новый frontend/backend не переписывают старые cover, absent, null или неизвестные untouched значения при редактировании другого поля.

Затронутые файлы и модули

• src/logic.ts, src/device-toggle.ts, src/houseplan-card.ts.
• src/houseplan-editor-runtime.ts; src/types.ts только если потребуется уточнить локальный effective-action type без сужения forward compatibility.
• src/i18n/{en,ru,de,fr}.json.
• custom_components/houseplan/validation.py.
• test/device-toggle.test.mjs, action/click contract tests, tests_backend/test_validation.py и целевой browser smoke диалога/маркера.
• docs/USER-GUIDE.md, docs/USER-GUIDE.ru.md, docs/CONFIG-COMPATIBILITY.md, docs/ARCHITECTURE.md, при необходимости docs/TESTING.md, оба changelog.

Критерии приёмки

• AC1 — selector и persisted value (unit + smoke). Селектор содержит пять canonical options с none последним; выбор сохраняет tap_action: "none", reopen/reload восстанавливает его, Cancel не пишет.
• AC2 — quiet no-op (unit + smoke). Mouse click, touch tap, Enter и Space по marker с none не открывают поверхности, не вызывают service/WS, toast, confirmation, press animation или activity stamp.
• AC3 — независимые жесты (smoke). Long press всё ещё открывает карточку House Plan, right click — HA more-info, а клик по тому же marker в Редакторе устройств — настройки marker.
• AC4 — presentation parity (unit, DOM assertion). До и после выбора совпадают DOM/classes/face/state/pulse/badge/LQI/Glow/tooltip/hit area и hover/focus; новый disabled-стиль не появляется.
• AC5 — defaults и legacy (unit). Absent/null/"" оставляют Toggle для primary light и Info для остальных; cover проецируется в Toggle; неизвестный token проецируется в Info; untouched Open → Save сохраняет исходный literal.
• AC6 — соседние действия (unit + smoke). info, more-info, toggle и run выполняют прежние ветки, а Toggle/Run fields и confirmation видны только при соответствующих effective actions.
• AC7 — backend и transfer (backend). Backend принимает none и все TAP_ACTIONS, отклоняет произвольный новый изменённый token; full/space transfer сохраняет none, duplicate virtualization удаляет его как раньше.
• AC8 — i18n и docs (unit + docs gate). Четыре словаря имеют паритет, обе версии руководства описывают none и неизменные long/right gestures, compatibility/architecture фиксируют literal и downgrade.
• AC9 — гейты и бюджет (commands). В цикле реализации зелёные npx tsc --noEmit, npm test, npm run build и целевой backend pytest; no-new-any, i18n/docs checks и browser smoke проходят на обязательном предрелизном прогоне. Существенного роста initial/editor bundle нет.

План автотестов

• Расширить таблицу projectedTapAction: explicit none для light/switch и неизменные absent/legacy/unknown варианты.
• Добавить целевой тест click dispatcher с шпионами на _infoCard, _openMoreInfo, callService, callWS, _tapConfirm, toast, _startDevicePressFeedback и _stampActivity.
• Проверить keyboard reuse того же dispatcher и сохранение stopPropagation / preventDefault на соответствующих путях.
• Проверить editor draft/save/reopen/Cancel и отсутствие Toggle/Run dependent controls для none; отдельно — lossless untouched legacy/unknown action.
• Расширить cross-language backend test TAP_ACTIONS и marker validation.
• Добавить import/export fixtures для full, space и duplicate virtualization.
• Целевой Playwright smoke: выбрать none, Save, reopen, reload, выполнить click/tap/keyboard no-op, long press и contextmenu; убедиться, что marker presentation не изменился.

Мутанты: не добавить none в backend → AC7; спроецировать none в info → AC1/AC2; поставить no-op после fallback-карточки → AC2; сделать ранний return до stopPropagation → AC2; связать none с unavailable Toggle → AC2/AC5; скрыть marker или изменить face → AC4.

Риски

• Смешение none с отсутствием значения. Truthy/falsy-проверка либо нестрогий fallback может вернуть light-маркеру Toggle или открыть Info вместо no-op. Снимается явной веткой none, расширенным возвращаемым union и таблицей absent/null/пустого/unknown/legacy/none в AC2 и AC5.
• Неполный охват потребителей tap_action. Помимо selector и click path поле участвует в devices fingerprint, virtual-light и cover presentation. Перед реализацией выполняется полный поиск consumers; код меняется только в action projection/dispatch, а AC4/AC6 фиксируют неизменность presentation и специальных Toggle-потребителей.
• Ранний return в неверной точке. Если выйти до stopPropagation, нажатие протечёт в комнату/план; если выйти после fallback, откроется карточка. Dispatcher-тест и соответствующие мутанты фиксируют точное окно между разрешением актуального marker и capability/info ветками.
• Mixed-version/downgrade. Новый frontend с прежним backend не сможет сохранить none; полный откат backend после уже записанных значений сделает последующую запись такого конфига невалидной. Интеграция поставляет frontend и backend одним релизом, а безопасный порядок аварийного отката описан ниже и сохраняет backend read/write allowlist до очистки данных.
• Пассивное нажатие могут принять за поломку. Выбор называется буквально «Ничего не делать», отдельного disabled-вида нет, а long press/right click остаются документированными. Smoke проверяет, что исчезло только выбранное короткое действие, а не сам marker или информационные жесты.

Откат

Feature flag и миграция отсутствуют. Безопасный аварийный откат выполняется в два этапа:

1. revert-нуть selector/runtime/i18n/docs-часть пользовательского изменения, но временно оставить "none" в backend MARKER_SCHEMA; reverted frontend уже проецирует этот неизвестный literal в безопасный info, а существующие конфиги продолжают загружаться и сохраняться;
2. если требуется убрать literal полностью, отдельной проверяемой data-fix заменить сохранённые tap_action: "none" на "info", и только после этого удалить его из backend allowlist.

Полный слепой git revert frontend и backend одним шагом запрещён после выхода релиза: уже записанный none останется в store, старый frontend покажет Info, но старый backend отклонит следующую запись всего конфига. Потеря данных при безопасном откате ограничена осознанным пользовательским намерением no-op, которое становится info; геометрия, marker binding, presentation и остальные поля не меняются. После любого отката повторяются backend validation, config Open → Save и click smoke на конфиге, содержащем none.

Производительность и безопасность

No-op — одна константная ветка до capability resolution и сетевых операций. Новых подписок, таймеров, cache entries, DOM-узлов и данных HA нет. Вызовов service/WS для none быть не может; backend принимает только точный allowlisted literal. Full performance/golden harness не требуется из-за отсутствия геометрической/визуальной дельты, но штатные предрелизные проверки проекта не отменяются.

Release-артефакты

• Пользовательская запись в docs/CHANGELOG.md и docs/CHANGELOG.ru.md в том же User-Visible: yes коммите, что реализация.
• Обновлённые EN/RU user guides, compatibility и architecture.
• Новый plan golden не требуется: marker pixels и геометрия не меняются. Открытое native select не является стабильной кроссплатформенной golden- поверхностью; наличие/текст option доказывают DOM unit и Playwright smoke.
• Docs screenshot не требуется: существующие изображения не утверждают полный список tap actions; текстовые разделы являются каноническими.
• Release/performance/security waiver не требуется; перед beta выполняется общий golden/smoke/performance набор по runbook.

Принятые предположения

• none расположен последним в текущем порядке selector; порядок можно свободно поменять до реализации без изменения контракта.
• Controls остаются редактируемыми, потому что используются presentation/light graph независимо от короткого действия.
• Существующая политика соседних полей сохраняется: смена с run на любое другое действие очищает tap_target при записи, а общие настройки marker не сбрасываются только из-за выбора none.
• Marker остаётся focusable и визуально интерактивным ради доступных hover, tooltip, long-press и context-menu путей; отдельный disabled appearance не вводится.