Feature/UI normalization tool

docs/normalization/README.md

@@ -0,0 +1,55 @@
+# Документация: UI Normalization
+
+Spec-driven описание **config-driven** форм (редактор **normalization-tool**, просмотр **transpile-viewer**, общий DSL).
+
+---
+
+## Итоговый вид документации (три слоя)
+
+```mermaid
+flowchart TB
+  subgraph layer1 [1. Обзор решения]
+    T[tooling.md]
+  end
+  subgraph layer2 [2. Фичи]
+    F[features/README.md]
+    F1[feat-*.md]
+  end
+  subgraph layer3 [3. Требования по эпикам]
+    P[plans/plan-*.md]
+  end
+  subgraph meta [Мета]
+    R[roadmap.md]
+  end
+  R --> T
+  R --> F
+  R --> P
+  T --> F
+  F --> F1
+  P --> F1
+```
+
+| Слой | Документ | Назначение |
+|------|----------|------------|
+| **1** | **[tooling.md](./tooling.md)** | Краткое **описание решения** (что строим, зачем, как устроено в целом) и **таблица ссылок** на фичи. В конце файла — **прежние ссылки на разделы** (`#…`) для совместимости. |
+| **2** | **[features/README.md](./features/README.md)** | **Дерево вложенных фич** и ссылки на файлы **`feat-*.md`**: контракты, ограничения, связь с кодом. |
+| **3** | **[plans/](./plans/)** | **Требования** закрытых и текущих эпиков: таблица *`id` · фича · описание*; трассировка к роадмапу и к файлам из **`features/`**. |
+| **Мета** | **[roadmap.md](./roadmap.md)** | Этапы **п.1–9**, статусы, указатели на слои 1–3. |
+
+**Точка входа для чтения:** [tooling.md](./tooling.md) → при необходимости углубления — конкретный **`features/feat-…`** → для приёмки эпика — **`plans/plan-…`**.
+
+**П.9 роадмапа** закрепляет поддержание этой структуры при эволюции кода.
+
+---
+
+## Быстрый указатель
+
+| Тема | Куда |
+|------|------|
+| Два приложения, паритет, границы продукта | [feat-product-and-parity.md](./features/feat-product-and-parity.md) |
+| `FormData`, дерево контролов | [feat-dsl-root-model.md](./features/feat-dsl-root-model.md) |
+| `configHook` | [feat-config-hook.md](./features/feat-config-hook.md) |
+| `handlers`, `useConfig`, хуки по узлам | [feat-schema-handlers.md](./features/feat-schema-handlers.md) |
+| Sucrase, чанки, `loadFormDslBrowserRuntime` | [feat-lazy-dsl-runtime.md](./features/feat-lazy-dsl-runtime.md) |
+| FSA, IndexedDB, `?form=` | [feat-workspace-browser.md](./features/feat-workspace-browser.md) |
+| Button / Text / Grid / Table / DSL п.2 | [plans/](./plans/) |

docs/normalization/features/README.md

@@ -0,0 +1,51 @@
+# Каталог фич: UI Normalization
+
+Иерархия **возможностей** (feature tree) туллинга. Каждая фича — отдельный файл: контракт, ограничения, связь с кодом. Сводный обзор решения и навигация — **[tooling.md](../tooling.md)**.
+
+---
+
+## Дерево (вложенность)
+
+```
+Решение: config-driven формы + Hexa UI
+│
+├── Продукт и поставка
+│   └── [Продукт, паритет, два приложения](./feat-product-and-parity.md)
+│
+├── DSL и исполнение
+│   ├── [Корневая модель FormData](./feat-dsl-root-model.md)
+│   ├── [Принцип «одна настройка — один способ»](./feat-dsl-one-setting.md)
+│   ├── [Контракт configHook](./feat-config-hook.md)
+│   ├── [handlers формы и useConfig (отдельные хуки)](./feat-schema-handlers.md)
+│   ├── [Привязка к модели (modelContract, dataBindPath)](./feat-form-model-binding.md)
+│   ├── [Видимость и блокировка по модели](./feat-form-visible-disabled.md)
+│   ├── [Ленивый рантайм: parseFormTs, Sucrase, чанки](./feat-lazy-dsl-runtime.md)
+│   └── [Типизация автором и импорты потребителя](./feat-typing-and-imports.md)
+│
+├── Рабочее пространство (браузер)
+│   └── [FSA, IndexedDB, URL form, сценарии, среда](./feat-workspace-browser.md)
+│
+├── Целевое состояние (роадмап)
+│   ├── [Архитектурные решения и направления](./feat-architecture-directions.md)
+│   ├── [Превью в редакторе — единый рендер-движок](./feat-editor-preview-target.md)
+│   └── [Один configHook на форму](./feat-form-config-hook-unified.md)
+│
+└── Репозиторий
+    └── [Пакеты и shared-модули](./feat-repo-layout.md)
+```
+
+---
+
+## Связь с другими документами
+
+| Документ | Роль |
+|----------|------|
+| [tooling.md](../tooling.md) | Краткое **описание решения** + таблица ссылок на фичи |
+| [roadmap.md](../roadmap.md) | Этапы п.1–9, статусы |
+| [plans/](../plans/) | **Требования** по эпикам (фича → описание), трассировка к роадмапу |
+
+---
+
+## Именование фич в требованиях (plans)
+
+В планах используются стабильные идентификаторы вида **`domain.short-name`** (например **`config-hook.button`**) для ссылок из обсуждений и PR.

