@cat-of-summer/st-script 1.4.2 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +1 -1
  2. package/dist/shape.esm.min.js +2 -0
  3. package/dist/{cut.esm.min.js.map → shape.esm.min.js.map} +4 -4
  4. package/dist/shape.min.js +2 -0
  5. package/dist/shape.min.js.map +7 -0
  6. package/docs/README.md +36 -0
  7. package/docs/src/README.md +29 -0
  8. package/docs/src/_traits/README.md +8 -0
  9. package/docs/src/_traits/hasInstanceSymbol.js.md +57 -0
  10. package/docs/src/app/README.md +13 -0
  11. package/docs/src/app/datepicker/README.md +9 -0
  12. package/docs/src/app/datepicker/_calendar.js.md +1 -0
  13. package/docs/src/app/datepicker/index.js.md +153 -0
  14. package/docs/src/app/form/README.md +8 -0
  15. package/docs/src/app/form/index.js.md +560 -0
  16. package/docs/src/app/index.js.md +1302 -0
  17. package/docs/src/cookie/README.md +8 -0
  18. package/docs/src/cookie/index.js.md +80 -0
  19. package/docs/src/core/README.md +8 -0
  20. package/docs/src/core/index.js.md +178 -0
  21. package/docs/src/index.js.md +1 -0
  22. package/docs/src/loader/README.md +8 -0
  23. package/docs/src/loader/index.js.md +125 -0
  24. package/docs/src/mask/README.md +10 -0
  25. package/docs/src/mask/_engine.js.md +1 -0
  26. package/docs/src/mask/_groups.js.md +1 -0
  27. package/docs/src/mask/index.js.md +411 -0
  28. package/docs/src/modal/README.md +8 -0
  29. package/docs/src/modal/index.js.md +809 -0
  30. package/docs/src/observer/README.md +9 -0
  31. package/docs/src/observer/_engine.js.md +28 -0
  32. package/docs/src/observer/index.js.md +259 -0
  33. package/docs/src/route/README.md +8 -0
  34. package/docs/src/route/index.js.md +385 -0
  35. package/docs/src/select/README.md +8 -0
  36. package/docs/src/select/index.js.md +115 -0
  37. package/docs/src/shape/README.md +9 -0
  38. package/docs/src/shape/_engine.js.md +1 -0
  39. package/docs/src/shape/index.js.md +98 -0
  40. package/docs/src/st_button_widget/README.md +9 -0
  41. package/docs/src/st_button_widget/README.txt.md +4 -0
  42. package/docs/src/st_button_widget/index.js.md +68 -0
  43. package/docs/src/st_links_widget/README.md +9 -0
  44. package/docs/src/st_links_widget/README.txt.md +4 -0
  45. package/docs/src/st_links_widget/index.js.md +46 -0
  46. package/docs/src/st_widget/README.md +8 -0
  47. package/docs/src/st_widget/button/README.md +4 -0
  48. package/docs/src/toggle/README.md +8 -0
  49. package/docs/src/toggle/index.js.md +572 -0
  50. package/docs/src/typograf/README.md +9 -0
  51. package/docs/src/typograf/_engine.js.md +75 -0
  52. package/docs/src/typograf/index.js.md +165 -0
  53. package/docs/src/uploader/README.md +8 -0
  54. package/docs/src/uploader/index.js.md +112 -0
  55. package/docs/src/validator/README.md +8 -0
  56. package/docs/src/validator/index.js.md +113 -0
  57. package/package.json +3 -2
  58. package/src/index.js +1 -1
  59. package/src/{cut → shape}/_engine.js +1 -1
  60. package/src/{cut → shape}/index.js +10 -10
  61. package/dist/cut.esm.min.js +0 -2
  62. package/dist/cut.min.js +0 -2
  63. package/dist/cut.min.js.map +0 -7
