diff --git a/docs/specs/086-settings-help-content-party1.md b/docs/specs/086-settings-help-content-party1.md new file mode 100644 index 00000000..39222939 --- /dev/null +++ b/docs/specs/086-settings-help-content-party1.md @@ -0,0 +1,250 @@ +# Issue #86 — подсказки к настройкам, партия 1 + +- **Issue:** https://github.com/Matysh/houseplan-card/issues/86 +- **Статус документа:** готово к будущей реализации; issue остаётся на `S3-spec` +- **Приоритет:** P2 +- **Тип:** polish/docs/tech-debt, обычный трек +- **Пользовательское изменение:** да +- **Зависимость:** механизм `hp-help` из #68 уже выпущен + +## 1. Сценарий + +Администратор настраивает план в общих настройках, диалоге пространства, +устройстве или Plan/Device editor и встречает параметр, ошибка в котором заметно +исказит геометрию, свет либо видимость объектов. Он открывает короткую подсказку +рядом с названием, не покидая текущий dialog/tool. + +## 2. Что человек увидит до и после + +До изменения критичные параметры объясняются неодинаковыми `title`/`.rhint` либо +не объясняются; после изменения первая партия получает единый `hp-help` с коротким +ответом «что изменится», а старое дублирующее объяснение исчезает. + +## 3. Проблема и граница партии + +#68 поставил presentation/lifecycle/a11y-механизм и пилотные подсказки. #86 +поставляет контент. Решение владельца: в этом issue реализуется **только партия +1** — настройки, ошибка в которых может повредить или заметно исказить план. + +Партии 2 и 3 из тела issue не входят сюда и до реализации оформляются отдельными +issue после проверки механики и текстов первой партии. + +## 4. Scope партии 1 + +Обязательные settings/affordances: + +1. масштаб пространства (`cell_cm`); +2. общий радиус Glow; существующий персональный радиус устройства проверяется; +3. режим заливки пространства в его актуальной post-#56 модели; +4. роль источника света Auto/Always/Never — существующий пилот уточняется; +5. «Управляет другими источниками света»; +6. общий и локальный север; +7. общий и локальный режим фона; +8. инструмент «Граница»/виртуальная граница; +9. «Показать все устройства» в Device editor. + +Каждая новая подсказка использует существующую `_help('literal.help')`, пару +`.help` + `.help.aria`, floating/overlay lifecycle и accessibility contract #68. + +## 5. Не входит в задачу + +- партия 2: проёмы, толщины, колонны/перегородки, decor, размеры room labels; +- партия 3: binding/display/size/tap action/hide/climate/vacuum source; +- rich text, Markdown, картинки и ссылки в tooltip; +- новый help component, второй floating controller либо иной icon; +- массовая миграция всех оставшихся `title=`; +- изменение поведения самих настроек; +- редакторский onboarding tour или постоянно открытая справка. + +## 6. Канонические тексты RU/EN + +Тексты ниже являются acceptance contract. Допустима только редакторская правка, +не меняющая смысл, длину более двух предложений или терминологию User Guide. + +| Ключ | RU `.help` | EN `.help` | +| --- | --- | --- | +| `space.cell_cm.help` | Связывает сетку с реальными размерами: от значения зависят длины и площади, толщина стен, размеры проёмов и радиус свечения; изменение после разметки меняет масштаб всего пространства. | Links the grid to real dimensions: lengths, areas, wall thickness, opening sizes and glow radius depend on it; changing it after drawing rescales the whole space. | +| `gs.glow_radius.help` | Задаёт общий радиус светового пятна в метрах или футах; персональный радиус устройства заменяет это значение. | Sets the default glow radius in metres or feet; a device-specific radius overrides it. | +| `space.fill_mode.help` | «Свой цвет» задаёт оформление, а «Свет», «Температура» и «LQI» используют текущие данные Home Assistant; Glow включается отдельно. | “Custom colour” is styling, while “Light”, “Temperature” and “LQI” use current Home Assistant data; Glow is enabled separately. | +| `marker.light_role.help` | «Авто» использует фактическую роль привязанного устройства, «Всегда» принудительно создаёт собственный источник, а «Никогда» исключает его; связанные лампы выше остаются независимыми. | “Auto” uses the bound device's resolved role, “Always” forces its own source and “Never” excludes it; linked lights above remain independent. | +| `marker.controls.help` | Перечисленные источники переключаются вместе с этим маркером, но световые пятна остаются у их собственных маркеров — этот маркер сам светиться не начинает. | The listed sources toggle with this marker, but their glow stays at their own markers; this marker does not become a light source. | +| `gs.north.help` | Угол отсчитывается по часовой стрелке от верхней вертикали плана; север нужен для оконных лучей, а не для фона «Следует за Солнцем». | The angle is measured clockwise from the plan's upward vertical; north is required for window rays, not for the “Follows the Sun” background. | +| `space.north.help` | Переопределяет общий север для этого пространства; угол отсчитывается по часовой стрелке от верхней вертикали плана и используется оконными лучами. | Overrides general north for this space; the angle is measured clockwise from the plan's upward vertical and is used by window rays. | +| `gs.bg_mode.help` | «Следует за Солнцем» использует `sun.sun`, а при недоступности — локальные часы браузера; статичный режим всегда показывает выбранный цвет. | “Follows the Sun” uses `sun.sun`, falling back to the browser's local clock; Static always shows the selected colour. | +| `space.bg_mode.help` | Выберите наследование общего фона либо переопределите это пространство статичным цветом или режимом «Следует за Солнцем». | Inherit the general background or override this space with a static colour or “Follows the Sun”. | +| `plan.boundary.help` | Виртуальная граница означает отсутствие стены: свет и заливка проходят между комнатами, а отдельные контуры комнат сохраняются. | A virtual boundary means there is no wall: light and fill pass between the rooms while their separate room outlines remain. | +| `devbar.show_all.help` | Временно показывает скрытые и деактивированные устройства только в редакторе устройств; фильтры и сохранённая видимость не меняются. | Temporarily shows hidden and disabled devices only in the Device editor; filters and saved visibility are unchanged. | + +Для каждого ключа добавляется цельная локализованная `.help.aria` в форме +«Подсказка: …» / `Help: …`, называющая настройку, а не повторяющая весь tooltip. + +## 7. Уже поставленные пилоты #68 + +`marker.glow_radius.help` и `marker.light_role.help` уже существуют. В этой задаче: + +- device radius не получает второй trigger; проверяется его единица и inheritance; +- текст light role заменяется каноническим из §6, потому что он обязан объяснять + динамический Auto/Always/Never contract; +- их `.aria` keys сохраняют текущие имена и остаются непустыми в обеих локалях; +- smoke #68 продолжает проходить без второго tooltip на том же control. + +## 8. Размещение triggers + +- Dialog field: trigger стоит рядом с label/legend, но не внутри `