@cat-of-summer/st-script 1.4.2 → 1.6.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 (127) hide show
  1. package/README.md +1 -1
  2. package/dist/app/datepicker.min.js +3 -3
  3. package/dist/app/datepicker.min.js.map +3 -3
  4. package/dist/app/form.min.js +1 -1
  5. package/dist/app/form.min.js.map +3 -3
  6. package/dist/app.esm.min.js +1 -1
  7. package/dist/app.esm.min.js.map +3 -3
  8. package/dist/app.min.js +1 -1
  9. package/dist/app.min.js.map +3 -3
  10. package/dist/core.esm.min.js +1 -1
  11. package/dist/core.esm.min.js.map +3 -3
  12. package/dist/core.min.js +1 -1
  13. package/dist/core.min.js.map +3 -3
  14. package/dist/loader.esm.min.js +1 -1
  15. package/dist/loader.esm.min.js.map +3 -3
  16. package/dist/loader.min.js +1 -1
  17. package/dist/loader.min.js.map +3 -3
  18. package/dist/mask.esm.min.js +1 -1
  19. package/dist/mask.esm.min.js.map +3 -3
  20. package/dist/mask.min.js +1 -1
  21. package/dist/mask.min.js.map +3 -3
  22. package/dist/modal.esm.min.js +1 -1
  23. package/dist/modal.esm.min.js.map +3 -3
  24. package/dist/modal.min.js +1 -1
  25. package/dist/modal.min.js.map +3 -3
  26. package/dist/observer.esm.min.js +1 -1
  27. package/dist/observer.esm.min.js.map +3 -3
  28. package/dist/observer.min.js +1 -1
  29. package/dist/observer.min.js.map +3 -3
  30. package/dist/route.esm.min.js.map +2 -2
  31. package/dist/route.min.js +1 -1
  32. package/dist/route.min.js.map +2 -2
  33. package/dist/select.esm.min.js +1 -1
  34. package/dist/select.esm.min.js.map +3 -3
  35. package/dist/select.min.js +1 -1
  36. package/dist/select.min.js.map +3 -3
  37. package/dist/shape.esm.min.js +2 -0
  38. package/dist/shape.esm.min.js.map +7 -0
  39. package/dist/shape.min.js +2 -0
  40. package/dist/shape.min.js.map +7 -0
  41. package/dist/toggle.esm.min.js +1 -1
  42. package/dist/toggle.esm.min.js.map +3 -3
  43. package/dist/toggle.min.js +1 -1
  44. package/dist/toggle.min.js.map +3 -3
  45. package/dist/typograf.esm.min.js +1 -1
  46. package/dist/typograf.esm.min.js.map +3 -3
  47. package/dist/typograf.min.js +1 -1
  48. package/dist/typograf.min.js.map +3 -3
  49. package/dist/uploader.esm.min.js +1 -1
  50. package/dist/uploader.esm.min.js.map +3 -3
  51. package/dist/uploader.min.js +1 -1
  52. package/dist/uploader.min.js.map +3 -3
  53. package/dist/validator.esm.min.js +1 -1
  54. package/dist/validator.esm.min.js.map +3 -3
  55. package/dist/validator.min.js +1 -1
  56. package/dist/validator.min.js.map +3 -3
  57. package/docs/README.md +90 -0
  58. package/docs/src/README.md +29 -0
  59. package/docs/src/_traits/README.md +8 -0
  60. package/docs/src/_traits/hasInstanceSymbol.js.md +57 -0
  61. package/docs/src/app/README.md +13 -0
  62. package/docs/src/app/datepicker/README.md +9 -0
  63. package/docs/src/app/datepicker/_calendar.js.md +1 -0
  64. package/docs/src/app/datepicker/index.js.md +153 -0
  65. package/docs/src/app/form/README.md +8 -0
  66. package/docs/src/app/form/index.js.md +560 -0
  67. package/docs/src/app/index.js.md +1386 -0
  68. package/docs/src/cookie/README.md +8 -0
  69. package/docs/src/cookie/index.js.md +80 -0
  70. package/docs/src/core/README.md +8 -0
  71. package/docs/src/core/index.js.md +224 -0
  72. package/docs/src/index.js.md +1 -0
  73. package/docs/src/loader/README.md +8 -0
  74. package/docs/src/loader/index.js.md +126 -0
  75. package/docs/src/mask/README.md +10 -0
  76. package/docs/src/mask/_engine.js.md +1 -0
  77. package/docs/src/mask/_groups.js.md +1 -0
  78. package/docs/src/mask/index.js.md +412 -0
  79. package/docs/src/modal/README.md +8 -0
  80. package/docs/src/modal/index.js.md +821 -0
  81. package/docs/src/observer/README.md +9 -0
  82. package/docs/src/observer/_engine.js.md +28 -0
  83. package/docs/src/observer/index.js.md +259 -0
  84. package/docs/src/route/README.md +8 -0
  85. package/docs/src/route/index.js.md +385 -0
  86. package/docs/src/select/README.md +8 -0
  87. package/docs/src/select/index.js.md +115 -0
  88. package/docs/src/shape/README.md +9 -0
  89. package/docs/src/shape/_engine.js.md +1 -0
  90. package/docs/src/shape/index.js.md +99 -0
  91. package/docs/src/st_button_widget/README.md +9 -0
  92. package/docs/src/st_button_widget/README.txt.md +4 -0
  93. package/docs/src/st_button_widget/index.js.md +68 -0
  94. package/docs/src/st_links_widget/README.md +9 -0
  95. package/docs/src/st_links_widget/README.txt.md +4 -0
  96. package/docs/src/st_links_widget/index.js.md +46 -0
  97. package/docs/src/st_widget/README.md +8 -0
  98. package/docs/src/st_widget/button/README.md +4 -0
  99. package/docs/src/toggle/README.md +8 -0
  100. package/docs/src/toggle/index.js.md +604 -0
  101. package/docs/src/typograf/README.md +9 -0
  102. package/docs/src/typograf/_engine.js.md +75 -0
  103. package/docs/src/typograf/index.js.md +165 -0
  104. package/docs/src/uploader/README.md +8 -0
  105. package/docs/src/uploader/index.js.md +113 -0
  106. package/docs/src/validator/README.md +8 -0
  107. package/docs/src/validator/index.js.md +114 -0
  108. package/package.json +3 -2
  109. package/src/_traits/hasInstanceSymbol.js +14 -1
  110. package/src/app/index.js +102 -15
  111. package/src/core/index.js +83 -13
  112. package/src/index.js +1 -1
  113. package/src/loader/index.js +13 -3
  114. package/src/mask/index.js +21 -2
  115. package/src/modal/index.js +16 -6
  116. package/src/observer/index.js +3 -3
  117. package/src/select/index.js +24 -4
  118. package/src/{cut → shape}/_engine.js +1 -1
  119. package/src/{cut → shape}/index.js +19 -10
  120. package/src/toggle/index.js +85 -28
  121. package/src/typograf/index.js +3 -3
  122. package/src/uploader/index.js +32 -9
  123. package/src/validator/index.js +20 -2
  124. package/dist/cut.esm.min.js +0 -2
  125. package/dist/cut.esm.min.js.map +0 -7
  126. package/dist/cut.min.js +0 -2
  127. package/dist/cut.min.js.map +0 -7
