startup-ui 0.12.0 → 1.0.0

package/llms/components/forms/sform.md

@@ -0,0 +1,240 @@
+# SForm > SFormRow
+
+SForm и SFormRow позволяют быстро собирать функциональные формы.
+
+<SToggleGroup>
+    <SToggle title="В чем отличие от аналогов?">
+        <p>В отличие от популярных библиотек компонентов для Vue3:</p>
+        <ol>
+            <li>Унифицирует и упрощает вспомогательные элементы (напр. подсказки под полями) и часто используемые состояния (напр. заголовки слева) до простых атрибутов. Это обеспечивает одинаковую реализацию разными программистами, избавляет от визуальных отличий, упрощает дальнейшую поддержку и сохраняет взаимозаменяемость между проектами.</li>
+            <li>Сразу из коробки связывает форму с InertiaJS-формами и/или Laravel FormRequest-ами, одинаково и аккуратно выводя ошибки валидации</li>
+            <li>Минимизируют синтаксис и связанность до одной модели на уровне SForm, что делает код чище, упрощает его написание, чтение и поддержку.</li>
+        </ol>
+    </SToggle>
+    <SToggle title="Что будет ценно улучшить">
+        <ol>
+            <li>Сразу привязывать лейблы правильным образом к соответствующим input-полям, что обеспечит поддержку <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA" target="_blank">ARIA</a> — это будет ценно для проектов на европейский рынок, т.к. там это требование законодательства.</li>
+        </ol>
+    </SToggle>
+</SToggleGroup>
+
+## С формой InertiaJS
+
+InertiaJS предлагает [useForm-компонент](https://inertiajs.com/docs/v2/data-props/remembering-state#form-helper), который мы используем по дефолту для всех форм.
+
+```vue
+<template>
+    <SForm v-model="form" method="post" action="/users/login">
+        <SFormRow title="Логин" name="login">
+            <SInput />
+        </SFormRow>
+        <SFormRow title="Пароль" name="password">
+            <SInput type="password" />
+        </SFormRow>
+        <SButton>Войти</SButton>
+    </SForm>
+</template>
+
+<script setup>
+import { useForm } from '@inertiajs/vue3';
+import { SForm, SFormRow, SInput, SButton } from 'startup-ui';
+
+const form = useForm({
+    login: '',
+    password: '',
+});
+</script>
+```
+
+Для компонентов внутри `<SFormRow />` не нужно отдельно прописывать модель — она автоматически берется из модели `<SForm />` по имени.
+
+Аналогично не нужно как-то обрабатывать loading-состояние и отдельно выводить ошибки валидации — при необходимости этот функционал уже реализован в форме.
+
+## С собственным submit-методом
+
+Если по какой-то причине нам нужно вместо атрибутов `method`/`action` задать собственный `submit`-метод, сделать это можно следующим образом:
+
+```vue
+<template>
+    <SForm v-model="form" @submit="submit" :errors="errors" :loading="isLoading">
+        <SFormRow title="Логин" name="login">
+            <SInput />
+        </SFormRow>
+        <SFormRow title="Пароль" name="password">
+            <SInput type="password" />
+        </SFormRow>
+        <SButton>Войти</SButton>
+    </SForm>
+</template>
+<script setup>
+import { ref } from 'vue'
+const isLoading = ref(false)
+const errors = ref({})
+const form = ref({ login: '', password: '' })
+
+function submit() {
+    isLoading.value = true
+    // Your request logic here
+    setTimeout(() => (isLoading.value = false), 1500)
+}
+</script>
+```
+
+Так как мы используем собственный метод, то для показа состояния загрузки формы может понадобиться задавать свой набор ошибок `errors`, а также loading-состояние, которое показывает, находится ли сейчас форма в процессе отправки (чтобы избежать повторной отправки по ошибке)
+
+## Подсказки под полями
+
+Если под полем нужно выводить подсказку, это делается в `<SFormRow>`:
+
+```vue
+<template>
+    <SForm v-model="form">
+        <SFormRow title="Логин" name="login" hint="Имя пользователя или email">
+            <SInput />
+        </SFormRow>
+        <SFormRow title="Пароль" name="password">
+            <SInput type="password" />
+        </SFormRow>
+        <SButton>Войти</SButton>
+    </SForm>
+</template>
+<script setup>
+import { ref } from 'vue'
+const form = ref({ login: '', password: '' })
+</script>
+```
+
+## Заголовки слева
+
+По умолчанию заголовки выводятся над полями формы, но иногда бывает нужно показать их слева от полей. Сделать это можно с помощью пропса `titles-at-left`. Ширину этих полей можно задать через `titles-width`.
+
+```vue
+<template>
+    <SForm v-model="form" titles-at-left :titles-width="80">
+        <SFormRow title="Логин" name="login" hint="Имя пользователя или email">
+            <SInput />
+        </SFormRow>
+        <SFormRow title="Пароль" name="password">
+            <SInput type="password" />
+        </SFormRow>
+        <SButton>Войти</SButton>
+    </SForm>
+</template>
+<script setup>
+import { ref } from 'vue'
+const form = ref({ login: '', password: '' })
+</script>
+```
+
+## Установка моделей инпутов напрямую
+
+По дефолту `<SFormRow />` привязывает модели вложенных компонентов к соответствующему полю из модели `<SForm />`. Но это делается исключительно для удобства и не является обязательным. Иногда, когда нужно задать модели вручную это возможно сделать напрямую:
+
+```vue
+<template>
+    <SForm v-model="form">
+        <SFormRow>
+            <SSwitch v-model="form.hasAgreement">Согласен с правилами</SSwitch>
+            <SSwitch v-model="form.hasNotifications">Согласен получать оповещения</SSwitch>
+        </SFormRow>
+    </SForm>
+</template>
+<script setup>
+import { ref } from 'vue'
+const form = ref({ hasAgreement: false, hasNotifications: false })
+</script>
+```
+
+## Вывод ошибок из кастомных ключей
+
+Иногда бывает нужно выводить ошибки из кастомных ключей errors-массива (или вложенных путей). Сделать это можно с помощью атрибута `error-key`:
+
+```vue
+<template>
+    <SForm v-model="form" :errors="errors" @submit.prevent="submit">
+        <SFormRow title="Кол-во заказов" :error-key="['orders.minCount', 'orders.maxCount']">
+            <div class="order-formrow">
+                <label class="order-formrow-item">
+                    <span>Минимум</span>
+                    <SInput v-model="form.minCount" type="number" min="0" style="max-width: 80px;" />
+                </label>
+                <label class="order-formrow-item">
+                    <span>Максимум</span>
+                    <SInput v-model="form.maxCount" type="number" min="0" style="max-width: 80px;" />
+                </label>
+            </div>
+        </SFormRow>
+        <SButton>Отправить</SButton>
+    </SForm>
+</template>
+<script setup>
+import { ref } from 'vue'
+const errors = ref({})
+const form = ref({ minCount: '', maxCount: '' })
+
+function submit() {
+    errors.value = {}
+    if (!form.value.minCount) errors.value['orders.minCount'] = 'Минимальное количество не может быть меньше 1'
+    if (!form.value.maxCount) errors.value['orders.maxCount'] = 'Максимальное количество не может быть меньше 1'
+}
+</script>
+```
+
+Поддерживаются:
+- Пути через точку: `orders.0`
+- Звездочка для всех вложенных ключей: `orders.*`
+- Массивы: `['orders.0', 'orders.1']`
+
+## Интерфейс компонента SForm
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| form | object | - | Объект формы InertiaJS (рекомендуется). |
+| method | string | `'post'` | HTTP-метод: `post`, `put`, `patch`, `delete`, `get`. |
+| action | string | - | URL для отправки формы. |
+| preserveScroll | boolean | `true` | Сохранять ли позицию скролла после отправки. |
+| isDirty | boolean | `false` | Состояние «изменено» (предупреждение при уходе со страницы). |
+| loading | boolean | `undefined` | Состояние загрузки (переопределяет внутреннее состояние формы). |
+| summaryErrors | boolean | `false` | Показывать ли список всех ошибок вверху формы. |
+
+### Слоты (Slots)
+
+| Название | Описание |
+|----------|----------|
+| default | Содержимое формы (инпуты, кнопки и т.д.). |
+
+## Интерфейс компонента SFormRow
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| title | string | - | Заголовок (лейбл) поля. |
+| hint | string | - | Текст-подсказка под заголовоком. |
+| error | string \| string[] | - | Текст ошибки или массив ошибок. |
+| errorKey | string | - | Ключ ошибки в объекте `form.errors` (если используется пропс `errorKey`). |
+| required | boolean | `false` | Помечает поле как обязательное (добавляет красную звездочку). |
+| side | boolean | `false` | Располагает заголовок слева от поля (горизонтальный лейаут). |
+
+### Слоты (Slots)
+
+| Название | Описание |
+|----------|----------|
+| default | Содержимое строки (обычно компонент ввода — инпут, селект и т.д.). |
+| title | Кастомный заголовок (вместо пропса title). |
+| hint | Кастомная подсказка (вместо пропса hint). |
+
+<style lang="scss">
+.order-formrow {
+    display: flex;
+    flex-direction: row;
+    gap: var(--s-base-margin);
+    &-item {
+        display: flex;
+        align-items: center;
+        gap: 5px;
+    }
+}
+</style>

package/llms/components/forms/shtmleditor.md

@@ -0,0 +1,143 @@
+# SHtmlEditor
+
+Визуальный HTML-редактор.
+
+<SToggleGroup>
+    <SToggle title="В чем отличие от аналогов?">
+        <p>В отличие от популярных библиотек компонентов для Vue3:</p>
+        <ol>
+            <li>Сразу используем самый удобный TinyMCE. Все остальные редакторы по юзабилити сильно хуже.</li>
+            <li>Поддержка ембеддинга видео из сервиса <a href="https://www.kinescope.com/" target="_blank">Kinescope</a>, который в моменте является наиболее удобной заменой блокируемого YouTube</li>
+        </ol>
+    </SToggle>
+</SToggleGroup>
+
+## Базовый пример
+
+<div class="docs-container">
+    <SHtmlEditor v-model="content1" upload-url="/image/upload" />
+</div>
+
+```vue
+<template>
+    <SHtmlEditor v-model="content" upload-url="/image/upload" />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { SHtmlEditor } from 'startup-ui';
+
+const content = ref('');
+</script>
+```
+
+## Плейсхолдер
+
+<div class="docs-container">
+    <SHtmlEditor v-model="content2" upload-url="/image/upload" placeholder="Введите контент" />
+</div>
+
+```vue
+<template>
+    <SHtmlEditor v-model="content" upload-url="/image/upload" placeholder="Введите контент" />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { SHtmlEditor } from 'startup-ui';
+
+const content = ref('');
+</script>
+```
+
+## Высота редактора
+
+По умолчанию высота равна 300px. Изменить её можно пропом `height` — например, увеличить до 500px:
+
+<div class="docs-container">
+    <SHtmlEditor v-model="content3" upload-url="/image/upload" :height="500" />
+</div>
+
+```vue
+<template>
+    <SHtmlEditor v-model="content" upload-url="/image/upload" :height="500" />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { SHtmlEditor } from 'startup-ui';
+
+const content = ref('');
+</script>
+```
+
+## Расширяемость
+
+Конфигурацию TinyMCE можно глубоко переопределить пропом `init` (глубокий merge в дефолты). Поле `setup` композируется с библиотечным (вызывается после него и не затирает обёртку картинок), а `plugins` объединяются с базовыми.
+
+```vue
+<SHtmlEditor
+    v-model="content"
+    upload-url="/image/upload"
+    :plugins="['wordcount']"
+    toolbar="blocks | bold italic | link image | fullscreen code"
+    :header-offset="60"
+    :init="{
+        setup(editor) {
+            // напр. кастомная кнопка «вставить шаблон ответа техподдержки»
+            editor.ui.registry.addButton('reply', {
+                text: 'Шаблон',
+                onAction: () => editor.insertContent('<p>Здравствуйте! </p>'),
+            });
+        },
+    }"
+    @init="onEditorInit"
+/>
+```
+
+- `header-offset` (или CSS-переменная `--s-header-height`) задаёт смещение шапки для корректного fullscreen.
+- `content-style` добавляется к базовым стилям контента, `content-css` подключает внешние стили.
+- Локаль интерфейса берётся из словаря (`htmlEditor.language`); язык можно задать и явно через `:init="{ language, language_url }"`.
+
+## Интерфейс компонента
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| v-model | `string` | `undefined` | HTML-содержимое редактора. |
+| upload-url | `string` | `undefined` | URL для загрузки изображений на сервер. |
+| placeholder | `string` | `''` | Текст-заполнитель, когда редактор пуст. |
+| height | `number` | `300` | Высота редактора, px. |
+| media | `boolean` | `false` | Включить плагин медиа (видео-эмбеды). |
+| plugins | `string[]` | `[]` | Доп. плагины TinyMCE (объединяются с базовыми). |
+| toolbar | `string` | (дефолтный) | Переопределение тулбара. |
+| menubar | `string \| boolean` | `false` | Меню-бар TinyMCE. |
+| content-style | `string` | `undefined` | Доп. CSS контента (добавляется к базовому). |
+| content-css | `string \| string[]` | `undefined` | Внешние CSS контента (`content_css`). |
+| header-offset | `number` | `undefined` | Смещение шапки для fullscreen, px. |
+| init | `object` | `undefined` | Глубокий merge в конфигурацию TinyMCE (наивысший приоритет). |
+
+### События (Events)
+
+| Название | Параметры | Описание |
+|----------|-----------|----------|
+| changeContent | - | Вызывается при любом изменении содержимого редактора. |
+| init | `editor` | Инстанс TinyMCE готов — для регистрации кастомных плагинов/кнопок. |
+
+<script setup>
+import { ref } from 'vue';
+import SToggleGroup from '../../../../packages/startup-ui/src/components/SToggleGroup.vue';
+import SToggle from '../../../../packages/startup-ui/src/components/SToggle.vue';
+import SHtmlEditor from '../../../resources/components/SHtmlEditor.client.vue';
+
+const content1 = ref('');
+const content2 = ref('');
+const content3 = ref('');
+const content = ref('');
+</script>
+<style lang="scss">
+.s-htmleditor {
+    font-family: var(--s-font-family);
+}
+</style>

package/llms/components/forms/sinput.md

@@ -0,0 +1,165 @@
+# SInput
+
+Базовые поля ввода.
+
+<SToggle title="В чем отличие от аналогов?">
+<p>В отличие от популярных библиотек компонентов для Vue3:</p>
+<ol>
+<li>Исключает опции, которые, как правило, не используются в стартапах (напр. размеры полей), но из-за которых разные программисты реализовывают компонент по-разному. Без лишних опций унифицируется код и внешний вид компонентов, упрощается поддержка и взаимозаменяемость.</li>
+</ol>
+</SToggle>
+
+## Стандартные поля ввода
+
+```vue
+<template>
+    <SInput v-model="value" placeholder="Обычный инпут" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const value = ref('')
+</script>
+```
+
+Также поддерживаются стандартные HTML-типы полей:
+
+```vue
+<template>
+    <SInput v-model="value1" type="number" placeholder="Номер" />
+    <SInput v-model="value2" type="email" placeholder="Email" />
+    <SInput v-model="value3" type="password" placeholder="Пароль" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const value1 = ref('')
+const value2 = ref('')
+const value3 = ref('')
+</script>
+```
+
+## Многострочное поле ввода
+
+```vue
+<template>
+    <SInput v-model="value" type="textarea" placeholder="Введите длинный текст..." />
+</template>
+<script setup>
+import { ref } from 'vue'
+const value = ref('')
+</script>
+```
+
+## Префикс / суффикс
+
+Простой текст задаём пропами `prefix` / `suffix`, а для произвольного контента (иконки и т.п.) — одноимёнными слотами:
+
+```vue
+<template>
+    <SInput v-model="value1" prefix="$" type="number" placeholder="Префикс" />
+    <SInput v-model="value2" type="number" placeholder="Кастомный префикс">
+        <template #prefix>
+            <FontAwesomeIcon icon="star" />
+        </template>
+    </SInput>
+    <SInput v-model="value3" suffix="₽" type="number" placeholder="Суффикс" />
+    <SInput v-model="value4" type="number" placeholder="Кастомный суффикс">
+        <template #suffix>
+            <STooltip>Подсказка к полю</STooltip>
+        </template>
+    </SInput>
+</template>
+<script setup>
+import { ref } from 'vue'
+const value1 = ref('')
+const value2 = ref('')
+const value3 = ref('')
+const value4 = ref('')
+</script>
+```
+
+## Недоступное состояние
+
+```vue
+<template>
+    <SInput v-model="value" disabled />
+</template>
+<script setup>
+import { ref } from 'vue'
+const value = ref('Иван Иванов')
+</script>
+```
+
+## Поле ввода с кнопкой очистки
+
+Добавляем атрибут `clearable` — кнопка очистки появляется, когда в поле есть значение:
+
+```vue
+<template>
+    <SInput v-model="value" clearable placeholder="Введите текст" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const value = ref('Очисти меня')
+</script>
+```
+
+## События
+
+```vue
+<template>
+    <SInput @change="(newValue) => console.log(newValue)" placeholder="Печатаем и смотрим консоль" style="width: 100%" />
+</template>
+
+<script setup>
+import { SInput } from 'startup-ui'
+</script>
+```
+
+## Кастомные стили для инпута
+
+Если нужно задать кастомные стили именно для вложенного инпута, то задаем их через `input-style`:
+
+```vue
+<template>
+    <SInput v-model="value" input-style="text-align: center" />
+</template>
+<script setup>
+import { ref } from 'vue'
+const value = ref('По центру')
+</script>
+```
+
+## Интерфейс компонента
+
+### Свойства (Props)
+
+| Название | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| modelValue / v-model | `number \| string \| null` | `undefined` | Связанное значение поля ввода. |
+| type | `'text' \| 'string' \| 'number' \| 'email' \| 'password' \| 'textarea'` | `'text'` | Внутренний тип поля. При значении `textarea` отрисовывается многострочное поле. |
+| placeholder | string | `undefined` | Текст-заполнитель, отображаемый, когда поле пустое. |
+| prefix | string | `undefined` | Простой текст для отображения в начале поля. Добавляет класс `.has-prefix` обертке. |
+| suffix | string | `undefined` | Простой текст для отображения в конце поля. Добавляет класс `.has-suffix` обертке. |
+| clearable | boolean | `false` | Показывает кнопку очистки, когда в поле есть значение. |
+| disabled | boolean | `false` | Флаг, отключающий интерактивность поля. |
+| rows | number | `3` | Количество видимых строк текста (применяется только при `type="textarea"`). |
+| inputStyle | `StyleValue` | `undefined` | CSS-стили, передаваемые напрямую внутреннему элементу (`input` или `textarea`). |
+
+### Слоты (Slots)
+
+| Название | Описание |
+|----------|----------|
+| prefix | Расширенный контент (например, иконки) перед текстом. Переопределяет проп `prefix`. |
+| suffix | Расширенный контент (например, иконки) после текста. Переопределяет проп `suffix`. |
+
+### События (Events)
+
+| Название | Параметры | Описание |
+|----------|-----------|----------|
+| change | `(value: string)` | Срабатывает на нативное событие `@input`. Передает текущее строковое значение. |
+
+<style lang="scss">
+.s-input {
+    color: var(--s-text);
+}
+</style>