poe-svelte-ui-lib 1.83.0 → 1.84.0

package/README.md

@@ -1,35 +1,36 @@
 # poe-svelte-ui-lib
 
-Библиотека компонентов на Svelte 5 (руны) для интерфейсов устройств компании. Один и тот же компонент выглядит и ведёт себя одинаково везде, где он используется:
+Библиотека компонентов на Svelte 5 для интерфейсов устройств. Её используют три приложения, и компонент в каждом выглядит и работает одинаково:
 
-- **DevCloud** — облако: конструктор GUI устройства, панель управления, документация;
-- **WebApp** — локальный веб-интерфейс прошивок ProdFactory-ESP, встроенный в устройство;
-- **DevTerminal** — настольный терминал разработчика.
+- **DevCloud** - облако: конструктор интерфейса устройства, панель управления, отладка;
+- **WebApp** - веб-интерфейс, который прошивка ProdFactory-ESP раздаёт с самого устройства;
+- **DevTerminal** - настольный терминал для отладки через COM-порт.
+
+Кроме компонентов, в библиотеке лежат ядро протоколов обмена с устройством, общий словарь команд, тема и переводы. Приложения не держат своих копий, всё берут отсюда.
 
 Витрина с живыми примерами: [oleg-perevyshin.github.io/ElementsUI](https://oleg-perevyshin.github.io/ElementsUI/).
 
-## Состав
+## Что внутри
+
+**Смарт-виджеты.** Готовые блоки под одну задачу. Виджет сам работает с группой полей прошивки по префиксу, привязывать переменные по одной не нужно.
 
-**Смарт-виджеты** — готовые блоки под конкретную задачу, работают с группой полей прошивки по префиксу, переменные привязывать не нужно; шапка со сворачиванием и мастер-цветом:
+- `WidgetWiFi` - режим сети, подключение к точке доступа, своя точка доступа, поиск сетей.
+- `WidgetDeviceInfo` - паспорт устройства, основные настройки, перезагрузка.
+- `WidgetFileSystem` - занятая память, список файлов, загрузка и удаление.
+- `WidgetStackInfo` - свободная память и запас стека задач, для отладки.
+- `WidgetRGBStrip` - адресная светодиодная лента: цвет, эффекты, параметры.
+- `WidgetPFD` - пилотажный дисплей: авиагоризонт, шкалы скорости и высоты, маршрут, сообщения автопилота.
+- `WidgetMap` - карта с объектами и их траекториями.
 
-- `WidgetWiFi` — настройка сети: режим, клиент, точка доступа, поиск сетей;
-- `WidgetDeviceInfo` — паспорт устройства и основные настройки, перезагрузка;
-- `WidgetFileSystem` — память, список файлов, удаление и закачка;
-- `WidgetStackInfo` — отладка: свободная память и запас стека задач;
-- `WidgetRGBStrip` — адресная светодиодная лента: цвет, эффекты, параметры ленты;
-- `WidgetPFD` — пилотажный дисплей: авиагоризонт, ленты, маршрут, связь, сообщения автопилота;
-- `WidgetMap` — карта объектов с траекториями, несколько групп-объектов на одной карте.
+**Компоненты.** Каждый привязывается к одной переменной устройства: `Input`, `Select`, `Switch`, `Slider`, `Button`, `Joystick`, `ProgressBar`, `Graph`, `PeriodChart`, `Table`, `FileAttach`, `VideoViewer`, `TextField`, `Widget`.
 
-**Компоненты** — привязываются к одной переменной устройства: `Input`, `Select`, `Switch`, `Slider`, `Button`, `Joystick`, `ProgressBar`, `Graph`, `PeriodChart`, `Table`, `FileAttach`, `VideoViewer`, `TextField`, `Widget` (карточка одного значения).
+**Раскладка.** `Accordion`, `Tabs`, `Divider`, `Carousel`, `Modal`.
 
-**Раскладка** — `Accordion`, `Tabs`, `Divider`, `Carousel`, `Modal`.
+**Ядро протоколов** (`poe-svelte-ui-lib/protocols`). Кодирование и разбор пакетов для всех каналов связи с устройством. Работает без Svelte, в том числе под Node.
 
-## Как устроено
+**Тема** (`poe-svelte-ui-lib/theme.css`) и **языки** (`poe-svelte-ui-lib/locales`).
 
-- **Компонент только отображает и сообщает.** Он получает значения через пропсы и отдаёт изменения колбэками (`onUpdate`, `onChange`, `onSave`…). С сетью, WebSocket и `DeviceStore` работает приложение (`GUIPreview` в DevCloud и WebApp): значения переменных устройства хранятся под ключами `<ModSN>|<ключ>`, смарт-виджеты читают свою группу (`MAV.Lat`, `CFG.DevName`…).
-- **Конструктор свойств.** У каждого компонента есть `<Компонент>Props.svelte` — панель свойств для конструктора DevCloud.
-- **Описания.** Короткое описание (i) — `component.info.<Тип>` в переводах (ru/en/zh), его показывают конструктор облака и витрина; развёрнутое — README рядом с исходником компонента.
-- **Тема** — один файл `poe-svelte-ui-lib/theme.css` для всех приложений: палитра светлой и тёмной темы, типографика, Markdown, роли заливки.
+Полный список экспортов в `src/lib/index.ts`. У каждого компонента рядом с исходником есть свой README с пропсами и примерами.
 
 ## Установка
 
@@ -37,41 +38,73 @@
 npm install poe-svelte-ui-lib
 ```
 
-### Требования (peerDependencies)
-
-- `svelte ^5.0.0`
-- `tailwindcss ^4.0.0` — компоненты стилизуются Tailwind-утилитами и CSS-переменными темы; сама тема поставляется файлом `theme.css`
+Приложению нужны `svelte` 5 и `tailwindcss` 4. Компоненты стилизуются утилитами Tailwind и переменными темы.
 
-### Подключение стилей и темы
-
-Тема поставляется пакетом — `poe-svelte-ui-lib/theme.css`: цветовые токены светлой и тёмной темы (`--back-color`, `--accent-color`, `--red-color`…), типографика тегов в `@layer base`, компактный Markdown (`.markdown-content` — обёртка для `{@html}` с результатом `RenderMarkdown`) и роли заливки `bg-*`/`border-*`. Эталон темы — DevCloud; витрина подключает тот же файл, поэтому компоненты в ней выглядят ровно как в облаке. В `app.css` потребителя:
+В `app.css` приложения:
 
 ```css
 @import "tailwindcss";
 @import "poe-svelte-ui-lib/theme.css";
 @source "../node_modules/poe-svelte-ui-lib/dist";
 @custom-variant dark (&:where(.dark, .dark *));
+```
 
-/* дальше — только собственные отличия приложения, например :root { min-width: 640px; } */
+Ниже можно дописать только то, чем приложение отличается от остальных.
+
+## Как пользоваться
+
+```svelte
+<script lang="ts">
+  import * as UI from "poe-svelte-ui-lib"
+
+  let value = $state("")
+</script>
+
+<UI.Input label={{ name: "Имя" }} bind:value type="text" />
+<UI.Button content={{ name: "Сохранить" }} onClick={() => console.log(value)} />
 ```
 
-**Поверхности — четыре ступени, заметные в обеих темах:** фон страницы `--bg-body` → панель `--back-color` → блок внутри панели `--container-color` → поле `--field-color` (в тёмной теме поле темнее блока — «утоплено»). Готовые рецепты — классы `ui-panel` (блок прямо на фоне страницы: карточка, шапка раздела, холст, область чата — заливка панели, волосяная рамка, лёгкая тень) и `ui-inset` (блок внутри панели: группа полей, шапка карточки, подложка сообщения). Отступы и скругление задаёт страница классами Tailwind. Панели не делаются полупрозрачными (`bg-(--back-color)/50` сливается с фоном): выпадающие меню и всплывающие блоки — `ui-panel` с тенью `--elevation-3`, свои сообщения в чатах — `--accent-soft`, чужие — `--container-color`.
+Главное правило: компонент только показывает данные и сообщает об изменениях. Значения приходят через пропсы, изменения уходят колбэками (`onUpdate`, `onChange`, `onSave` и другие). Сетью, WebSocket и хранилищем значений занимается приложение.
+
+В DevCloud и WebApp значения устройства хранятся под ключами вида `<ModSN>|<ключ>`. Смарт-виджет читает свою группу целиком, например все поля `CFG.*` или `MAV.*`.
+
+У каждого компонента есть парный `<Компонент>Props.svelte`. Это панель свойств для конструктора DevCloud. Пропсы у всех панелей одинаковые:
+
+| Пропс | Что это |
+|---|---|
+| `component` | Компонент интерфейса и его свойства |
+| `onPropertyChange` | Сообщает об изменении свойств, имени, доступа или события |
+| `forConstructor` | `true` — полная панель конструктора, `false` — упрощённая для редактирования |
 
-**Названия смарт-виджетов** — в словаре библиотеки на всех языках (WiFi, «Об устройстве», «Файловая система», «Стек и задачи», «RGB лента», «Пилотажный дисплей», «Карта»); пустой `label.name` показывает название на языке пользователя, `widgetTitle(type)` отдаёт его сразу на всех языках `{ ru, en, zh }` — так конструктор заполняет заголовок нового виджета.
+## Протоколы
 
-**Битовые поля конфигурации** — `bitFieldGet(word, start, end)`/`bitFieldSet(word, start, end, value)`: поле `start..end` 32-битного слова `{GROUP}.Cfg` (Select/Input с `bitMode`) обычной арифметикой, без знаковых 32-битных операций JS — бит 31 разбирается и собирается корректно, результат всегда 0..2³²−1; тест против эталона на BigInt — `tests/bitField.test.mjs`.
+Пакет `poe_cbor_pkt` один для CAN, CAN FD, RS485 и UART-консоли. В нём адрес получателя, адрес отправителя, команда и данные в CBOR. Библиотека умеет:
 
-**Ядро протоколов** — `poe-svelte-ui-lib/protocols`, описание протокола — [`src/lib/protocols/PROTOCOL.md`](src/lib/protocols/PROTOCOL.md) (без Svelte, работает и под Node без Vite): общий для DevCloud, WebApp и DevTerminal CBOR-кодек (RFC 8949); `valueToCbor`/`cborToValue` — обычные значения, двоичные данные как `Uint8Array` (WebSocket, хранилище, телеметрия); `jsonToCbor` — JSON-совместимое значение в CBOR, строки base64 под ключами с `BIN` — байты (поля ввода терминала и отладки). Пакет `poe_cbor_pkt` — indefinite-массив объектов `[[TrgBusID, SrcBusID, HAR, Payload, CRC16], …]` (CAN, RS485, UART-консоль), `Payload` — одно CBOR item (сырые данные — `encodePacketBytesPayload`, пустой массив — `null`): `encodePacket`/`decodePacket` (разбор с начала буфера — `complete` с длиной, `incomplete` для потока или `garbage`; объекты одному адресату не склеиваются, порядок сохраняется, неверный CRC — флаг `crcOk`), `BUS_ID_REGEXP`/`parseBusId`/`formatBusId` — поля BusID в HEX и вывод `0x0000`, `makeHar(header, argument, reply = true)`/`splitHar` — `HAR`: заголовок в битах 14-15, аргумент в битах 1-13 (0..8191), флаг ответа в бите 0 (как `HAR`/`HAR_NR` прошивки), `packetObjectCrc`; контрольная сумма `crc16Kermit` — строго побайтная, как в `common.c` прошивок. Байты совпадают с `poe_cbor_pkt.c` прошивки — проверка `npm run TestProtocols` (`tests/protocols.test.mjs`, эталонные пакеты собраны прошивочным кодом). Протокол xPOE-Debug (UART-консоль `system_console`) — тот же пакет `poe_cbor_pkt` вперемешку с текстом загрузчика: `encodeXPoeDebugFrame(header, argument, payload, srcId, trgId, reply)` кодирует запрос, `xPoeDebugHar` — HAR по именам словаря, `createXPoeDebugParser().push(байты)` разбирает поток пакетов (каждая запись — отдельный элемент) и внешний текст (`raw`), логи `OK! DebugLog` — `[уровень, тег, текст, FHS]` (`DEBUG_LOG_ARGUMENT`, FHS — в `freeHeap`). Строка таблицы — `xPoeDebugRow`, колонки — `xPoeDebugTableColumns` (основной вход библиотеки): общие для отладки облака и терминала. Ячейка Value — `formatXPoeDebugValue` (CBOR одной строкой, `DebugLog` — уровень · тег · текст), окно по клику — `formatXPoeDebugModal`: Value в развёрнутом виде (`formatXPoeDebugPretty` — то же чистым текстом; карты и массивы с отступами, `DebugLog` — уровень и тег, ниже текст или дамп и FHS) в цветах палитры темы — ключи `--pink-color`, строки `--purple-color`, числа `--red-color`, логические `--orange-color`, `null` — `--cyan-color`, байты `--green-color`, HEX — исходные байты `Payload` сплошной строкой; числа float32 выводятся кратчайшей записью (`0.12`). CAN/CAN FD через slcan-адаптер (`can_service` прошивки): `canFragments`/`encodeCanPacket` — нарезка пакета на кадры как `CAN_Send` (бит 10 ID — «последний», биты 0..9 — `packetId`, по 8 / 64 байта), `encodeSlcanFrame`, `createCanParser().push(байты)` — разбор кадров slcan со сборкой фрагментов и обрезкой паддинга CAN FD. RS485 — сырой поток пакетов: `createPacketStreamParser().push(байты)` (пауза обрывает недособранное, мусор пропускается по байту). Открытие slcan-адаптера — `slcanOpenCommands(скорость, скоростьДанных?)`. Поле Value команды xPOE-Debug из ввода — `xPoeDebugValueFromText` (hex как есть, JSON → CBOR, пусто — пустой Payload). Графики отладки — пакет `OK! DebugPlot` (`LOG_PLOT` прошивки, `DEBUG_PLOT_ARGUMENT`): `debugPlotValues(value)` — пары `[имя, число]` из HEX CBOR-карты `Payload`, `createPlotGroups().update(пары)` раскладывает по группам (префикс до точки) в порядке карты и возвращает обновлённые группы, `data(группа)` — последние значения. Словарь протокола — `HEADER_CODES`, `DEFAULT_ARGUMENT_CODES` (генерируется из мастер-словаря `src/lib/protocols/dictionary.yaml` — `npm run Dictionary`, перед упаковкой автоматически; сам файл поставляется как `poe-svelte-ui-lib/protocols/dictionary.yaml`, `.framework/Dictionary.yaml` прошивок — его справочные копии, сборка прошивок сверяет с ними `api_har.h`), `parseArgumentDictionary` (строки `- [Строка, Enum, Число]`), `nameByCode`. Своих копий протоколов и словаря в приложениях не держим: терминал и отладка облака читают и пишут порт сырыми байтами, разбор и сборка — здесь.
+- собирать и разбирать пакеты, считать CRC;
+- резать пакет на кадры CAN и CAN FD и собирать обратно, общаться со slcan-адаптером;
+- разбирать поток консоли xPOE-Debug, где пакеты идут вперемешку с текстом загрузчика;
+- показывать отладочные логи `DebugLog` и графики `DebugPlot` из прошивки;
+- переводить значения между JSON и CBOR.
 
-**Шапка смарт-виджета** (`WidgetHeader`): значок, заголовок и сворачивание слева, «?» в правом краю; правая часть (режимы, «Обновить» и т. п.) стоит в той же строке, а если не помещается — уходит второй строкой под заголовок и там переносится.
+Байты совпадают с тем, что собирает прошивка. Это проверяет `npm run TestProtocols`: тесты сверяют результат с эталонными пакетами, собранными кодом прошивки.
 
-**Подсказки смарт-виджетов** — `hints.ts`: у каждого виджета своя кнопка «?» в правом краю шапки (`WidgetHeader` с пропом `hints`), по умолчанию подсказки выключены, выбор оператора запоминается в браузере для виджетов этого типа (`hintsSetting("WidgetPFD")`, ключ `localStorage` `WidgetHints.<тип>`, пишется только по нажатию «?»), глобального переключателя нет. Элемент получает подсказку действием `use:hint={{ text, enabled: $hints }}` — всплывающее окно в стиле темы над элементом; тексты — в словаре библиотеки (`widget.*.hint.*`), только там, где смысл поля не очевиден.
+Формат пакета, адресация, транспорты и список функций описаны в [PROTOCOL.md](src/lib/protocols/PROTOCOL.md).
 
-**Предпросмотр темы** — вкладка «Тема» на главной витрины (`src/routes/ThemePreview.svelte`): палитра токенов и состояния, затем все компоненты и виджеты в порядке меню витрины — каждый тип в своём разделе с живыми демо-данными (графики, видео, полёт для PFD и карты), в конце типографика и Markdown; тема переключается кнопкой в шапке витрины. Правьте `theme.css` и смотрите результат там.
+## Словарь команд
 
-Текст в Markdown, таблицы и код переносятся по ширине контейнера — горизонтальной прокрутки быть не должно, только вертикальная. Markdown рендерится с `breaks: true` (как в облаке), поэтому абзац и пункт списка пишутся одной строкой — ручной перенос внутри абзаца превращается в разрыв строки.
+Все команды (`GET`, `SET`, `ModCfg`, `Restart` и остальные) записаны в одном файле `src/lib/protocols/dictionary.yaml`. Из него генерируется `DEFAULT_ARGUMENT_CODES` для JS (`npm run Dictionary`, перед публикацией запускается сам).
 
-**Глобальные стили тегов — только в `@layer base`.** Компоненты задают размеры текста и отступы Tailwind-утилитами (например `text-[12px]` у подписи `<h5>`). Правило вне слоя (`h5 { font-size: 1rem }`, `label { … }`, `p { … }`) сильнее любой утилиты, и в приложении подписи станут крупнее задуманного и перестанут помещаться. Поэтому типографику тегов оборачивайте:
+Прошивки ProdFactory-ESP и ProdFactory-STM держат копию словаря в `.framework/Dictionary.yaml`. При сборке прошивки она сверяется с `api_har.h`. Новую команду сначала добавляют сюда, потом копируют в оба фреймворка.
+
+## Тема
+
+Тема одна для всех приложений. Эталоном служит DevCloud, витрина подключает тот же файл.
+
+Поверхности идут в четыре ступени: фон страницы `--bg-body`, панель `--back-color`, блок внутри панели `--container-color`, поле ввода `--field-color`. Для частых случаев есть готовые классы. `ui-panel` для блока прямо на фоне страницы, `ui-inset` для блока внутри панели.
+
+Панели не делают полупрозрачными, на фоне они теряются. Выпадающие меню делают через `ui-panel` с тенью `--elevation-3`.
+
+Стили тегов в приложении пишите только внутри `@layer base`. Правило вне слоя сильнее утилит Tailwind, и подписи в компонентах станут крупнее, чем задумано.
 
 ```css
 @layer base {
@@ -79,74 +112,78 @@ npm install poe-svelte-ui-lib
     font-size: 1rem;
     font-weight: 600;
   }
-  label {
-    font-size: 0.8rem;
-  }
 }
 ```
 
-Классы ролей (`.bg-red`, `.bg-max`, …) и темы (`.light`/`.dark`) остаются вне слоя — они как раз должны перебивать утилиты.
+Классы ролей (`.bg-red`, `.bg-max` и другие) и классы темы (`.light`, `.dark`) остаются вне слоя. Они как раз должны перебивать утилиты.
 
-Необязательный токен `--table-header-color` — фон шапки `Table` (по умолчанию `--container-color`); смарт-виджеты задают его сами из мастер-цвета.
+Шапку `Table` можно перекрасить переменной `--table-header-color`. По умолчанию она `--accent-soft`, смарт-виджеты задают её сами от своего цвета.
 
-Справочник по регулярным выражениям для проверки полей ввода — вкладка «Регулярные выражения» на главной витрины (`src/routes/RegExp.md`). Протокол обмена с устройством описан в документации DevCloud (разделы «Протокол устройства» и «Обмен данными с устройством»).
+Посмотреть всю тему разом можно на вкладке «Тема» на главной витрины. Там палитра, все компоненты с демо-данными, типографика и Markdown.
 
-## Использование
+## Языки
 
-```svelte
-<script lang="ts">
-  import * as UI from "poe-svelte-ui-lib"
+Список языков задан в одном месте, `LANGUAGES` в `src/lib/locales/languages.ts`. Сейчас это RU, EN и ZH. Чтобы добавить язык, достаточно одной записи там. Переключатели языка во всех приложениях подхватят его сами. Пока перевода нет, показывается русский текст.
 