@@ -0,0 +1,821 @@
1
+ # modal
2
+
3
+ ## Содержание
4
+
5
+ 1. [Описание](#1-описание)
6
+ 2. [DOM-структура](#2-dom-структура)
7
+ 3. [Машина состояний](#3-машина-состояний)
8
+ 4. [Параметры конструктора](#4-параметры-конструктора)
9
+ 5. [Хуки жизненного цикла](#5-хуки-жизненного-цикла)
10
+ 6. [Публичные свойства и методы](#6-публичные-свойства-и-методы)
11
+ 7. [Статические методы](#7-статические-методы)
12
+ 8. [action="close"](#8-actionclose)
13
+ 9. [CSS-анимация через атрибут state](#9-css-анимация-через-атрибут-state)
14
+ 10. [Блокировка прокрутки страницы](#10-блокировка-прокрутки-страницы)
15
+ 11. [Примеры](#11-примеры)
16
+ 12. [Известные особенности и ограничения](#12-известные-особенности-и-ограничения)
17
+
18
+ ---
19
+
20
+ ## 1. Описание
21
+
22
+ `Modal` — класс для создания модальных окон. Каждый экземпляр порождает дерево
23
+ нестандартных HTML-элементов (`<modal>`, `<modal-overlay>`, `<modal-area>`, `<modal-container>`) и вставляет
24
+ их в указанный контейнер (по умолчанию — `<body>`).
25
+
26
+ **Ключевые принципы:**
27
+
28
+ - **Анимация — только CSS.** Открытие/закрытие управляется атрибутом `state` на
29
+ элементе `<modal>`. Разработчик сам определяет CSS-правила для каждого значения
30
+ этого атрибута.
31
+ - **Нет зависимостей.** Чистый ES6-класс, экспортируется как ES-модуль.
32
+ - **Гибкий контент.** Принимает HTML-строку, CSS-селектор существующего элемента
33
+ или готовый `Element`.
34
+ - **Закрытие без JS.** Любой элемент с атрибутом `action="close"` внутри контента
35
+ автоматически закрывает модал по клику.
36
+
37
+ ---
38
+
39
+ ## 2. DOM-структура
40
+
41
+ После вызова `new Modal(params)` в DOM появляется следующее дерево:
42
+
43
+ ```
44
+ <modal state="hidden"> ← фиксированный слой на весь экран
45
+ <modal-overlay> ← (опционально) затемнение/размытие фона
46
+ <modal-area> ← слой прокрутки, выравнивает контейнер по горизонтали
47
+ <modal-container> ← позиционируемая обёртка контента
48
+ {content} ← пользовательский элемент
49
+ ```
50
+
51
+ ### Inline-стили, проставляемые автоматически
52
+
53
+ | Элемент | Ключевые стили |
54
+ |---|---|
55
+ | `<modal>` | `position: fixed; top/left/right/bottom: 0; display: none; overflow: hidden; pointer-events: none; z-index: zIndex` |
56
+ | `<modal-overlay>` | `position: absolute; top/left/right/bottom: 0; background-color: var(--modal-overlay-color, rgba(0,0,0,overlay_shading)); backdrop-filter: var(--modal-overlay-filter, blur(overlay_blur)); z-index: zIndex+1` |
57
+ | `<modal-area>` | `position: absolute; top/left/right/bottom: 0; overflow-y: auto; overflow-x: clip; display: flex; align-items: flex-start; justify-content` по горизонтали из `location`; `pointer-events: all; z-index: zIndex+2` |
58
+ | `<modal-container>` | `position: relative; flex-shrink: 0; width/height: max-content; max-width: 100vw` (при `fluid: true` — `width: 100%; max-width: none`); `pointer-events: all; z-index: zIndex+3; margin-*` по `location` |
59
+ | `content` | `transition: inherit` |
60
+
61
+ > [!warning] Инлайн-стили не перебиваются обычным CSS
62
+ > Правило из таблицы стилей вида `modal-container { width: 100% }` проиграет инлайну при любой
63
+ > специфичности. Если контейнер должен тянуться на всю ширину `<modal-area>` (например, меню во
64
+ > весь экран), передайте `fluid: true`. Без этого ширина контейнера равна ширине самого широкого
65
+ > ребёнка, и раскладка «по окну» внутри него разъедется.
66
+
67
+ > [!tip] Цвет затемнения из CSS
68
+ > Фон и размытие оверлея берутся из CSS-переменных, а параметры `overlay_shading` и `overlay_blur` —
69
+ > только запасные значения. Тема задаётся без `!important`:
70
+ >
71
+ > ```css
72
+ > modal-overlay {
73
+ > --modal-overlay-color: rgb(1 4 9 / .7);
74
+ > --modal-overlay-filter: blur(2px);
75
+ > }
76
+ > ```
77
+
78
+ > **z-index:** значение `zIndex` из параметров последовательно инкрементируется —
79
+ > `<modal-overlay>` (`zIndex + 1`), `<modal-area>` (`zIndex + 2`), `<modal-container>` (`zIndex + 3`).
80
+ > При нескольких модалках на одной странице используйте разные базовые `zIndex`.
81
+
82
+ ### Связь DOM-элементов с экземпляром
83
+
84
+ Каждый из элементов (`modal`, `overlay`, `area`, `container`, `content`) хранит
85
+ ссылку на экземпляр `Modal` через приватный Symbol. Получить экземпляр по
86
+ элементу или CSS-селектору можно через `Modal.find()`.
87
+
88
+ ---
89
+
90
+ ## 3. Машина состояний
91
+
92
+ У каждого экземпляра есть внутреннее состояние, доступное через getter `state`.
93
+
94
+ ### Диаграмма переходов
95
+
96
+ ```
97
+ show() on_show()
98
+ hidden ──────────► showing ──────────────────► shown
99
+ ▲ │
100
+ │ on_hide() hide() │
101
+ ◄──────────── hiding ◄──────────────────────── ┘
102
+ ```
103
+
104
+ | Состояние | Описание |
105
+ |---|---|
106
+ | `hidden` | Модал скрыт, `<modal>` имеет `display: none` |
107
+ | `showing` | Идёт анимация открытия, прошёл один `requestAnimationFrame` |
108
+ | `shown` | Анимация завершена, модал полностью открыт |
109
+ | `hiding` | Идёт анимация закрытия |
110
+
111
+ ### Как происходит переход (внутренняя механика)
112
+
113
+ 1. `show()` / `hide()` вызывают внутреннюю функцию `toggle()`.
114
+ 2. `toggle()` вызывает хук `before_show` / `before_hide`, затем устанавливает
115
+ `display: flex` на `<modal>`.
116
+ 3. Первый `requestAnimationFrame` устанавливает промежуточное состояние
117
+ (`showing` / `hiding`) — это запускает CSS-переход.
118
+ 4. Второй `requestAnimationFrame` запускает `setTimeout(duration * 1000)`.
119
+ 5. По окончании таймаута устанавливается финальное состояние (`shown` / `hidden`),
120
+ вызывается хук `on_show` / `on_hide`, и при `hidden` — `display: none`.
121
+
122
+ Двойной `requestAnimationFrame` гарантирует, что браузер успеет применить
123
+ промежуточное состояние перед началом анимации.
124
+
125
+ ### allow_interrupt
126
+
127
+ По умолчанию (`allow_interrupt: false`) вызов `hide()` во время анимации открытия
128
+ (`showing`) игнорируется. Вызов `show()` во время закрытия не теряется: он
129
+ откладывается и выполняется сразу после перехода в `hidden`, с тем же `data`.
130
+ Так одно окно подтверждения можно открыть повторно сразу после закрытия. Новый
131
+ `hide()` отменяет отложенный показ.
132
+
133
+ При `allow_interrupt: true` эти вызовы отменяют текущую анимацию и стартуют
134
+ обратную, что позволяет реализовать плавный реверс.
135
+
136
+ ---
137
+
138
+ ## 4. Параметры конструктора
139
+
140
+ ```js
141
+ new Modal(params)
142
+ ```
143
+
144
+ Все параметры необязательны — конструктор содержит дефолтные значения для каждого.
145
+
146
+ ### Контент и контейнер
147
+
148
+ | Параметр | Тип | По умолчанию | Описание |
149
+ |---|---|---|---|
150
+ | `content` | `string \| Element` | `'<div></div>'` | HTML-строка, CSS-селектор или готовый `Element`. Если передан селектор — элемент **физически перемещается** в `<modal-container>`. Если HTML-строка — парсится через `DOMParser`, берётся первый дочерний элемент `<body>`. |
151
+ | `container` | `string \| Element` | `'body'` | Куда вставить `<modal>`. Принимает CSS-селектор или `Element`. |
152
+
153
+ > [!tip] Тема на корне приложения
154
+ > Окно по умолчанию уходит в конец `<body>`, за пределы корня приложения. Если тема объявлена CSS-переменными на корне (Primer - на `[data-color-mode]`, своя тема - на `.app`), окно её не видит: цвета и отступы пропадают. Вставляйте окно внутрь корня: `container: '.app'` (или `'[data-color-mode]'`). Окно позиционируется `fixed`, поэтому место в DOM на раскладку не влияет.
155
+
156
+ ### Позиционирование
157
+
158
+ | Параметр | Тип | По умолчанию | Описание |
159
+ |---|---|---|---|
160
+ | `location` | `string` | `'center center'` | Позиция `<modal-container>` внутри `<modal-area>`. Задаётся двумя словами через пробел (порядок не важен): вертикаль (`top` / `bottom` / `center`) и горизонталь (`left` / `right` / `center`). Реализуется через `margin: auto` / `margin: 0` на соответствующих сторонах и `justify-content` у `<modal-area>`. |
161
+ | `fluid` | `boolean` | `false` | Растянуть `<modal-container>` на всю ширину `<modal-area>`: `width: 100%; max-width: none` вместо `max-content` / `100vw`. Нужен, когда внутри модалки раскладка должна считаться от ширины окна, а не от контента — полноэкранное меню, шторка. Учтите: у `<modal-area>` своя полоса прокрутки (`overflow-y: auto`), и там, где она занимает место, `100%` будет уже окна на её ширину. |
162
+
163
+ **Примеры значений `location`:**
164
+
165
+ | Значение | Результат |
166
+ |---|---|
167
+ | `'center center'` | По центру экрана (по умолчанию) |
168
+ | `'top center'` | Сверху по центру |
169
+ | `'bottom left'` | Снизу слева |
170
+ | `'top right'` | Сверху справа |
171
+ | `'bottom center'` | Снизу по центру — удобно для cookie-баннеров |
172
+
173
+ ### Анимация
174
+
175
+ | Параметр | Тип | По умолчанию | Описание |
176
+ |---|---|---|---|
177
+ | `duration` | `number` | `0` | Длительность CSS-перехода в секундах. Применяется как `transition: all {duration}s` на `<modal>`, и наследуется дочерними элементами. |
178
+ | `zIndex` | `number` | `1000` | Базовый z-index. `<modal-overlay>` получает `zIndex+1`, `<modal-area>` — `zIndex+2`, `<modal-container>` — `zIndex+3`. |
179
+ | `allow_interrupt` | `boolean` | `false` | Разрешить отмену текущей анимации при вызове обратного действия. Без него `show()` во время закрытия откладывается до `hidden`. |
180
+
181
+ ### Оверлей
182
+
183
+ | Параметр | Тип | По умолчанию | Описание |
184
+ |---|---|---|---|
185
+ | `overlay` | `boolean` | `true` | Создавать элемент `<modal-overlay>`. При `false` — `<modal-overlay>` отсутствует в DOM. |
186
+ | `overlay_shading` | `number` | `0.5` | Непрозрачность затемнения от `0` (прозрачный) до `1` (полностью чёрный). Используется как `rgba(0, 0, 0, N)`, если не задана CSS-переменная `--modal-overlay-color`. |
187
+ | `overlay_blur` | `string` | `'5px'` | Размытие фона через `backdrop-filter: blur(N)`, если не задана CSS-переменная `--modal-overlay-filter`. Передаётся любое валидное CSS-значение, например `'0px'`, `'10px'`. |
188
+ | `overlay_scroll_lock` | `boolean` | `true` | Блокировать прокрутку страницы, пока модал открыт. Работает только при `overlay: true`. Подробнее — в разделе [10](#10-блокировка-прокрутки-страницы). |
189
+
190
+ ### Закрытие
191
+
192
+ | Параметр | Тип | По умолчанию | Описание |
193
+ |---|---|---|---|
194
+ | `close_by_overlay` | `boolean` | `true` | Закрывать модал по клику мимо контента — в любом месте `<modal-area>` вне `<modal-container>`. Работает и при `overlay: false`. |
195
+ | `close_by_esc` | `boolean` | `true` | Закрывать модал по нажатию клавиши `Escape`. При нескольких открытых окнах закрывается только верхнее (открытое последним). Если у верхнего окна `close_by_esc: false`, Esc ничего не закрывает. Неблокирующие окна (`blocking: false`) при выборе верхнего пропускаются. |
196
+ | `return_focus` | `boolean` | `true` | После закрытия вернуть фокус элементу, который был активен до показа. Не срабатывает, если пользователь уже перевёл фокус за пределы окна. |
197
+ | `blocking` | `boolean` | `true` | `false` — окно не перекрывает страницу: `<modal-area>` пропускает клики (`pointer-events: none`, `overflow: visible`), прокрутка не блокируется, Esc его пропускает. Для уведомлений. |
198
+ | `auto_close` | `number` | `-1` | Автоматически закрыть модал через N секунд после открытия. `-1` — выключено. |
199
+
200
+ ### Триггеры
201
+
202
+ | Параметр | Тип | По умолчанию | Описание |
203
+ |---|---|---|---|
204
+ | `trigger` | `string \| Element \| NodeList \| Array \| function \| null` | `null` | Элементы, которые открывают модал по клику: селектор, элементы или функция, которая их возвращает. Привязываются при создании; появившиеся позже (их отрисовал App, Vue) привязывает `refresh()`. Нажатая кнопка передаётся в `show(trigger)`, поэтому `before_show` / `on_show` получают её как `data` - по ней удобно менять заголовок или состав формы. |
205
+
206
+ ### Хуки жизненного цикла
207
+
208
+ | Параметр | Тип | По умолчанию | Описание |
209
+ |---|---|---|---|
210
+ | `before_init` | `function` | `() => {}` | Вызывается **до** создания DOM-элементов. Получает объект `params`. |
211
+ | `on_init` | `function` | `() => {}` | Вызывается **после** создания DOM и навешивания всех обработчиков. Получает объект `params`. |
212
+ | `before_show` | `function` | `() => {}` | Вызывается **до** старта анимации открытия. Получает `data` из `show(data)`. |
213
+ | `on_show` | `function` | `() => {}` | Вызывается **после** завершения анимации открытия. Получает `data` из `show(data)`. |
214
+ | `before_hide` | `function` | `() => {}` | Вызывается **до** старта анимации закрытия. Получает `data` из источника закрытия (кнопка, оверлей, ESC, `auto_close` или явный вызов `hide(data)`). |
215
+ | `on_hide` | `function` | `() => {}` | Вызывается **после** завершения анимации закрытия. Получает `data` аналогично `before_hide`. |
216
+
217
+ ---
218
+
219
+ ## 5. Хуки жизненного цикла
220
+
221
+ ### Порядок вызова при открытии
222
+
223
+ ```
224
+ show(data)
225
+ → before_show(data) ← немедленно
226
+ → [requestAnimationFrame x2 + setTimeout(duration)]
227
+ → on_show(data) ← после завершения анимации
228
+ ```
229
+
230
+ ### Порядок вызова при закрытии
231
+
232
+ ```
233
+ hide(data)
234
+ → before_hide(data) ← немедленно
235
+ → [requestAnimationFrame x2 + setTimeout(duration)]
236
+ → on_hide(data) ← после завершения анимации, display: none уже установлен
237
+ ```
238
+
239
+ ### Инициализация
240
+
241
+ ```
242
+ new Modal(params)
243
+ → before_init(params) ← до создания DOM
244
+ → [создание modal, overlay, area, container, content, обработчиков]
245
+ → on_init(params) ← после полной инициализации
246
+ ```
247
+
248
+ ### Привязка контекста
249
+
250
+ Все хуки автоматически привязываются к экземпляру через `.bind(this)`. Внутри хука
251
+ `this` указывает на экземпляр `Modal`, что позволяет обращаться к его свойствам:
252
+
253
+ ```js
254
+ const modal = new Modal({
255
+ content: `<div><p id="msg"></p><button action="close">Закрыть</button></div>`,
256
+ before_show(data) {
257
+ // this — экземпляр Modal
258
+ this.content.querySelector('#msg').textContent = `Открыто с данными: ${data}`;
259
+ },
260
+ on_hide() {
261
+ console.log('Текущее состояние после скрытия:', this.state); // 'hidden'
262
+ }
263
+ });
264
+ ```
265
+
266
+ ### Параметр data
267
+
268
+ `data` — произвольное значение, которое передаётся в `show(data)` или `hide(data)`.
269
+ По умолчанию `null`.
270
+
271
+ При открытии через `trigger` значение `data` — нажатый элемент-триггер.
272
+
273
+ При закрытии через встроенные механизмы значение `data`:
274
+ - **`action="close"` кнопка** — `null` (вызов без аргумента)
275
+ - **Клик мимо контента** (`close_by_overlay`) — объект события `MouseEvent`
276
+ - **Клавиша ESC** — объект события `KeyboardEvent`
277
+ - **`auto_close`** — `null`
278
+
279
+ ### DOM-события
280
+
281
+ Вместе с хуками на элементе `content` вызываются события. Они всплывают, в `detail` — `{ modal, data }`:
282
+
283
+ | Событие | Когда |
284
+ |---|---|
285
+ | `modal:show` | сразу после `before_show` |
286
+ | `modal:shown` | после `on_show` |
287
+ | `modal:hide` | сразу после `before_hide` |
288
+ | `modal:hidden` | после `on_hide`, окно скрыто |
289
+
290
+ События удобны, когда окно и его содержимое пишут в разных местах: компонент `<st-app>` внутри окна узнаёт о закрытии без `on_hide` в параметрах окна. Событие идёт от `content` вверх, поэтому вложенный компонент слушает документ и проверяет, что окно — его:
291
+
292
+ ```js
293
+ App.create({
294
+ app: 'dialog',
295
+ setup() {
296
+ document.addEventListener('modal:hidden', e => {
297
+ if (e.target.contains(this)) this.reset();
298
+ });
299
+ },
300
+ // Закрыть своё окно с результатом для open():
301
+ submit() {
302
+ Modal.find(this.closest('modal'))?.hide(this.value);
303
+ },
304
+ });
305
+ ```
306
+
307
+ `Modal.find` принимает и `<modal>`, и `content`: оба помечены экземпляром.
308
+
309
+ Форма `app/form` в окне после успешной отправки остаётся на экране "Спасибо" - как вернуть её при
310
+ закрытии окна, см. ["Форма в модалке"](../app/form/index.js.md#форма-в-модалке).
311
+
312
+ ---
313
+
314
+ ## 6. Публичные свойства и методы
315
+
316
+ ### Свойства (DOM-элементы)
317
+
318
+ | Свойство | Тип | Описание |
319
+ |---|---|---|
320
+ | `modal` | `HTMLElement` | Элемент `<modal>` — корневой контейнер |
321
+ | `overlay` | `HTMLElement \| undefined` | Элемент `<modal-overlay>`. `undefined`, если `overlay: false` |
322
+ | `area` | `HTMLElement` | Элемент `<modal-area>` — слой прокрутки и выравнивания |
323
+ | `container` | `HTMLElement` | Элемент `<modal-container>` — обёртка, управляющая позицией |
324
+ | `content` | `HTMLElement` | Пользовательский элемент контента |
325
+
326
+ ### Геттеры
327
+
328
+ | Геттер | Возвращает | Описание |
329
+ |---|---|---|
330
+ | `state` | `string` | Текущее состояние: `'hidden'` / `'showing'` / `'shown'` / `'hiding'` |
331
+ | `params` | `object` | Объект с параметрами экземпляра (без методов) |
332
+
333
+ ### Методы
334
+
335
+ #### `show(data?)`
336
+
337
+ Открывает модал. Запускает машину состояний `hidden → showing → shown`.
338
+
339
+ - Игнорируется, если окно уже открыто или открывается.
340
+ - Во время закрытия при `allow_interrupt: false` откладывается и выполняется после `hidden`; при `allow_interrupt: true` прерывает закрытие.
341
+ - Если `overlay_scroll_lock: true` и `overlay` присутствует — блокирует прокрутку.
342
+ - Если `auto_close > 0` — запускает таймер автозакрытия.
343
+
344
+ ```js
345
+ modal.show(); // data = null
346
+ modal.show('some data');
347
+ modal.show({ userId: 42 });
348
+ ```
349
+
350
+ #### `open(data?)`
351
+
352
+ Открывает окно и возвращает `Promise`, который разрешается после полного закрытия значением из `hide(value)`. Закрытие по Esc, клику мимо окна или `[action="close"]` даёт `null`. Если окно уже открыто, промис ждёт ближайшего закрытия; если отложенный показ отменён вызовом `hide()`, промис получает `null`.
353
+
354
+ ```js
355
+ const name = await dialog.open({ title: 'Новый блок' });
356
+ if (name === null) return; // отмена
357
+
358
+ // внутри окна, по кнопке «Создать»:
359
+ dialog.hide(input.value);
360
+ ```
361
+
362
+ #### `hide(data?)`
363
+
364
+ Закрывает модал. Запускает машину состояний `shown → hiding → hidden`.
365
+
366
+ - Игнорируется, если текущее состояние не `'shown'` (а при `allow_interrupt: false` — и не `'showing'`).
367
+ - После завершения анимации восстанавливает прокрутку страницы.
368
+
369
+ ```js
370
+ modal.hide();
371
+ modal.hide(someElement); // элемент попадёт в before_hide/on_hide как data
372
+ ```
373
+
374
+ `data` — ещё и результат для `open()`. Esc и клик мимо окна передают событие, оно результатом не считается (`null`).
375
+
376
+ #### `clone(params)`
377
+
378
+ Создаёт новый экземпляр `Modal` на основе текущего.
379
+
380
+ - Клонирует DOM-элемент `content` (через `cloneNode(true)`, со всеми дочерними элементами).
381
+ - Параметры и методы текущего экземпляра используются как основа; переданный `params` их переопределяет.
382
+ - Новый экземпляр получает ссылку на оригинал через параметр `parent`.
383
+
384
+ **Управление `id` клона:**
385
+
386
+ | Что передано | Результат |
387
+ |---|---|
388
+ | `params.id: 'my_id'` | `id` будет `'my_id'` |
389
+ | `params.suffix: '_2'` | `id` строится как `{оригинальный id}_2` (суффикс заменяет символы `#` в конце) |
390
+ | Ничего | `id` строится как `{оригинальный id}_copy` |
391
+
392
+ ```js
393
+ const original = new Modal({
394
+ content: `<div id="alert">Сообщение</div>`,
395
+ duration: 0.3
396
+ });
397
+
398
+ // Клон с другой позицией
399
+ const copy = original.clone({
400
+ location: 'top right',
401
+ suffix: '_top'
402
+ // content.id станет 'alert_top'
403
+ });
404
+
405
+ copy.show();
406
+ ```
407
+
408
+ #### `destroy()`
409
+
410
+ Разбирает окно: снимает обработчики (оверлей, `[action="close"]`, триггеры) и таймеры, возвращает прокрутку страницы, если окно её заблокировало, кладёт `content` обратно на место в документе, откуда его взяли, и удаляет разметку окна (`modal`). Ждущие `open()` получают `null`. Повторный вызов ничего не делает.
411
+
412
+ Нужен, когда контент живёт меньше страницы — компонент SPA, который уходит со сменой маршрута. Контент возвращается на место, поэтому фреймворк удаляет его как обычно, а в `body` не остаётся пустых окон.
413
+
414
+ ```js
415
+ const modal = new Modal({ content: el });
416
+ // компонент снимается
417
+ modal.destroy();
418
+ ```
419
+
420
+ #### `refresh()`
421
+
422
+ Привязывает триггеры по `trigger`, которых ещё нет: их отрисовал App, Vue или другой код после создания окна. Уже привязанные не дублируются, ушедшие из DOM отпадают вместе с узлами. Возвращает экземпляр.
423
+
424
+ ```js
425
+ const modal = new Modal({ content: '#confirm', trigger: '[data-open-confirm]' });
426
+ app.addEventListener('updated', () => modal.refresh()); // <st-app> перерисовал кнопки
427
+ ```
428
+
429
+ ---
430
+
431
+ ## 7. Статические методы
432
+
433
+ ### `Modal.find(element | selector)`
434
+
435
+ Возвращает экземпляр `Modal`, связанный с переданным DOM-элементом или CSS-селектором.
436
+
437
+ Работает для любого из элементов: `modal`, `overlay`, `area`, `container`, `content`.
438
+
439
+ ```js
440
+ // Получить экземпляр по элементу <modal>
441
+ const instance = Modal.find(document.querySelector('modal'));
442
+ instance.hide();
443
+
444
+ // Получить экземпляр по <modal-container>
445
+ const instance2 = Modal.find(someModal.container);
446
+
447
+ // Получить по CSS-селектору (ищет первый совпавший элемент)
448
+ const instance3 = Modal.find('modal');
449
+ ```
450
+
451
+ > **Совет:** `Modal.find()` полезен в ситуациях, когда прямой ссылки на
452
+ > экземпляр нет — например, внутри обработчиков событий или при делегировании.
453
+
454
+ ---
455
+
456
+ ## 8. action="close"
457
+
458
+ Клик по любому элементу с атрибутом `action="close"` внутри `content` (или по его
459
+ потомку) вызывает `hide()`. Обработчик делегирован на `content`, поэтому кнопки,
460
+ добавленные или пересозданные позже (например, шаблоном `App`), тоже работают.
461
+
462
+ ```html
463
+ <div>
464
+ <h2>Заголовок</h2>
465
+ <p>Текст модала</p>
466
+ <button action="close">Закрыть</button>
467
+ <!-- или иконка -->
468
+ <span action="close">✕</span>
469
+ </div>
470
+ ```
471
+
472
+ ---
473
+
474
+ ## 9. CSS-анимация через атрибут state
475
+
476
+ Единственный механизм анимации — CSS. Никаких встроенных переходов нет.
477
+
478
+ ### Атрибут `[state]`
479
+
480
+ `<modal>` имеет атрибут `state`, который меняется по мере прохождения машины
481
+ состояний. CSS-правила, привязанные к этому атрибуту — единственный способ
482
+ задать визуальное поведение модала.
483
+
484
+ Доступные значения: `hidden`, `showing`, `shown`, `hiding`.
485
+
486
+ `transition` задаётся через параметр `duration` и наследуется всеми дочерними
487
+ элементами (`transition: inherit`).
488
+
489
+ ### Основной принцип
490
+
491
+ Стили для `showing` и `shown` — «конечная точка» анимации (видимое состояние).
492
+ Стили для `hidden` и `hiding` — «стартовая / конечная точка» (скрытое состояние).
493
+
494
+ Если нужно разное визуальное поведение при открытии и закрытии, `showing` и
495
+ `hiding` можно оформить по-разному.
496
+
497
+ ### Паттерн: Fade (простое появление)
498
+
499
+ ```css
500
+ [state="hidden"],
501
+ [state="hiding"] { opacity: 0 }
502
+
503
+ [state="showing"],
504
+ [state="shown"] { opacity: 1 }
505
+ ```
506
+
507
+ ### Паттерн: Grow (масштабирование контента)
508
+
509
+ ```css
510
+ /* Прозрачность на <modal> */
511
+ [state="hidden"], [state="hiding"] { opacity: 0 }
512
+
513
+ /* Масштаб на элементе класса .grow внутри content */
514
+ [state="hidden"] .grow { transform: scale(0) }
515
+ [state="showing"] .grow { transform: scale(1.3) }
516
+ [state="shown"] .grow { transform: scale(1) }
517
+ [state="hiding"] .grow { transform: scale(3) }
518
+ ```
519
+
520
+ ```html
521
+ <div class="grow">
522
+ <button action="close">✕</button>
523
+ <p>Контент</p>
524
+ </div>
525
+ ```
526
+
527
+ ### Паттерн: Vertical slide (выезд сверху)
528
+
529
+ ```css
530
+ [state="hidden"] .slide-v { transform: translateY(-100%) }
531
+ [state="shown"] .slide-v { transform: translateY(0) }
532
+ [state="hiding"] .slide-v { transform: translateY(-100%) }
533
+ /* showing намеренно пропущен — начальная позиция = hidden */
534
+ ```
535
+
536
+ ```js
537
+ new Modal({
538
+ content: `<div class="slide-v">...</div>`,
539
+ location: 'top right',
540
+ overlay: false,
541
+ duration: 0.4
542
+ })
543
+ ```
544
+
545
+ ### Паттерн: Line slide (горизонтальный выезд)
546
+
547
+ ```css
548
+ [state="hidden"] .slide-h { transform: translateX(-100vw) }
549
+ [state="shown"] .slide-h { transform: translateX(0) }
550
+ [state="hiding"] .slide-h { transform: translateX(100vw) }
551
+ ```
552
+
553
+ ```js
554
+ new Modal({
555
+ content: `<div class="slide-h">...</div>`,
556
+ location: 'bottom center',
557
+ overlay: false,
558
+ duration: 1
559
+ })
560
+ ```
561
+
562
+ > **Совет:** Можно задавать состояния как на самом `<modal>` (например,
563
+ > `opacity`), так и на дочерних элементах через CSS-комбинаторы
564
+ > `[state="..."] .class-name`. Это позволяет иметь разные анимации для разных
565
+ > частей модала.
566
+
567
+ ---
568
+
569
+ ## 10. Блокировка прокрутки страницы
570
+
571
+ При `overlay_scroll_lock: true` (по умолчанию) и наличии `<modal-overlay>` при открытии
572
+ модала прокрутка страницы блокируется через следующий механизм:
573
+
574
+ **При открытии (`show()`):**
575
+ 1. Сохраняются текущие `scrollY`, `scrollX` и inline-стили `body`.
576
+ 2. `document.documentElement.style.scrollBehavior` устанавливается в `'unset'`.
577
+ 3. На `<body>` устанавливаются:
578
+ ```css
579
+ position: fixed;
580
+ width: auto;
581
+ top: -{scrollY}px;
582
+ left: -{scrollX}px;
583
+ right: {scrollX}px;
584
+ ```
585
+ Ширина задаётся парой `left`/`right`, а не `100vw`: `100vw` включает полосу прокрутки, и
586
+ при классическом скроллбаре (Windows) `body` становился шире контента — fixed-элементы
587
+ страницы сдвигались при открытии модала.
588
+
589
+ **При закрытии (`hide()`):**
590
+ 1. Inline-стили `body` восстанавливаются до исходных значений.
591
+ 2. Страница прокручивается обратно к сохранённой позиции через `window.scrollTo()`.
592
+ 3. `scrollBehavior` восстанавливается.
593
+
594
+ Этот подход позволяет правильно обрабатывать страницы с прокруткой: пользователь
595
+ не «прыгает» наверх при открытии/закрытии модала.
596
+
597
+ ---
598
+
599
+ ## 11. Примеры
600
+
601
+ ### Базовый модал
602
+
603
+ ```js
604
+ import Modal from './modal.js';
605
+
606
+ const modal = new Modal({
607
+ content: `
608
+ <div style="padding: 24px; background: white; border-radius: 8px;">
609
+ <h2>Заголовок</h2>
610
+ <p>Текст</p>
611
+ <button action="close">Закрыть</button>
612
+ </div>
613
+ `,
614
+ duration: 0.3
615
+ });
616
+
617
+ modal.show();
618
+ ```
619
+
620
+ ```css
621
+ [state="hidden"], [state="hiding"] { opacity: 0 }
622
+ [state="showing"], [state="shown"] { opacity: 1 }
623
+ ```
624
+
625
+ ---
626
+
627
+ ### Cookie-баннер (снизу, без overlay, с анимацией)
628
+
629
+ ```js
630
+ const cookie_modal = new Modal({
631
+ content: `
632
+ <div class="cookie-bar">
633
+ <p>Мы используем файлы cookie.</p>
634
+ <button action="close">Принять</button>
635
+ <a href="/policy/" target="_blank">Подробнее</a>
636
+ </div>
637
+ `,
638
+ overlay: false,
639
+ location: 'bottom center',
640
+ duration: 0.5
641
+ });
642
+
643
+ // Растянуть контейнер на всю ширину
644
+ cookie_modal.container.style.width = '100vw';
645
+ cookie_modal.show();
646
+ ```
647
+
648
+ ```css
649
+ [state="hidden"] .cookie-bar { transform: translateX(-100vw) }
650
+ [state="shown"] .cookie-bar { transform: translateX(0) }
651
+ [state="hiding"] .cookie-bar { transform: translateX(100vw) }
652
+ ```
653
+
654
+ ---
655
+
656
+ ### Авто-закрывающееся уведомление
657
+
658
+ ```js
659
+ const notify = new Modal({
660
+ content: `<div class="toast">Файл сохранён!</div>`,
661
+ overlay: false,
662
+ location: 'top right',
663
+ duration: 0.3,
664
+ auto_close: 4, // автоматически скроется через 4 секунды
665
+ on_hide() {
666
+ console.log('уведомление скрыто');
667
+ }
668
+ });
669
+
670
+ notify.show();
671
+ ```
672
+
673
+ ---
674
+
675
+ ### Открытие по кнопке через параметр trigger
676
+
677
+ ```html
678
+ <button class="open-btn">Открыть модал</button>
679
+ ```
680
+
681
+ ```js
682
+ const modal = new Modal({
683
+ content: `<div class="dialog"><button action="close">✕</button><p>Привет!</p></div>`,
684
+ trigger: '.open-btn', // найдёт все .open-btn при инициализации; новые - refresh()
685
+ duration: 0.3
686
+ });
687
+ // Обработчик клика добавлен автоматически, явный addEventListener не нужен
688
+ ```
689
+
690
+ ---
691
+
692
+ ### Модал с контентом из существующего DOM-элемента
693
+
694
+ ```html
695
+ <div id="my-form" style="display:none">
696
+ <form>...</form>
697
+ <button action="close">Отмена</button>
698
+ </div>
699
+ ```
700
+
701
+ ```js
702
+ const modal = new Modal({
703
+ content: '#my-form', // элемент перемещается в <modal-container>
704
+ duration: 0.4
705
+ });
706
+
707
+ modal.show();
708
+ ```
709
+
710
+ > **Внимание:** элемент физически перемещается в DOM. После закрытия он остаётся
711
+ > внутри `<modal-container>`, а не возвращается на исходное место.
712
+
713
+ ---
714
+
715
+ ### Клонирование модала
716
+
717
+ ```js
718
+ const base = new Modal({
719
+ content: `<div class="popup" id="popup">
720
+ <p class="message"></p>
721
+ <button action="close">OK</button>
722
+ </div>`,
723
+ duration: 0.3,
724
+ on_init() {
725
+ this._msg = this.content.querySelector('.message');
726
+ }
727
+ });
728
+
729
+ function showPopup(text) {
730
+ const copy = base.clone({ suffix: '_instance' });
731
+ copy.content.querySelector('.message').textContent = text;
732
+ copy.show();
733
+ }
734
+
735
+ showPopup('Операция выполнена успешно');
736
+ showPopup('Ошибка: файл не найден');
737
+ ```
738
+
739
+ ---
740
+
741
+ ### Modal.find() — получение экземпляра из DOM
742
+
743
+ ```js
744
+ // Где-то в коде создаётся модал
745
+ const modal = new Modal({ content: `<div id="my-modal">...</div>` });
746
+
747
+ // В другом месте, без прямой ссылки на переменную modal:
748
+ document.addEventListener('click', e => {
749
+ if (e.target.closest('#my-modal')) {
750
+ const instance = Modal.find(e.target.closest('#my-modal'));
751
+ instance.hide();
752
+ }
753
+ });
754
+
755
+ // Или по элементу <modal>:
756
+ const instance = Modal.find(document.querySelector('modal'));
757
+ instance.show();
758
+ ```
759
+
760
+ ---
761
+
762
+ ### Хуки: наполнение контента перед открытием
763
+
764
+ ```js
765
+ const confirm_modal = new Modal({
766
+ content: `<div class="confirm">
767
+ <p class="confirm__text"></p>
768
+ <button class="confirm__ok">Да</button>
769
+ <button action="close">Нет</button>
770
+ </div>`,
771
+ duration: 0.3,
772
+ before_show(data) {
773
+ // data — объект, переданный в show(data)
774
+ this.content.querySelector('.confirm__text').textContent = data.message;
775
+ this.content.querySelector('.confirm__ok').onclick = () => {
776
+ data.onConfirm?.();
777
+ this.hide();
778
+ };
779
+ }
780
+ });
781
+
782
+ confirm_modal.show({
783
+ message: 'Удалить этот элемент?',
784
+ onConfirm: () => deleteItem(42)
785
+ });
786
+ ```
787
+
788
+ ---
789
+
790
+ ## 12. Известные особенности и ограничения
791
+
792
+ ### content как CSS-селектор перемещает элемент
793
+
794
+ При передаче CSS-селектора в `content` целевой элемент **физически перемещается**
795
+ из своего исходного места в DOM в `<modal-container>`. Он не клонируется. После
796
+ закрытия модала элемент остаётся внутри `<modal-container>`.
797
+
798
+ ### before_init вызывается до создания DOM
799
+
800
+ В хуке `before_init` элементы `modal`, `overlay`, `area`, `container`, `content` ещё не
801
+ существуют — обращение к `this.modal` и другим свойствам вернёт `undefined`.
802
+ Используйте этот хук только для изменения параметров инициализации.
803
+
804
+ ### trigger привязывается один раз, статически
805
+
806
+ `querySelectorAll(trigger)` выполняется один раз при вызове конструктора.
807
+ Элементы, добавленные в DOM динамически после создания экземпляра, не получают
808
+ обработчик автоматически. Решение — добавлять обработчики вручную или
809
+ использовать делегирование событий.
810
+
811
+ ### display: none сбрасывается при каждом show()
812
+
813
+ Перед запуском анимации `<modal>` получает `display: flex`. После завершения
814
+ анимации закрытия — `display: none`. CSS-правила, переопределяющие `display` на
815
+ элементе `<modal>`, могут конфликтовать с этим поведением.
816
+
817
+ ### auto_close и duration используют один setTimeout
818
+
819
+ При `duration > 0` и `auto_close > 0` внутренний таймер `timeout` используется
820
+ совместно. Убедитесь, что `auto_close > duration`.
821
+