houseplan-card/README.md

House Plan Card — интерактивный план дома для Home Assistant

Нативная Lovelace-карточка «План дома» (дача, Кирилловское) + интеграция для серверного хранения раскладки иконок. Замена прототипа /local/houseplan/ (iframe + токен + localStorage).

• Работает без токена — использует объект hass фронтенда (сессия пользователя).
• План этажей (подложки РЕМПЛАННЕР 1489×1053, 1 ед. = 1 px) + двор, комнаты-зоны кликабельны.
• Устройства строятся из реестров HA (devices/entities/areas) с курированием и группировкой ламп — те же правила, что в прототипе. Новое устройство с area появляется само.
• Живые состояния: температура у датчиков, подсветка вкл/выкл (свет/розетки/медиа), открыто/закрыто (шторы/ворота/замки/датчики), приглушение при unavailable. Всё реактивно.
• Клик по иконке → штатное окно more-info (группа ламп → меню: вся группа / отдельные).
• Клик по комнате → страница зоны (/config/areas/area/…) без перезагрузки.
• Правка: кнопка ✥ — drag иконок + ввод X/Y; позиции сохраняются на сервере (WS-команды интеграции houseplan) — раскладка одна на все устройства и браузеры. Без интеграции карточка откатывается на localStorage.

Установка (HACS)

1. HACS → меню (⋮) → Custom repositories → URL этого репозитория, категория Integration.
2. Установить «House Plan», перезапустить HA.
3. Настройки → Устройства и службы → Добавить интеграцию → House Plan (одна запись; опция «правка только администраторами»). Интеграция сама раздаёт и подключает JS карточки — ресурс Lovelace добавлять не нужно.
4. В дашборд добавить карточку:

type: custom:houseplan-card
title: План дома · Кирилловское
default_floor: f1        # f1 | f2 | yard
icon_size: 22            # px
show_temperature: true
live_states: true

Только карточка (без серверного хранения): категория Dashboard/Lovelace, ресурс /hacsfiles/houseplan-card/houseplan-card.js — позиции будут в localStorage браузера.

WS-API интеграции

Команда	Параметры	Действие
houseplan/layout/get	—	вернуть раскладку {device_id: {x, y}}
houseplan/layout/set	layout	заменить целиком
houseplan/layout/update	device_id, pos	обновить одну позицию

Хранилище: .storage/houseplan.layout (helpers.storage.Store).

Почему не ha-floorplan

Оценивали ExperienceLovelace/ha-floorplan (установлен в этом HA): он закрывает SVG-план, привязку сущностей и стили по состоянию, но привязки статичны (entity → элемент SVG прописывается руками в YAML/SVG), нет автопоявления новых устройств из реестра, нет курирования/группировки ламп и главное — нет drag-раскладки с серверным сохранением. Перенос этих требований в ha-floorplan потребовал бы генератор SVG+конфига и всё равно не дал бы редактирование из UI. Своя карточка (~1 файл) оказалась дешевле и полностью повторяет прототип. Решение: свой card.

Документация

• docs/ARCHITECTURE.md — устройство карточки и интеграции, координаты, WS API
• docs/DEVELOPMENT.md — сборка, деплой, грабли окружения (обязательно к прочтению)
• docs/CHANGELOG.md — история версий
• docs/ROADMAP.md — план до публикации в HACS (универсализация, редактор разметки, виртуальные устройства)

Разработка

npm install
npm run build        # dist/houseplan-card.js (+ скопировать в custom_components/houseplan/frontend/)

Геометрия комнат/viewBox — src/data/house.ts; подложки — src/data/backgrounds.ts (генерируются из data.js прототипа); правила иконок/курирования — src/rules.ts.

Релиз: тег vX.Y.Z → GitHub Release; workflow соберёт и приложит houseplan-card.js.