-  let value = $state("")
-</script>
+Приложения не держат свой список языков. Они берут его из библиотеки, а свой словарь подключают так:
 
-<UI.Input label={{ name: "Имя" }} bind:value type="text" />
-<UI.Button content={{ name: "Сохранить" }} onClick={() => console.log(value)} />
+```ts
+export const T = createTranslator(translations)
 ```
 
-Полный список компонентов и типов — в `src/lib/index.ts`. У каждого компонента есть README рядом с исходником (`src/lib/<Component>/README.md`, для `Modal`/`Dragging` — `src/lib/<Component>.README.md`) с описанием пропсов, примерами и внутренним устройством; живая витрина — `npm run dev`: на главной вкладки «Обзор» (этот README), «Тема» (предпросмотр `theme.css`) и «Регулярные выражения», дальше страница на каждый компонент.
-
-**Витрина повторяет конструктор DevCloud:** слева компонент и код (прижат к низу), справа панель свойств шириной `24rem` с тем же оформлением, что в облаке, — переполнение подписей видно сразу. Кнопка (i) в шапке панели открывает описание компонента.
+Один вызов `setLanguage` переключает язык и в библиотеке, и в приложении. Выбор сохраняется в браузере. В SSR-приложениях сохранённый язык восстанавливают вызовом `restoreLanguage()` в `onMount` корневого layout.
 
