startup-ui 0.11.3 → 1.0.0

package/llms/components/data/sfilter.md

@@ -0,0 +1,194 @@
+# SFilterGroup > SFilter
+
+Фильтры
+
+<SToggleGroup>
+    <SToggle title="В чем отличие от аналогов?">
+        <p>В популярных библиотеках компонентов для Vue3 прямого аналога нет. По сравнению с ручной сборкой из других компонентов SFilter позволяет:</p>
+        <ol>
+            <li>Минимальным синтаксисом собирать функциональные фильтры на страницах. Это обеспечивает одинаковую реализацию разными программистами, избавляет от визуальных отличий, упрощает дальнейшую поддержку и сохраняет взаимозаменяемость между проектами.</li>
+            <li>Брать первоначальные значения фильтра напрямую из GET-параметров, а не пробрасывать из контроллера (сохранение «тонких контроллеров»).</li>
+            <li>Дебаунсить применение значений одним атрибутом, что всегда нужно для приятного UX ввода текстовых значений.</li>
+            <li>Для пустых/незаданных значений фильтров не добавляет GET-параметры, чтобы сохранять консистентность URL.</li>
+        </ol>
+    </SToggle>
+</SToggleGroup>
+
+## Базовый пример
+
+```vue
+<template>
+    <SFilterGroup v-model="filter">
+        <SFilter name="plan">
+            <SRadioGroup buttons>
+                <SRadio value="">Все тарифы</SRadio>
+                <SRadio value="base">Базовый</SRadio>
+                <SRadio value="premium">Премиум</SRadio>
+            </SRadioGroup>
+        </SFilter>
+        <SFilter name="period">
+            <SDatePicker range value-format="YYYYMMDD" />
+        </SFilter>
+    </SFilterGroup>
+    <p>Текущее значение: <code>{{ filter }}</code></p>
+</template>
+<script setup>
+import { ref } from 'vue'
+const filter = ref({})
+</script>
+```
+
+## Привязка к GET-параметрам
+
+Часто бывает удобно привязать модель напрямую к GET-параметрам:
+<ol>
+<li>Взять стартовые значения модели из GET-параметров (без необходимости проброса через контроллер)</li>
+
+<li>При изменениях модели автоматически обновлять GET-параметры, сбрасывая page, но оставляя любые другие параметры.</li>
+</ol>
+
+В этом случае можно использовать атрибут `bind-to-query` , который включит такое поведение:
+
+```vue
+<SFilterGroup bind-to-query>
+    <!-- ... -->
+</SFilterGroup>
+```
+
+По умолчанию `bind-to-query` синхронизирует URL через нативный History API — без серверного рефетча и без зависимости от какого-либо роутера (компонент не требует InertiaJS). Если нужно, чтобы изменение фильтра инициировало серверный запрос (SPA-навигация), зарегистрируйте роутер один раз при подключении плагина — например, роутер Inertia:
+
+```js
+// app.js
+import StartupUI from 'startup-ui';
+import { router } from '@inertiajs/vue3';
+
+app.use(StartupUI, { router });
+```
+
+Подойдёт любой объект с совместимой сигнатурой `get(url, params, options)`. Если роутер не зарегистрирован — `bind-to-query` работает «в чистом виде» (только синхронизация URL).
+
+## Часто используемые поля
+
+### Горизонтальные радио-кнопки
+
+```vue
+<template>
+    <SFilterGroup v-model="filter">
+        <SFilter name="role">
+            <SRadioGroup buttons placeholder="Все" :options="roles" />
+        </SFilter>
+    </SFilterGroup>
+    <p>Текущее значение: <code>{{ filter }}</code></p>
+</template>
+<script setup>
+import { ref } from 'vue'
+const filter = ref({})
+const roles = { customer: 'Пользователь', admin: 'Админ', editor: 'Редактор' }
+</script>
+```
+
+Placeholder задает «не выбранный вариант» — null-значение.
+
+## Выпадающий список
+
+```vue
+<template>
+    <SFilterGroup v-model="filter">
+        <SFilter name="status">
+            <SSelect placeholder="Любой статус" :options="statusOptions" clearable />
+        </SFilter>
+    </SFilterGroup>
+    <p>Текущее значение: <code>{{ filter }}</code></p>
+</template>
+<script setup>
+import { ref } from 'vue'
+const filter = ref({})
+const statusOptions = { warning: 'Предупреждение', success: 'Удачно', error: 'Ошибка' }
+</script>
+```
+
+## Текстовое поле ввода
+
+```vue
+<template>
+    <SFilterGroup v-model="filter">
+        <SFilter name="q" :debounce="500" style="max-width: 350px">
+            <SInput placeholder="Поиск по никнейму" clearable />
+        </SFilter>
+    </SFilterGroup>
+    <p>Текущее значение: <code>{{ filter }}</code></p>
+</template>
+<script setup>
+import { ref } from 'vue'
+const filter = ref({})
+</script>
+```
+
+## Выбор периода дат
+
+```vue
+<template>
+    <SFilterGroup v-model="filter">
+        <SFilter name="period">
+            <SDatePicker range value-format="YYYYMMDD" />
+        </SFilter>
+    </SFilterGroup>
+    <p>Текущее значение: <code>{{ filter }}</code></p>
+</template>
+<script setup>
+import { ref } from 'vue'
+const filter = ref({})
+</script>
+```
+
+## Интерфейс компонента SFilterGroup
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| v-model | `Object` | `{}` | Объект, хранящий состояние всех вложенных `SFilter`. |
+| bindToQuery | boolean | `false` | Синхронизирует состояние с GET-параметрами. По умолчанию через History API; если зарегистрирован роутер (`app.use(StartupUI, { router })`) — через него (напр. Inertia-визит с серверным рефетчем). |
+| ignoreQueryNames | `string[]` | `['page']` | GET-параметры, которые игнорируются при сбросе фильтров. |
+| ignoreQueryValues | `any[]` | `['', null, undefined, false]` | Значения, при которых параметр удаляется из URL (чтобы не мусорить пустой строкой). |
+| title | string | - | Заголовок группы фильтров. |
+| loading | boolean | `false` | Состояние загрузки (скелетон или спиннер). |
+| showAll | boolean | `false` | Если `true`, кнопка «Показать все» заменяется на «Скрыть». |
+
+### Слоты (Slots)
+
+| Название | Описание |
+|----------|----------|
+| default | Содержимое группы (обычно компоненты `SFilter`). |
+
+## Интерфейс компонента SFilter
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| name | string | `undefined` | **Обязательное.** Ключ для хранения значения в `v-model` родительской группы. |
+| debounce | number | `0` | Задержка в миллисекундах перед сохранением. Критично для текстовых инпутов при `bindToQuery`. |
+| title | string | - | Заголовок конкретного фильтра. |
+| opened | boolean | `false` | Раскрыт ли фильтр по умолчанию. |
+
+### Слоты (Slots)
+
+| Название | Описание |
+|----------|----------|
+| default | Содержимое фильтра (чекбоксы, инпуты и т.д.). |
+
+<style lang="scss" scoped>
+.vp-doc ol {
+    margin: var(--s-base-margin) !important;
+}
+.vp-doc li {
+    margin-bottom: 10px !important;
+}
+.s-datepicker {
+    color: var(--s-text);
+}
+.s-filtergroup {
+    margin-bottom: 0;
+}
+</style>

