startup-ui 0.12.0 → 1.0.0

package/llms/components/forms/sradio.md

@@ -0,0 +1,164 @@
+# SRadioGroup > SRadio
+
+Радио-кнопки.
+
+<SToggleGroup>
+    <SToggle title="В чем отличие от аналогов?">
+        <p>В отличие от популярных библиотек компонентов для Vue3:</p>
+        <ol>
+            <li>Сразу идет с кликабельным стандартизированным лейблом в качестве простого атрибута. Это унифицирует код и внешний вид компонентов, упрощается поддержка и взаимозаменяемость.</li>
+            <li>Сразу из коробки идет кнопочный стиль, который часто используется.</li>
+            <li>Поддерживает три формата передачи опций в группы радио-кнопок, что удобно в зависимости от кейса:
+            <ol>
+                <li><code>&lt;SRadio /&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>Взаимозаменяемость формата опций с другими выбиралками из вариантов. Это позволяет легко заменять SRadioGroup на <a href="/pages/components/forms/sselect.html">SSelect</a> или <a href="/pages/components/forms/scheckbox.html">SCheckboxGroup</a>, не трогая бэкенд код.</li>
+        </ol>
+    </SToggle>
+</SToggleGroup>
+
+## Группа радио-кнопок
+
+```vue
+<template>
+    <SRadioGroup v-model="type">
+        <SRadio value="bug">Ошибка</SRadio>
+        <SRadio value="question">Вопрос</SRadio>
+        <SRadio value="idea">Идея</SRadio>
+    </SRadioGroup>
+    <p>Модель будет принимать значение выбранного варианта: <code>{{ type }}</code></p>
+</template>
+<script setup>
+import { ref } from 'vue'
+const type = ref('bug')
+</script>
+```
+
+## Динамический набор значений
+
+В предыдущем примере набор вариантов хардкодился в шаблоне, что удобно, когда набор значений относится к логическому уровню интерфейса. Но когда набор вариантов идет из базы данных или конфига, очень неудобно каждый раз формировать набор элементов через v-for, и вместо этого используем атрибут `options`.
+
+```vue
+<template>
+    <SRadioGroup v-model="type" :options="options" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const options = { 1: 'Ошибка', 2: 'Вопрос', 3: 'Идея' }
+const type = ref(1)
+</script>
+```
+
+Где options — это объект вариантов выбора в формате <code>{value1: title1, value2: title2}</code> или массив в формате <code>[[value1, title1], [value2, title2]]</code>
+
+## Кнопочный стиль
+
+Чтобы заменить стиль с кружочками на группу кнопок, добавляем атрибут `buttons`:
+
+```vue
+<template>
+    <SRadioGroup v-model="type" :options="options" buttons />
+</template>
+<script setup>
+import { ref } from 'vue'
+const options = { 1: 'Ошибка', 2: 'Вопрос', 3: 'Идея' }
+const type = ref(1)
+</script>
+```
+
+## Вертикальный список радио-кнопок
+
+Чтобы выводить группу радио-кнопок вертикальным списком, добавляем атрибут `vertical`:
+
+```vue
+<template>
+    <SRadioGroup v-model="type" :options="options" vertical />
+</template>
+<script setup>
+import { ref } from 'vue'
+const options = { 1: 'Ошибка', 2: 'Вопрос', 3: 'Идея' }
+const type = ref(1)
+</script>
+```
+
+## Недоступное значение
+
+Добавляем `disabled`-атрибут значению, которое должно быть недоступно для переключения.
+
+```vue
+<template>
+    <SRadioGroup v-model="type">
+        <SRadio value="bug" disabled>Ошибка</SRadio>
+        <SRadio value="question">Вопрос</SRadio>
+        <SRadio value="idea">Идея</SRadio>
+    </SRadioGroup>
+</template>
+<script setup>
+import { ref } from 'vue'
+const type = ref('question')
+</script>
+```
+
+## Нулевое значение (плейсхолдер)
+
+У радио-кнопок иногда бывает «не выбранное значение», особенно в фильтрах при заданном наборе вариантов. Для этого удобно использовать синтаксис `placeholder`:
+
+```vue
+<template>
+    <SRadioGroup v-model="type" placeholder="Все" :options="options" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const options = { 1: 'Ошибка', 2: 'Вопрос', 3: 'Идея' }
+const type = ref(null)
+</script>
+```
+
+## Интерфейс компонента SRadioGroup
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| v-model | `any` | `undefined` | Выбранное значение. |
+| options | `Record \| Array` | `{}` | Список вариантов (объект `{value: title}` или массив `[[value, title]]`). |
+| buttons | `boolean` | `false` | Использовать стиль кнопок вместо кружочков. |
+| vertical | `boolean` | `false` | Расположение элементов в колонку. |
+| placeholder | `string` | `undefined` | Текст для «нулевого» варианта выбора (с пустым значением). |
+
+### Слоты (Slots)
+
+| Название | Описание |
+|----------|----------|
+| default | Содержимое группы (обычно компоненты `SRadio`). |
+
+### События (Events)
+
+| Название | Параметры | Описание |
+|----------|-----------|----------|
+| change | `(value: any)` | Вызывается при изменении выбранного значения. |
+
+## Интерфейс компонента SRadio
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| value | `string \| number \| boolean` | - | **Обязательное.** Значение элемента. |
+| disabled | `boolean` | `false` | Отключает возможность выбора. |
+| labelClass | `string` | `undefined` | Кастомные CSS классы для лейбла. |
+
+### Слоты (Slots)
+
+| Название | Описание |
+|----------|----------|
+| default | Текст или HTML-содержимое лейбла радио-кнопки. |
+
+<style lang="scss">
+.s-radio {
+    color: var(--s-text);
+}
+</style>