-**Описания компонентов (i)** — ключи `component.info.<Тип>` в `src/lib/locales/translations.ts` (ru/en/zh, Markdown). Один источник для витрины и конструктора DevCloud: облако показывает кнопку (i) у любого компонента, для которого есть описание. Добавляя компонент, допишите описание строго по шаблону — разделы всегда в этом порядке, неприменимые опускаются:
+Серверный код, который запускается под Node без Vite, импортирует языки из `poe-svelte-ui-lib/locales`. Корень пакета тянет Svelte-компоненты, и Node его не загрузит.
 
-| Раздел                | Что писать                                                                                                                                                                                           |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `🎯 **Назначение**`   | 1–2 фразы: что это и когда применять                                                                                                                                                                 |
-| `📦 **Пакет данных**` | откуда данные (переменная, группа полей, объект ответа), каким пакетом и как часто их слать, что и когда компонент отправляет сам или «только отображение»; не связан с устройством — так и написать |
-| `🔑 **Ключи**`        | по пункту на ключ: `` `Ключ` — тип, единицы, смысл``, обязательность; у простых компонентов — формат значения переменной                                                                             |
-| `✨ **Особенности**`  | поведение, ограничения, советы, связь с другими компонентами                                                                                                                                         |
-| `⚙️ **Настройки**`    | что меняется в панели свойств                                                                                                                                                                        |
+Тексты бывают двух видов:
 
