@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.
Files changed (68) hide show
  1. package/README.md +1 -1
  2. package/dist/app/datepicker.esm.min.js +25 -27
  3. package/dist/app/datepicker.esm.min.js.map +2 -2
  4. package/dist/app/datepicker.min.js +23 -25
  5. package/dist/app/datepicker.min.js.map +2 -2
  6. package/dist/shape.esm.min.js +2 -0
  7. package/dist/{cut.esm.min.js.map → shape.esm.min.js.map} +4 -4
  8. package/dist/shape.min.js +2 -0
  9. package/dist/shape.min.js.map +7 -0
  10. package/docs/README.md +36 -0
  11. package/docs/src/README.md +29 -0
  12. package/docs/src/_traits/README.md +8 -0
  13. package/docs/src/_traits/hasInstanceSymbol.js.md +57 -0
  14. package/docs/src/app/README.md +13 -0
  15. package/docs/src/app/datepicker/README.md +9 -0
  16. package/docs/src/app/datepicker/_calendar.js.md +1 -0
  17. package/docs/src/app/datepicker/index.js.md +153 -0
  18. package/docs/src/app/form/README.md +8 -0
  19. package/docs/src/app/form/index.js.md +560 -0
  20. package/docs/src/app/index.js.md +1302 -0
  21. package/docs/src/cookie/README.md +8 -0
  22. package/docs/src/cookie/index.js.md +80 -0
  23. package/docs/src/core/README.md +8 -0
  24. package/docs/src/core/index.js.md +178 -0
  25. package/docs/src/index.js.md +1 -0
  26. package/docs/src/loader/README.md +8 -0
  27. package/docs/src/loader/index.js.md +125 -0
  28. package/docs/src/mask/README.md +10 -0
  29. package/docs/src/mask/_engine.js.md +1 -0
  30. package/docs/src/mask/_groups.js.md +1 -0
  31. package/docs/src/mask/index.js.md +411 -0
  32. package/docs/src/modal/README.md +8 -0
  33. package/docs/src/modal/index.js.md +809 -0
  34. package/docs/src/observer/README.md +9 -0
  35. package/docs/src/observer/_engine.js.md +28 -0
  36. package/docs/src/observer/index.js.md +259 -0
  37. package/docs/src/route/README.md +8 -0
  38. package/docs/src/route/index.js.md +385 -0
  39. package/docs/src/select/README.md +8 -0
  40. package/docs/src/select/index.js.md +115 -0
  41. package/docs/src/shape/README.md +9 -0
  42. package/docs/src/shape/_engine.js.md +1 -0
  43. package/docs/src/shape/index.js.md +98 -0
  44. package/docs/src/st_button_widget/README.md +9 -0
  45. package/docs/src/st_button_widget/README.txt.md +4 -0
  46. package/docs/src/st_button_widget/index.js.md +68 -0
  47. package/docs/src/st_links_widget/README.md +9 -0
  48. package/docs/src/st_links_widget/README.txt.md +4 -0
  49. package/docs/src/st_links_widget/index.js.md +46 -0
  50. package/docs/src/st_widget/README.md +8 -0
  51. package/docs/src/st_widget/button/README.md +4 -0
  52. package/docs/src/toggle/README.md +8 -0
  53. package/docs/src/toggle/index.js.md +572 -0
  54. package/docs/src/typograf/README.md +9 -0
  55. package/docs/src/typograf/_engine.js.md +75 -0
  56. package/docs/src/typograf/index.js.md +165 -0
  57. package/docs/src/uploader/README.md +8 -0
  58. package/docs/src/uploader/index.js.md +112 -0
  59. package/docs/src/validator/README.md +8 -0
  60. package/docs/src/validator/index.js.md +113 -0
  61. package/package.json +3 -2
  62. package/src/app/datepicker/index.js +25 -25
  63. package/src/index.js +1 -1
  64. package/src/{cut → shape}/_engine.js +1 -1
  65. package/src/{cut → shape}/index.js +10 -10
  66. package/dist/cut.esm.min.js +0 -2
  67. package/dist/cut.min.js +0 -2
  68. package/dist/cut.min.js.map +0 -7