package/llms/components/forms/sselect.md

@@ -0,0 +1,149 @@
+# SSelect
+
+Выпадающий список с вариантами выбора.
+
+<SToggleGroup>
+    <SToggle title="В чем отличие от аналогов?">
+        <p>В отличие от популярных библиотек компонентов для Vue3:</p>
+        <ol>
+            <li>Исключает опции, которые, как правило, не используются в стартапах (флоат лейблы, размеры), но из-за которых разные программисты реализовывают компонент по-разному. Без лишних опций унифицируется код и внешний вид компонентов, упрощается поддержка и взаимозаменяемость.</li>
+            <li>Поддерживает два формата передачи опций, удобных для выгрузки из контроллеров Laravel:
+            <ol>
+                <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>Взаимозаменяемость формата опций с другими выбиралками из вариантов. Это позволяет легко заменять SSelect на <a href="/pages/components/forms/scheckbox.html">SCheckboxGroup</a> или <a href="/pages/components/forms/sradio.html">SRadioGroup</a>, не трогая бэкенд код.</li>
+        </ol>
+    </SToggle>
+</SToggleGroup>
+
+## Классический вариант
+```vue
+<template>
+    <SSelect v-model="value" :options="options" placeholder="Выберите" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const options = { 1: 'Иванов', 2: 'Петров', 3: 'Сидоров' }
+const value = ref(null)
+</script>
+```
+
+Где options — это объект вариантов выбора в формате <code>{value1: title1, value2: title2}</code> или массив в формате <code>[[value1, title1], [value2, title2]]</code>
+
+## Фильтрация при вводе
+
+```vue
+<template>
+    <SSelect v-model="value" :options="options" filterable placeholder="Выберите" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const options = { 1: 'Иванов', 2: 'Петров', 3: 'Сидоров' }
+const value = ref(null)
+</script>
+```
+
+## Получение значений по API
+
+Список значений можно подгружать по API — в том числе на каждый ввод. Ниже живой пример: варианты приходят с публичного тестового API [DummyJSON](https://dummyjson.com), запрос уходит в обработчике события `@filter`. Начните вводить имя (например, «jo»):
+
+```vue
+<template>
+    <SSelect v-model="value" :options="options" filterable @filter="onFilter" placeholder="Начните вводить имя" />
+</template>
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const value = ref(null)
+const options = ref([])
+
+// Подгружаем варианты с публичного тестового API (DummyJSON):
+// при пустом запросе — первые 10, иначе — поиск по введённой строке
+async function load(query = '') {
+    const url = query
+        ? `https://dummyjson.com/users/search?q=${encodeURIComponent(query)}&select=firstName,lastName`
+        : 'https://dummyjson.com/users?limit=10&select=firstName,lastName'
+    const { users } = await (await fetch(url)).json()
+    options.value = users.map(u => [u.id, `${u.firstName} ${u.lastName}`])
+}
+
+// Запрашиваем только непустую строку: при выборе значения фильтр сбрасывается в '',
+// и перезагружать список не нужно — иначе выбранный вариант пропал бы из опций
+const onFilter = (query) => { if (query) load(query) }
+
+onMounted(() => load())
+</script>
+```
+
+Обработчик `@filter` получает введённую строку; ответ API мы приводим к формату опций (`[[value, title]]` или `{value: title}`) и кладём в `:options`. В реальном проекте запрос обычно стоит дебаунсить.
+
+## Возможность сброса значения
+
+Иногда бывает нужно сделать возможность сбрасывать значение в невыбранное (null). Для этого используется атрибут `clearable`:
+
+```vue
+<template>
+    <SSelect v-model="user" :options="options" clearable placeholder="Не выбрано" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const options = { 1: 'Иванов', 2: 'Петров', 3: 'Сидоров' }
+const user = ref(null)
+</script>
+```
+
+## Виртуальный скролл
+
+Когда доступно очень много вариантов выбора, можно применить виртуальный скролл для более быстрой загрузки, добавив атрибут `virtual`:
+
+```vue
+<template>
+    <SSelect v-model="region" :options="regions" virtual placeholder="Выберите регион" />
+</template>
+<script setup>
+import { ref } from 'vue'
+// 1000 options — virtual scroll keeps it fast by rendering only the visible window
+const regions = Object.fromEntries(
+    Array.from({ length: 1000 }, (_, i) => [i + 1, `Регион ${i + 1}`])
+)
+const region = ref(null)
+</script>
+```
+
+## Интерфейс компонента
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| v-model | any | - | Текущее выбранное значение. |
+| options | Record \| Array | - | Список вариантов (объект или массив пар). |
+| placeholder | string | - | Текст заглушки. |
+| filterable | boolean | `false` | Включает текстовый поиск. |
+| clearable | boolean | `false` | Показывает кнопку сброса значения. |
+| disabled | boolean | `false` | Отключает компонент. |
+| inline | boolean | `false` | Убирает границы и делает селект компактным. |
+| virtual | boolean | `false` | Включает виртуальный скролл. |
+| virtualScrollSize | number | `10` | Количество одновременно отображаемых элементов при виртуальном скролле. |
+
+### Слоты (Slots)
+
+| Название | Параметры | Описание |
+|----------|-----------|----------|
+| value | `{ value: any }` | Кастомное отображение выбранного значения. |
+| option | `{ option: { label: string, value: any } }` | Кастомное отображение элемента в выпадающем списке. |
+
+### События (Events)
+
+| Название | Параметры | Описание |
+|----------|-----------|----------|
+| change | `(value: any)` | Вызывается при изменении значения. |
+| filter | `(query: string)` | Вызывается при вводе текста в режиме поиска. |
+
+<style lang="scss">
+.s-select {
+    min-width: 200px;
+}
+</style>

package/llms/components/forms/sswitch.md

@@ -0,0 +1,69 @@
+# SSwitch
+
+Включатель-выключатель.
+
+<SToggle title="В чем отличие от аналогов?">
+<p>В отличие от популярных библиотек компонентов для Vue3:</p>
+<ol>
+<li>Сразу идет с кликабельным стандартизированным лейблом в качестве простого атрибута. Это унифицирует код и внешний вид компонентов, упрощается поддержка и взаимозаменяемость.</li>
+</ol>
+</SToggle>
+
+## Базовый пример
+
+```vue
+<template>
+    <SSwitch v-model="checked">Значение: {{ checked }}</SSwitch>
+</template>
+<script setup>
+import { ref } from 'vue'
+const checked = ref(false)
+</script>
+```
+
+Модель принимает значение true/false.
+
+## Недоступное состояние
+
+```vue
+<template>
+    <SSwitch v-model="checked" disabled>Не работает</SSwitch>
+</template>
+<script setup>
+import { ref } from 'vue'
+const checked = ref(false)
+</script>
+```
+
+## Кастомные да/нет-значения
+
+Для включенного/отключенного состояния можно задать кастомные значения:
+
+```vue
+<template>
+    <SSwitch v-model="value" true-value="yes" false-value="no">
+        Значение: {{ value }}
+    </SSwitch>
+</template>
+<script setup>
+import { ref } from 'vue'
+const value = ref('no')
+</script>
+```
+
+## Интерфейс компонента
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| v-model | `any` | `null` | Состояние переключателя. |
+| disabled | `boolean` | `false` | Отключает возможность переключения. |
+| true-value | `any` | `true` | Значение для «включенного» состояния. |
+| false-value | `any` | `false` | Значение для «выключенного» состояния. |
+
+### Слоты (Slots)
+
+| Название | Описание |
+|----------|----------|
+| default | Текст лейбла (описания) рядом с переключателем. |

package/llms/components/forms/supload.md

@@ -0,0 +1,189 @@
+# SUpload
+
+Загрузка файла. Всегда вставляется внутри некой формы, не используется в отрыве от неё.
+
+<SToggleGroup>
+    <SToggle title="В чем отличие от аналогов?">
+        <p>В отличие от популярных библиотек компонентов для Vue3:</p>
+        <ol>
+            <li>В других библиотеках Upload работает как поле, которое по дефолту сразу отправляет файл после выбора (что удобно, например, при импорте таблиц). На практике же гораздо чаще встречается кейс, когда файл/картинка — это атрибут некой модели, и этот файл нужно добавлять-редактировать в форме редактирования модели. SUpload в первую очередь заточен под этот, более частый кейс.</li>
+            <li>SUpload сразу работает в связке с SForm, что позволяет использовать его так же просто, как простые текстовые SInput, не задумываясь о том, как связывать данные с формой.</li>
+        </ol>
+    </SToggle>
+</SToggleGroup>
+
+## Базовый пример
+
+Если нужно вставить полем в форму. Сама отправка идёт через Inertia, поэтому базовый пример показан кодом (вживую не запускается):
+
+```vue
+<template>
+    <SUpload v-model="screenshot" />
+    <SButton v-if="screenshot" @click="submit">Отправить</SButton>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { router } from '@inertiajs/vue3';
+import { SUpload, SButton, SAlert } from 'startup-ui';
+
+const screenshot = ref(null);
+
+function submit() {
+    router.post('/photos', { screenshot: screenshot.value }, {
+        preserveState: true,
+        onError: (errors) => console.error(errors),
+        onSuccess: () => SAlert.success('Файл отправлен'),
+    });
+}
+</script>
+```
+
+## Авто-отправка при выборе
+
+Если нужна авто-отправка, то выполняем отправку формы по событию `@select`:
+
+```vue
+<template>
+    <SUpload v-model="screenshot" @select="submit" />
+</template>
+<script setup>
+import { ref } from 'vue'
+import { SAlert } from 'startup-ui'
+const screenshot = ref(null)
+// в реальном приложении здесь router.post(...) (Inertia)
+function submit() {
+    SAlert.success('Файл отправлен')
+}
+</script>
+```
+
+## Кастомный текст кнопки
+
+Можно задать произвольный текст кнопки с помощью атрибута `upload-button-title`
+
+```vue
+<template>
+    <SUpload v-model="screenshot" upload-button-title="Выбрать скриншот" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const screenshot = ref(null)
+</script>
+```
+
+## Кастомный шаблон
+
+```vue
+<template>
+    <SUpload v-model="screenshot">
+        <template #header="{ choose, clear, files, isDragging }">
+            <div class="s-upload-area" :class="{ dragging: isDragging }">
+                <FontAwesomeIcon icon="cloud-arrow-up" class="s-upload-area-icon" />
+                <p>Перетащите файл сюда или <a href="javascript:void(0)" @click="choose">нажмите</a> для загрузки</p>
+            </div>
+        </template>
+        <template #preview="{ files, remove }">
+            <div v-if="files && files.length">
+                Файл выбран <SActionIcon @click="remove(files[0])" icon="trash" />
+            </div>
+        </template>
+    </SUpload>
+</template>
+<script setup>
+import { ref } from 'vue'
+const screenshot = ref(null)
+</script>
+```
+
+Слоты сразу пробрасывают методы и переменные, которые могут быть полезны в собственных шаблонах:
+
+* В слоте кнопки выбора `#header`: `choose()` открывает окно выбора файла, `clear()` очищает набор выбранных файлов, `files` — список текущих выбранных файлов, `isDragging` — булево значение, равное true, когда над компонентом перемещают файл.
+* В слоте предпросмотра выбранных файлов `#preview`: `files` — список текущих выбранных файлов, `remove(file)` — удаление конкретного файла из набора (передаётся элемент массива `files`).
+
+## Ограничения выбора
+
+Для ограничения выбора по расширению добавляем атрибут `accept`:
+
+```vue
+<template>
+    <SUpload v-model="screenshot" accept=".txt,.csv,.xlsx" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const screenshot = ref(null)
+</script>
+```
+
+Для ограничения выбора по размеру файла добавляем атрибут `max-file-size`. Можно указывать человекочитаемо (`2M`, `512K`, `1.5GB` — единицы 1024-кратные, как в php.ini) или числом в байтах:
+
+```vue
+<template>
+    <SUpload v-model="screenshot" max-file-size="500K" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const screenshot = ref(null)
+</script>
+```
+
+## Выбор нескольких файлов
+
+```vue
+<template>
+    <SUpload v-model="screenshots" multiple />
+</template>
+<script setup>
+import { ref } from 'vue'
+const screenshots = ref([])
+</script>
+```
+
+## Интерфейс компонента
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| v-model | `any \| any[]` | `null` | Выбранный файл (объект File или строка) или массив файлов. |
+| accept | `string` | `undefined` | Допустимые типы файлов (напр. `.jpg,.png`). |
+| max-file-size | `number \| string` | `undefined` | Максимальный размер файла: в байтах (число) или человекочитаемо (`2M`, `512K`, `1.5GB`). |
+| multiple | `boolean` | `false` | Позволяет выбирать несколько файлов. |
+| upload-button-title | `string` | `'Выбрать файл(ы)'` | Текст на кнопке выбора (если не используется слот `header`). |
+
+### Слоты (Slots)
+
+| Название | Параметры | Описание |
+|----------|-----------|----------|
+| header | `{ choose, clear, files, isDragging }` | Кастомная область выбора (триггер). |
+| preview | `{ files, remove }` | Кастомная область предпросмотра выбранных файлов. |
+| default | - | Содержимое под списком файлов. |
+
+### События (Events)
+
+| Название | Параметры | Описание |
+|----------|-----------|----------|
+| select | `value` | Вызывается при выборе файлов. |
+| clear | - | Вызывается при полной очистке списка. |
+
+<style lang="scss">
+.s-upload-area {
+    border: 1px dashed var(--s-border);
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    border-radius: var(--s-border-radius);
+    padding: var(--s-base-margin);
+    gap: var(--s-base-margin);
+    cursor: pointer;
+
+    &-icon {
+        font-size: 56px;
+        color: var(--s-primary);
+    }
+
+    &:hover, &.dragging {
+        border-color: var(--s-primary);
+    }
+}
+</style>