-Пункты — списком `- `, без вложенных списков; имена ключей и значения — в обратных кавычках; одинаковые для нескольких виджетов ключи (`Lat`, `Lon`, `DevName`...) описываются одинаково.
+- **Встроенные тексты компонентов**: подписи, кнопки, подсказки. Они только в словаре `src/lib/locales/translations.ts` и выводятся через `$T("ключ")`. Русских строк прямо в разметке быть не должно.
+- **Тексты из конструктора**: название поля, варианты списка, заголовки колонок. Это строка или объект `{ ru, en, zh }`. Приложение переводит всё описание интерфейса функцией `localizeDeep` перед показом. В конструкторе их правят в окне «Тексты и переводы», которое есть у каждого компонента.
 
-**README компонента** (`src/lib/<Компонент>/README.md`, вкладка «Инфо» витрины) — развёрнутая документация для разработчика. Первые разделы повторяют описание (i) и не должны ему противоречить, дальше идут разработческие: `## Назначение` (плюс заметка о размерах) → `## Пакет данных` (плюс `### Протокол устройства` / пример кода прошивки) → `## Ключи` (таблица «Ключ / Описание», те же формулировки, что в (i)) → `## Особенности` (поведение, ограничения) → `## Пропсы` (таблица «Название / Тип / По умолчанию / Описание», колбэки — `### Колбэки`) → `## Примеры` (Svelte) → `## Конструктор свойств (<Компонент>Props.svelte)` → `## Внутреннее устройство`.
+## Как описывать компонент
 