docs/normalization/features/feat-architecture-directions.md

@@ -0,0 +1,29 @@
+# Фича: архитектурные решения и долгосрочные направления
+
+**Родитель:** целевое состояние (роадмап п.5–8 и часть п.7).
+
+---
+
+## Описание
+
+Зафиксированные и целевые решения, которые задают рамку эволюции кода и продуктов, без пошаговой инструкции внедрения.
+
+---
+
+## Требования / направления
+
+- **`arch.dsl.shared-module`:** один общий модуль DSL в дереве репозитория; **отдельный publishable npm-пакет** под DSL **не вводится**; **двух расходящихся копий** полного DSL **нет**.
+- **`arch.forms.ts-only`:** артефакты форм в каталоге — **только `.ts`**.
+- **`arch.code.genericity`:** контролы обрабатываются общими механизмами; частное — в дескрипторах и типах, не копипаста веток в рендерерах.
+- **`arch.products.storybook`:** tool — целевой сценарий аддона **Storybook**; viewer — общий движок рендера для Storybook и прод.
+- **`arch.shell.hexa`:** оболочки инструментов на **Hexa UI**; целевое **dogfooding** — UI инструментов из DSL + общего рендерера (оговорки для холста/DnD — при проектировании).
+- **`arch.rename`:** целевые имена пакетов **`kant-editor`** / **`kant-renderer`**.
+- **`arch.compat.json-ui-builder`:** обратная совместимость **`form-dsl`** и артефактов с **JSON UI Builder** (или явный мост версий).
+- **`arch.viewer.adapters`:** viewer на адаптерах и **Auto UI** без монолитного маппинга всех типов; **Auto UI** — миграция на **React** end-to-end.
+
+---
+
+## Ссылки
+
+- [roadmap.md](../roadmap.md) п.5–8, п.7
+- Детализация превью в редакторе: [feat-editor-preview-target.md](./feat-editor-preview-target.md)

docs/normalization/features/feat-config-hook.md

@@ -0,0 +1,43 @@
+# Фича: контракт configHook
+
+**Родитель:** DSL и исполнение. Зависит от [feat-dsl-one-setting](./feat-dsl-one-setting.md). Загрузка модулей — [feat-lazy-dsl-runtime](./feat-lazy-dsl-runtime.md).
+
+---
+
+## Описание
+
+В динамическом режиме пропсы экземпляра компонента ДС задаёт логика **`configHook`**. Для **нормализованной** формы модуль **один на всю форму** — см. [feat-form-config-hook-unified](./feat-form-config-hook-unified.md): default export возвращает объект **`control.id` → хук контрола**. Колбэки (`onClick`, `onChange`, …) объявляются **внутри** объекта пропсов, который возвращает функция для конкретного контрола.
+
+**Исполнение в tool / viewer:** вместо фабричного реестра **`configHook`** на корне формы используется **`handlers.useConfig`** на каждом узле; сигнатура хука на контрол **та же** (**`FormSlice` → пропсы ДС \| `null`**). Форма и загрузка модулей — [feat-schema-handlers](./feat-schema-handlers.md).
+
+---
+
+## Требования
+
+- **`config-hook.api.input`:** единственный аргумент функции для контрола — **`FormSlice`** (`state` + `config.elements`, при необходимости **`mergeState`**, контекст таблицы, опционально **`dataBind`** при **`dataBindPath`** — [feat-form-model-binding](./feat-form-model-binding.md)); тип контрола задаётся телом этой функции в форменном модуле (по ключу **`control.id`** в реестре).
+- **`config-hook.api.output`:** полный объект пропсов экземпляра компонента ДС **или `null`**; **`null`** — не монтировать компонент; отдельных полей `visible` в DSL для этого нет.
+- **`config-hook.react`:** модуль исполняется как React-хук; пересчёт через React и стейт, без декларативного списка зависимостей в DSL.
+- **`config-hook.context.layers`:** в колбэках автор разводит контекст **формы/инструмента** и контекст **Hexa** (события, пропсы экземпляра).
+- **`config-hook.file.ts-only`:** путь в DSL и в пикере — только **`.ts`**; перед исполнением в браузере — транспиляция (см. ленивый рантайм).
+
+### Примеры возврата (Hexa UI)
+
+- Кнопка: **`ButtonProps | null`**
+- Текст: **`TextProps | null`**
+- Сетка / таблица: см. планы [plan-grid](../plans/plan-grid.md), [plan-table](../plans/plan-table.md)
+
+### Артефакты формы
+
+| Артефакт | Расширение | Загрузка |
+|----------|------------|----------|
+| **`configHook`** | **`.ts`** | [feat-lazy-dsl-runtime](./feat-lazy-dsl-runtime.md) → транспиляция → blob → `import()` |
+| В **`.ts`** формы | — | путь к хуку сериализуется как **`() => import('./…')`** |
+
+Пути **`handlers`** на форме/контроле в UI могут указывать **`.js`** или **`.ts`**; для новых артефактов приоритет **TS** ([tooling — обзор](../tooling.md)).
+
+---
+
+## Ссылки
+
+- Пример стиля: `packages/kaspersky-ui-normalization-tool/dsl/demo/demo.config-hook.ts`
+- Код: `loadConfigHookDefaultExport` в tool и viewer (legacy); резолв **`useConfig`** — **`lifecycle-resolve.ts`**, см. [feat-schema-handlers](./feat-schema-handlers.md)