@@ -0,0 +1,75 @@
1
+ # _engine.js
2
+
3
+ ## Описание
4
+
5
+ Чистая типографика [Typograf](index.js.md) без DOM: на вход идут строки. Плоские именованные
6
+ экспорты, тесты — `node tests/typograf.test.mjs`.
7
+
8
+ ## Экспорты
9
+
10
+ | Экспорт | Что делает |
11
+ |---|---|
12
+ | `RULES` | Правила по умолчанию: `{ words, particles, numbers, dash, abbr, initials, last_word }` — все `true`, и предел `max_chain: 14` |
13
+ | `glue(parts, rules)` | Тексты подряд идущих текстовых узлов одного прогона → массив той же длины со склейками. `rules` накладываются поверх `RULES` |
14
+ | `text(str, rules)` | То же для одной строки: `glue([str], rules)[0]` |
15
+
16
+ ## Как работает `glue`
17
+
18
+ 1. Части склеиваются в одну строку — так «в `<b>`доме`</b>`» обрабатывается так же, как «в доме».
19
+ 2. Строка делится на куски текста (`\S+`, с пунктуацией) и пробельные промежутки между ними.
20
+ NBSP тоже считается пробелом, поэтому повторный прогон даёт тот же результат.
21
+ 3. Для каждого промежутка между куском `L` и куском `R` правила решают, клеить ли.
22
+ Затем `max_chain` проверяет длину получившихся цепочек (см. ниже).
23
+ 4. Склеенный промежуток целиком заменяется одним NBSP: первый символ становится ` `,
24
+ остальные (перевод строки и отступы из HTML) удаляются. Иначе после NBSP остался бы
25
+ схлопываемый пробел, а на нём строка рвётся.
26
+ 5. Результат нарезается обратно по границам частей. Часть может стать короче или пустой, но
27
+ их число и порядок не меняются.
28
+
29
+ Не трогаются: ведущие и хвостовые пробелы строки и промежутки, которые уже целиком
30
+ неразрывные (` `, узкий ` `, цифровой ` `) — авторские «10&nbsp;000» остаются как есть.
31
+
32
+ ## Правила
33
+
34
+ | Правило | Клеит промежуток, если | Пример |
35
+ |---|---|---|
36
+ | `words` | `L` — предлог, союз или частица из словаря (без учёта регистра, открывающие `(«„"'[` отбрасываются), и после него нет пунктуации | `в доме` → `в~доме`, `(на столе)`, но не `в, конце` |
37
+ | `particles` | `R` — `же`, `ж`, `ли`, `ль`, `бы`, `б` (пунктуация после допускается) | `он же` → `он~же`, `Был ли?` |
38
+ | `numbers` | `L` оканчивается цифрой | `2024 год`, `10 000 рублей`, `COVID-19 вирус` |
39
+ | `dash` | `R` — одиночное тире `—`, `–` или `-` | `Москва — столица` → `Москва~— столица` |
40
+ | `abbr` | `L` — сокращение из списка: `т.`, `тыс.`, `млн`, `млрд`, `г.`, `гг.`, `ул.`, `пр.`, `пер.`, `кв.`, `стр.`, `рис.`, `табл.`, `им.`, `см.`, `ок.`, `св.`, `№`, `§` | `т. е.`, `и т. д.`, `г. Москва`, `№ 5` |
41
+ | `initials` | `L` — заглавная буква с точкой, а `R` начинается с заглавной, или наоборот | `А. С. Пушкин`, `Пушкин А. С.`, `J. R. R. Tolkien` |
42
+ | `last_word` | промежуток между двумя последними кусками строки | `Он сказал правду` → `Он сказал~правду` |
43
+
44
+ Словарь `words`: предлоги (`в`, `во`, `на`, `по`, `с`, `со`, `к`, `ко`, `у`, `о`, `об`, `обо`,
45
+ `за`, `из`, `изо`, `до`, `от`, `при`, `под`, `подо`, `над`, `надо`, `без`, `для`, `про`, `через`,
46
+ `сквозь`, `между`, `меж`, `перед`, `передо`, `около`, `среди`, `кроме`, `вокруг`, `вдоль`,
47
+ `против`, `ради`, `вместо`, `внутри`, `сверху`, `снизу`, `возле`, `напротив`, `благодаря`,
48
+ `согласно`, `вопреки`), союзы (`и`, `а`, `но`, `да`, `или`, `либо`, `что`, `чтоб`, `чтобы`, `как`,
49
+ `если`, `ибо`, `хотя`, `пока`, `когда`, `куда`, `откуда`, `зачем`, `почему`) и частицы, которые
50
+ относятся к следующему слову (`ведь`, `лишь`, `уж`, `аж`, `то`, `ни`, `не`, `ну`, `вон`, `вот`).
51
+ Постпозитивные частицы (`же`, `ли`, `бы`) вынесены в `particles` и клеятся к предыдущему слову.
52
+
53
+ ## Предел цепочки `max_chain`
54
+
55
+ Склеенная цепочка переносится только целиком, и в узкой колонке длинная цепочка вылезает за
56
+ край. Поэтому длина цепочки в символах (промежуток считается за один) ограничена `max_chain`,
57
+ по умолчанию 14 — около 120–130 px при шрифте 16 px. `0` или `false` снимает предел.
58
+
59
+ Цепочки проверяются справа налево: если очередная связь сделала бы цепочку длиннее предела,
60
+ отпускается именно она, а связи правее остаются. Так при нехватке места рвётся самая дальняя
61
+ связь, а ближняя — предлог при своём слове — цела:
62
+
63
+ | Вход | Результат |
64
+ |---|---|
65
+ | `А когда наступал` | `А когда~наступал` (16 символов целиком — больше предела) |
66
+ | `как над городом` | `как над~городом` |
67
+ | `вопреки ожиданиям` | `вопреки ожиданиям` (17 символов) |
68
+ | `а и в доме` | `а~и~в~доме` (10 символов) |
69
+
70
+ Авторские неразрывные промежутки входят в длину, но не рвутся: в `10&nbsp;000&nbsp;000 рублей`
71
+ связь `000~рублей` ставится, хотя вся цепочка длиннее предела.
72
+
73
+ `last_word` в `glue` действует на конец всей строки. Где строка кончается на самом деле — в конце
74
+ блока или перед `<br>`, а где её просто прерывает `<code>`, — знает DOM-слой: он включает
75
+ правило только для настоящих концов строк.
@@ -0,0 +1,165 @@
1
+ # Typograf.js
2
+
3
+ ## Описание
4
+
5
+ Расставляет неразрывные пробелы в русском тексте: предлоги и союзы не висят в конце строки,
6
+ частицы не отрываются от своих слов, числа — от единиц, инициалы — от фамилий, а последнее
7
+ слово абзаца не остаётся на строке одно. Пишет прямо в `nodeValue` текстовых узлов: тегов не
8
+ добавляет, структуру DOM не меняет.
9
+
10
+ Один инстанс обслуживает все подходящие цели. Цели у экрана обрабатываются сразу, дальние —
11
+ при приближении. Правки текста (фреймворки, сторонние скрипты, `innerHTML`) подхватываются
12
+ `MutationObserver`: новый текст остаётся новым и сразу получает склейки.
13
+
14
+ Склейки не зависят от ширины: NBSP запрещает разрыв в конкретном месте, а где пройдёт перенос,
15
+ решает браузер. Поэтому ресайз ничего не пересчитывает.
16
+
17
+ ## Правила
18
+
19
+ | Правило | Что клеит | Пример |
20
+ |---|---|---|
21
+ | `words` | Предлог, союз, частицу — к следующему слову | `жил в~доме`, `а~и~в~саду`, `«в~доме»` |
22
+ | `particles` | `же`, `ли`, `бы`, `б`, `ж`, `ль` — к предыдущему слову | `он~же`, `был~бы рад` |
23
+ | `numbers` | Число — к следующему слову | `2024~год`, `10~000~рублей` |
24
+ | `dash` | Слово — к тире после него | `Москва~— столица` |
25
+ | `abbr` | Сокращение — к следующему слову | `т.~е.`, `и~т.~д.`, `г.~Москва`, `№~5` |
26
+ | `initials` | Инициалы — к фамилии | `А.~С.~Пушкин`, `Пушкин~А.~С.` |
27
+ | `last_word` | Последнее слово строки — к предпоследнему | `Он сказал~правду.` |
28
+ | `max_chain` | Не правило, а предел: цепочка не длиннее 14 символов, лишняя связь — самая дальняя — отпускается | `А когда~наступал`, `как над~городом` |
29
+
30
+ `~` — неразрывный пробел. Словари и точные условия — в [_engine.js](_engine.js.md).
31
+
32
+ **Сквозь inline-теги.** Текст абзаца склеивается в одну строку через элементы с вычисленным
33
+ `display: inline` или `contents` (`<b>`, `<a>`, `<span>`, `<em>`…): `в <b>доме</b>`,
34
+ `<a>на</a> сайте` клеятся так же, как обычный текст. Слово, разрезанное тегом (`сло<b>во</b>`),
35
+ со словарным «во» не путается.
36
+
37
+ **Где кончается строка.** Прогон текста прерывают блочные элементы, `inline-block`, замещаемые
38
+ элементы и пропускаемые. `last_word` срабатывает в конце блока и перед `<br>`; там, где строку
39
+ прерывает `<code>` или `inline-block`, — нет.
40
+
41
+ ## Что не трогается
42
+
43
+ - Элементы под `skip` (по умолчанию `script`, `style`, `noscript`, `template`, `code`, `pre`,
44
+ `textarea`, `kbd`, `samp`, `var`, `svg`, `math`, редактируемые `[contenteditable]` и
45
+ `[typograf-skip]`). Правки внутри них не вызывают обработку — ввод в редактор не правится
46
+ под курсором.
47
+ - Блоки с вычисленным `white-space: pre`, `pre-wrap`, `pre-line`, `break-spaces`: там перевод
48
+ строки значимый, и замена пробела на NBSP сломала бы вёрстку.
49
+ - Промежутки, уже целиком неразрывные: авторские `&nbsp;`, узкий пробел `&#8239;`.
50
+
51
+ ## Конструктор
52
+
53
+ ```js
54
+ new Typograf(params)
55
+ ```
56
+
57
+ | Параметр | По умолчанию | Описание |
58
+ |---|---|---|
59
+ | `target` | `'[typograf]'` | Селектор / Element / NodeList целей |
60
+ | `root` | `null` | Контейнер прокрутки для ленивости (селектор / Element); `null` — viewport |
61
+ | `lazy` | `true` | Обрабатывать цель, когда до неё остаётся не больше экрана. `false` — все цели сразу |
62
+ | `live` | `false` | Подхватывать новые цели по `target` (`MutationObserver` на документе). Только для строкового `target` |
63
+ | `rules` | `{}` | Поверх правил по умолчанию: `{ last_word: false }` выключает одно правило, `{ max_chain: 20 }` меняет предел цепочки, `{ max_chain: 0 }` снимает его |
64
+ | `skip` | см. выше | Селектор того, что не трогается. Свой список заменяет стандартный целиком |
65
+
66
+ ### Хуки
67
+
68
+ Передаются в `params` и привязываются к инстансу (`this` — Typograf). Ошибка в хуке пишется в
69
+ консоль и не мешает обработке.
70
+
71
+ | Хук | Аргументы | Когда |
72
+ |---|---|---|
73
+ | `before_init` / `on_init` | `(params)` | В начале и в конце конструктора |
74
+ | `on_apply` | `(el)` | Цель обработана: первый раз или после правки её текста |
75
+
76
+ ## Публичные методы и свойства
77
+
78
+ | Член | Описание |
79
+ |---|---|
80
+ | `observe(target)` | Взять цели в работу, в том числе отпущенные раньше через `unobserve`; возвращает `this` |
81
+ | `unobserve(target)` | Отпустить цели и вернуть их исходный текст; при `live` по селектору заново не берутся |
82
+ | `apply(target?)` | Обработать сейчас, мимо ленивости; без аргумента — все цели |
83
+ | `refresh()` | Пересканировать `target`, отпустить ушедшие из DOM, пересчитать цели у экрана |
84
+ | `destroy()` | Отключить наблюдателей и вернуть исходный текст всем целям |
85
+ | `clone(params)` | Новый инстанс с объединёнными параметрами (`rules` мержатся) и `parent: this` |
86
+ | `params` | Конфигурация без функций |
87
+ | `elements` | Цели в работе |
88
+ | `Typograf.find(el)` | Инстанс, владеющий целью |
89
+ | `Typograf.text(str, rules?)` | Типографика строки без DOM: для шаблонов, `title`, `alt` |
90
+
91
+ ## Как устроено внутри
92
+
93
+ - **Движок** — чистые функции [_engine.js](_engine.js.md): `glue(parts)` получает тексты
94
+ текстовых узлов одного прогона и возвращает их со склейками, сохраняя число частей.
95
+ - **Обход** — цель обходится по дереву; текстовые узлы собираются в прогоны до первой
96
+ границы (блок, `<br>`, `inline-block`, пропускаемый элемент). Каждый прогон проходит через
97
+ движок; узел перезаписывается, только если его текст изменился.
98
+ - **Исходный текст** — на уровне модуля два `WeakMap`: `originals` (текст до первой правки) и
99
+ `written` (что записано последним). Обработка всегда идёт от исходного текста, поэтому при
100
+ дописывании абзаца склейка прежнего последнего слова снимается. Если `nodeValue` отличается
101
+ от `written`, текст изменил кто-то другой — новое значение становится исходным.
102
+ - **Свои записи** — отличаются от чужих сравнением с `written`, без `takeRecords()`: чужие
103
+ правки, пришедшие в том же такте, не теряются.
104
+ - **Правки** — `MutationObserver` по каждой цели (при `live` — один на документ). Правка
105
+ пересчитывает только блок, в котором произошла: подъём от узла по inline-предкам.
106
+ - **Ленивость** — `IntersectionObserver` с `rootMargin: 100%`. Цели у экрана обрабатываются
107
+ синхронно в конструкторе, без мигания сырого текста. Правка в далёкой цели помечает её
108
+ грязной и применяется при подходе.
109
+
110
+ ## Примеры
111
+
112
+ ### Весь контент статьи
113
+
114
+ ```html
115
+ <article typograf>…</article>
116
+ <script defer src="dist/typograf.min.js"></script>
117
+ <script>addEventListener('DOMContentLoaded', () => new Typograf())</script>
118
+ ```
119
+
120
+ ### Контент, который рендерит фреймворк
121
+
122
+ ```js
123
+ new Typograf({ target: '[typograf]', live: true }); // новые [typograf] подхватываются сами
124
+ ```
125
+
126
+ Правки текста внутри целей подхватываются и без `live`; он нужен, только когда в DOM
127
+ появляются новые цели.
128
+
129
+ ### Только заголовки и лид, без последнего слова
130
+
131
+ ```js
132
+ new Typograf({ target: 'h1, h2, .lead', rules: { last_word: false } });
133
+ ```
134
+
135
+ ### Строка без DOM
136
+
137
+ ```js
138
+ el.title = Typograf.text('Скидка 10 % на все товары в магазине');
139
+ ```
140
+
141
+ ### Отключить на фрагменте
142
+
143
+ ```html
144
+ <p typograf>Обычный текст. <span typograf-skip>Здесь — как написано.</span></p>
145
+ ```
146
+
147
+ Демо со всеми правилами, живыми правками и ленивым блоком — `examples/typograf.html`.
148
+
149
+ ## Ограничения
150
+
151
+ - **Inline определяется по вычисленному `display`.** `<span style="display:block">` —
152
+ граница прогона, `<div style="display:inline">` — нет. Так склейки следуют вёрстке, но
153
+ обход цели вызывает `getComputedStyle` для каждого элемента.
154
+ - **Узкие колонки.** Цепочка склеенных слов переносится только целиком. Предел `max_chain: 14`
155
+ держит цепочки в ~120–130 px при шрифте 16 px; в колонке уже этого цепочка вылезет, как
156
+ вылезло бы и одно длинное слово. Для крупного шрифта или узких карточек уменьшите
157
+ `max_chain`, для широкой колонки его можно поднять.
158
+ - **Текст, переписанный чужим кодом из обработанного,** несёт уже поставленные NBSP:
159
+ `el.textContent = el.textContent + '…'` сохранит прежние склейки, и после `destroy()` они
160
+ останутся.
161
+ - **Ленивость считает от viewport.** При `lazy: true` цели дальше экрана от видимой области не
162
+ обработаны, пока до них не дошла прокрутка: копирование текста страницы или поиск по ней
163
+ увидят их без склеек. Для таких случаев — `lazy: false` или `apply()`.
164
+ - **Одна цель — один Typograf.** Цель, уже занятая другим инстансом, пропускается с
165
+ предупреждением.
@@ -0,0 +1,8 @@
1
+ <!-- DOCGEN:START -->
2
+ # uploader
3
+
4
+ ## Файлы
5
+
6
+ - [index.js](index.js.md)
7
+
8
+ <!-- DOCGEN:END -->
@@ -0,0 +1,112 @@
1
+ # uploader.js
2
+
3
+ ## Описание
4
+
5
+ Компонент загрузки файлов с поддержкой drag & drop, предпросмотром изображений, ограничениями (количество, размер, типы) и поддержкой уже существующих файлов (для редактирования). Структура HTML описывается через атрибуты-маркеры.
6
+
7
+ Подключение:
8
+
9
+ ```js
10
+ // ESM / npm
11
+ import Uploader from '@cat-of-summer/st-script/uploader';
12
+ ```
13
+
14
+ ```html
15
+ <!-- CDN / IIFE: объявляет глобальный Uploader -->
16
+ <script defer src="dist/uploader.min.js"></script>
17
+ ```
18
+
19
+ ## Статические методы
20
+
21
+ | Метод | Описание |
22
+ |---|---|
23
+ | `Uploader.formatSize(bytes)` | Преобразует байты в читаемую строку (Б, КБ, МБ, ГБ, ТБ) |
24
+ | `Uploader.find(element \| selector)` | Возвращает экземпляр, которому принадлежит контейнер (или `undefined`) |
25
+
26
+ ## Конструктор
27
+
28
+ ```js
29
+ new Uploader(params)
30
+ ```
31
+
32
+ ### Основные параметры
33
+
34
+ | Параметр | Описание |
35
+ |---|---|
36
+ | `target` | Корневой контейнер: CSS-селектор (можно несколько совпадений), элемент или список элементов |
37
+ | `input_name` | Имя `<input file>` для передачи файлов в форме. Обязателен. При `limits.files != 1` к нему дописывается `[]` |
38
+ | `delete_name` | Имя поля для значений удалённых существующих файлов (по умолчанию `<input_name>_to_delete`) |
39
+ | `entry` | Шаблон записи файла: CSS-селектор существующих записей (по умолчанию `'*[file-item]'`) или HTML-строка |
40
+
41
+ Шаблон записи берётся в таком порядке: первая существующая запись по селектору `entry`, HTML из `entry`, содержимое `<template entry>` внутри контейнера. Если ничего не нашлось, конструктор бросает ошибку.
42
+
43
+ ### callbacks
44
+
45
+ `before_init`, `on_init`, `before_files_add`, `on_files_add`, `before_file_delete`, `on_file_delete`, `before_drop`, `on_drop`, `handle_exception`
46
+
47
+ Колбэки привязываются к контейнеру: внутри них `this` — элемент `target`. `before_file_delete` может вернуть `false`, чтобы отменить удаление по кнопке.
48
+
49
+ ### `limits`
50
+
51
+ | Параметр | Описание |
52
+ |---|---|
53
+ | `limits.files` | Макс. количество файлов (`0` = без ограничений) |
54
+ | `limits.file_size` | Макс. размер одного файла в байтах |
55
+ | `limits.total_size` | Макс. общий размер всех файлов в байтах |
56
+ | `limits.mimes` | Допустимые MIME-типы (`['image/*', 'application/pdf']`) |
57
+
58
+ ### Ошибки лимитов
59
+
60
+ Нарушение лимита сначала вызывает событие `uploader:error`, затем `handle_exception(error)`. У `error` есть `message`, `file` и `code`: `0` — количество, `1` — размер файла, `2` — общий размер, `3` — тип. Если `handle_exception` не задан и ни один слушатель события не вызвал `preventDefault()`, показывается `alert`.
61
+
62
+ ## HTML-маркеры в шаблоне
63
+
64
+ | Атрибут | На каком элементе | Описание |
65
+ |---|---|---|
66
+ | `add-button` | `<button>` или `<div>` | Кнопка добавления файла |
67
+ | `drop-zone` | любой | Зона drag & drop |
68
+ | `files-list` | любой | Контейнер списка файлов |
69
+ | `file-item` | любой | Запись файла |
70
+ | `entry` | `<template>` | Шаблон записи, если существующих записей нет |
71
+ | `preview` | `<img>` | Превью изображения |
72
+ | `filename` | любой | Название файла |
73
+ | `fileweight` | любой | Размер файла |
74
+ | `delete-button` | `<button>` | Кнопка удаления |
75
+
76
+ ## События
77
+
78
+ Вызываются на контейнере `target` и всплывают:
79
+
80
+ | Событие | `detail` | Когда |
81
+ |---|---|---|
82
+ | `uploader:add` | `{ files }` | Добавлены файлы, прошедшие лимиты (после `on_files_add`) |
83
+ | `uploader:delete` | `{ file }` | Запись удалена кнопкой или `clear()` (после `on_file_delete`) |
84
+ | `uploader:error` | `{ error }` | Нарушен лимит. Отменяемое: `preventDefault()` убирает `alert` |
85
+
86
+ ## Методы
87
+
88
+ - `uploader.clear()` — убрать все записи из всех контейнеров экземпляра. Для каждой вызываются `on_file_delete` и `uploader:delete`; `before_file_delete` не спрашивается. Существующие файлы уходят в `delete_name`, как при удалении кнопкой.
89
+ - `target.clear()` — то же для одного контейнера.
90
+ - `uploader.destroy()` — разобрать: снять обработчики и скрытое поле выбора файлов. Записи и поля с файлами остаются в разметке, контейнер можно передать в новый `Uploader`.
91
+
92
+ ## Свойства `target` после инициализации
93
+
94
+ - `target.files` (тип `Map`) — все выбранные файлы
95
+ - `target.total_size` — общий размер прикреплённых файлов
96
+
97
+ ## Пример
98
+
99
+ ```js
100
+ new Uploader({
101
+ target: '.upload-wrapper',
102
+ input_name: 'FILES',
103
+ delete_name: 'FILES_TO_DELETE',
104
+ limits: {
105
+ files: 3,
106
+ file_size: 5 * 1024 * 1024,
107
+ mimes: ['image/*', 'application/pdf']
108
+ }
109
+ });
110
+
111
+ document.addEventListener('uploader:add', e => console.log('Добавлено:', e.detail.files));
112
+ ```
@@ -0,0 +1,8 @@
1
+ <!-- DOCGEN:START -->
2
+ # validator
3
+
4
+ ## Файлы
5
+
6
+ - [index.js](index.js.md)
7
+
8
+ <!-- DOCGEN:END -->
@@ -0,0 +1,113 @@
1
+ # validator.js
2
+
3
+ ## Описание
4
+
5
+ Валидирует поля (и любые элементы) по набору правил на заданных событиях. Один инстанс
6
+ обслуживает все подходящие элементы (модель как у `Select` и `Mask`). Результат проверки
7
+ отдаётся тремя путями:
8
+
9
+ - атрибут `state="valid" | "invalid"` на самом элементе — внешний вид задаёт CSS потребителя;
10
+ - `setCustomValidity` — нативная валидация формы (`:invalid`, `reportValidity`, блокировка submit);
11
+ - хуки `on_valid` / `on_invalid` / `on_check`.
12
+
13
+ Порядок проверки: встроенные ограничения браузера (`required`, `type`, `pattern`, …, только при
14
+ `native: true`) → наличие `attribute` → правила `test` по очереди до первого провала.
15
+
16
+ ## Конструктор
17
+
18
+ ```js
19
+ new Validator(params)
20
+ ```
21
+
22
+ | Параметр | По умолчанию | Описание |
23
+ |---|---|---|
24
+ | `target` | `'[validate]'` | Селектор / Element / NodeList / Array валидируемых элементов |
25
+ | `events` | `['input', 'blur']` | События, запускающие проверку |
26
+ | `test` | `null` | Правило или массив правил (все должны пройти): `RegExp`, строка-regexp или `fn(el)` |
27
+ | `property` | `null` | Свойство элемента, к которому применяются regexp-правила (`innerHTML`, `textContent`, …) |
28
+ | `attribute` | `null` | Атрибут обязан присутствовать; без `property` regexp-правила проверяют его значение |
29
+ | `message` | `'Некорректное значение'` | Сообщение об ошибке: строка или `fn(el)` |
30
+ | `native` | `true` | Учитывать встроенные ограничения и вызывать `setCustomValidity` (если он есть у элемента) |
31
+ | `check_on_init` | `false` | Сразу проверить все элементы с проставлением `state` и вызовом хуков |
32
+
33
+ Источник строки для regexp-правил: `property` → значение `attribute` → `el.value`.
34
+
35
+ Функция-правило возвращает `true`/`false` или строку — строка означает «невалидно» с этим
36
+ сообщением вместо `message`.
37
+
38
+ ### Хуки
39
+
40
+ Передаются в `params`, привязываются к инстансу.
41
+
42
+ | Хук | Аргументы | Описание |
43
+ |---|---|---|
44
+ | `before_check` | `(el)` | Перед проверкой; `return false` отменяет её |
45
+ | `on_valid` | `(el)` | Элемент прошёл проверку |
46
+ | `on_invalid` | `(el, message)` | Элемент не прошёл проверку |
47
+ | `on_check` | `(el, valid, message)` | После каждой проверки |
48
+ | `before_init` / `on_init` | `(params)` | В начале / конце инициализации |
49
+
50
+ ## Методы и геттеры
51
+
52
+ | Член | Описание |
53
+ |---|---|
54
+ | `check(target?)` | Проверить элементы (по умолчанию — все свои): `state`, `setCustomValidity`, хуки. Возвращает `true`, если все валидны |
55
+ | `reset(target?)` | Снять `state`; `setCustomValidity` пересчитывается без хуков, чтобы submit оставался заблокированным |
56
+ | `clone(params)` | Новый инстанс с объединёнными параметрами и `parent: this` |
57
+ | `destroy()` | Разобрать: снять обработчики (в том числе `reset` на форме), `state`, `setCustomValidity` и `el.check()`/`el.reset()` со своих полей. На поле можно поднять новый Validator |
58
+ | `get params()` | Текущая конфигурация (без хуков) |
59
+ | `get valid()` | Массив `boolean` по привязанным элементам — без `state` и хуков |
60
+ | `Validator.find(el)` | Инстанс, владеющий элементом |
61
+
62
+ На самом элементе публикуются `el.check()` и `el.reset()`.
63
+
64
+ ## Поведение
65
+
66
+ - При инициализации каждый элемент проверяется «тихо»: только `setCustomValidity`, без
67
+ `state` и хуков. Нативный submit блокируется сразу, хотя поле ещё не трогали.
68
+ - Попытка отправить форму вызывает у невалидных полей событие `invalid` — валидатор
69
+ ловит его и делает полную проверку, так что поля получают `state="invalid"`.
70
+ - Сброс формы (`reset`) снимает `state` с её полей.
71
+ - На элемент можно привязать только один валидатор — повторная привязка бросает исключение.
72
+ Несколько правил задаются массивом в `test`.
73
+
74
+ ## Пример
75
+
76
+ ```html
77
+ <form>
78
+ <label>
79
+ E-mail
80
+ <input type="text" name="email" required>
81
+ </label>
82
+ <button type="submit">Отправить</button>
83
+ </form>
84
+
85
+ <script type="module">
86
+ import Validator from '../dist/validator.esm.min.js';
87
+
88
+ new Validator({
89
+ target: 'input[name=email]',
90
+ test: [
91
+ /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
92
+ el => !el.value.endsWith('.ru') || 'Домены .ru не принимаются',
93
+ ],
94
+ message: 'Введите e-mail',
95
+ on_invalid: (el, message) => console.log(message),
96
+ });
97
+ </script>
98
+ ```
99
+
100
+ ```css
101
+ /* Внешний вид — на CSS по атрибуту [state]. */
102
+ [state="valid"] { border-color: green; }
103
+ [state="invalid"] { border-color: red; }
104
+ label:has([state="invalid"]) { color: red; }
105
+ ```
106
+
107
+ ## Замечания
108
+
109
+ - Для элементов без `setCustomValidity` (`div` и т. п.) работают только `state` и хуки.
110
+ - С `native: false` встроенные ограничения браузера не учитываются, а `setCustomValidity`
111
+ не вызывается — валидатор судит только по `attribute` и `test`.
112
+ - Подключение: ESM — `import Validator from '../dist/validator.esm.min.js'`; глобал для CDN —
113
+ `<script defer src="../dist/validator.min.js">`, класс доступен как `window.Validator`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cat-of-summer/st-script",
3
- "version": "1.4.1",
3
+ "version": "1.5.0",
4
4
  "description": "Standalone JS classes/components (Modal, App, Typograf , …), shipped as ESM and IIFE/CDN builds.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -10,7 +10,8 @@