-**Языки — единственный источник в библиотеке.** Список языков — `LANGUAGES` в `locales/languages.ts`: код, название и флаг (SVG-строка), без Svelte — годится и для серверного кода. **Новый язык — одна запись в `LANGUAGES`**: переключатели языка во всех приложениях (`LOCALES`), колонки окна «Тексты и переводы», многоязычные тексты GUI и словари подхватывают его сами; пока перевода нет — показывается текст языка по умолчанию (`DEFAULT_LANGUAGE`, `ru`). Словари (`Translations`) — строки-объекты по кодам `{ ru: "…", en: "…", zh: "…" }`: обязателен только язык по умолчанию, порядок не важен; недостающие переводы показывает `findMissingTranslations(словарь)`. `locales/i18n.ts` — текущий язык `Language`/`setLanguage` (неизвестный код не применяется, выбор сохраняется в `localStorage` `AppLanguage`), `restoreLanguage()` (сохранённый или язык браузера; стартовое значение всегда язык по умолчанию — серверный рендер совпадает с гидратацией, поэтому SSR-приложения вызывают его в `onMount` корневого layout, SPA — при старте), `LOCALES` (с флагом `flag`) и механизм перевода `createTranslator(словарь)`. Код вне компонентов берёт текущий язык через `getLanguage()` (например, для заголовка `Accept-Language`), ключ хранилища и язык по умолчанию в приложениях не повторяются; серверный код переводит функцией `translate(словарь, язык, ключ)` на язык запроса, разобранный `resolveLanguage(Accept-Language)`. Серверный код, который Node запускает без Vite (например WebSocket-сервер облака через `tsx`), импортирует языки и перевод из `poe-svelte-ui-lib/locales` — корень пакета экспортируется только для Svelte (условие `svelte`) и тянет компоненты, Node его не загрузит. Приложения (DevCloud, WebApp, терминал) свой список языков, хранилище и функцию перевода не держат: берут их из библиотеки и строят свой `$T` из своего словаря — `export const T = createTranslator(translations)`. Одно `setLanguage` переключает и компоненты библиотеки, и приложение. Многоязычные тексты GUI распознаются по виду ключей (коды языков), поэтому данные с языком, убранным из списка, не ломаются.
+У компонента два описания.
 
-**Языки (ru/en/zh) — два слоя:**
+**Короткое**, по кнопке (i). Лежит в словаре под ключом `component.info.<Тип>`. Его показывают витрина и конструктор DevCloud. Разделы идут в таком порядке, ненужные пропускаются:
 
-- **Встроенные тексты компонентов** (подписи полей виджетов, кнопки, подсказки, `aria-label`) — только через словарь `src/lib/locales/translations.ts` и `$T("ключ")`; строка с числами — параметрами: `$T("widget.fs.files", { n: files.length })` на ключ `"Файлов: {n}"`. Русских литералов в разметке и скриптах компонентов быть не должно. Списки вариантов с подписями — `$derived`, иначе не переключатся при смене языка. Исключение — шкалы прибора `WidgetPFD`: там общепринятые авиационные сокращения (`SPD`, `ALT`, `AS`, `VS`, `NO DATA`) на всех языках, переводятся только подсказки и строки состояния.
-- **Тексты, введённые в конструкторе** (`label.name`, `placeholder`, `options[].name`, вкладки, заголовки колонок, подписи переключателя и т.п.) — тип `LocalizedText` (`locales/localize.ts`): простая строка (только `ru`) или объект `{ ru, en, zh }`; при отсутствии перевода показывается `ru`, затем первый непустой. Компоненты получают уже готовые строки: приложение разрешает описание GUI функцией `localizeDeep(UIBlocks, язык)` перед рендером. Окна свойств (`*Props.svelte`) тексты не показывают и не правят — у каждого компонента одна кнопка «Тексты и переводы» (`TextsEditor`): модальное окно само собирает все тексты компонента (`collectTexts` по полям `name`, `label`, `labels`, `placeholder`, `text`, `info`, `title`, `captionLeft`/`captionRight`, `units`/`unit`, `footer`, `hiddenInfo`, `alt`; технические `id`, `class`, `icon`, `keys`, данные — никогда; у `Switch` варианты — короткие метки битов битового режима, их имя правится в окне свойств и не переводится — `NOT_TEXTS` в `TextsEditor.svelte`) и даёт по три поля RU/EN/ZH. Сохранение (`packLocalized`): пусто — `""`, только RU — строка, иначе объект из заполненных языков. Читая текст в окне свойств для логики, берите `localizeText(поле, "ru")` — поле может быть объектом. Заголовок смарт-виджета по умолчанию пустой — виджет показывает своё название из словаря на текущем языке.
+| Раздел | Что писать |
+|---|---|
+| Назначение | Одна-две фразы: что это и когда применять |
+| Пакет данных | Откуда данные, каким пакетом и как часто их слать, что компонент отправляет сам |
+| Ключи | По пункту на ключ: тип, единицы, смысл |
+| Особенности | Поведение, ограничения, советы |
+| Настройки | Что меняется в панели свойств |
 
-**Иконки вариантов панелей свойств** — `src/lib/libIcons/propsIcons.ts` (контурные SVG 24×24 строками), подставляются в `IOption.icon` в `options.ts`.
+**Подробное**, `src/lib/<Компонент>/README.md`. Оно открывается на вкладке «Инфо» витрины. Начало повторяет короткое описание и не должно ему противоречить. Дальше идут пропсы, примеры, панель свойств и внутреннее устройство.
 
 ## Разработка
 
 ```bash
-npm run dev        # витрина компонентов (SvelteKit dev-сервер)
-npm run build       # сборка пакета (svelte-kit sync + svelte-package + publint) → dist/
-npm run Formatting  # prettier --write .
+npm run dev            # витрина на локальном сервере
+npm run check          # проверка типов
+npm run TestProtocols  # тесты протоколов и битовых полей
+npm run Formatting     # prettier
+npm run build          # сборка витрины в docs/
+npm pack               # сборка пакета в dist/ с проверками
 ```
 
