houseplan-card/docs/design/505-summary-panel/reference/DEVELOPER-HANDOFF.md

Dashboard 5 — передача в разработку

Дата пакета: 8 сентября 2026 года.
Основание: houseplan-card issue #437 и согласованные уточнения встречи от 8 сентября 2026 года.

Назначение

Dashboard 5 — интерактивный HTML-прототип конфигурируемой информационной панели рядом с планом House Plan. Пакет предназначен как визуальная и поведенческая основа для реализации внутри существующей Lovelace-карточки.

Зафиксированное поведение

• Информационная панель плавает поверх плана и не участвует в геометрии, content bbox или автоматическом fit.
• В горизонтальной ориентации панель размещается справа.
• В портретной ориентации панель размещается снизу, центрируется и подстраивает ширину под содержимое с ограничением шириной экрана.
• Панель имеет собственный пользовательский заголовок.
• В шапке House Plan используется составной контрол: слева настройка, справа показ или скрытие панели.
• Правая кнопка использует svg/layout-sidebar-right.svg.
• Отдельного состояния сворачивания всей панели и сворачивания блоков нет.
• Значения в строках выровнены по правому краю.
• Панель и её содержимое ограничены по высоте; при переполнении прокручиваются данные, а не план.
• В режиме киоска панель располагается ниже плавающего блока управления.

Структура данных

информационная панель
└── блок
    └── значение: пользовательское название — источник/состояние

Предлагаемая модель:

{
  title: "Сводная информация",
  showOnMobile: true,
  blocks: [
    {
      id: "stable-block-id",
      title: "Общее",
      visible: true,
      scope: { type: "all" },
      values: [
        {
          id: "stable-value-id",
          label: "Количество устройств",
          source: { type: "system", key: "device_count" }
        }
      ]
    }
  ]
}

Для блока, привязанного к пространству:

scope: { type: "space", spaceId: "stable-space-id" }

Для сущности Home Assistant:

source: { type: "entity", entityId: "sensor.example" }

Начальная конфигурация

• Название панели: «Сводная информация».
• Один включённый блок «Общее» для всех пространств.
• Системные строки в порядке:
  1. «Количество устройств»;
  2. «Общая площадь комнат»;
  3. «Текущие дата и время».

Диалог настроек

Диалог работает с единым черновиком. «Сохранить» применяет все изменения атомарно. «Отмена», крестик и Escape отбрасывают весь черновик.

Поддерживаются:

• название панели;
• общий показ панели;
• показ в нативном узком режиме Home Assistant;
• создание, переименование, включение, выключение и удаление блоков;
• выбор области блока: все пространства или одно определённое;
• создание, переименование, сортировка и удаление строк;
• сортировка блоков и строк перетаскиванием и квадратными кнопками «выше/ниже»;
• выбор сущности по имени и entity_id;
• состояния загрузки, устаревания и недоступности;
• проверка обязательных полей и блокировка сохранения при ошибках;
• подтверждение удаления непустого блока.

Ограничения структуры: не более 10 блоков, не более 20 значений в блоке, заголовок панели или блока до 48 символов, название значения до 64 символов.

Интеграция с Home Assistant

Прототип содержит демонстрационный список сущностей. В продукте необходимо:

1. Получать полный доступный пользователю список из hass.states.
2. Использовать стабильный entity_id и форматирование состояния средствами Home Assistant.
3. Показывать системные показатели в том же селекторе источников, что и сущности.
4. Автоматически включать в список новые Template-сущности.
5. Сохранять ранее выбранную недоступную сущность и отмечать её как требующую внимания.
6. Получать мобильный/узкий режим из нативного контекста Home Assistant, а не из собственного числового breakpoint.
7. Интегрировать конфигурацию с постоянным хранилищем House Plan, совместной работой и экспортом/импортом, не добавляя данные панели в геометрию плана.
8. Следовать действующей модели прав House Plan для доступа к структурным настройкам.

Файлы прототипа

• index.html — экран House Plan, панель и диалоги.
• dashboard-5.js — состояние, черновик настроек, фильтрация по пространству и адаптивная позиция.
• dashboard-5.css — компоновка, темы, киоск и анимации.
• styles.css, components.css, components.html — базовая демонстрационная оболочка.
• svg/ — локальные иконки интерфейса.

Проверки перед реализацией

• Обычный и нативный узкий режим Home Assistant.
• Альбомная и портретная ориентации телефона и планшета.
• Панель справа и снизу, короткий и максимальный состав.
• Светлая и тёмная темы, 200% zoom и safe area.
• Клавиатурная навигация, Escape, фокус после сортировки.
• Pan/pinch/scroll плана при открытой панели.
• Переход между пространствами без fit/refit и скачка масштаба.
• Загрузка, отсутствие данных, unknown, unavailable, восстановленная и удалённая сущность.
• Удалённое пространство, сохранённая проблемная привязка и смена активного пространства.
• Перезагрузка страницы, совместное редактирование, импорт и экспорт конфигурации.

Запуск прототипа

Из папки Dashboard 5:

python -m http.server 8768

Открыть http://127.0.0.1:8768/.

Граница ответственности прототипа

HTML-прототип демонстрирует интерфейс и взаимодействия. Статические системные числа, демонстрационный массив сущностей и localStorage не являются готовой продуктовой реализацией. Источники данных, постоянное хранение, права, i18n и интеграционные тесты реализуются в кодовой базе House Plan.