@cat-of-summer/st-script 1.4.1 → 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.
- package/README.md +1 -1
- package/dist/app/datepicker.esm.min.js +25 -27
- package/dist/app/datepicker.esm.min.js.map +2 -2
- package/dist/app/datepicker.min.js +23 -25
- package/dist/app/datepicker.min.js.map +2 -2
- package/dist/shape.esm.min.js +2 -0
- package/dist/{cut.esm.min.js.map → shape.esm.min.js.map} +4 -4
- package/dist/shape.min.js +2 -0
- package/dist/shape.min.js.map +7 -0
- package/docs/README.md +36 -0
- package/docs/src/README.md +29 -0
- package/docs/src/_traits/README.md +8 -0
- package/docs/src/_traits/hasInstanceSymbol.js.md +57 -0
- package/docs/src/app/README.md +13 -0
- package/docs/src/app/datepicker/README.md +9 -0
- package/docs/src/app/datepicker/_calendar.js.md +1 -0
- package/docs/src/app/datepicker/index.js.md +153 -0
- package/docs/src/app/form/README.md +8 -0
- package/docs/src/app/form/index.js.md +560 -0
- package/docs/src/app/index.js.md +1302 -0
- package/docs/src/cookie/README.md +8 -0
- package/docs/src/cookie/index.js.md +80 -0
- package/docs/src/core/README.md +8 -0
- package/docs/src/core/index.js.md +178 -0
- package/docs/src/index.js.md +1 -0
- package/docs/src/loader/README.md +8 -0
- package/docs/src/loader/index.js.md +125 -0
- package/docs/src/mask/README.md +10 -0
- package/docs/src/mask/_engine.js.md +1 -0
- package/docs/src/mask/_groups.js.md +1 -0
- package/docs/src/mask/index.js.md +411 -0
- package/docs/src/modal/README.md +8 -0
- package/docs/src/modal/index.js.md +809 -0
- package/docs/src/observer/README.md +9 -0
- package/docs/src/observer/_engine.js.md +28 -0
- package/docs/src/observer/index.js.md +259 -0
- package/docs/src/route/README.md +8 -0
- package/docs/src/route/index.js.md +385 -0
- package/docs/src/select/README.md +8 -0
- package/docs/src/select/index.js.md +115 -0
- package/docs/src/shape/README.md +9 -0
- package/docs/src/shape/_engine.js.md +1 -0
- package/docs/src/shape/index.js.md +98 -0
- package/docs/src/st_button_widget/README.md +9 -0
- package/docs/src/st_button_widget/README.txt.md +4 -0
- package/docs/src/st_button_widget/index.js.md +68 -0
- package/docs/src/st_links_widget/README.md +9 -0
- package/docs/src/st_links_widget/README.txt.md +4 -0
- package/docs/src/st_links_widget/index.js.md +46 -0
- package/docs/src/st_widget/README.md +8 -0
- package/docs/src/st_widget/button/README.md +4 -0
- package/docs/src/toggle/README.md +8 -0
- package/docs/src/toggle/index.js.md +572 -0
- package/docs/src/typograf/README.md +9 -0
- package/docs/src/typograf/_engine.js.md +75 -0
- package/docs/src/typograf/index.js.md +165 -0
- package/docs/src/uploader/README.md +8 -0
- package/docs/src/uploader/index.js.md +112 -0
- package/docs/src/validator/README.md +8 -0
- package/docs/src/validator/index.js.md +113 -0
- package/package.json +3 -2
- package/src/app/datepicker/index.js +25 -25
- package/src/index.js +1 -1
- package/src/{cut → shape}/_engine.js +1 -1
- package/src/{cut → shape}/index.js +10 -10
- package/dist/cut.esm.min.js +0 -2
- package/dist/cut.min.js +0 -2
- package/dist/cut.min.js.map +0 -7
|
@@ -0,0 +1,385 @@
|
|
|
1
|
+
# route
|
|
2
|
+
|
|
3
|
+
## Содержание
|
|
4
|
+
|
|
5
|
+
1. [Описание](#1-описание)
|
|
6
|
+
2. [Модель: реакции на текущий URL](#2-модель-реакции-на-текущий-url)
|
|
7
|
+
3. [Параметры конструктора](#3-параметры-конструктора)
|
|
8
|
+
4. [Хуки жизненного цикла](#4-хуки-жизненного-цикла)
|
|
9
|
+
5. [Регистрация маршрутов](#5-регистрация-маршрутов)
|
|
10
|
+
6. [Синтаксис путей: {param} и wildcard](#6-синтаксис-путей-param-и-wildcard)
|
|
11
|
+
7. [Обработчик и middleware](#7-обработчик-и-middleware)
|
|
12
|
+
8. [Группы, префиксы, точка входа](#8-группы-префиксы-точка-входа)
|
|
13
|
+
9. [События](#9-события)
|
|
14
|
+
10. [Публичные свойства и методы](#10-публичные-свойства-и-методы)
|
|
15
|
+
11. [Примеры](#11-примеры)
|
|
16
|
+
12. [Известные особенности и ограничения](#12-известные-особенности-и-ограничения)
|
|
17
|
+
13. [SPA-режим: history и hash](#13-spa-режим-history-и-hash)
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## 1. Описание
|
|
22
|
+
|
|
23
|
+
`Route` — клиентский диспетчер **реакций**. В CMS и кастомных проектах один JS подключается на
|
|
24
|
+
множестве страниц; `Route` по **текущему URL** решает, какие замыкания выполнить. Это аналог
|
|
25
|
+
серверного `Route.php`, но в браузере «запрос» — это всегда уже загруженный документ (метод
|
|
26
|
+
всегда `GET`).
|
|
27
|
+
|
|
28
|
+
**Ключевые принципы:**
|
|
29
|
+
|
|
30
|
+
- **По умолчанию — только реакция, без навигации.** В режиме `static` класс не трогает
|
|
31
|
+
`history`, не подменяет URL и не перехватывает клики/формы. Он лишь сопоставляет
|
|
32
|
+
`location.pathname` с маршрутами и вызывает замыкания. Для одностраничных приложений есть
|
|
33
|
+
режимы `history` и `hash`, см. раздел [13](#13-spa-режим-history-и-hash).
|
|
34
|
+
- **Строго замыкания.** И обработчики, и middleware — функции (не имена классов/строки).
|
|
35
|
+
- **Старт на `DOMContentLoaded`.** К этому моменту DOM построен; `Modal`/`Toggle` уже
|
|
36
|
+
инициализированы (если созданы синхронно). `App` (`st-app`) может ещё дорендериваться — см.
|
|
37
|
+
раздел [12](#12-известные-особенности-и-ограничения).
|
|
38
|
+
- **События — только DOM.** Диспатчатся `CustomEvent` на `document` (без отдельной шины): один
|
|
39
|
+
«предвестник» до сопоставления и события на каждый совпавший маршрут — чтобы любой код
|
|
40
|
+
(Modal/App/Toggle/свой) мог реагировать по имени события. См. раздел [9](#9-события).
|
|
41
|
+
- **Нет зависимостей.** Чистый ES6-класс, экспортируется как ES-модуль (`export default`).
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 2. Модель: реакции на текущий URL
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
new Route({ point, name, match_all })
|
|
49
|
+
│ регистрация (синхронно) диспетчеризация (на DOMContentLoaded)
|
|
50
|
+
├── get('index.html', fn) dispatch → document 'route' (предвестник, до матчинга)
|
|
51
|
+
├── get('catalog.html', fn) location.pathname ─► сопоставление с #routes
|
|
52
|
+
├── get('product-{id}.html', fn, 'product') ─► для каждого совпавшего:
|
|
53
|
+
└── get('*', fn) ← глобальная middleware-гарды → обработчик →
|
|
54
|
+
document 'route::<alias>' / 'route::<uri>'
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Маршруты регистрируются синхронно при загрузке скрипта. Сопоставление и вызовы происходят после
|
|
58
|
+
`DOMContentLoaded`: в режиме `static` один раз, в SPA-режимах ещё и на каждом переходе. Если DOM уже готов на момент создания, диспетчеризация
|
|
59
|
+
откладывается микротаской — чтобы синхронно объявленные ниже маршруты успели зарегистрироваться.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## 3. Параметры конструктора
|
|
64
|
+
|
|
65
|
+
```js
|
|
66
|
+
new Route(params)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Все параметры необязательны.
|
|
70
|
+
|
|
71
|
+
| Параметр | Тип | По умолчанию | Описание |
|
|
72
|
+
|---|---|---|---|
|
|
73
|
+
| `point` | `string` | `'/'` | Базовый префикс пути. Маршруты строятся относительно него — удобно, если сайт лежит в подкаталоге. Входит в итоговый паттерн (как `point()` в PHP). |
|
|
74
|
+
| `name` | `string` | `''` | Неймспейс событий. Предвестник — `route:<name>`, совпадения — `route:<name>:<alias>` / `route:<name>:<uri>`. Нужен, если на странице **несколько роутеров** (см. раздел [9](#9-события)). По умолчанию пусто — имена сводятся к `route` (предвестник) и `route::<alias>` / `route::<uri>` (совпадения). |
|
|
75
|
+
| `match_all` | `boolean` | `true` | `true` — выполнять замыкания **всех** совпавших маршрутов (например, глобальный `*` + страничный); `false` — только **первого** совпавшего. |
|
|
76
|
+
| `mode` | `string` | `'static'` | `'static'` — один разбор адреса при загрузке. `'history'` и `'hash'` — SPA-режимы, раздел [13](#13-spa-режим-history-и-hash). |
|
|
77
|
+
| `intercept_links` | `boolean` | `true` | В SPA-режимах перехватывать клики по внутренним ссылкам и вести их через `navigate()`. |
|
|
78
|
+
| `strict_mode` | `boolean` | `true` | Нормализация путей при построении паттерна (паритет с PHP). На само сопоставление влияет слабо: хвостовой слеш всегда необязателен. Можно переопределить для отдельного маршрута через 3-й аргумент `get`. |
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## 4. Хуки жизненного цикла
|
|
83
|
+
|
|
84
|
+
Хуки инициализации (как в `Modal`/`Toggle`). Привязываются к экземпляру через `.bind(this)` —
|
|
85
|
+
внутри хука `this` указывает на экземпляр `Route`. Для реакции на загрузку и совпадения маршрутов
|
|
86
|
+
используйте **события** (раздел [9](#9-события)) и сами замыкания обработчиков.
|
|
87
|
+
|
|
88
|
+
| Хук | Когда | Аргумент |
|
|
89
|
+
|---|---|---|
|
|
90
|
+
| `before_init` | до настройки экземпляра | `params` |
|
|
91
|
+
| `on_init` | после инициализации (до `DOMContentLoaded`) | `params` |
|
|
92
|
+
| `not_found` | ни один маршрут не совпал (или все отсеяны middleware) | `path` |
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## 5. Регистрация маршрутов
|
|
97
|
+
|
|
98
|
+
### `get(uri, closure, params = {})`
|
|
99
|
+
|
|
100
|
+
Регистрирует маршрут. `uri` строится относительно `point` и текущего префикса. `closure` —
|
|
101
|
+
обработчик-замыкание. Возвращает `this` (цепочки).
|
|
102
|
+
|
|
103
|
+
Третий аргумент — **строка-алиас** или объект параметров:
|
|
104
|
+
|
|
105
|
+
```js
|
|
106
|
+
router.get('product-{id}.html', fn, 'product'); // алиас → событие route::product
|
|
107
|
+
router.get('product-{id}.html', fn, { alias: 'product', strict_mode: false });
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Повторная регистрация **того же итогового пути** бросает ошибку (как в PHP). Единственный метод
|
|
111
|
+
регистрации — `get`: на загрузке страницы запрос всегда `GET`, других глаголов нет.
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## 6. Синтаксис путей: `{param}` и wildcard
|
|
116
|
+
|
|
117
|
+
| Синтаксис | RegExp | Что захватывает |
|
|
118
|
+
|---|---|---|
|
|
119
|
+
| `{name}` | `([^/]+)` | один сегмент (без `/`); попадает в `this.params.name` и в позиционные аргументы |
|
|
120
|
+
| `*` | `(.*)` | весь остаток пути (может содержать `/`); попадает в `this.params['*']` и последним позиционным аргументом |
|
|
121
|
+
| литералы | экранируются | совпадают как есть |
|
|
122
|
+
|
|
123
|
+
Хвостовой слеш необязателен: паттерн `about` совпадёт и с `/about`, и с `/about/`. Значения
|
|
124
|
+
сегментов декодируются через `decodeURIComponent` (битый `%`-escape не роняет матч — возвращается
|
|
125
|
+
как есть).
|
|
126
|
+
|
|
127
|
+
```js
|
|
128
|
+
router.get('catalog/{category}/{id}', (category, id) => { /* … */ });
|
|
129
|
+
router.get('docs/*', (rest) => { /* docs/a/b/c → rest = "a/b/c" */ });
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## 7. Обработчик и middleware
|
|
135
|
+
|
|
136
|
+
### Аргументы обработчика — **позиционные**
|
|
137
|
+
|
|
138
|
+
Значения `{param}` передаются по порядку появления; wildcard-остаток — последним. `this`
|
|
139
|
+
привязан к экземпляру `Route`, поэтому помимо аргументов доступны контекстные свойства
|
|
140
|
+
(`this.params`, `this.query`, `this.path`, `this.url`).
|
|
141
|
+
|
|
142
|
+
```js
|
|
143
|
+
router.get('product-{id}.html', function (id) {
|
|
144
|
+
console.log(id, this.query, this.path); // '42', {...}, '/.../product-42.html'
|
|
145
|
+
});
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### `middleware(fn | fn[])`
|
|
149
|
+
|
|
150
|
+
Добавляет гард(ы)-замыкания в **текущий контекст** (см. раздел [8](#8-группы-префиксы-точка-входа)).
|
|
151
|
+
Гард получает **те же позиционные аргументы**, что и обработчик (и `this`). Если хотя бы один
|
|
152
|
+
вернёт falsy — маршрут пропускается. Возвращает `this`.
|
|
153
|
+
|
|
154
|
+
```js
|
|
155
|
+
const allowed = ['1', '2'];
|
|
156
|
+
router
|
|
157
|
+
.middleware((id) => allowed.includes(id)) // гард для следующего маршрута в этом контексте
|
|
158
|
+
.get('product-{id}.html', (id) => { /* выполнится только для id 1 и 2 */ });
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
> `middleware` действует на **область** (текущий кадр/группу), а не на одну строку. Чтобы
|
|
162
|
+
> ограничить гард единственным маршрутом, оборачивайте его в группу (раздел [8](#8-группы-префиксы-точка-входа)).
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## 8. Группы, префиксы, точка входа
|
|
167
|
+
|
|
168
|
+
### `prefix(uri)`
|
|
169
|
+
|
|
170
|
+
Открывает вложенный контекст с добавленным префиксом пути (наследует middleware родителя).
|
|
171
|
+
Возвращает `this`.
|
|
172
|
+
|
|
173
|
+
### `group(closure)`
|
|
174
|
+
|
|
175
|
+
Выполняет `closure()` в текущем контексте и затем закрывает его (снимает верхний кадр).
|
|
176
|
+
|
|
177
|
+
```js
|
|
178
|
+
router.prefix('admin').middleware(() => isAdmin).group(() => {
|
|
179
|
+
router.get('dashboard', () => { /* /admin/dashboard, под гардом isAdmin */ });
|
|
180
|
+
router.get('users/{id}', (id) => { /* /admin/users/{id} */ });
|
|
181
|
+
});
|
|
182
|
+
|
|
183
|
+
router.get('login', () => { /* вне группы — без гарда isAdmin */ });
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
> Это перенос статического `prefix()->group()` из PHP на стек контекста экземпляра.
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## 9. События
|
|
191
|
+
|
|
192
|
+
`Route` диспатчит только **DOM `CustomEvent` на `document`** (отдельной шины `on`/`emit` нет —
|
|
193
|
+
слушайте через `document.addEventListener`). Имена неймспейсятся параметром `name` (раздел
|
|
194
|
+
[3](#3-параметры-конструктора)); ниже — формат и его вид при `name=''` (по умолчанию).
|
|
195
|
+
|
|
196
|
+
| Событие | Когда | `detail` |
|
|
197
|
+
|---|---|---|
|
|
198
|
+
| `route:<name>` → `route` | **до** сопоставления `uri` — предвестник скорого матчинга. В `static` один раз, в SPA-режимах на каждом переходе | `{ name, path, query, url }` |
|
|
199
|
+
| `route:<name>:<alias>` → `route::<alias>` | на каждый совпавший маршрут, если задан алиас | объект маршрута |
|
|
200
|
+
| `route:<name>:<uri>` → `route::<uri>` | на каждый совпавший маршрут, по исходному `uri` | объект маршрута |
|
|
201
|
+
| `route:<name>:404` → `route::404` | ни один маршрут не совпал | `{ name, path, query, url }` |
|
|
202
|
+
|
|
203
|
+
Маршрутные события используют **два** разделителя (`route:<name>:<…>`), поэтому при пустом имени это
|
|
204
|
+
`route::<alias>` / `route::<uri>`. Двойное двоеточие — намеренно: предвестник `route:<name>` никогда
|
|
205
|
+
не совпадёт с маршрутным `route:<name>:<…>`, а пустое имя не создаст коллизий, даже если алиас равен
|
|
206
|
+
имени другого роутера.
|
|
207
|
+
|
|
208
|
+
Объект маршрута в `detail` (у маршрутных событий):
|
|
209
|
+
|
|
210
|
+
```js
|
|
211
|
+
{ name, pattern, uri, alias, params, values, query, path, url }
|
|
212
|
+
// ↑ неймспейс ↑ полный путь ↑ raw uri ↑ {name:value} ↑ позиционные значения
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
```js
|
|
216
|
+
// предвестник — один раз, до матчинга (удобно для инициализации виджетов)
|
|
217
|
+
document.addEventListener('route', () => initWidgets());
|
|
218
|
+
|
|
219
|
+
// совпадение по алиасу 'product' (имя пустое → двойное двоеточие)
|
|
220
|
+
document.addEventListener('route::product', (e) => track('product', e.detail.params.id));
|
|
221
|
+
|
|
222
|
+
// совпадение по uri
|
|
223
|
+
document.addEventListener('route::catalog.html', () => initCatalog());
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### Несколько роутеров на странице
|
|
227
|
+
|
|
228
|
+
Инстансы независимы (свои таблицы маршрутов и контекст), но события идут на общий `document`.
|
|
229
|
+
Чтобы развязать их, задайте каждому свой `name` — тогда имена не пересекаются:
|
|
230
|
+
|
|
231
|
+
```js
|
|
232
|
+
new Route({ name: 'shop' }).get('product-{id}.html', fn, 'product'); // route:shop + route:shop:product
|
|
233
|
+
new Route({ name: 'blog' }).get('post-{id}.html', fn, 'post'); // route:blog + route:blog:post
|
|
234
|
+
|
|
235
|
+
document.addEventListener('route:shop:product', …); // только товары
|
|
236
|
+
document.addEventListener('route:blog:post', …); // только посты
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
> Без `name` оба роутера дадут одинаковые имена (`route`, `route::product`…) — слушатель не отличит
|
|
240
|
+
> источник. `detail.name` тоже доступен для фильтрации.
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
## 10. Публичные свойства и методы
|
|
245
|
+
|
|
246
|
+
### Геттеры / свойства
|
|
247
|
+
|
|
248
|
+
| Член | Описание |
|
|
249
|
+
|---|---|
|
|
250
|
+
| `routes` | Массив зарегистрированных маршрутов (только чтение). |
|
|
251
|
+
| `params` | Извлечённые параметры текущего совпадения (`{ name: value, '*': rest }`). |
|
|
252
|
+
| `query` | GET-параметры текущего URL (объект из `location.search`). |
|
|
253
|
+
| `path` | Путь на момент диспетчеризации: `location.pathname`, в `hash`-режиме — часть после `#`. |
|
|
254
|
+
| `url` | `location.href` на момент диспетчеризации. |
|
|
255
|
+
|
|
256
|
+
### Методы
|
|
257
|
+
|
|
258
|
+
| Метод | Назначение |
|
|
259
|
+
|---|---|
|
|
260
|
+
| `get(uri, closure, alias \| params?)` | Зарегистрировать маршрут (3-й аргумент — строка-алиас или объект). → `this` |
|
|
261
|
+
| `prefix(uri)` | Открыть вложенный контекст с префиксом. → `this` |
|
|
262
|
+
| `group(closure)` | Выполнить замыкание в контексте и закрыть его. |
|
|
263
|
+
| `middleware(fn \| fn[])` | Добавить гард(ы) в текущий контекст. → `this` |
|
|
264
|
+
| `navigate(url, { replace? })` | Перейти по адресу. В SPA-режимах — через History API без перезагрузки, с повторной диспетчеризацией; в `static` — обычный переход `location.assign` / `location.replace`. |
|
|
265
|
+
| `clone(params)` | Новый `Route` на базе текущего (слияние параметров/хуков, переопределение через `params`, ссылка на оригинал в `parent`). |
|
|
266
|
+
|
|
267
|
+
---
|
|
268
|
+
|
|
269
|
+
## 11. Примеры
|
|
270
|
+
|
|
271
|
+
Полная рабочая демонстрация (несколько страниц + общий `routes.js`) — в
|
|
272
|
+
[`examples/route/`](../../../examples/route/).
|
|
273
|
+
|
|
274
|
+
### Реакции по страницам + глобальная реакция
|
|
275
|
+
|
|
276
|
+
```js
|
|
277
|
+
const router = new Route({ match_all: true });
|
|
278
|
+
|
|
279
|
+
router.get('*', function () { // на каждой странице
|
|
280
|
+
highlightNav(this.path);
|
|
281
|
+
}, 'global');
|
|
282
|
+
router.get('index.html', () => initHome(), 'home');
|
|
283
|
+
router.get('catalog.html', function () {
|
|
284
|
+
filterCatalog(this.query.category); // ?category= из URL
|
|
285
|
+
}, 'catalog');
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
### Параметр пути + гард + алиас
|
|
289
|
+
|
|
290
|
+
```js
|
|
291
|
+
const allowed = ['1', '2'];
|
|
292
|
+
router
|
|
293
|
+
.middleware((id) => allowed.includes(id))
|
|
294
|
+
.get('product-{id}.html', function (id) {
|
|
295
|
+
document.getElementById('title').textContent = `Товар #${id}`;
|
|
296
|
+
}, 'product');
|
|
297
|
+
|
|
298
|
+
// внешний код реагирует на совпадение этого маршрута (имя пустое → двойное двоеточие)
|
|
299
|
+
document.addEventListener('route::product', (e) => track('view', e.detail.params.id));
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
### Группа с префиксом и middleware
|
|
303
|
+
|
|
304
|
+
```js
|
|
305
|
+
router.prefix('account').middleware(() => isLoggedIn).group(() => {
|
|
306
|
+
router.get('profile', () => renderProfile());
|
|
307
|
+
router.get('orders/{id}', (id) => renderOrder(id));
|
|
308
|
+
});
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
### Координация с другими механизмами через события
|
|
312
|
+
|
|
313
|
+
```js
|
|
314
|
+
// Любой модуль слушает предвестник матчинга (до сопоставления uri) без ссылки на router:
|
|
315
|
+
document.addEventListener('route', () => {
|
|
316
|
+
new Modal({ trigger: '[data-modal]' });
|
|
317
|
+
new Toggle({ trigger: '#tabs [trigger]' });
|
|
318
|
+
});
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
---
|
|
322
|
+
|
|
323
|
+
## 12. Известные особенности и ограничения
|
|
324
|
+
|
|
325
|
+
### В `static` старт один раз, на `DOMContentLoaded`
|
|
326
|
+
|
|
327
|
+
В режиме по умолчанию сопоставление и вызовы происходят однократно — это диспетчер реакций для
|
|
328
|
+
многостраничных проектов. Для SPA включите `mode: 'history'` или `'hash'`.
|
|
329
|
+
|
|
330
|
+
### `App` (`st-app`) рендерится асинхронно
|
|
331
|
+
|
|
332
|
+
На момент `DOMContentLoaded` кастомные элементы `App` могут ещё дорендериваться. Реакции, которым
|
|
333
|
+
нужна готовая App-разметка, слушайте per-instance событие `App` `'rendered'`.
|
|
334
|
+
|
|
335
|
+
### `point` входит в паттерн, не вычитается
|
|
336
|
+
|
|
337
|
+
Базовый префикс добавляется в итоговый путь маршрута и сопоставляется с полным `location.pathname`
|
|
338
|
+
(как в PHP). Для подкаталога задавайте `point` равным этому подкаталогу.
|
|
339
|
+
|
|
340
|
+
### `middleware` действует на область
|
|
341
|
+
|
|
342
|
+
Гард применяется ко всему текущему кадру/группе, а не к одной строке. Для гарда на единственный
|
|
343
|
+
маршрут используйте отдельную `prefix().group()`.
|
|
344
|
+
|
|
345
|
+
### Только `GET`
|
|
346
|
+
|
|
347
|
+
Других глаголов нет, формы/`fetch` не перехватываются — загрузка документа всегда `GET`.
|
|
348
|
+
|
|
349
|
+
---
|
|
350
|
+
|
|
351
|
+
## 13. SPA-режим: history и hash
|
|
352
|
+
|
|
353
|
+
```js
|
|
354
|
+
let router = new Route({
|
|
355
|
+
mode: 'history',
|
|
356
|
+
not_found: path => showScreen('404'),
|
|
357
|
+
});
|
|
358
|
+
|
|
359
|
+
router.get('/', () => showScreen('home'));
|
|
360
|
+
router.get('/coins/{id}', id => showScreen('coin', id));
|
|
361
|
+
|
|
362
|
+
router.navigate('/coins/btc'); // pushState + диспетчеризация
|
|
363
|
+
router.navigate('/login', { replace: true }); // replaceState
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
| Режим | Где путь | Переходы назад/вперёд | Нужна настройка сервера |
|
|
367
|
+
|---|---|---|---|
|
|
368
|
+
| `history` | `location.pathname` | `popstate` | Да: сервер отдаёт один документ на все пути приложения |
|
|
369
|
+
| `hash` | после `#`: `/#/coins/btc?tab=1` | `hashchange` | Нет |
|
|
370
|
+
|
|
371
|
+
Что меняется по сравнению со `static`:
|
|
372
|
+
|
|
373
|
+
- **Диспетчеризация на каждом переходе.** Первый разбор — как раньше, на `DOMContentLoaded`.
|
|
374
|
+
Дальше — после `navigate()`, кнопок «назад»/«вперёд» и перехваченных кликов. Перед каждым
|
|
375
|
+
разбором `params` и `query` сбрасываются.
|
|
376
|
+
- **Перехват ссылок** (`intercept_links: true`). Клик левой кнопкой по `<a href>` без
|
|
377
|
+
модификаторов ведётся через `navigate()`, если ссылка ведёт на тот же origin, путь начинается с
|
|
378
|
+
`point`, и у неё нет `target` (кроме `_self`), `download` и `rel="external"`. Якоря на той же
|
|
379
|
+
странице не перехватываются. В `hash`-режиме перехватываются только ссылки вида `href="#/…"`.
|
|
380
|
+
- **404.** Если ни один маршрут не совпал или все отсеяны middleware, вызывается хук `not_found(path)`
|
|
381
|
+
и диспатчится событие `route:<name>:404`.
|
|
382
|
+
|
|
383
|
+
> [!note] Замыкания маршрутов и повторный вход
|
|
384
|
+
> В SPA-режимах замыкание маршрута вызывается при каждом заходе на адрес. Код, который должен
|
|
385
|
+
> выполниться один раз (подписки, создание `Modal`), держите вне замыканий или защищайте флагом.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# select.js
|
|
2
|
+
|
|
3
|
+
## Описание
|
|
4
|
+
|
|
5
|
+
Заменяет нативный `<select>` кастомным дропдауном, сохраняя сам `<select>` рабочим
|
|
6
|
+
держателем значения (валидно для форм, диспатчит `change`). Один инстанс оборачивает все
|
|
7
|
+
подходящие `<select>` (модель как у `Toggle`). Открытие/закрытие идёт через атрибут `state`
|
|
8
|
+
(`closed → opening → open → closing → closed`) — внешний вид и анимацию задаёт CSS потребителя
|
|
9
|
+
по `[state]`. Поддерживает `<select multiple>`.
|
|
10
|
+
|
|
11
|
+
На каждый `<select>` создаётся структура:
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
<select-container state="closed">
|
|
15
|
+
<select-trigger>текущий выбор</select-trigger>
|
|
16
|
+
<select>…</select> <!-- визуально скрыт, держит значение -->
|
|
17
|
+
<select-options>
|
|
18
|
+
<select-option [selected] [disabled]>…</select-option>
|
|
19
|
+
…
|
|
20
|
+
</select-options>
|
|
21
|
+
</select-container>
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Конструктор
|
|
25
|
+
|
|
26
|
+
```js
|
|
27
|
+
new Select(params)
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
| Параметр | По умолчанию | Описание |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| `target` | `'select'` | Селектор / Element / NodeList нативных `<select>` |
|
|
33
|
+
| `location` | `'bottom center'` | Позиция панели: `top` / `bottom` / `left` / `right` / `center` |
|
|
34
|
+
| `action` | `'click'` | Как открывать: `'click'` (или иное событие) либо `'hover'` |
|
|
35
|
+
| `duration` | `0` | Длительность перехода, сек (для `transition` и тайминга `state`) |
|
|
36
|
+
| `allow_interrupt` | `false` | Прерывать незавершённый переход обратным действием |
|
|
37
|
+
| `close_on_select` | `true` | Закрывать после выбора (для одиночного; для `multiple` игнорируется) |
|
|
38
|
+
| `close_on_outside` | `true` | Закрывать по клику вне контейнера |
|
|
39
|
+
|
|
40
|
+
### Хуки
|
|
41
|
+
|
|
42
|
+
Передаются в `params`, привязываются к инстансу.
|
|
43
|
+
|
|
44
|
+
| Хук | Аргументы | Описание |
|
|
45
|
+
|---|---|---|
|
|
46
|
+
| `before_open` / `on_open` | `(container)` | До / после открытия панели |
|
|
47
|
+
| `before_close` / `on_close` | `(container)` | До / после закрытия панели |
|
|
48
|
+
| `before_change` | `(option, select)` | Перед выбором опции; `return false` отменяет выбор |
|
|
49
|
+
| `on_change` | `(option, select)` | После выбора и синхронизации значения |
|
|
50
|
+
| `before_init` / `on_init` | `(params)` | В начале / конце инициализации |
|
|
51
|
+
|
|
52
|
+
## Методы и геттеры
|
|
53
|
+
|
|
54
|
+
| Член | Описание |
|
|
55
|
+
|---|---|
|
|
56
|
+
| `open(el)` / `close(el)` / `toggle(el)` | Управление панелью; `el` — контейнер, `<select>` или вложенный элемент |
|
|
57
|
+
| `clone(params)` | Новый инстанс с объединёнными параметрами и `parent: this` |
|
|
58
|
+
| `refresh(target?)` | Пересобрать пункты и текст триггера по нативному `<select>` (по умолчанию — все свои): после смены `<option>` или значения из кода (`select.value = …`, `v-model`). Возвращает `this` |
|
|
59
|
+
| `destroy()` | Разобрать: снять обработчики (в том числе клик мимо на `document`), вернуть `<select>` на место контейнера с прежним `style`, убрать `select-container`. Поле можно снова передать в `new Select` |
|
|
60
|
+
| `get params()` | Текущая конфигурация (без функций) |
|
|
61
|
+
| `get value()` | Массив значений по управляемым `<select>` (для `multiple` — массив массивов) |
|
|
62
|
+
| `Select.find(el)` | Инстанс, владеющий элементом (через `own`/`find`) |
|
|
63
|
+
|
|
64
|
+
## Пример
|
|
65
|
+
|
|
66
|
+
```html
|
|
67
|
+
<form>
|
|
68
|
+
<select id="color" name="color">
|
|
69
|
+
<option value="red">Красный</option>
|
|
70
|
+
<option value="green">Зелёный</option>
|
|
71
|
+
<option value="blue">Синий</option>
|
|
72
|
+
</select>
|
|
73
|
+
<button type="submit">Отправить</button>
|
|
74
|
+
</form>
|
|
75
|
+
|
|
76
|
+
<script type="module">
|
|
77
|
+
import Select from '../dist/select.esm.min.js';
|
|
78
|
+
|
|
79
|
+
new Select({
|
|
80
|
+
target: '#color',
|
|
81
|
+
location: 'bottom center',
|
|
82
|
+
action: 'click',
|
|
83
|
+
duration: 0.2,
|
|
84
|
+
before_change: (option) => option.value !== 'blue', // запретить «Синий»
|
|
85
|
+
});
|
|
86
|
+
</script>
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
```css
|
|
90
|
+
/* Внешний вид и анимация — на CSS по атрибуту [state]. */
|
|
91
|
+
select-trigger { display: inline-block; padding: 8px 12px; border: 1px solid #ddd; }
|
|
92
|
+
|
|
93
|
+
select-options {
|
|
94
|
+
min-width: 100%; background: #fff; border: 1px solid #ddd;
|
|
95
|
+
opacity: 0; transform: translateY(-6px); pointer-events: none; transition: all .2s;
|
|
96
|
+
}
|
|
97
|
+
select-container[state="open"] select-options,
|
|
98
|
+
select-container[state="opening"] select-options {
|
|
99
|
+
opacity: 1; transform: translateY(0); pointer-events: auto;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
select-option { display: block; padding: 8px 12px; cursor: pointer; }
|
|
103
|
+
select-option:hover { background: #f3f3f3; }
|
|
104
|
+
select-option[selected] { font-weight: 700; }
|
|
105
|
+
select-option[disabled] { opacity: .4; cursor: default; }
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Замечания
|
|
109
|
+
|
|
110
|
+
- Нативный `<select>` остаётся в DOM визуально скрытым — значение уходит в форму, событие
|
|
111
|
+
`change` диспатчится при каждом выборе.
|
|
112
|
+
- Для `<select multiple>` выбор накапливается, панель не закрывается (`close_on_select`
|
|
113
|
+
игнорируется).
|
|
114
|
+
- Подключение: ESM — `import Select from '../dist/select.esm.min.js'`; глобал для CDN —
|
|
115
|
+
`<script defer src="../dist/select.min.js">`, класс доступен как `window.select`.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
# _engine.js
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# shape.js
|
|
2
|
+
|
|
3
|
+
## Описание
|
|
4
|
+
|
|
5
|
+
Фигуры по путям из Figma: углы сохраняют размер, прямые участки тянутся. В элемент первым ребёнком кладётся
|
|
6
|
+
`<svg class="shape-layer"><path/></svg>`: это фон и обводка. Сам элемент клипается тем же путём
|
|
7
|
+
(`clip-path: path()`). Форма пересчитывается, когда меняется размер элемента, брейкпоинт или атрибуты.
|
|
8
|
+
|
|
9
|
+
Каждая точка пути привязывается к ближнему краю. `x` левее середины фрейма считается от левого края,
|
|
10
|
+
правее середины - от правого; так же по `y`. Поэтому вырезы сохраняют размер, а прямые участки
|
|
11
|
+
тянутся под реальный размер элемента.
|
|
12
|
+
|
|
13
|
+
Цвета задаёт CSS. Готовые правила есть в st-style, атрибут `shape`: `--shape-bg`, `--shape-line`, `--shape-width`.
|
|
14
|
+
Умолчания там не объявлены на элементе, поэтому ховер родителя перекрашивает фигуру на дочернем `__bg`.
|
|
15
|
+
|
|
16
|
+
Подключение:
|
|
17
|
+
|
|
18
|
+
```js
|
|
19
|
+
// ESM / npm
|
|
20
|
+
import Shape from '@cat-of-summer/st-script/shape';
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
```html
|
|
24
|
+
<!-- CDN / IIFE: объявляет глобальный Shape -->
|
|
25
|
+
<script defer src="dist/shape.min.js"></script>
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Разметка
|
|
29
|
+
|
|
30
|
+
```html
|
|
31
|
+
<div shape="594 237 | M10.4 1L1 10.2V134.4L10.4 144H594V1Z" shape-lp="1200 300 | M…Z">…</div>
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
| Атрибут | Значение |
|
|
35
|
+
|---|---|
|
|
36
|
+
| `shape` | `ширина высота \| d`: размер фрейма в px макета и путь Figma как есть (абсолютные `M L H V C S Q Z`). Кривые (скругления в пару px) заменяются отрезком до конечной точки |
|
|
37
|
+
| `shape-<брейкпоинт>` | своя фигура от `min` этого брейкпоинта и шире (`shape-md`, `shape-lp`…). Берётся самый широкий подходящий брейкпоинт с заданной фигурой |
|
|
38
|
+
|
|
39
|
+
Путь копируется из Figma: Copy as SVG, атрибут `d` у `<path>` фигуры. Размер берётся из `width` и `height` того же svg.
|
|
40
|
+
|
|
41
|
+
## Статические методы
|
|
42
|
+
|
|
43
|
+
| Метод | Описание |
|
|
44
|
+
|---|---|
|
|
45
|
+
| `Shape.find(element \| selector)` | экземпляр, которому принадлежит элемент (или `undefined`) |
|
|
46
|
+
|
|
47
|
+
## Конструктор
|
|
48
|
+
|
|
49
|
+
```js
|
|
50
|
+
new Shape(params)
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### Основные параметры
|
|
54
|
+
|
|
55
|
+
| Параметр | По умолчанию | Описание |
|
|
56
|
+
|---|---|---|
|
|
57
|
+
| `target` | `'[shape]'` | элементы: селектор, Element, NodeList, массив |
|
|
58
|
+
| `attribute` | `'shape'` | имя атрибута; варианты - `<attribute>-<брейкпоинт>` |
|
|
59
|
+
| `breakpoints` | `{ xs: 360, sm: 576, md: 768, lp: 1024, lg: 1280, dt: 1536, xl: 1920 }` | шкала брейкпоинтов (min, px). По умолчанию это шкала st-style. Своя шкала проекта передаётся сюда же |
|
|
60
|
+
| `scale` | `10` | px макета в `1rem`: координаты переводятся в rem и масштабируются вместе с вёрсткой. `0` - без масштаба, 1px макета = 1px экрана |
|
|
61
|
+
|
|
62
|
+
### callbacks
|
|
63
|
+
|
|
64
|
+
| Хук | Аргументы | Когда |
|
|
65
|
+
|---|---|---|
|
|
66
|
+
| `before_init` | `params` | до привязки элементов |
|
|
67
|
+
| `on_init` | `params` | после привязки |
|
|
68
|
+
| `on_draw` | `element, d` | после каждого пересчёта формы |
|
|
69
|
+
|
|
70
|
+
## Методы
|
|
71
|
+
|
|
72
|
+
- `refresh(target = params.target)` - перечитать атрибуты и перерисовать. Элементы под `target`, которых
|
|
73
|
+
ещё нет у экземпляра, берутся под управление: так подключают разметку, добавленную после инициализации.
|
|
74
|
+
- `destroy()` - снять наблюдатели и слушатели, убрать svg, вернуть элементу прежний `clip-path`.
|
|
75
|
+
- `clone(params)` - новый экземпляр с теми же параметрами и хуками.
|
|
76
|
+
|
|
77
|
+
## Свойства
|
|
78
|
+
|
|
79
|
+
- `params` - параметры экземпляра.
|
|
80
|
+
- `elements` - элементы под управлением.
|
|
81
|
+
|
|
82
|
+
## Замечания
|
|
83
|
+
|
|
84
|
+
- Клип срезает всё, что выходит за фигуру. Выступающие картинки и тени - повод поставить фигуру на
|
|
85
|
+
дочерний слой (`__bg` с `position: absolute; inset: 0; z-index: -1`), а не на саму карточку.
|
|
86
|
+
- Обводка рисуется по краю клипа, видна её внутренняя половина: `stroke-width: 2px` даёт линию в 1px.
|
|
87
|
+
- Атрибут меняется из кода (`el.setAttribute('shape-lp', …)`) - форма перечитывается сама.
|
|
88
|
+
|
|
89
|
+
## Пример
|
|
90
|
+
|
|
91
|
+
```js
|
|
92
|
+
// Шкала брейкпоинтов проекта и макет с 1rem = 10px
|
|
93
|
+
new Shape({
|
|
94
|
+
breakpoints: { md: 768, lp: 1024 },
|
|
95
|
+
scale: 10,
|
|
96
|
+
on_draw(el, d) { el.dataset.shapeReady = ''; },
|
|
97
|
+
});
|
|
98
|
+
```
|