package/llms/components/data/spagination.md

@@ -0,0 +1,114 @@
+# SPagination
+
+Постраничная навигация.
+
+<SToggleGroup>
+    <SToggle title="В чем отличие от аналогов?">
+        <p>В отличие от популярных библиотек компонентов для Vue3:</p>
+        <ol>
+            <li>Принимает атрибуты ровно в том формате, в котором его отдает пагинатор Laravel, что позволяет сразу пробросить исходный пагинатор без дополнительных прописываний атрибутов через v-bind.</li>
+        </ol>
+    </SToggle>
+</SToggleGroup>
+
+## Базовый пример
+
+```vue
+<template>
+    <!-- inertia('User/Index', ['users' => Users::paginate()]) -->
+    <SPagination v-bind="users" />
+</template>
+<script setup>
+import { ref } from 'vue'
+
+// Объект в том же виде, в каком его отдаёт пагинатор Laravel
+const users = ref({
+    current_page: 2,
+    from: 16,
+    to: 30,
+    per_page: 15,
+    total: 72,
+    links: [
+        { url: '?page=1', label: '&#8592;', active: false },
+        { url: '?page=1', label: '1', active: false },
+        { url: '?page=2', label: '2', active: true },
+        { url: '?page=3', label: '3', active: false },
+        { url: '?page=4', label: '4', active: false },
+        { url: '?page=5', label: '5', active: false },
+        { url: '?page=3', label: '&#8594;', active: false },
+    ],
+})
+</script>
+```
+
+Laravel-пагинатор на выходе формирует объект с ключами `{current_page, from, last_page, links, per_page, to, total}`. SPaginator использует ровно то же именование входных атрибутов, поэтому пробрасываем их как есть через v-bind.
+
+## Выбор кол-ва результатов на странице
+
+Чтобы также выводить выпадающий список в кол-вом результатов на странице, можно добавить атрибут <strong>per-page-options</strong>:
+
+```vue
+<template>
+    <SPagination v-bind="users" :per-page-options="[15, 25, 50]" />
+</template>
+<script setup>
+import { ref } from 'vue'
+
+const users = ref({
+    current_page: 2,
+    from: 16,
+    to: 30,
+    per_page: 15,
+    total: 72,
+    links: [
+        { url: '?page=1', label: '&#8592;', active: false },
+        { url: '?page=1', label: '1', active: false },
+        { url: '?page=2', label: '2', active: true },
+        { url: '?page=3', label: '3', active: false },
+        { url: '?page=4', label: '4', active: false },
+        { url: '?page=5', label: '5', active: false },
+        { url: '?page=3', label: '&#8594;', active: false },
+    ],
+})
+</script>
+```
+
+Изменение кол-ва вариантов на странице меняет query-параметр perpage, сбрасывает query-параметр page и сохраняет все остальные query-параметры нетронутыми.
+
+## Интерфейс компонента
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| links | `PaginationLink[]` | `[]` | Массив ссылок `[{ url, label, active }]`. Обычно генерируется бекэндом Laravel. |
+| perPageOptions | `number[] \| string[]` \ `Record` | `undefined` | Опции для выпадающего списка кол-ва элементов на странице (например, `[10, 20, 50]`). |
+| url | string | `location.pathname` | Базовый URL, используемый при смене кол-ва элементов на странице. |
+| preserveScroll | boolean | `true` | Пробрасывается в зарегистрированный `Link` (Inertia). Сохраняет позицию скролла. |
+| preserveState | boolean | `false` | Пробрасывается в зарегистрированный `Link` (Inertia). Сохраняет локальный стейт страницы. |
+| per_page | number | `undefined` | Выбранное кол-во элементов на странице. |
+| from | number | `undefined` | Начальный индекс (для надписи «Показано X-Y из Z»). |
+| to | number | `undefined` | Конечный индекс. |
+| total | number | `undefined` | Общее количество записей. |
+
+### Слоты (Slots)
+
+| Название | Описание |
+|----------|----------|
+| default | По умолчанию слоты отсутствуют, пагинация генерируется автоматически по пропсам. |
+
+<style lang="scss">
+:root {
+    .vp-doc ul {
+        padding-left: 0;
+        margin: 0;
+    }
+
+    .vp-doc li + li {
+        margin: 0;
+    }
+    .s-demo-preview .s-pagination {
+        margin-bottom: 0;
+    }
+}
+</style>