10
10
  },
11
11
  "files": [
12
12
  "src",
13
- "dist"
13
+ "dist",
14
+ "docs/**/*.md"
14
15
  ],
15
16
  "exports": {
16
17
  "./*": "./dist/*.esm.min.js",
@@ -24,6 +24,7 @@ const ICON = '<svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke
24
24
  // Календарь: поле с маской ДД.ММ.ГГГГ (или два — для диапазона), кнопка и всплывающая сетка
25
25
  // месяца; inline — только сетка с кнопками "Сбросить" и "Выбрать". В форму уходит ISO из
26
26
  // скрытых полей: name — одиночная дата, name_from и name_to — диапазон.
27
+ // Разметка — template ниже; разметка внутри <st-app> её заменяет (свой шаблон в проекте).
27
28
  // Регистрация — App.create(datepicker); Mask входит в бандл, App — нет.
28
29
  export default {
29
30
  app: 'datepicker',
@@ -62,33 +63,32 @@ export default {
62
63
  return this.year ? title(this.year, this.month) : '';
63
64
  },
64
65
 
66
+ // Корень — сам <st-app app="datepicker">: стили — от [app="datepicker"], модификаторы — на элементах.
65
67
  template: `
66
- <div class="datepicker" #class="{ 'datepicker--range': range, 'datepicker--inline': inline, 'datepicker--open': is_open, 'datepicker--invalid': invalid }">
67
- <div class="datepicker__field" #show="!inline">
68
- <input class="datepicker__input" datepicker-from type="text" inputmode="numeric" autocomplete="off" id="{{ inputId }}" required="{{ required }}">
69
- <span class="datepicker__dash" #show="range" aria-hidden="true">—</span>
70
- <input class="datepicker__input" datepicker-to type="text" inputmode="numeric" autocomplete="off" aria-label="Конец периода" #show="range" required="{{ required && range }}">
71
- <button class="datepicker__toggle" type="button" aria-label="Открыть календарь" aria-haspopup="dialog" aria-expanded="{{ is_open }}" @click="toggle()">${ICON}</button>
68
+ <div class="datepicker__field" #class="{ 'datepicker__field--invalid': invalid }" #show="!inline">
69
+ <input class="datepicker__input" datepicker-from type="text" inputmode="numeric" autocomplete="off" id="{{ inputId }}" required="{{ required }}">
70
+ <span class="datepicker__dash" #show="range" aria-hidden="true">—</span>
71
+ <input class="datepicker__input" datepicker-to type="text" inputmode="numeric" autocomplete="off" aria-label="Конец периода" #show="range" required="{{ required && range }}">
72
+ <button class="datepicker__toggle" type="button" aria-label="Открыть календарь" aria-haspopup="dialog" aria-expanded="{{ is_open }}" @click="toggle()">${ICON}</button>
73
+ </div>
74
+ <input type="hidden" datepicker-value="from" name="{{ name ? (range ? name + '_from' : name) : '' }}">
75
+ <input type="hidden" datepicker-value="to" name="{{ name && range ? name + '_to' : '' }}" disabled="{{ !range }}">
76
+ <div class="datepicker__popup" #class="{ 'datepicker__popup--inline': inline }" role="dialog" aria-label="Выбор даты" hidden="{{ !inline && !is_open }}">
77
+ <div class="datepicker__nav">
78
+ <button class="datepicker__prev" type="button" aria-label="Предыдущий месяц" @click="go(-1)">‹</button>
79
+ <span class="datepicker__caption" aria-live="polite">{{ caption }}</span>
80
+ <button class="datepicker__next" type="button" aria-label="Следующий месяц" @click="go(1)">›</button>
72
81
  </div>
73
- <input type="hidden" datepicker-value="from" name="{{ name ? (range ? name + '_from' : name) : '' }}">
74
- <input type="hidden" datepicker-value="to" name="{{ name && range ? name + '_to' : '' }}" disabled="{{ !range }}">
75
- <div class="datepicker__popup" role="dialog" aria-label="Выбор даты" hidden="{{ !inline && !is_open }}">
76
- <div class="datepicker__nav">
77
- <button class="datepicker__prev" type="button" aria-label="Предыдущий месяц" @click="go(-1)">‹</button>
78
- <span class="datepicker__caption" aria-live="polite">{{ caption }}</span>
79
- <button class="datepicker__next" type="button" aria-label="Следующий месяц" @click="go(1)">›</button>
80
- </div>
81
- <div class="datepicker__grid">
82
- <span class="datepicker__weekday" aria-hidden="true" #for="day in weekdays">{{ day }}</span>
83
- <button class="datepicker__day" type="button" #for="cell in days" #key="$index"
84
- #class="{ 'datepicker__day--other': cell.other, 'datepicker__day--today': cell.today, 'datepicker__day--selected': cell.selected, 'datepicker__day--in-range': cell.in_range, 'datepicker__day--range-from': cell.range_from, 'datepicker__day--range-to': cell.range_to }"
85
- disabled="{{ cell.disabled }}" aria-pressed="{{ cell.selected }}" aria-label="{{ cell.label }}"
86
- @click="pick(cell.iso)">{{ cell.day }}</button>
87
- </div>
88
- <div class="datepicker__buttons" #show="inline">
89
- <button class="datepicker__reset" type="button" @click="clear()">Сбросить</button>
90
- <button class="datepicker__apply" type="button" @click="apply()">Выбрать</button>
91
- </div>
82
+ <div class="datepicker__grid">
83
+ <span class="datepicker__weekday" aria-hidden="true" #for="day in weekdays">{{ day }}</span>
84
+ <button class="datepicker__day" type="button" #for="cell in days" #key="$index"
85
+ #class="{ 'datepicker__day--other': cell.other, 'datepicker__day--today': cell.today, 'datepicker__day--selected': cell.selected, 'datepicker__day--in-range': cell.in_range, 'datepicker__day--range-from': cell.range_from, 'datepicker__day--range-to': cell.range_to }"
86
+ disabled="{{ cell.disabled }}" aria-pressed="{{ cell.selected }}" aria-label="{{ cell.label }}"
87
+ @click="pick(cell.iso)">{{ cell.day }}</button>
88
+ </div>
89
+ <div class="datepicker__buttons" #show="inline">
90
+ <button class="datepicker__reset" type="button" @click="clear()">Сбросить</button>
91
+ <button class="datepicker__apply" type="button" @click="apply()">Выбрать</button>
92
92
  </div>
93
93
  </div>`,
94
94
 
package/src/index.js CHANGED
@@ -14,4 +14,4 @@ export { default as Toggle } from './toggle/index.js';
14
14
  export { default as Typograf } from './typograf/index.js';
15
15
  export { default as Uploader } from './uploader/index.js';
16
16
  export { default as Validator } from './validator/index.js';
17
- export { default as Cut } from './cut/index.js';
17
+ export { default as Shape } from './shape/index.js';
@@ -1,4 +1,4 @@
1
- // Фигура с вырезами: путь из Figma → путь под реальный размер элемента. Чистые функции без DOM.
1
+ // Фигура по пути из Figma → путь под реальный размер элемента. Чистые функции без DOM.
2
2
  //
3
3
  // Значение атрибута — "ширина высота | d": размер фрейма в px макета и путь Figma как есть
4
4
  // (абсолютные M L H V C S Q Z). Кривые — скругления углов в пару px — заменяются отрезком