package/llms/components/interfaces/sactionbar.md

@@ -0,0 +1,40 @@
+# SActionBar
+
+Полоска действия (обычно, для выбранных элементов).
+
+<SToggle title="В чем отличие от аналогов?">В популярных библиотеках прямого аналога нет.</SToggle>
+
+## Базовый пример
+
+```vue
+<template>
+    <SCheckboxGroup v-model="users" :options="userOptions" />
+    <SActionBar v-if="users.length">
+        <SSelect v-model="massAction" :options="massActions" style="width: 250px" />
+        <SButton @click="applyMassAction">Применить</SButton>
+    </SActionBar>
+</template>
+<script setup>
+import { ref } from 'vue'
+import { SAlert } from 'startup-ui'
+
+const userOptions = { 1: 'Иванов', 2: 'Петров', 3: 'Сидоров' }
+const users = ref([])
+
+const massActions = { sendBonus: 'Отправить бонус', greet: 'Поприветствовать', delete: 'Удалить' }
+const massAction = ref('sendBonus')
+
+function applyMassAction() {
+    users.value = []
+    SAlert.success('Действие выполнено')
+}
+</script>
+```
+
+## Интерфейс компонента
+
+### Слоты (Slots)
+
+| Название | Описание |
+|----------|----------|
+| default | Интерактивные элементы, кнопки или формы для отображения в панели действий. Контент использует flexbox, элементы располагаются в ряд. |