@@ -0,0 +1,1302 @@
1
+ # app
2
+
3
+ ## Обзор
4
+
5
+ `App` (`app.min.js`) — минималистичный реактивный фреймворк, основанный на [Custom Elements](https://developer.mozilla.org/ru/docs/Web/API/CustomElementRegistry). Каждый компонент — это нативный HTML-элемент `<st-app>`. Нет сборщиков, нет зависимостей, нет виртуального DOM — просто один файл и тег `<script>`.
6
+
7
+ **Ключевые возможности:**
8
+
9
+ - Реактивность через `Proxy` — DOM обновляется автоматически при изменении данных
10
+ - Батчировинг обновлений через `Promise.resolve()` — несколько мутаций за один тик сливаются в один проход
11
+ - Директивы шаблона: интерполяция `{{ }}`, `#if/#else-if/#else`, `#for` (с ключами `#key`), `#show`, `#model`, `#html`, `@event`, `:attr`
12
+ - Вычисляемые свойства — геттеры с авто-трекингом зависимостей
13
+ - Двусторонняя привязка форм через `#model`
14
+ - Вложенные компоненты с реактивной передачей данных через `:attr`
15
+ - Переключение шаблонов на лету через `applyTemplate()`
16
+ - Наблюдатели через `watch()`
17
+
18
+ ---
19
+
20
+ ## Подключение
21
+
22
+ ### Классический `<script>`
23
+
24
+ Достаточно одного тега. Никакого Node.js, Webpack или npm.
25
+
26
+ ```html
27
+ <script src="https://cdn.jsdelivr.net/npm/@cat-of-summer/st-script/dist/app.min.js"></script>
28
+ ```
29
+
30
+ Класс `App` и тег `<st-app>` становятся глобально доступны.
31
+
32
+ ### ES-модуль (import)
33
+
34
+ ```html
35
+ <script type="module">
36
+ import App from '@cat-of-summer/st-script/app';
37
+
38
+ App.create({
39
+ app: 'counter',
40
+ count: 0,
41
+ template: `<button @click="count++">{{ count }}</button>`
42
+ });
43
+ </script>
44
+ ```
45
+
46
+ Или в отдельном `.js`-файле:
47
+
48
+ ```js
49
+ import App from '@cat-of-summer/st-script/app';
50
+
51
+ export function initApp() {
52
+ App.create({ app: 'myApp', /* ... */ });
53
+ }
54
+ ```
55
+
56
+ > **Важно:** `<st-app>` регистрируется как Custom Element при загрузке класса — это происходит на уровне статического инициализатора (`static { customElements.define('st-app', this) }`). При ES-модульном импорте это отрабатывает автоматически в момент импорта.
57
+
58
+ > **Внимание при ES-модулях:** `<script type="module">` выполняется **после** парсинга DOM (defer по умолчанию). Если `<st-app>` находится в HTML выше `<script type="module">`, фреймворк дождётся регистрации компонента — элемент будет ждать вызова `App.create()`.
59
+
60
+ ---
61
+
62
+ ## App.create(options) — регистрация компонента
63
+
64
+ ```js
65
+ App.create({
66
+ app: 'myApp', // обязательно — уникальный id
67
+ template: `...`, // HTML-шаблон
68
+ setup() { ... }, // вызывается после init реактивности
69
+ events: { }, // объект обработчиков событий компонента
70
+
71
+ // произвольные реактивные свойства:
72
+ count: 0,
73
+ items: [],
74
+ user: { name: 'Иван' },
75
+
76
+ // методы:
77
+ increment() { this.count++; },
78
+
79
+ // вычисляемые свойства (геттеры):
80
+ get total() { return this.items.length; }
81
+ });
82
+ ```
83
+
84
+ | Поле | Тип | Описание |
85
+ |---|---|---|
86
+ | `app` | `string` | Уникальный идентификатор; совпадает со значением атрибута `app` на элементе |
87
+ | `template` | `string` | HTML-шаблон компонента. Если пустая строка — используется `innerHTML` элемента |
88
+ | `setup()` | `function` | Вызывается один раз после инициализации реактивности, до рендеринга. `this` — экземпляр компонента |
89
+ | `events` | `object` | Карта `{ eventName: handler }` — навешиваются через `addEventListener` на элемент |
90
+ | `...data` | `any` | Произвольные реактивные свойства. Примитивы, объекты и массивы — все становятся реактивными |
91
+ | `method()` | `function` | Метод компонента. Доступен в шаблоне и через `this` |
92
+ | `get prop()` | `function` | Вычисляемое свойство. Пересчитывается при изменении зависимостей. Доступно в шаблоне |
93
+ | `helpers` | `object` | Значения, видимые в шаблоне, но не реактивные: форматтеры, фасады модулей. См. "Помощники шаблона" |
94
+
95
+ > **Важно:** `App.create()` бросает ошибку, если приложение с таким `app` уже зарегистрировано.
96
+
97
+ ### Помощники шаблона: `helpers` и `App.helpers()`
98
+
99
+ Форматтеры и фасады, которые шаблон вызывает в `{{ }}` и обработчиках, не нужно класть в конфиг (там методы оборачиваются и вызов из обработчика перерисовывает их читателей) или в `window`:
100
+
101
+ ```js
102
+ import { format } from './format.js';
103
+
104
+ App.helpers({ format }); // видно во всех приложениях
105
+
106
+ App.create({
107
+ app: 'list',
108
+ helpers: { Api }, // видно только в этом приложении
109
+ items: [],
110
+ });
111
+ ```
112
+
113
+ ```html
114
+ <span>{{ format.date(item.updated_at) }}</span>
115
+ <button @click="Api.reload()">Обновить</button>
116
+ ```
117
+
118
+ Имя ищется по порядку: свойства компонента и переменные цикла, `helpers` конфига, `App.helpers()`, глобальные. Помощники не становятся свойствами элемента и ничего не перерисовывают сами. `App.extend` сливает `helpers` базового и нового конфига.
119
+
120
+ ---
121
+
122
+ ## App.extend(app, options) — расширение компонента
123
+
124
+ Создаёт новый компонент на основе существующего, переопределяя нужные поля. `events` сливаются, а не заменяются. Геттеры (вычисляемые свойства) переносятся как геттеры и в наследнике считаются от его данных.
125
+
126
+ ```js
127
+ App.create({
128
+ app: 'base',
129
+ count: 0,
130
+ label: 'База',
131
+ template: `<p>{{ label }}: {{ count }}</p>`
132
+ });
133
+
134
+ App.extend('base', {
135
+ app: 'extended',
136
+ label: 'Расширенный',
137
+ count: 100
138
+ });
139
+ ```
140
+
141
+ ```html
142
+ <st-app app="extended"></st-app>
143
+ <!-- Выведет: Расширенный: 100 -->
144
+ ```
145
+
146
+ ---
147
+
148
+ ## App.toRaw(value) и App.snapshot(value) — данные без реактивности
149
+
150
+ Объекты и массивы конфига отдаются через `Proxy`. Чтобы отправить их на сервер, сравнить с исходником или сохранить копию:
151
+
152
+ - `App.toRaw(value)` — исходный объект под обёрткой, вложенные значения как есть. Значение без обёртки возвращается без изменений.
153
+ - `App.snapshot(value)` — глубокая копия без обёрток: массивы и простые объекты копируются, остальное (`Date`, `File`, `Map`, экземпляры классов) идёт как есть. Циклические ссылки сохраняются.
154
+
155
+ ```js
156
+ const body = App.snapshot(this.form); // вместо JSON.parse(JSON.stringify(this.form))
157
+ const changed = App.toRaw(this.item) !== original;
158
+ ```
159
+
160
+ ---
161
+
162
+ ## Монтирование компонента
163
+
164
+ ```html
165
+ <!-- Монтирование по id -->
166
+ <st-app app="counter"></st-app>
167
+
168
+ <!-- Компонент без App.create() — только атрибуты + innerHTML как шаблон -->
169
+ <st-app :title="Привет" :count="42">
170
+ <h1>{{ title }}</h1>
171
+ <p>Счётчик: {{ count }}</p>
172
+ </st-app>
173
+ ```
174
+
175
+ ### Атрибут `app`
176
+
177
+ Связывает HTML-элемент с конфигурацией, зарегистрированной через `App.create()`. Если элемент появляется в DOM раньше вызова `App.create()` — он ждёт регистрации.
178
+
179
+ ---
180
+
181
+ ## Реактивные данные
182
+
183
+ Все свойства, объявленные в `App.create()`, становятся реактивными автоматически:
184
+
185
+ - **Примитивы** (`number`, `string`, `boolean`) — отслеживаются по ключу
186
+ - **Объекты и массивы** — оборачиваются в `Proxy`. Работает на любой глубине вложенности
187
+ - **Функции** — оборачиваются в прокси, который тригерит зависимости после вызова
188
+
189
+ При изменении данных DOM обновляется асинхронно (батч через `Promise.resolve()`), поэтому несколько синхронных мутаций приводят к одному проходу обновлений.
190
+
191
+ ```js
192
+ App.create({
193
+ app: 'reactive',
194
+ user: { profile: { name: 'Иван', age: 25 } },
195
+
196
+ incrementAge() {
197
+ this.user.profile.age++; // глубокое изменение — DOM обновится
198
+ },
199
+
200
+ template: `
201
+ <div>
202
+ <p>{{ user.profile.name }}, {{ user.profile.age }} лет</p>
203
+ <button @click="incrementAge()">+1 год</button>
204
+ </div>
205
+ `
206
+ });
207
+ ```
208
+
209
+ ### Реактивные массивы
210
+
211
+ Все мутирующие методы массива (`push`, `pop`, `splice`, `shift`, `unshift`, `sort`, `reverse`) тригерят обновление DOM:
212
+
213
+ ```js
214
+ this.items.push('новый элемент'); // ✓ реактивно
215
+ this.items.splice(2, 1); // ✓ реактивно
216
+ this.items = [...this.items, 'x']; // ✓ тоже работает
217
+ ```
218
+
219
+ ---
220
+
221
+ ## Вычисляемые свойства (геттеры)
222
+
223
+ Геттеры автоматически отслеживают зависимости и пересчитываются при их изменении:
224
+
225
+ ```js
226
+ App.create({
227
+ app: 'form',
228
+ username: '',
229
+ email: '',
230
+ agreed: false,
231
+
232
+ get isValid() {
233
+ // зависит от username, email, agreed — пересчитается при изменении любого из них
234
+ return this.username.length >= 3
235
+ && this.email.includes('@')
236
+ && this.agreed;
237
+ },
238
+
239
+ template: `
240
+ <div>
241
+ <input #model="username" placeholder="Имя (мин. 3 символа)">
242
+ <input #model="email" placeholder="Email">
243
+ <label><input type="checkbox" #model="agreed"> Согласен</label>
244
+ <button disabled="{{ !isValid }}">Отправить</button>
245
+ <p #show="isValid" style="color:green">Форма валидна!</p>
246
+ </div>
247
+ `
248
+ });
249
+ ```
250
+
251
+ > **Геттеры — read-only.** Присваивание в геттер не сработает. Для хранения состояния используйте обычное свойство.
252
+
253
+ ---
254
+
255
+ ## Директивы шаблона
256
+
257
+ ### `{{ expr }}` — интерполяция
258
+
259
+ Вычисляет любое JS-выражение в контексте компонента (`this`). Поддерживается как в текстовых узлах, так и в значениях атрибутов.
260
+
261
+ ```html
262
+ <!-- Текстовый узел -->
263
+ <p>Привет, {{ user.name }}!</p>
264
+ <p>Итого: {{ items.length * price }}</p>
265
+ <p>{{ isActive ? 'Включено' : 'Выключено' }}</p>
266
+ <p>{{ JSON.stringify(data, null, 2) }}</p>
267
+
268
+ <!-- В значении атрибута -->
269
+ <div class="badge-{{ status }}"></div>
270
+ <div style="color: {{ score > 90 ? 'green' : 'red' }}"></div>
271
+ <img src="{{ baseUrl + '/images/' + filename }}">
272
+ ```
273
+
274
+ Если выражение вернёт `null` или `undefined` — выводится пустая строка.
275
+
276
+ > [!note] Порядок атрибутов не важен
277
+ > `#pre`, `#if` и `#for` обрабатываются раньше остальных атрибутов элемента, где бы они ни стояли. `<li class="{{ row.kind }}" #for="row in rows">` видит переменную цикла, `<b title="{{ x }}" #if="on">` связывается внутри ветки.
278
+
279
+ ---
280
+
281
+ ### `@event="statement"` — обработчики событий
282
+
283
+ Имя директивы — это имя DOM-события без `@`. Значение — JS-выражение (statement), выполняется в контексте компонента. Доступна переменная `$event` — нативный объект события.
284
+
285
+ ```html
286
+ <button @click="count++">+1</button>
287
+ <button @click="increment()">Метод</button>
288
+ <input @keyup="if ($event.key === 'Enter') submit()">
289
+ <form @submit="$event.preventDefault(); save()">
290
+ <div @mousemove="updatePosition($event)">
291
+ ```
292
+
293
+ **В циклах** `$index` и переменная цикла корректно захватываются замыканием:
294
+
295
+ ```html
296
+ <li #for="item in items">
297
+ <button @click="removeItem($index)">Удалить {{ item }}</button>
298
+ </li>
299
+ ```
300
+
301
+ **Модификатор `.self`** — обработчик срабатывает, только если событие отправлено самим элементом (`$event.target` — этот элемент), а не всплыло от потомков:
302
+
303
+ ```html
304
+ <!-- Только событие input, которое отправил сам компонент; нативный input из его полей не ловится -->
305
+ <st-app app="editor" @input.self="onEditorInput($event.detail)"></st-app>
306
+ ```
307
+
308
+ Вешая обработчик на вложенный `<st-app>`, помните: нативные события его полей (`input`, `change`, `click`) всплывают до него. Для событий компонента используйте `.self` или имя, которое не совпадает с нативным (`commit`, `editor:save`).
309
+
310
+ ---
311
+
312
+ ### `#if="cond"` / `#else-if="cond"` / `#else` — условный рендеринг
313
+
314
+ Элемент добавляется в DOM только при выполнении условия. При ложном условии — удаляется, подписки очищаются. При каждом повторном показе ветка собирается заново из исходной разметки: состояние полей ввода внутри неё не сохраняется (для этого есть `#show`). `#else-if` и `#else` должны идти на **непосредственном следующем** соседнем элементе.
315
+
316
+ ```html
317
+ <div #if="score >= 90">🌟 Отлично!</div>
318
+ <div #else-if="score >= 70">👍 Хорошо</div>
319
+ <div #else-if="score >= 50">⚠️ Удовлетворительно</div>
320
+ <div #else>❌ Плохо</div>
321
+ ```
322
+
323
+ ```html
324
+ <p #if="items.length === 0">Список пуст</p>
325
+ <ul #else>
326
+ <li #for="item in items">{{ item }}</li>
327
+ </ul>
328
+ ```
329
+
330
+ > **Отличие от `#show`:** при `#if` элемент физически удаляется из DOM. При `#show` — остаётся, но скрыт через `display: none`. Используйте `#if` когда нужно уничтожить дочерние компоненты; `#show` — когда нужна быстрая смена видимости.
331
+
332
+ ---
333
+
334
+ ### `#show="cond"` — видимость без удаления из DOM
335
+
336
+ ```html
337
+ <div #show="isLoading">⏳ Загрузка...</div>
338
+ <p #show="items.length > 0">Найдено {{ items.length }} элементов</p>
339
+ <small #show="error">{{ error }}</small>
340
+
341
+ <!-- Опциональная цепочка работает нормально: -->
342
+ <ul #show="availablePages?.length">...</ul>
343
+ ```
344
+
345
+ При `cond === false` устанавливает `style.display = 'none'`. При `true` — убирает этот стиль.
346
+
347
+ ---
348
+
349
+ ### `#class="{ 'имя': условие }"` — классы по условию
350
+
351
+ Ставит и снимает классы поверх статического `class` и `class="{{ }}"`:
352
+
353
+ ```html
354
+ <li class="item" #class="{ 'item--active': selected === row.id, 'item--muted item--small': row.hidden }">
355
+ <b #class="[loading && 'is-loading', size]"></b>
356
+ ```
357
+
358
+ - Объект: ключ — одно имя или несколько через пробел, значение — условие.
359
+ - Массив или строка: имена; ложные элементы массива пропускаются.
360
+ - Имена лежат в разметке литералами, поэтому их видит очистка неиспользуемого CSS. Склейка имени из частей (`'item--' + kind`) ей не видна.
361
+ - Не дублируйте в `#class` имя из статического `class`: при ложном условии оно снимется.
362
+
363
+ ---
364
+
365
+ ### `#for="item in collection"` — цикл
366
+
367
+ Работает с **массивами** и **объектами**.
368
+
369
+ #### Цикл по массиву
370
+
371
+ ```html
372
+ <ul>
373
+ <li #for="item in items">
374
+ {{ $index + 1 }}. {{ item }}
375
+ <button @click="items.splice($index, 1)">✕</button>
376
+ </li>
377
+ </ul>
378
+ ```
379
+
380
+ | Переменная | Значение |
381
+ |---|---|
382
+ | `item` | текущий элемент массива |
383
+ | `$index` | числовой индекс (0, 1, 2, …) |
384
+
385
+ #### Цикл по объекту
386
+
387
+ ```html
388
+ <ul>
389
+ <li #for="val in settings">{{ $key }}: {{ val }}</li>
390
+ </ul>
391
+ ```
392
+
393
+ | Переменная | Значение |
394
+ |---|---|
395
+ | `val` | значение свойства объекта |
396
+ | `$key` | строковый ключ свойства |
397
+ | `$index` | порядковый номер итерации |
398
+
399
+ #### Вложенные циклы
400
+
401
+ ```html
402
+ <div #for="group in groups">
403
+ <h3>{{ group.name }}</h3>
404
+ <ul>
405
+ <li #for="item in group.items">{{ item }}</li>
406
+ </ul>
407
+ </div>
408
+ ```
409
+
410
+ > **Переменная цикла изолирована.** После завершения `#for` переменная `item` удаляется. Если у компонента есть одноимённое свойство — оно восстанавливается.
411
+
412
+ #### Ключи: `#key`
413
+
414
+ Без ключа любое изменение коллекции пересоздаёт все строки: поля ввода теряют фокус и набранный текст. С `#key` строки с тем же ключом переиспользуются, создаются только новые, удаляются только пропавшие:
415
+
416
+ ```html
417
+ <li #for="row in rows" #key="row.id">
418
+ <input #model="row.name">
419
+ </li>
420
+ ```
421
+
422
+ Ключ должен быть уникален в пределах списка, на дубли выводится предупреждение.
423
+
424
+ Одного совпадения ключа мало: строка переиспользуется, только если элемент — **тот же объект**. Позиция не важна. Строка, сдвинутая `unshift`, `splice` или сортировкой, переносится вместе с узлами, полями, фокусом и вложенными `<st-app>`: она получает новые `$index` и путь к элементу, её привязки перезапускаются.
425
+
426
+ > [!warning] Коллекция из метода или геттера, который каждый раз строит новые объекты
427
+ > `#for="row in visible()"`, где `visible()` возвращает `rows.map(r => ({ ...r }))`, копию через JSON или заново полученные с сервера данные, на каждом проходе отдаёт новые объекты. Ключи совпадают, но строки пересоздаются целиком: теряются фокус и набранный текст, анимации и прокрутка внутри строк "прыгают".
428
+ >
429
+ > Перебирайте реактивный список из конфига и меняйте его на месте (правка полей, `push`, `splice`). Фильтруйте через `#show` или `#if` внутри строки, а не новым массивом копий. Если данные приходят с сервера, переносите новые значения в существующие объекты, а не заменяйте их.
430
+
431
+ #### Двусторонняя привязка внутри цикла
432
+
433
+ Работает в рамках реактивного объекта:
434
+
435
+ ```html
436
+ <li #for="todo in todos">
437
+ <input type="checkbox" #model="todo.done">
438
+ <span style="{{ todo.done ? 'text-decoration:line-through' : '' }}">{{ todo.text }}</span>
439
+ </li>
440
+ ```
441
+
442
+ ---
443
+
444
+ ### `#model="prop"` — двусторонняя привязка
445
+
446
+ Синхронизирует поле формы с реактивным свойством. Тип преобразования зависит от типа элемента:
447
+
448
+ | Элемент / тип | Событие | Значение |
449
+ |---|---|---|
450
+ | `<input>` (text, email, …) | `input` | `string` |
451
+ | `<input type="number">`, `<input type="range">` | `input` | `number` (через `valueAsNumber`); пустое поле — `null` |
452
+ | `<input type="checkbox">` | `input` | `boolean` (`checked`) |
453
+ | `<input type="radio">` | `input` | `string` (`value` выбранного) |
454
+ | `<select>` | `change` | `string` (текущий `value`) |
455
+ | `<textarea>` | `input` | `string` |
456
+
457
+ ```html
458
+ <!-- text -->
459
+ <input type="text" #model="username">
460
+
461
+ <!-- число — автоматически парсится в Number -->
462
+ <input type="number" #model="age">
463
+ <input type="range" #model="volume" min="0" max="100">
464
+
465
+ <!-- checkbox — boolean -->
466
+ <input type="checkbox" #model="agreed">
467
+
468
+ <!-- select -->
469
+ <select #model="country">
470
+ <option value="ru">Россия</option>
471
+ <option value="us">США</option>
472
+ </select>
473
+
474
+ <!-- поле вложенного объекта -->
475
+ <input type="text" #model="user.profile.name">
476
+ ```
477
+
478
+ `<select>` с опциями из `#for` работает: значение выставляется после отрисовки опций и сохраняется при их перерисовке.
479
+
480
+ ---
481
+
482
+ ### `:attr="value"` — атрибуты с привязкой
483
+
484
+ Атрибуты, начинающиеся с `:`, передают данные в компонент. Атрибут `:step` задаёт свойство `step`, kebab-case переводится в camelCase: `:initial-count` → `initialCount`. Писать `:initialCount` бесполезно: браузер приводит имена атрибутов к нижнему регистру.
485
+
486
+ Строка атрибута приводится к **типу значения из конфига**:
487
+
488
+ | Значение в конфиге | Строка атрибута становится |
489
+ |---|---|
490
+ | строка (`pin: ''`) | строкой как есть: `"0123"` → `'0123'`, `"true"` → `'true'` |
491
+ | число (`port: 0`) | `Number(...)`; нечисловая строка остаётся строкой |
492
+ | `boolean` (`open: false`) | `false` для `"false"`, `"0"`, `"null"`, `"undefined"`, иначе `true` |
493
+ | объект или массив | `JSON.parse(...)` |
494
+ | свойства нет в конфиге или там `null` | угадывается по виду: `"true"`/`"false"` → `boolean`, `"42"` → `number`, разбираемое JSON → объект, иначе строка |
495
+
496
+ Модификатор после точки задаёт приведение явно и перекрывает тип из конфига: `.string`, `.number`, `.boolean`, `.json`. Свойство называется по имени до точки.
497
+
498
+ ```html
499
+ <st-app app="settings" :pin="0123" :port="8080" :options.json='{"a":1}' :code.string="007"></st-app>
500
+ ```
501
+
502
+ **Пустое значение.** Пустой атрибут при монтировании берёт значение из конфига (см. ниже). Если атрибут стал пустым позже, например `:value="{{ draft }}"` при `draft = ''`, свойство получает `''`, а нестроковое свойство получает `null`.
503
+
504
+ #### `:attr` без значения — значение из прототипа
505
+
506
+ Если атрибут `:prop` при монтировании указан **без значения**, фреймворк берёт значение свойства `prop` из конфигурации `App.create()`. Объекты при этом сериализуются в JSON и синхронизируются двусторонне:
507
+
508
+ ```html
509
+ <!-- :options без значения — значение берётся из конфига App.create() -->
510
+ <st-app app="myApp" :options></st-app>
511
+ ```
512
+
513
+ ```js
514
+ App.create({
515
+ app: 'myApp',
516
+ options: { theme: 'dark', limit: 10 }, // ← этот объект будет подставлен
517
+ template: `
518
+ <input #model="options.theme">
519
+ <p>Атрибут :options синхронизирован: {{ JSON.stringify(options) }}</p>
520
+ `
521
+ });
522
+ ```
523
+
524
+ #### Реактивная передача данных от родителя к ребёнку
525
+
526
+ Самый важный паттерн для вложенных компонентов. Значение атрибута интерполируется через `{{ }}`:
527
+
528
+ ```html
529
+ <!-- В шаблоне родительского компонента -->
530
+ <st-app app="child" :count="{{ sharedCount }}" :name="{{ userName }}"></st-app>
531
+ ```
532
+
533
+ При изменении `sharedCount` в родителе атрибут `:count` на дочернем элементе обновляется автоматически, дочерний компонент получает новое значение.
534
+
535
+ ---
536
+
537
+ ### Boolean-атрибуты
538
+
539
+ Следующие атрибуты обрабатываются как булевы: при falsy-значении атрибут **удаляется** из DOM, при truthy — **добавляется** (со значением `""`):
540
+
541
+ ```
542
+ disabled, checked, readonly, required, selected, hidden, open, autofocus
543
+ ```
544
+
545
+ ```html
546
+ <!-- если isValid === false → атрибут disabled удалится из кнопки -->
547
+ <button disabled="{{ !isValid }}">Отправить</button>
548
+
549
+ <!-- если isRequired === true → добавится required="" -->
550
+ <input type="text" required="{{ isRequired }}">
551
+ ```
552
+
553
+ У `checked` и `selected` атрибут задаёт только начальное состояние: после клика пользователя браузер смотрит на свойство. Поэтому привязка выставляет и атрибут, и свойство (`input.checked`, `option.selected`), и флажок продолжает следовать данным после щелчков. То же для `value="{{ }}"` у `<input>`: после ввода поле показывает свойство `value`, и привязка обновляет его, когда меняются данные.
554
+
555
+ Привязка односторонняя. Если пользователь снял флажок, а данные не изменились, флажок останется снятым. Чтобы состояние и поле совпадали, используйте `#model` или меняйте данные в обработчике (`@change="on = $event.target.checked"`).
556
+
557
+ ---
558
+
559
+ ### `#html="expr"` — сырой HTML
560
+
561
+ Записывает результат выражения в `innerHTML` элемента. Директивы и `{{ }}` внутри вставленной разметки не обрабатываются.
562
+
563
+ ```html
564
+ <div #html="captchaWidget"></div>
565
+ ```
566
+
567
+ > [!warning]
568
+ > Только для доверенной разметки. Пользовательский ввод через `#html` — это XSS.
569
+
570
+ ---
571
+
572
+ ### `#once` — одноразовая обработка
573
+
574
+ Элемент обрабатывается единожды при первом рендеринге. Атрибут снимается, реактивных эффектов не создаётся:
575
+
576
+ ```html
577
+ <p #once>Этот текст никогда не обновится: {{ initialValue }}</p>
578
+ ```
579
+
580
+ ---
581
+
582
+ ### `#pre` — пропуск поддерева
583
+
584
+ Элемент и всё его содержимое пропускаются при обработке директив. Используется для встраивания `{{ }}` как буквального текста (например, в примерах кода):
585
+
586
+ ```html
587
+ <pre #pre>
588
+ Здесь {{ это }} не будет обработано как выражение
589
+ </pre>
590
+ ```
591
+
592
+ ---
593
+
594
+ ## Жизненный цикл компонента
595
+
596
+ ```
597
+ 1. <st-app> добавлен в DOM (connectedCallback)
598
+ ↓
599
+ Если <st-app> лежит внутри другого <st-app>, который ещё не взял шаблон, он ждёт:
600
+ родитель заберёт эту разметку в шаблон и создаст копии заново.
601
+ ↓
602
+ 2. #boot() — копирование конфига, оборачивание данных в Proxy
603
+ ↓
604
+ 3. Диспатч события 'setup' → вызов setup()
605
+ ↓
606
+ 4. Применение атрибутов `:attr` (разбор, типизация, создание реактивных свойств)
607
+ ↓
608
+ 5. Рендеринг шаблона (applyTemplate)
609
+ ↓
610
+ 6. Диспатч события 'rendered'
611
+ ↓
612
+ 7. MutationObserver следит за изменениями атрибутов `:*`
613
+ ```
614
+
615
+ ```
616
+ 8. <st-app> удалён из DOM (disconnectedCallback)
617
+ ↓
618
+ Очистка откладывается на микрозадачу. Если элемент к этому моменту снова
619
+ в DOM (перенос в другой контейнер, в Modal), ничего не снимается.
620
+ ↓
621
+ Иначе — очистка всех эффектов, подписок, слушателей событий
622
+ ↓
623
+ 9. Возврат в DOM после очистки — шаблон собирается заново.
624
+ Подписки watch() из setup() не восстанавливаются: setup() повторно не вызывается.
625
+ ```
626
+
627
+ ### setup()
628
+
629
+ `setup()` — правильное место для:
630
+ - вызовов `this.watch()`
631
+ - инициализации данных на основе переданных атрибутов
632
+ - первичного вызова `this.applyTemplate()`
633
+
634
+ ```js
635
+ App.create({
636
+ app: 'myApp',
637
+ items: [],
638
+
639
+ async setup() {
640
+ // данные из :attr уже доступны здесь
641
+ this.items = await fetch('/api/items').then(r => r.json());
642
+
643
+ this.watch('items', (newVal) => {
644
+ console.log('items changed:', newVal.length);
645
+ });
646
+ },
647
+
648
+ template: `<ul><li #for="item in items">{{ item.name }}</li></ul>`
649
+ });
650
+ ```
651
+
652
+ ---
653
+
654
+ ## watch() — наблюдатель изменений
655
+
656
+ ```js
657
+ let unwatch = this.watch(source, callback, options?)
658
+ ```
659
+
660
+ | Параметр | Описание |
661
+ |---|---|
662
+ | `source` | Что наблюдать (см. варианты ниже) |
663
+ | `callback(newVal, oldVal, unwatch)` | Вызывается при изменении; третий аргумент `unwatch()` — остановить наблюдение |
664
+ | `options.immediate` | `boolean` — вызвать `callback` сразу при подписке |
665
+ | `options.deep` | `boolean` — глубокое наблюдение за объектом/массивом |
666
+
667
+ Возвращаемое значение — функция `unwatch()`, вызов которой снимает подписку.
668
+
669
+ ### Варианты `source`
670
+
671
+ #### Строка — имя свойства
672
+
673
+ ```js
674
+ this.watch('count', (newVal, oldVal, unwatch) => {
675
+ console.log(`count: ${oldVal} → ${newVal}`);
676
+
677
+ // автоматически отменить наблюдение при достижении 10
678
+ if (newVal >= 10) unwatch();
679
+ }, { immediate: true }); // ← вызвать callback сразу
680
+ ```
681
+
682
+ #### Строка — путь к вложенному свойству
683
+
684
+ ```js
685
+ this.watch('user.name', (newVal) => {
686
+ console.log('Имя изменилось:', newVal);
687
+ });
688
+ ```
689
+
690
+ #### Строка — глубокое наблюдение за объектом
691
+
692
+ ```js
693
+ this.watch('user', (newVal, oldVal) => {
694
+ // вызывается при изменении любого вложенного свойства
695
+ console.log('Объект user изменился');
696
+ }, { deep: true });
697
+ ```
698
+
699
+ #### Строка `'method()'` — перехват вызова метода
700
+
701
+ ```js
702
+ this.watch('save()', (args, result, unwatch) => {
703
+ console.log('save() вызван с аргументами:', args);
704
+ console.log('Вернул:', result);
705
+ });
706
+ ```
707
+
708
+ > `callback` при перехвате метода получает: `args` — массив аргументов, `result` — возвращённое значение (или Promise).
709
+
710
+ #### Функция-геттер
711
+
712
+ Автоматически отслеживает использованные реактивные свойства:
713
+
714
+ ```js
715
+ this.watch(
716
+ () => this.firstName + ' ' + this.lastName, // ← геттер-вычисление
717
+ (newFullName, oldFullName) => {
718
+ console.log('ФИО изменилось:', newFullName);
719
+ }
720
+ );
721
+ ```
722
+
723
+ ### Полный пример watch()
724
+
725
+ ```js
726
+ App.create({
727
+ app: 'watchDemo',
728
+ count: 0,
729
+ user: { name: 'Гость', role: 'user' },
730
+ firstName: 'Иван',
731
+ lastName: 'Петров',
732
+
733
+ setup() {
734
+ // 1. Наблюдение за примитивом, автостоп при 5
735
+ this.watch('count', (newVal, oldVal, unwatch) => {
736
+ console.log('[count]', oldVal, '->', newVal);
737
+ if (newVal >= 5) unwatch();
738
+ }, { immediate: true });
739
+
740
+ // 2. Глубокое наблюдение за объектом
741
+ this.watch('user', (n) => console.log('[user deep]', n), { deep: true });
742
+
743
+ // 3. Путь к вложенному свойству
744
+ this.watch('user.name', (n) => console.log('[user.name]', n));
745
+
746
+ // 4. Функция-геттер
747
+ this.watch(
748
+ () => this.firstName + ' ' + this.lastName,
749
+ (v) => console.log('[fullName]', v)
750
+ );
751
+
752
+ // 5. Перехват метода
753
+ this.watch('save()', (args, result) => console.log('[save()]', result));
754
+ },
755
+
756
+ save() { return { ok: true, ts: Date.now() }; },
757
+
758
+ template: `
759
+ <div>
760
+ <button @click="count++">count: {{ count }}</button>
761
+ <input #model="user.name">
762
+ <input #model="firstName"> <input #model="lastName">
763
+ <button @click="save()">save()</button>
764
+ </div>
765
+ `
766
+ });
767
+ ```
768
+
769
+ ---
770
+
771
+ ## applyTemplate() — переключение шаблонов
772
+
773
+ ```js
774
+ this.applyTemplate(html?)
775
+ ```
776
+
777
+ - `applyTemplate(htmlStr)` — применяет переданный HTML как шаблон. Старые эффекты и слушатели очищаются. **Базовый шаблон при этом не меняется.**
778
+ - `applyTemplate()` (без аргументов) — возвращается к базовому шаблону из `App.create()`.
779
+
780
+ Реактивные данные (`this.count`, `this.name`, и т.д.) **сохраняются** при любом переключении шаблона.
781
+
782
+ ```js
783
+ const TMPL_LOADING = `
784
+ <div style="text-align:center;padding:48px;">
785
+ <p>⏳ Загрузка...</p>
786
+ </div>`;
787
+
788
+ const TMPL_SETTINGS = `
789
+ <div>
790
+ <h3>⚙️ Настройки</h3>
791
+ <label>Имя: <input #model="name"></label>
792
+ <button @click="applyTemplate()">← Назад</button>
793
+ </div>`;
794
+
795
+ App.create({
796
+ app: 'app',
797
+ name: 'Пользователь',
798
+
799
+ setup() {
800
+ // Показать экран загрузки, затем вернуться к основному
801
+ this.applyTemplate(TMPL_LOADING);
802
+ setTimeout(() => this.applyTemplate(), 1500);
803
+ },
804
+
805
+ template: `
806
+ <div>
807
+ <h3>🏠 Главный экран</h3>
808
+ <p>Привет, {{ name }}!</p>
809
+ <button @click="applyTemplate(TMPL_SETTINGS)">⚙️ Настройки</button>
810
+ </div>
811
+ `
812
+ });
813
+ ```
814
+
815
+ ---
816
+
817
+ ## Вложенные компоненты
818
+
819
+ `<st-app>` можно вкладывать внутрь другого `<st-app>`: в строку `template` или в разметку родителя, которую он берёт шаблоном, в том числе внутрь `#for`. Вложенный компонент не отрисовывается, пока родитель не взял шаблон, поэтому каждая копия собирается из исходной разметки. Данные передаются через атрибуты `:attr`, события — через `dispatchEvent` и `@имя.self` (см. `@event`).
820
+
821
+ ### Передача данных через `:attr="{{ expr }}"`
822
+
823
+ ```js
824
+ // Родитель
825
+ App.create({
826
+ app: 'parent',
827
+ sharedCount: 0,
828
+ userName: 'Пользователь',
829
+
830
+ template: `
831
+ <div>
832
+ <p>Родитель: {{ sharedCount }}</p>
833
+ <button @click="sharedCount++">+1</button>
834
+ <input #model="userName">
835
+
836
+ <!-- Передача реактивных значений дочернему компоненту -->
837
+ <st-app app="child"
838
+ :count="{{ sharedCount }}"
839
+ :name="{{ userName }}">
840
+ </st-app>
841
+ </div>
842
+ `
843
+ });
844
+
845
+ // Дочерний
846
+ App.create({
847
+ app: 'child',
848
+ count: 0, // будет перезаписано из :count
849
+ name: '', // будет перезаписано из :name
850
+
851
+ template: `
852
+ <div style="border: 1px solid #ccc; padding: 10px; margin-top: 10px;">
853
+ <p>Дочерний получил: count={{ count }}, name={{ name }}</p>
854
+ </div>
855
+ `
856
+ });
857
+ ```
858
+
859
+ При изменении `sharedCount` или `userName` в родителе дочерний компонент автоматически получает новые значения.
860
+
861
+ ### Трёхуровневая вложенность
862
+
863
+ ```html
864
+ <!-- grandparent → parent2 → grandchild -->
865
+ <st-app app="grandparent"></st-app>
866
+ ```
867
+
868
+ ```js
869
+ App.create({
870
+ app: 'grandparent', data: 42,
871
+ template: `
872
+ <div>
873
+ <button @click="data = Math.random() * 100 | 0">🎲</button>
874
+ <st-app app="parent2" :data="{{ data }}"></st-app>
875
+ </div>
876
+ `
877
+ });
878
+
879
+ App.create({
880
+ app: 'parent2', data: 0,
881
+ template: `<st-app app="grandchild" :data="{{ data }}"></st-app>`
882
+ });
883
+
884
+ App.create({
885
+ app: 'grandchild', data: 0,
886
+ template: `<p>Финальные данные: <strong>{{ data }}</strong></p>`
887
+ });
888
+ ```
889
+
890
+ ---
891
+
892
+ ## innerHTML как шаблон
893
+
894
+ Если `template: ''` (или `template` не задан), а у элемента `<st-app>` есть содержимое — оно будет использовано как шаблон:
895
+
896
+ ```html
897
+ <st-app app="inlineTemplate">
898
+ <div>
899
+ <h3>{{ title }}</h3>
900
+ <input type="text" #model="message">
901
+ <p>{{ message }}</p>
902
+ </div>
903
+ </st-app>
904
+ ```
905
+
906
+ ```js
907
+ App.create({
908
+ app: 'inlineTemplate',
909
+ title: 'Заголовок',
910
+ message: 'Привет!',
911
+ template: '' // ← пустой шаблон → берётся innerHTML
912
+ });
913
+ ```
914
+
915
+ Также работает без `App.create()` совсем — тогда атрибуты `:attr` задают данные напрямую:
916
+
917
+ ```html
918
+ <!-- Без App.create() — данные через атрибуты, шаблон из innerHTML -->
919
+ <st-app :name="Иван" :count="5">
920
+ <p>{{ name }}: {{ count }}</p>
921
+ <button @click="count++">+1</button>
922
+ </st-app>
923
+ ```
924
+
925
+ ---
926
+
927
+ ## Публичный API экземпляра
928
+
929
+ ### `this.watch(source, callback, options?)` — подробно описан выше
930
+
931
+ ### `this.applyTemplate(html?)` — подробно описан выше
932
+
933
+ ### `this.nextTick()`
934
+
935
+ Обновление DOM асинхронное: изменения копятся и применяются в микрозадаче. `nextTick()` возвращает промис, который разрешается, когда эффекты и колбэки `watch()` отработали и DOM соответствует данным:
936
+
937
+ ```js
938
+ app.count = 5;
939
+ await app.nextTick();
940
+ app.querySelector('p').textContent; // '5'
941
+ ```
942
+
943
+ Первую отрисовку компонента и вложенных `<st-app>` он не ждёт. Для неё есть событие `rendered`: подписка после отрисовки срабатывает сразу.
944
+
945
+ ### `this.clone(options?)`
946
+
947
+ Создаёт копию компонента через `App.extend()`, используя `app` из текущего атрибута `app`:
948
+
949
+ ```js
950
+ // Внутри метода компонента:
951
+ this.clone({ label: 'Клон', count: 999 });
952
+ ```
953
+
954
+ ### `this.unwatch()`
955
+
956
+ Снимает **все** активные наблюдатели, установленные через `watch()` на данном экземпляре — key-подписки, getter-эффекты и перехваты методов. Перехваченные методы восстанавливаются к своим оригинальным реализациям.
957
+
958
+ ```js
959
+ setup() {
960
+ this.watch('count', (n) => console.log('count:', n));
961
+ this.watch('user', (n) => console.log('user:', n), { deep: true });
962
+ this.watch('save()', (args, result) => console.log('saved:', result));
963
+
964
+ // ... позже снять сразу все:
965
+ this.unwatch();
966
+ }
967
+ ```
968
+
969
+ > **Отличие от `unwatch()`, возвращаемой `watch()`:** вызов отдельной функции `unwatch` снимает одну конкретную подписку. `this.unwatch()` снимает сразу все.
970
+
971
+ ### `this.hasWatchers()`
972
+
973
+ Возвращает `number` — суммарное количество активных наблюдателей (key-подписки + getter-подписки + перехваты методов). Полезно для отладки и условной проверки.
974
+
975
+ ```js
976
+ setup() {
977
+ this.watch('count', () => {});
978
+ this.watch('name', () => {});
979
+ this.watch('save()', () => {});
980
+
981
+ console.log(this.hasWatchers()); // 3
982
+
983
+ this.unwatch();
984
+ console.log(this.hasWatchers()); // 0
985
+ }
986
+ ```
987
+
988
+ ### `this.watched(source, callback, options?)`
989
+
990
+ Комбинированный метод «заменить подписку»: сначала снимает все существующие подписки для указанного `source`, затем добавляет новую. Сигнатура и варианты `source` идентичны `watch()`.
991
+
992
+ Полезен при повторной инициализации — не допускает дублирования наблюдателей:
993
+
994
+ ```js
995
+ // Обычный watch — при повторном вызове добавляет вторую подписку
996
+ this.watch('count', handlerA);
997
+ this.watch('count', handlerB); // теперь оба активны
998
+
999
+ // watched — автоматически снимает предыдущую перед добавлением
1000
+ this.watched('count', handlerA);
1001
+ this.watched('count', handlerB); // handlerA снят, активен только handlerB
1002
+ ```
1003
+
1004
+ ```js
1005
+ // Поддерживаются все варианты source:
1006
+ this.watched('prop', callback);
1007
+ this.watched('obj.nested', callback, { deep: true });
1008
+ this.watched(() => this.a + this.b, callback);
1009
+ this.watched('method()', (args, result) => { ... });
1010
+ ```
1011
+
1012
+ ### `this.dispatchEvent(event, detail?, options?)`
1013
+
1014
+ Переопределённый `dispatchEvent`. Если первый аргумент — строка, создаёт и диспатчит `CustomEvent` (по умолчанию не всплывает, `cancelable: true`). Если передан готовый объект `Event` — диспатчит его напрямую. Возвращает `boolean` (результат нативного `dispatchEvent`).
1015
+
1016
+ ```js
1017
+ let ok = this.dispatchEvent('my-event', { value: 42 }, { bubbles: true });
1018
+ if (ok) {
1019
+ // событие не было отменено через preventDefault()
1020
+ }
1021
+ ```
1022
+
1023
+ ```js
1024
+ // Подписка слушателя:
1025
+ document.querySelector('st-app').addEventListener('my-event', e => {
1026
+ console.log(e.detail.value); // 42
1027
+ });
1028
+ ```
1029
+
1030
+ ### `this.attrs` — объект для работы с атрибутами
1031
+
1032
+ | Метод | Описание |
1033
+ |---|---|
1034
+ | `this.attrs.get(name)` | `getAttribute(name)` |
1035
+ | `this.attrs.set(name, value)` | `setAttribute(name, value)` |
1036
+ | `this.attrs.remove(name)` | `removeAttribute(name)` |
1037
+ | `this.attrs.has(name)` | `hasAttribute(name)` |
1038
+ | `this.attrs.toggle(name, force?)` | переключить атрибут |
1039
+ | `this.attrs.keys()` | массив имён всех атрибутов |
1040
+ | `this.attrs.entries()` | массив пар `[name, value]` |
1041
+
1042
+ ```js
1043
+ setup() {
1044
+ // Чтение произвольных атрибутов, заданных на <st-app>
1045
+ let mode = this.attrs.get('data-mode') || 'default';
1046
+ }
1047
+ ```
1048
+
1049
+ ### `this.template` — геттер базового шаблона
1050
+
1051
+ Возвращает строку базового шаблона, установленного при инициализации:
1052
+
1053
+ ```js
1054
+ let baseHtml = this.template;
1055
+ ```
1056
+
1057
+ ### `this.cycleAttribute(name, value1?, value2?)`
1058
+
1059
+ Переключает атрибут между `value1` и `value2`. Без значений — переключает наличие атрибута:
1060
+
1061
+ ```js
1062
+ this.cycleAttribute('data-mode', 'dark', 'light');
1063
+ this.cycleAttribute('hidden');
1064
+ ```
1065
+
1066
+ `toggleAttribute(name, force?)` работает по стандарту: `el.toggleAttribute('hidden', false)` снимает атрибут. Вызов со строковыми значениями (`toggleAttribute('data-mode', 'dark', 'light')`) оставлен для совместимости и передаётся в `cycleAttribute`.
1067
+
1068
+ ---
1069
+
1070
+ ## Подводные камни
1071
+
1072
+ - **Шаблон и CSP.** Выражения компилируются через `new Function` и `with`, поэтому странице нужен `script-src 'unsafe-eval'`. Со строгим CSP `App` не работает.
1073
+ - **Реактивны только поля конфига.** Свойство, которого нет в `App.create()` (`this.loaded = true` в `setup()`), шаблон прочитает, но при изменении не перерисует. При первом чтении такого свойства из шаблона в консоль выводится предупреждение. Объявите поле в конфиге (`loaded: false`). Для вычисляемого состояния используйте геттер или `watch(() => выражение, cb)`.
1074
+ - **Ожидание перерисовки.** После изменения данных DOM ещё старый. Перед проверкой DOM вызовите `await this.nextTick()`.
1075
+ - **Имена переменных шаблона.** Выражения видят свойства компонента, в том числе унаследованные от `HTMLElement`: `id`, `title`, `hidden`, `children`, `dataset`, `remove()`, `append()`. Свойство конфига с таким именем перекрывает родное. А чтение неописанного в конфиге `title` вернёт атрибут элемента, а не `undefined`.
1076
+ - **Сравнение по ссылке.** Вложенные объекты отдаются через `Proxy`. Для одного и того же пути прокси один, поэтому `items.indexOf(item)` внутри шаблона и методов работает. Сравнивать прокси с исходным объектом, переданным в конфиг, бесполезно: это разные ссылки. Исходник даёт `App.toRaw(value)`, копию без прокси — `App.snapshot(value)`.
1077
+ - **Методы в шаблоне.** Вызов метода из `{{ }}` или атрибута ничего не перерисовывает. Вызов из обработчика события или из кода перерисовывает выражения, которые этот метод читают. Состояние, от которого зависит результат, держите в реактивных полях.
1078
+ - **`#if` пересоздаёт ветку.** Набранный текст и фокус внутри скрытой ветки теряются. Чтобы их сохранить, используйте `#show`.
1079
+ - **Поле, которое само выключает свой `#if`.** Если условие ветки зависит от значения, которое правит поле внутри неё (`<textarea #if="!text || editing" #model="text">`), то на первом символе ветка пропадает и поле теряет фокус. Обработчики этого же события (`@input` на поле и на предках внутри ветки) всё равно вызываются, но вернувшаяся ветка — уже новое поле без фокуса. Флаг ставьте раньше, до изменения значения (`@focus="editing = true"` или `@beforeinput`), или используйте `#show`.
1080
+ - **Списки с полями ввода — с `#key`.** Без ключа добавление строки пересоздаёт весь список. Ключ сохраняет строку, пока элемент — тот же объект, даже если строка сместилась. Метод, который каждый раз возвращает копии, пересоздаёт строки и с ключом (см. "Ключи: `#key`").
1081
+ - **Долгое отключение.** Если `<st-app>` вынули из DOM и вернули в другой задаче, шаблон собирается заново, а подписки `watch()` из `setup()` пропадают. Перенос в той же задаче (`append` в другой контейнер, в `Modal`) безопасен.
1082
+
1083
+ ---
1084
+
1085
+ ## Комплексные примеры
1086
+
1087
+ ### Todo-список
1088
+
1089
+ ```js
1090
+ App.create({
1091
+ app: 'todo',
1092
+ todos: [
1093
+ { id: 1, text: 'Изучить фреймворк', done: true },
1094
+ { id: 2, text: 'Создать приложение', done: false }
1095
+ ],
1096
+ newTodo: '',
1097
+ filter: 'all',
1098
+
1099
+ get filteredTodos() {
1100
+ if (this.filter === 'active') return this.todos.filter(t => !t.done);
1101
+ if (this.filter === 'completed') return this.todos.filter(t => t.done);
1102
+ return this.todos;
1103
+ },
1104
+
1105
+ get stats() {
1106
+ return {
1107
+ total: this.todos.length,
1108
+ active: this.todos.filter(t => !t.done).length,
1109
+ completed: this.todos.filter(t => t.done).length
1110
+ };
1111
+ },
1112
+
1113
+ addTodo() {
1114
+ if (!this.newTodo.trim()) return;
1115
+ this.todos.push({ id: Date.now(), text: this.newTodo.trim(), done: false });
1116
+ this.newTodo = '';
1117
+ },
1118
+
1119
+ removeTodo(id) {
1120
+ let idx = this.todos.findIndex(t => t.id === id);
1121
+ if (idx !== -1) this.todos.splice(idx, 1);
1122
+ },
1123
+
1124
+ clearCompleted() {
1125
+ this.todos = this.todos.filter(t => !t.done);
1126
+ },
1127
+
1128
+ template: `
1129
+ <div>
1130
+ <input #model="newTodo" placeholder="Что сделать?"
1131
+ @keyup="if ($event.key === 'Enter') addTodo()">
1132
+ <button @click="addTodo()">➕ Добавить</button>
1133
+
1134
+ <div style="margin: 10px 0;">
1135
+ <button @click="filter = 'all'">Все ({{ stats.total }})</button>
1136
+ <button @click="filter = 'active'">Активные ({{ stats.active }})</button>
1137
+ <button @click="filter = 'completed'">Завершённые ({{ stats.completed }})</button>
1138
+ </div>
1139
+
1140
+ <ul>
1141
+ <li #for="todo in filteredTodos"
1142
+ style="display:flex;align-items:center;gap:10px;">
1143
+ <input type="checkbox" #model="todo.done">
1144
+ <span style="{{ todo.done ? 'text-decoration:line-through;color:#999' : '' }}">
1145
+ {{ todo.text }}
1146
+ </span>
1147
+ <button @click="removeTodo(todo.id)">🗑️</button>
1148
+ </li>
1149
+ </ul>
1150
+
1151
+ <p #show="filteredTodos.length === 0" style="color:#999;">Задач нет</p>
1152
+ <button #show="stats.completed > 0" @click="clearCompleted()">
1153
+ Очистить завершённые
1154
+ </button>
1155
+ </div>
1156
+ `
1157
+ });
1158
+ ```
1159
+
1160
+ ### Вложенные реактивные объекты
1161
+
1162
+ ```js
1163
+ App.create({
1164
+ app: 'nested',
1165
+ user: {
1166
+ profile: { name: 'Иван', age: 25 },
1167
+ settings: { theme: 'dark', notifications: true }
1168
+ },
1169
+
1170
+ toggleTheme() {
1171
+ this.user.settings.theme =
1172
+ this.user.settings.theme === 'dark' ? 'light' : 'dark';
1173
+ },
1174
+
1175
+ template: `
1176
+ <div>
1177
+ <input #model="user.profile.name">
1178
+ <input type="number" #model="user.profile.age">
1179
+ <input type="checkbox" #model="user.settings.notifications">
1180
+ <button @click="toggleTheme()">Тема: {{ user.settings.theme }}</button>
1181
+ <pre>{{ JSON.stringify(user, null, 2) }}</pre>
1182
+ </div>
1183
+ `
1184
+ });
1185
+ ```
1186
+
1187
+ ### applyTemplate — многоэкранный интерфейс
1188
+
1189
+ ```js
1190
+ const TMPL_LOADING = `<div style="text-align:center;padding:48px;">⏳ Загрузка...</div>`;
1191
+ const TMPL_SETTINGS = `
1192
+ <div>
1193
+ <h3>⚙️ Настройки</h3>
1194
+ <label>Имя: <input #model="name"></label>
1195
+ <select #model="theme">
1196
+ <option value="light">Светлая</option>
1197
+ <option value="dark">Тёмная</option>
1198
+ </select>
1199
+ <button @click="applyTemplate()">← Назад</button>
1200
+ </div>`;
1201
+
1202
+ App.create({
1203
+ app: 'screens',
1204
+ name: 'Пользователь',
1205
+ theme: 'light',
1206
+ counter: 0,
1207
+
1208
+ setup() {
1209
+ this.applyTemplate(TMPL_LOADING);
1210
+ setTimeout(() => this.applyTemplate(), 1500);
1211
+ },
1212
+
1213
+ template: `
1214
+ <div>
1215
+ <h3>🏠 Главный экран</h3>
1216
+ <p>Привет, {{ name }}! Счётчик: {{ counter }}</p>
1217
+ <button @click="counter++">+1</button>
1218
+ <button @click="applyTemplate(TMPL_SETTINGS)">⚙️ Настройки</button>
1219
+ <button @click="applyTemplate(TMPL_LOADING); setTimeout(() => applyTemplate(), 1500)">
1220
+ 🔄 Перезагрузить
1221
+ </button>
1222
+ </div>
1223
+ `
1224
+ });
1225
+ ```
1226
+
1227
+ ---
1228
+
1229
+ ## Быстрая шпаргалка
1230
+
1231
+ ```html
1232
+ <!-- Монтирование -->
1233
+ <st-app app="myApp"></st-app>
1234
+ <st-app app="myApp" :prop="value" :number="42" :flag="true"></st-app>
1235
+
1236
+ <!-- Интерполяция -->
1237
+ {{ expression }}
1238
+ {{ user.name }} {{ count * 2 }} {{ isOk ? 'да' : 'нет' }}
1239
+
1240
+ <!-- Условия -->
1241
+ <div #if="a">A</div>
1242
+ <div #else-if="b">B</div>
1243
+ <div #else>C</div>
1244
+
1245
+ <!-- Цикл по массиву -->
1246
+ <li #for="item in items">{{ $index }}: {{ item }}</li>
1247
+
1248
+ <!-- Цикл с ключом: строки переиспользуются -->
1249
+ <li #for="row in rows" #key="row.id"><input #model="row.name"></li>
1250
+
1251
+ <!-- Цикл по объекту -->
1252
+ <li #for="val in obj">{{ $key }}: {{ val }}</li>
1253
+
1254
+ <!-- Видимость -->
1255
+ <p #show="isVisible">текст</p>
1256
+
1257
+ <!-- Двусторонняя привязка -->
1258
+ <input #model="name">
1259
+ <input type="checkbox" #model="agreed">
1260
+ <input type="number" #model="age">
1261
+ <select #model="country">...</select>
1262
+
1263
+ <!-- События -->
1264
+ <button @click="count++">+</button>
1265
+ <button @click="doSomething()">действие</button>
1266
+ <input @keyup="if ($event.key === 'Enter') submit()">
1267
+
1268
+ <!-- Реактивный атрибут (с интерполяцией) -->
1269
+ <div class="item-{{ status }}"></div>
1270
+ <button disabled="{{ !isValid }}">Отправить</button>
1271
+
1272
+ <!-- Передача данных дочернему компоненту -->
1273
+ <st-app app="child" :value="{{ parentData }}"></st-app>
1274
+
1275
+ <!-- Сырой HTML (только доверенный) -->
1276
+ <div #html="trustedHtml"></div>
1277
+
1278
+ <!-- Пропустить поддерево -->
1279
+ <pre #pre>{{ не будет обработано }}</pre>
1280
+ ```
1281
+
1282
+ ```js
1283
+ // Регистрация
1284
+ App.create({ app: 'id', prop: val, method() {}, get computed() {}, template: `...` });
1285
+ App.extend('base', { app: 'derived', ...overrides });
1286
+
1287
+ // В setup() / методах:
1288
+ this.watch('prop', (n, o, unwatch) => { ... }, { immediate: true, deep: false });
1289
+ this.watch('prop.nested', callback);
1290
+ this.watch(() => this.a + this.b, callback);
1291
+ this.watch('method()', (args, result, unwatch) => { ... });
1292
+
1293
+ this.applyTemplate(htmlString); // переключить шаблон
1294
+ this.applyTemplate(); // вернуться к базовому
1295
+
1296
+ this.dispatchEvent('my-event', detail, { bubbles: true });
1297
+ this.clone({ ...overrides });
1298
+ this.unwatch(); // снять все подписки
1299
+ this.hasWatchers(); // число активных наблюдателей
1300
+ this.watched('prop', callback); // заменить подписку (без дублей)
1301
+ this.attrs.get('name');
1302
+ ```