startup-ui 0.12.0 → 1.0.0

package/llms/components/data/stree.md

@@ -0,0 +1,213 @@
+# STree
+
+Дерево элементов.
+
+<SToggleGroup>
+    <SToggle title="Что будет ценно улучшить?">
+        <ol>
+            <li>Если сейчас перетаскивать элементы, но ничего не делать по drop-событию, то они не перетаскиваются.</li>
+        </ol>
+    </SToggle>
+</SToggleGroup>
+
+## Базовый пример
+
+```vue
+<template>
+    <STree :data="pages" />
+</template>
+<script setup>
+const pages = [
+    { id: 1, label: 'Главная' },
+    { id: 2, label: 'Каталог', children: [
+        { id: 3, label: 'Электроника' },
+        { id: 4, label: 'Одежда' },
+    ] },
+    { id: 5, label: 'Контакты' },
+]
+</script>
+```
+
+Где `pages` — это массив вида: `[{id, label, children: [...]}, ...]`
+
+## Выбор элемента
+
+Для возможности выбора элемента добавляем атрибут <strong>selectable</strong>
+
+```vue
+<template>
+    <STree :data="pages" selectable v-model="value" />
+    <p>В модель подставляется ID. Текущее значение: <code>{{ value ?? 'null' }}</code></p>
+</template>
+<script setup>
+import { ref } from 'vue'
+const value = ref(null)
+const pages = [
+    { id: 1, label: 'Главная' },
+    { id: 2, label: 'Каталог', children: [
+        { id: 3, label: 'Электроника' },
+        { id: 4, label: 'Одежда' },
+    ] },
+    { id: 5, label: 'Контакты' },
+]
+</script>
+```
+
+Также изменения можно отслеживать с помощью change-события:
+
+```vue
+<template>
+    <STree :data="pages" selectable @change="(node) => console.log(node)" />
+</template>
+<script setup>
+const pages = [
+    { id: 1, label: 'Главная' },
+    { id: 2, label: 'Каталог' },
+    { id: 5, label: 'Контакты' },
+]
+</script>
+```
+
+## Кастомный шаблон элемента
+
+```vue
+<template>
+    <STree :data="pages">
+        <template #node="{ node }">
+            <FontAwesomeIcon :icon="node.icon" v-if="node.icon" /> {{ node.label }}
+        </template>
+    </STree>
+</template>
+<script setup>
+const pages = [
+    { id: 1, label: 'Главная', icon: 'house' },
+    { id: 2, label: 'Каталог', icon: 'folder' },
+    { id: 5, label: 'Контакты', icon: 'envelope' },
+]
+</script>
+```
+
+## Раскрытые корневые элементы
+
+Набор раскрытых корневых элементов передаём с помощью атрибута <strong>expanded-keys</strong>
+
+```vue
+<template>
+    <STree :data="pages" :expanded-keys="[2]" />
+</template>
+<script setup>
+const pages = [
+    { id: 1, label: 'Главная' },
+    { id: 2, label: 'Каталог', children: [
+        { id: 3, label: 'Электроника' },
+        { id: 4, label: 'Одежда' },
+    ] },
+    { id: 5, label: 'Контакты' },
+]
+</script>
+```
+
+## Перетаскивание элементов
+
+Для поддержки перетаскивания элементов добавляем атрибут <strong>draggable</strong>
+
+```vue
+<template>
+    <STree :data="pages" draggable @drop="onDrop" />
+</template>
+<script setup>
+const pages = [
+    { id: 1, label: 'Главная' },
+    { id: 2, label: 'Каталог', children: [
+        { id: 3, label: 'Электроника' },
+        { id: 4, label: 'Одежда' },
+    ] },
+    { id: 5, label: 'Контакты' },
+]
+
+function onDrop(targetNode, event, dropType) {
+    console.log('Dropped on:', targetNode.label, 'Type:', dropType)
+    // Your node-reordering logic on the pages array goes here
+}
+</script>
+```
+
+При этом выполняются события:
+
+<ul>
+    <li><strong>dragstart(node, event)</strong> — при начале перетаскивания;</li>
+    <li><strong>drop(targetNode, event, dropType)</strong> — при заверешнии перетаскивания.</li>
+</ul>
+
+## Чек-боксы
+
+Для поддержки чек-боксов у элементов добавляем атрибут <strong>checkboxes</strong>
+
+```vue
+<template>
+    <STree v-model="selectedPageIds" :data="pages" checkboxes />
+    <p>Выбрано: <code>{{ selectedPageIds }}</code></p>
+</template>
+<script setup>
+import { ref } from 'vue'
+const selectedPageIds = ref([])
+const pages = [
+    { id: 1, label: 'Главная' },
+    { id: 2, label: 'Каталог', children: [
+        { id: 3, label: 'Электроника' },
+        { id: 4, label: 'Одежда' },
+    ] },
+    { id: 5, label: 'Контакты' },
+]
+</script>
+```
+
+Если нужно, чтобы при выборе чек-бокса автоматически выбирались чек-боксы вложенных элементов, добавьте атрибут **select-with-children**:
+
+```vue
+<template>
+    <STree v-model="selectedPageIds" :data="pages" checkboxes select-with-children />
+    <p>Выбрано: <code>{{ selectedPageIds }}</code></p>
+</template>
+<script setup>
+import { ref } from 'vue'
+const selectedPageIds = ref([])
+const pages = [
+    { id: 1, label: 'Главная' },
+    { id: 2, label: 'Каталог', children: [
+        { id: 3, label: 'Электроника' },
+        { id: 4, label: 'Одежда' },
+    ] },
+    { id: 5, label: 'Контакты' },
+]
+</script>
+```
+
+## Интерфейс компонента
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| data | `STreeNode[]` | - | Массив данных дерева. |
+| expandedKeys | `(string \| number)[]` | `[]` | Список ID раскрытых узлов. |
+| draggable | boolean | `false` | Разрешить перетаскивание узлов. |
+| selectable | boolean | `false` | Разрешить выбор одного узла (через клик). |
+| checkboxes | boolean | `false` | Отображать чекбоксы для множественного выбора. |
+| selectWithChildren | boolean | `false` | При выборе родителя выбирать всех его детей. |
+| storeExpandedKeysTo | string | - | Ключ в `localStorage` для сохранения состояния раскрытых узлов. |
+| bordered | boolean | `false` | Добавить границы вокруг ячеек. |
+
+### События (Events)
+
+| Название | Параметры | Описание |
+|----------|-----------|----------|
+| dragstart | `(node: STreeNode, event: DragEvent)` | Вызывается при начале перетаскивания узла. |
+| drop | `(targetNode: STreeNode, event: DragEvent, dropType: string \| undefined)` | Вызывается при завершении перетаскивания. |
+| change | `(node: STreeNode)` | Вызывается при смене выбранного узла (если `selectable`). |
+
+### Слоты (Slots)
+
+| Название | Параметры | Описание |
+|----------|-----------|----------|
+| node | `{ node: STreeNode }` | Кастомный шаблон для содержимого узла дерева. |