-### Публикация в npm
+Витрина устроена как конструктор DevCloud: слева компонент и его код, справа панель свойств той же ширины, что в облаке. Если подпись не влезает, это видно сразу.
+
+Внутри библиотеки импорты относительные. Витрина импортирует библиотеку через `#lib` (поле `imports` в `package.json`).
+
+## Выпуск
+
+Выпуск запускается сообщением коммита в `main`:
+
+- `[publish]` публикует пакет в npm;
+- `[deploy]` обновляет витрину на GitHub Pages.
 
-Коммит в `main` с `[publish]` в сообщении (`"X.Y.Z [deploy] [publish]"`, версия поднята в `package.json`) запускает `.github/workflows/npm_publish.yaml`. Публикация идёт через **trusted publisher** npm (OIDC): workflow получает одноразовый токен от GitHub (`permissions: id-token: write`), постоянный `NPM_TOKEN` не нужен, provenance добавляется автоматически. Требования npm: npm CLI 11.5.1+ (workflow обновляет его сам), Node 22.14+, `repository.url` в `package.json` дословно совпадает с репозиторием.
+Перед выпуском поднимите версию в `package.json`. Версия на витрине берётся оттуда же.
 
-Связь настраивается на npmjs.com → пакет → Settings → Trusted Publisher: GitHub Actions, `Oleg-Perevyshin/ElementsUI`, workflow `npm_publish.yaml`, разрешение «npm publish». Новая связь подтверждается первой успешной публикацией и должна пройти её в течение 2 дней, иначе истекает. Существующую связь изменить нельзя — только удалить и создать заново.
+Публикация идёт через trusted publisher npm, постоянный токен не нужен. Связь настроена на npmjs.com в настройках пакета: GitHub Actions, репозиторий `Oleg-Perevyshin/ElementsUI`, workflow `npm_publish.yaml`.
 
-**Обновление DevCloud — автоматически.** После публикации job `update-devcloud` того же workflow ждёт новую версию в npm, клонирует `xPOE-Studio/DevCloud` (Forgejo) по секрету `DEVCLOUD_ACCESS_TOKEN` (токен Forgejo с правом записи в репозиторий), ставит `poe-svelte-ui-lib@<версия>`, прогоняет `svelte-kit sync`, `prisma generate` (с заглушкой `DATABASE_URL`, к БД не подключается) и `svelte-check` и, если проверка прошла, пушит в `main` коммит «Автообновление poe-svelte-ui-lib до <версия> — переразвёртывание облака [deploy]» с пояснением, что он создан автоматически при выпуске библиотеки, — облако разворачивается само. Вручную версию в облаке не поднимаем; изменения кода облака, которым нужна новая версия библиотеки, коммитятся без `[deploy]` до выпуска — их развернёт этот коммит. Если `svelte-check` упал, коммита нет, облако остаётся на прежней версии (смотрите лог job в GitHub Actions).
+После публикации облако обновляется само. Workflow ставит новую версию в DevCloud, проверяет типы и, если всё прошло, поднимает вторую цифру версии облака и пушит туда коммит вида `1.6 [deploy] Обновление ElementsUI до 1.84.0`. Вручную версию библиотеки в облаке не поднимают. Если проверка упала, облако остаётся на старой версии, причину ищите в логе job `update-devcloud`.
 
 ---
 
-Лицензия: MIT — см. `LICENSE`.
+Лицензия MIT, см. `LICENSE`.

package/dist/Accordion/Accordion.svelte

@@ -1,5 +1,4 @@
-<!-- $lib/Accordion/Accordion.svelte — заголовок не увеличивается при раскрытии, радиус 14.
-     Мастер-цвет (componentClass) — как у смарт-виджетов: иконка и текст заголовка цветом, фон заголовка — его мягким оттенком. -->
+<!-- $lib/Accordion/Accordion.svelte — заголовок не увеличивается при раскрытии, радиус 14. Мастер-цвет (componentClass) — как у смарт-виджетов: иконка и текст заголовка цветом, фон заголовка — его мягким оттенком. -->
 <script lang="ts">
   import { slide } from "svelte/transition"
   import type { IAccordionProps } from "../types"
@@ -27,8 +26,7 @@
   transition:slide={{ duration: 200 }}
 >
   <div class="overflow-hidden rounded-[14px] border border-(--hairline-color) bg-(--back-color)">
-    <!-- Фон заголовка — мягкий оттенок мастер-цвета (светлый в светлой теме, тёмный в тёмной), текст — мастер-цвет с цветом шрифта 60/40,
-         раскрытое содержимое остаётся на чистом фоне (--back-color). -->
+    <!-- Фон заголовка — мягкий оттенок мастер-цвета (светлый в светлой теме, тёмный в тёмной), текст — мастер-цвет с цветом шрифта 60/40, раскрытое содержимое остаётся на чистом фоне (--back-color). -->
     <button
       class="flex w-full cursor-pointer items-center justify-between gap-3 bg-(--accent-soft) px-4 py-3 text-left text-[color-mix(in_srgb,var(--accent-color)_60%,var(--font-color))] transition-colors duration-150 hover:bg-[color-mix(in_srgb,var(--accent-color)_12%,var(--accent-soft))]"
       onclick={toggle}

package/dist/Accordion/README.md

@@ -1,148 +1,54 @@
-# Accordion Component
+# Accordion
+
+Сворачиваемый блок. В нём группируют компоненты, которые нужны не всегда: настройки, диагностику, редкие разделы.
 
 ## Назначение
 
-Сворачиваемый блок для группировки компонентов: настройки, диагностика, редко используемые разделы.
+Сворачиваемый блок для группировки компонентов.
 
 ## Пакет данных
 
-Не связан с устройством — сам ничего не читает и не отправляет.
+С устройством не связан, ничего не читает и не отправляет.
 
 ## Особенности
 