docs/normalization/features/feat-dsl-one-setting.md

@@ -0,0 +1,24 @@
+# Фича: одна настройка — один способ
+
+**Родитель:** DSL и исполнение.
+
+---
+
+## Описание
+
+У каждого **пропа** экземпляра компонента ДС в форме ровно **один** источник значения: либо статическое поле в DSL (инспектор), либо динамика целиком через **`handlers.useConfig`** (хук для узла). Смешивание для одного пропа запрещено. Контракт хука совпадает с [feat-config-hook](./feat-config-hook.md); размещение в форме — [feat-schema-handlers](./feat-schema-handlers.md).
+
+---
+
+## Требования
+
+- **`dsl.setting.single-source`:** параметр либо **статический** (хранится в DSL и задаётся в панели свойств), либо **динамический** (только из **`handlers.useConfig`** для данного **`control.id`**; отдельного поля DSL для этого пропа нет).
+- **`dsl.setting.no-merge`:** нет объединения статики и динамики и нет «динамика перекрывает статику» для одного и того же пропа.
+
+---
+
+## Ссылки
+
+- Контракт динамики (вход/выход хука): [feat-config-hook.md](./feat-config-hook.md)
+- **`handlers`** и **`useConfig`:** [feat-schema-handlers.md](./feat-schema-handlers.md)
+- Исторически — один **`configHook`** на форму: [feat-form-config-hook-unified.md](./feat-form-config-hook-unified.md)

docs/normalization/features/feat-dsl-root-model.md

@@ -0,0 +1,32 @@
+# Фича: корневая модель DSL (FormData)
+
+**Родитель:** DSL и исполнение.
+
+---
+
+## Описание
+
+Форма в рантайме — объект **`FormData`**: идентификаторы, опционально схема полей и обработчики уровня формы, дерево контролов. Источник в репозитории — **`shared/types/form.ts`** и нормализация в **`shared/normalization-form-dsl/form-dsl-core.ts`**.
+
+---
+
+## Требования
+
+- **`dsl.root.fields`:** корень содержит **`id`** формы.
+- **`dsl.root.schema`:** опционально — описание полей данных формы в модуле/JSON; **в normalization-tool не редактируется** (нет смысла в UI: превью и **`FormRenderer`** на это поле не опираются).
+- **`dsl.root.handlers`:** опционально — жизненный цикл формы (**`onFormInit`**, **`onFormSubmit`**) и др.; значения — путь к **`.ts`**, ленивый **`import()`**, либо функция после нормализации. Семантика и резолв — [feat-schema-handlers](./feat-schema-handlers.md). Редактор вызывает lifecycle при загрузке хуков (**`FormEditorConfigHookProvider`**).
+- **`dsl.root.modelContract`:** опционально — модуль **контракта модели** (тип
+  для **`data.ts`**, плюс **`MODEL_INITIAL`** → списки путей в **tool**);
+  формат ссылки как у **`handlers`**. Детали и **`FormSlice.dataBind`** —
+  [feat-form-model-binding](./feat-form-model-binding.md).
+- **`dsl.root.elements`:** дерево контролов: семантический **`type`**, **`id`**, привязки к данным, валидация, **`visibleWhen`** / **`disabledWhen`** по **`modelPath`** в **`state`**, обработчики на контроле; опционально **`dataBindPath`** (путь из контракта для **`useConfig`**) — [feat-form-model-binding](./feat-form-model-binding.md), [feat-form-visible-disabled](./feat-form-visible-disabled.md).
+- **`dsl.mapping.semantics-to-hexa`:** маппинг «семантика контрола → компонент ДС» живёт в **реестрах / рендерерах** приложений, не как отдельный дублирующий метатип в DSL.
+
+---
+
+## Ссылки
+
+- Типы: `shared/types/form.ts`
+- Логика контролов: `shared/normalization-form-dsl/form-dsl-core.ts`, entry `form-dsl.ts`
+- **`handlers` / `useConfig`:** [feat-schema-handlers](./feat-schema-handlers.md)
+- **Привязка к модели:** [feat-form-model-binding](./feat-form-model-binding.md)