package/llms/components/forms/scheckbox.md

@@ -0,0 +1,139 @@
+# SCheckboxGroup > SCheckbox
+
+Одиночная галочка или набор галочек.
+
+<SToggleGroup>
+    <SToggle title="В чем отличие от аналогов?">
+        <p>В отличие от популярных библиотек компонентов для Vue3:</p>
+        <ol>
+            <li>Сразу идет с кликабельным стандартизированным лейблом в качестве простого атрибута. Это унифицирует код и внешний вид компонентов, упрощается поддержка и взаимозаменяемость.</li>
+            <li>Поддерживает три формата передачи опций в группы чекбоксов, что удобно в зависимости от кейса:
+            <ol>
+                <li><code>&lt;SCheckbox /&gt;</code> — там где опции являются частью дизайна, их можно и удобно хардкодить в шаблон;</li>
+                <li><code>{value1: title1, value2: title2}</code> — что удобно для быстрого получения из key-value конфигов, а также из моделей — <code>User::pluck('name', 'id')</code>;</li>
+                <li><code>[[value1, title1], [value2, title2]]</code> — что удобно для выгрузки там, где важен порядок. Это минимизирует код в контроллерах, помогая сохранять принцип «тонкого контроллера», которого мы придерживаемся.</li>
+            </ol>
+            </li>
+            <li>Взаимозаменяемость формата опций с другими выбиралками из вариантов. Это позволяет легко заменять SCheckboxGroup на <a href="/pages/components/forms/sselect.html">SSelect</a> или <a href="/pages/components/forms/sradio.html">SRadioGroup</a>, не трогая бэкенд код.</li>
+        </ol>
+    </SToggle>
+</SToggleGroup>
+
+## Одиночная галочка
+
+```vue
+<template>
+    <SCheckbox v-model="isAccepted">Я согласен</SCheckbox>
+</template>
+<script setup>
+import { ref } from 'vue'
+const isAccepted = ref(false)
+</script>
+```
+
+Модель принимает значение true/false.
+
+## Группа галочек
+
+```vue
+<template>
+    <SCheckboxGroup v-model="types">
+        <SCheckbox value="bug">Ошибка</SCheckbox>
+        <SCheckbox value="question">Вопрос</SCheckbox>
+        <SCheckbox value="idea">Идея</SCheckbox>
+    </SCheckboxGroup>
+    <p>В модели будет храниться массив выбранных значений: <code>{{ types }}</code></p>
+</template>
+<script setup>
+import { ref } from 'vue'
+const types = ref([])
+</script>
+```
+
+## Динамический набор значений
+
+В предыдущем примере набор вариантов хардкодился в шаблоне, что удобно, когда набор значений относится к логическому уровню интерфейса. Но когда набор вариантов идет из базы данных или конфига, очень неудобно каждый раз формировать набор элементов через v-for, и вместо этого используем атрибут `options`.
+
+```vue
+<template>
+    <SCheckboxGroup v-model="users" :options="userOptions" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const users = ref([])
+const userOptions = { 1: 'Иванов', 2: 'Петров', 3: 'Сидоров' }
+</script>
+```
+
+Где options — это объект вариантов выбора в формате <code>{value1: title1, value2: title2}</code> или массив в формате <code>[[value1, title1], [value2, title2]]</code>
+
+## Вертикальный список галочек
+
+Чтобы выводить группу галочек вертикальным списком, добавляем атрибут `vertical`:
+
+```vue
+<template>
+    <SCheckboxGroup v-model="users" :options="userOptions" vertical />
+</template>
+<script setup>
+import { ref } from 'vue'
+const users = ref([])
+const userOptions = { 1: 'Иванов', 2: 'Петров', 3: 'Сидоров' }
+</script>
+```
+
+## Недоступное значение
+
+Добавляем атрибут `disabled` значению, которое должно быть недоступно для переключения.
+
+```vue
+<template>
+    <SCheckboxGroup v-model="types">
+        <SCheckbox value="bug" disabled>Ошибка</SCheckbox>
+        <SCheckbox value="question">Вопрос</SCheckbox>
+        <SCheckbox value="idea">Идея</SCheckbox>
+    </SCheckboxGroup>
+</template>
+<script setup>
+import { ref } from 'vue'
+const types = ref([])
+</script>
+```
+
+## Интерфейс компонента SCheckboxGroup
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| v-model | `any[]` | `[]` | Массив выбранных значений. |
+| options | Record \| Array | `{}` | Список вариантов (объект или массив пар). |
+| vertical | boolean | `false` | Расположение элементов в колонку. |
+
+### Слоты (Slots)
+
+| Название | Описание |
+|----------|----------|
+| default | Содержимое группы (обычно компоненты `SCheckbox`). |
+
+## Интерфейс компонента SCheckbox
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| v-model | any | - | Значение (для одиночного использования). |
+| value | any | `undefined` | Значение элемента (для использования в группе). |
+| disabled | boolean | `false` | Отключает возможность выбора. |
+
+### Слоты (Slots)
+
+| Название | Описание |
+|----------|----------|
+| default | Текст лейбла рядом с галочкой. |
+
+### События (Events)
+
+| Название | Параметры | Описание |
+|----------|-----------|----------|
+| change | `(value: any)` | Вызывается при изменении состояния. |