-- Перетащите компоненты внутрь — у аккордеона своя сетка, её размер задаётся при создании и ресайзе
-- Заголовок с иконкой открывает и закрывает содержимое
-- Мастер-цвет — как у смарт-виджетов (`widgetAccentStyle`): иконка, текст и стрелка заголовка — цветом из палитры, смешанным с цветом шрифта (читается в обеих темах), фон заголовка — его мягким оттенком (`--<цвет>-soft`: очень светлый в светлой теме, тёмный в тёмной); без выбора — акцент темы. Цвет из `label.class` перекрывает цвет текста
-- По высоте занимает одну строку сетки и растягивается по содержимому
-
-### Адаптивность
-
-- Сетка содержимого адаптируется под размеры экрана (sm:p-3)
-
-### Ограничения
-
-- При использовании изображения фона высота строк сетки устанавливается в `minmax(6.5rem, auto)` вместо `auto`
-- Необходимо убедиться, что переданный компонент иконки является валидным Svelte компонентом или SVG строкой
-- Размеры сетки должны быть положительными числами (по умолчанию 1x1)
-
-### Производительность
-
-- Содержимое аккордеона рендерится только при его открытии (`{#if isOpen}`)
+- В конструкторе компоненты перетаскивают внутрь аккордеона. У него своя сетка, её размер задаётся при создании и меняется растягиванием.
+- Заголовок с иконкой открывает и закрывает содержимое.
+- Мастер-цвет работает как у смарт-виджетов: иконка, текст и стрелка заголовка окрашены цветом из палитры, фон заголовка его мягким оттенком. Без цвета используется акцент темы. Цвет из `label.class` перекрывает цвет текста.
+- Закрытый аккордеон занимает одну строку сетки, открытый растягивается по содержимому.
+- Содержимое рисуется, только когда аккордеон открыт.
+- С картинкой фона (`image`) строки сетки не ниже `6.5rem`.
 
 ## Пропсы
 
-| Название         | Тип                                                    | По умолчанию          | Описание                                                                                 |
-| ---------------- | ------------------------------------------------------ | --------------------- | ---------------------------------------------------------------------------------------- |
-| `id`             | `string`                                               | `crypto.randomUUID()` | Уникальный идентификатор компонента                                                      |
-| `isOpen`         | `boolean`                                              | `false`               | Состояние открытия/закрытия; `$bindable` — `bind:isOpen` получает раскрытие по клику     |
-| `wrapperClass`   | `string`                                               | `""`                  | Дополнительные CSS-классы для обертки компонента                                         |
-| `componentClass` | `string`                                               | `""`                  | Мастер-цвет: роль `bg-red`, `bg-green`... из палитры `COLOR_OPTIONS`; `""` — акцент темы |
-| `size`           | `object`                                               | `-`                   | Размеры сетки содержимого (количество колонок и строк)                                   |
-| `size.height`    | `number`                                               | `1`                   | Количество строк в сетке содержимого                                                     |
-| `size.width`     | `number`                                               | `1`                   | Количество колонок в сетке содержимого                                                   |
-| `label`          | `object`                                               | `-`                   | Настройки заголовка аккордеона                                                           |
-| `label.name`     | `string`                                               | `""`                  | Текст заголовка аккордеона                                                               |
-| `label.class`    | `string`                                               | `"text-left"`         | CSS-классы для стилизации текста заголовка                                               |
-| `label.icon`     | `ConstructorOfATypedSvelteComponent \| string \| null` | `null`                | Иконка, отображаемая в заголовке (SVG строка или компонент)                              |
-| `children`       | `Snippet`                                              | `undefined`           | Слот для содержимого, которое будет отображаться при открытии                            |
-| `image`          | `string`                                               | `""`                  | URL изображения для фона содержимого аккордеона                                          |
-
-### Колбэки
-
-Компонент не генерирует специфические события, но использует встроенную функцию `toggle()` для переключения состояния открытия/закрытия при клике на кнопку заголовка.
+| Название | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `id` | `string` | `crypto.randomUUID()` | Идентификатор |
+| `isOpen` | `boolean` | `false` | Открыт ли. Можно связать через `bind:isOpen` |
+| `wrapperClass` | `string` | `""` | Классы обёртки |
+| `componentClass` | `string` | `""` | Мастер-цвет: `bg-red`, `bg-green` и другие из `COLOR_OPTIONS`. Пусто — акцент темы |
+| `size` | `{ width, height }` | `1 × 1` | Сетка содержимого: колонки и строки |
+| `label.name` | `string` | `""` | Заголовок |
+| `label.class` | `string` | `"text-left"` | Классы текста заголовка |
+| `label.icon` | `Component \| string \| null` | `null` | Иконка заголовка |
+| `image` | `string` | `""` | Картинка фона содержимого |
+| `children` | `Snippet` | | Содержимое |
 
-## Примеры
-
-### Базовое использование
-
-```svelte
-<script>
-  import * as UI from "poe-svelte-ui-lib"
-</script>
-
-<UI.Accordion label={{ name: "Accordion" }} isOpen={true}>
-  <div class="flex flex-col">
-    <h1>Содержимое компонента</h1>
-    <h1>Содержимое компонента</h1>
-    <h1>Содержимое компонента</h1>
-  </div>
-</UI.Accordion>
-```
+Колбэков нет. Открытие и закрытие компонент обрабатывает сам.
 
-### Вложенные аккордеоны
+## Пример
 
 ```svelte
 <script>
   import * as UI from "poe-svelte-ui-lib"
+  let open = $state(false)
 </script>
 
-<UI.Accordion label={{ name: "Main Accordion" }} isOpen={true}>
-  <UI.Accordion label={{ name: "Nested Accordion 1", class: "" }} isOpen={false} wrapperClass="col-span-3">
-    <h6>Содержимое вложенного Accordion 1</h6>
-    <h5>Содержимое вложенного Accordion 1</h5>
-    <h4>Содержимое вложенного Accordion 1</h4>
-    <h3>Содержимое вложенного Accordion 1</h3>
-    <h2>Содержимое вложенного Accordion 1</h2>
-    <h1>Содержимое вложенного Accordion 1</h1>
-  </UI.Accordion>
-  <UI.Accordion label={{ name: "Nested Accordion 2", class: "" }} isOpen={false} wrapperClass="col-span-3">
-    <h1>Содержимое вложенного Accordion 2</h1>
-    <h2>Содержимое вложенного Accordion 2</h2>
-    <h3>Содержимое вложенного Accordion 2</h3>
-    <h4>Содержимое вложенного Accordion 2</h4>
-    <h5>Содержимое вложенного Accordion 2</h5>
-  </UI.Accordion>
-  <UI.Accordion label={{ name: "Nested Accordion 3", class: "" }} isOpen={false} wrapperClass="col-span-3">
-    <h4>Содержимое вложенного Accordion 3</h4>
-    <h3>Содержимое вложенного Accordion 3</h3>
-    <h2>Содержимое вложенного Accordion 3</h2>
-    <h1>Содержимое вложенного Accordion 3</h1>
-  </UI.Accordion>
+<UI.Accordion label={{ name: "Сеть" }} componentClass="bg-blue" bind:isOpen={open}>
+  <UI.Input label={{ name: "SSID" }} />
 </UI.Accordion>
 ```
 