package/llms/components/forms/sdatepicker.md

@@ -0,0 +1,161 @@
+# SDatePicker
+
+Поле выбора даты.
+
+<SToggleGroup>
+    <SToggle title="В чем отличие от аналогов?">
+        <p>В отличие от популярных библиотек компонентов для Vue3:</p>
+        <ol>
+            <li>Сразу поддерживает на уровне атрибута <a href="#выбор-вариантов-кнопками">кнопки с готовыми наборами значений</a>, которые часто нужны в фильтрах по диапазону дат.</li>
+            <li>Сразу из коробки по дефолту заточено под русскоязычную локализацию.</li>
+            <li>В отличие от западных библиотек — позволяет выбирать диапазон дат, начиная с более поздней даты. Удобно, когда нужно выбрать несколько последних месяцев.</li>
+        </ol>
+    </SToggle>
+</SToggleGroup>
+
+## Стандартный пример
+
+```vue
+<template>
+    <SDatePicker v-model="value" />
+    <p>Текущее значение: <code>{{ value ?? 'null' }}</code></p>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const value = ref(null)
+</script>
+```
+
+Выбирает значение в формате `YYYY-MM-DD`.
+
+## Минимальное и максимальное значения
+
+```vue
+<template>
+    <SDatePicker v-model="value" :min="minDate" :max="maxDate" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const value = ref(null)
+const minDate = '2026-06-01'
+const maxDate = '2026-06-30'
+</script>
+```
+
+## Кастомный формат значения
+
+```vue
+<template>
+    <SDatePicker v-model="value" value-format="YYYYMMDD" />
+    <p>Текущее значение: <code>{{ value ?? 'null' }}</code></p>
+</template>
+<script setup>
+import { ref } from 'vue'
+const value = ref(null)
+</script>
+```
+
+Независимо от этого атрибуты min/max всегда идут в своём стандартном формате `YYYY-MM-DD`.
+
+## Выбор периода
+
+Для выбора периода добавляем атрибут `range`:
+
+```vue
+<template>
+    <SDatePicker range v-model="value" value-format="YYYYMMDD" />
+    <p>Текущее значение: <code>{{ value ?? 'null' }}</code></p>
+</template>
+<script setup>
+import { ref } from 'vue'
+const value = ref(null)
+</script>
+```
+
+В модель подставляется массив из двух дат в формате, указанном в `value-format`.
+
+## Выбор вариантов кнопками
+
+Очень часто в фильтрах по диапазону дат удобно использовать однокликовый выбор предзаданного диапазона. Набор таких диапазонов мы устанавливаем через атрибут `buttons`.
+
+```vue
+<template>
+    <SDatePicker range v-model="value" value-format="YYYYMMDD" :buttons="buttons" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const value = ref(null)
+const buttons = {
+    '2 недели': '20250901-20250914',
+    'Месяц': '20250815-20250914',
+}
+</script>
+```
+
+Набор доступных кнопок задается в формате <code>{title: value.join('-')}</code>, например: <code>{"2 недели": "20250901-20250914", "Месяц": "20250815-20250914"}</code>
+
+Именно в этом формате backend-класс DateInterval возвращает набор доступных кнопок: `(new DateInterval(request()->period))->titles`
+
+## Выбор времени
+
+Чтобы выбирать время, добавляем атрибут `with-time`. При этом, выходное значение будет в формате <strong>2025-12-22 12:27</strong>:
+
+```vue
+<template>
+    <SDatePicker with-time v-model="value" value-format="YYYYMMDD HH:mm" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const value = ref(null)
+</script>
+```
+
+Часы и минуты — это `SSelect` с фильтрацией, поэтому значение можно как выбрать мышью, так и набрать с клавиатуры. В локалях с 12-часовым форматом (например `en-US`) вместо часов 0–23 показываются часы 1–12 и переключатель AM/PM.
+
+## Очистка значения
+
+Атрибут `clearable` добавляет кнопку очистки (×), которая появляется, когда значение выбрано:
+
+```vue
+<template>
+    <SDatePicker clearable v-model="value" />
+    <p>Текущее значение: <code>{{ value ?? 'null' }}</code></p>
+</template>
+<script setup>
+import { ref } from 'vue'
+const value = ref('2026-06-18')
+</script>
+```
+
+## Интерфейс компонента
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| v-model | `string \| string[]` | `null` | Выбранное значение (строка для одиночного выбора, массив для диапазона). |
+| range | `boolean` | `false` | Режим выбора периода (диапазона дат). |
+| value-format | `string` | `'YYYY-MM-DD'` | Формат значения в модели. Если `with-time` включен, по умолчанию `'YYYY-MM-DD HH:mm'`. |
+| input-format | `string` | `'DD.MM.YYYY'` | Формат отображения даты в текстовом поле. |
+| min | `string` | `undefined` | Минимально допустимая дата (в формате `YYYY-MM-DD`). |
+| max | `string` | `undefined` | Максимально допустимая дата (в формате `YYYY-MM-DD`). |
+| number-of-months | `number` | `1 \| 2` | Количество отображаемых месяцев в календаре (по умолчанию 2 для `range`, иначе 1). |
+| buttons | `Record<string, string>` | `undefined` | Набор кнопок быстрого выбора диапазона (`{ название: 'date1-date2' }`). |
+| with-time | `boolean` | `false` | Позволяет выбирать время (часы и минуты). Только для одиночного выбора. |
+| clearable | `boolean` | `false` | Показывает кнопку очистки (×), когда значение выбрано. |
+| first-day | `number` | (из локали) | Первый день недели: `0` — воскресенье, `1` — понедельник. |
+| icon | `string \| string[]` | `undefined` | Необязательная FontAwesome-иконка календаря (например `['far', 'calendar']`). По умолчанию используется встроенная SVG-иконка — компонент не требует FontAwesome. |
+
+Названия дней недели и месяцев, а также 12/24-часовой формат времени больше не задаются атрибутами per-instance — они берутся из активной локали и переопределяются глобально через параметры локализации (`configureStartupUi`). Подробнее — в разделе [Локализация](/pages/welcome/basics/localization).
+
+Иконки (календарь и стрелки переключения месяца) — встроенные SVG, поэтому FontAwesome для `SDatePicker` не обязателен. Дни соседних месяцев в сетке кликабельны. Поддерживается управление с клавиатуры: в фокусе стрелка вниз открывает календарь, стрелки двигают маркер по датам, Enter фиксирует выбор, Esc закрывает.
+
+<style lang="scss" scoped>
+.s-datepicker {
+    color: var(--s-text);
+}
+</style>