-## Конструктор свойств (AccordionProps.svelte)
-
-### Описание
-
-Компонент `AccordionProps.svelte` предоставляет визуальный интерфейс для редактирования свойств аккордеона. Поддерживает два режима отображения: для конструктора и для редактирования.
-
-### Пропсы конструктора
-
-| Название           | Тип                                                                                                                                 | По умолчанию | Описание                                                |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------- |
-| `component`        | `UIComponent & { properties: Partial<IAccordionProps> }`                                                                            | `-`          | Объект компонента с его свойствами                      |
-| `onPropertyChange` | `(updates: Partial<{ properties?: string \| object; name?: string; access?: string; eventHandler?: IUIComponentHandler }>) => void` | `-`          | Коллбэк для обновления свойств компонента               |
-| `forConstructor`   | `boolean`                                                                                                                           | `true`       | Режим отображения (для конструктора или редактирования) |
-
-### Особенности конструктора
-
-- Включает модальное окно для выбора иконок из библиотеки
-- Поддерживает загрузку изображений для фона
-- Поддерживает валидацию числовых значений (min/max) для размеров
-
-### Что настраивается
-
-- Заголовок, иконка, мастер-цвет заголовка, «Открыт по умолчанию» — состояние при загрузке интерфейса
-- Картинка фона — изображение под содержимым (например схема устройства), поверх неё располагаются компоненты
-
-## Внутреннее устройство
-
-### Реактивность
-
-- Переменная `isOpen` является реактивной и управляет состоянием отображения содержимого
-- Функция `toggle()` изменяет состояние `isOpen`, вызывая повторный рендеринг компонента
-
-### Сторы и зависимости
-
-- Применяется переход `slide` из `svelte/transition` для анимации открытия/закрытия
-
-### Директивы
-
-- `transition:slide` для анимации открытия/закрытия содержимого
-- `@render children` для отображения переданного содержимого
-- `bind:isOpen` в конструкторе свойств для двусторонней привязки состояния
-
-### Слоты
+## Панель свойств (AccordionProps.svelte)
 
-- `children` - слот для содержимого, которое отображается внутри аккордеона при его открытии
+В конструкторе задают заголовок, иконку, мастер-цвет, картинку фона и размер сетки.

package/dist/Button/Button.svelte

@@ -1,12 +1,4 @@
-<!-- $lib/Button/Button.svelte — шаг 3 плана.
-     API не изменён: id, wrapperClass, componentClass, disabled, content, keyBind, onClick.
-     Что изменилось внутри:
-       • роль определяется значением bg-* (намерение), а не фактом его наличия;
-       • убрано автоподчёркивание текста — кнопка больше не выглядит ссылкой;
-       • единый радиус 10px (иконка без подписи — круг), высота 32px (стандарт полей h-8), кегль 14/600;
-       • кольцо фокуса вместо размытой тени;
-       • disabled через токены, а не opacity: 0.5;
-       • иконка встала в поток (flex + gap) вместо absolute left-3. -->
+<!-- $lib/Button/Button.svelte — кнопка: роль по значению bg-*, радиус 10px (иконка без подписи — круг), высота 32px, кольцо фокуса, иконка в потоке через flex + gap -->
 <script lang="ts">
   import { onMount } from "svelte"
   import type { IButtonProps } from "../types"
@@ -29,11 +21,7 @@
 
   let showInfo = $state(false)
 
-  /* ─── Роль кнопки по последнему классу bg-* ─────────────────────────
-     bg-blue / bg-green / bg-cyan / bg-purple / bg-orange / bg-yellow → primary     (заливка + белый текст)
-     bg-red / bg-pink                                                → destructive
-     bg-max / bg-gray / bg-*-soft                                    → secondary   (поверхность + контур)
-     bg-transparent / без bg-*                                       → plain       (текст акцентом) */
+  /* ─── Роль кнопки по последнему классу bg-* ───────────────────────── bg-blue / bg-green / bg-cyan / bg-purple / bg-orange / bg-yellow → primary (заливка + белый текст) bg-red / bg-pink → destructive bg-max / bg-gray / bg-*-soft → secondary (поверхность + контур) bg-transparent / без bg-* → plain (текст акцентом) */
   const SURFACE_BG = ["bg-max", "bg-gray"]
   const DANGER_BG = ["bg-red", "bg-pink"]
 
@@ -51,10 +39,7 @@
 
   const isIconOnly = $derived(!!content?.icon && !content.name?.trim())
 
-  /* bg-(--bg-color) намеренно не входит в roleClass: он приклеивается к готовому
-     className вне twMerge (см. разметку ниже) — иначе twMerge видит его и явный
-     bg-* из componentClass (bg-red, bg-max…) как конфликтующие утилиты одной
-     группы и вырезает один из них, из-за чего заливка кнопки пропадает. */
+  /* bg-(--bg-color) намеренно не входит в roleClass: он приклеивается к готовому className вне twMerge (см. разметку ниже) — иначе twMerge видит его и явный bg-* из componentClass (bg-red, bg-max…) как конфликтующие утилиты одной группы и вырезает один из них, из-за чего заливка кнопки пропадает. */
   const roleBg = $derived.by(() => {
     if (disabled) return "bg-(--gray-color)"
     if (role === "plain") return "bg-transparent"