@central-design-system/components 4.0.0-alpha.2 → 4.0.0-alpha.4

package/llms/llms-components.txt

@@ -1,6 +1,6 @@
 # Central Design System (CDS 4) — компоненты
 
-> Версия: 4.0.0-alpha.2
+> Версия: 4.0.0-alpha.4
 > Документация всех компонентов `@central-design-system/components`: назначение, примеры и полный контракт API.
 > Сгенерировано автоматически (`bun run generate:meta` → `bun run generate:llms`). Не редактировать вручную.
 
@@ -19750,6 +19750,517 @@ function onUpdateModelValue(value: boolean, id: number) {
 
 ---
 
+# CdsOtpInput
+
+_Категория: Controls · появился в 4.0.0 · статус: new_
+
+Поле ввода одноразового кода — из SMS, письма или приложения-аутентификатора. Внешне это ряд отдельных ячеек, но ввод принимает один скрытый `input`: поэтому работают автозаполнение кода из SMS, вставка целой строкой из буфера, выделение и стрелки, а фокус не приходится перепрыгивать между ячейками вручную.
+
+**Смотрите также:** Для обычного короткого текста или числа возьмите CdsTextInput: `CdsOtpInput` нужен там, где длина ввода известна заранее и каждый символ показывается отдельной ячейкой.
+
+## Анатомия
+
+Ячейки (`CdsOtpField`) только рисуют код — введённый символ, заполнитель или
+мигающую каретку. Настоящий ввод принимает скрытый `input`: он прижат к нижнему
+краю компонента, поэтому подсказка автозаполнения из SMS появляется под ячейками
+и ничего не перекрывает. Между ячейками может стоять разделитель
+(`CdsOtpSeparator`), а в слитном виде ячейки собираются в группу (`CdsOtpGroup`).
+
+**Пример — `Anatomy.vue`:**
+
+```vue
+<script setup lang="ts">
+import AnatomyDemo from '@cds/utils/docs/AnatomyDemo.vue';
+import { CdsOtpInput } from '@central-design-system/components';
+
+// Схема 1: обычный ряд — ячейки и разделители между ними
+const fieldsMarkers = [
+  { selector: '.cds-otp-input__content', label: 'Ряд ячеек', side: 'right' as const },
+  { selector: '.cds-otp-field', label: 'Ячейка (CdsOtpField)', side: 'top' as const },
+  { selector: '.cds-otp-separator', label: 'Разделитель (CdsOtpSeparator)', side: 'bottom' as const },
+  { selector: '.cds-otp-field__placeholder', label: 'Символ-заполнитель', side: 'bottom' as const }
+];
+
+// Схема 2: слитный вид — ячейки собраны в общую группу
+const mergedMarkers = [
+  { selector: '.cds-otp-field', label: 'Ячейка (CdsOtpField)', side: 'top' as const },
+  { selector: '.cds-otp-group', label: 'Группа (CdsOtpGroup)', side: 'bottom' as const }
+];
+</script>
+
+<template>
+  <div class="flex flex-col gap-600">
+    <AnatomyDemo :markers="fieldsMarkers">
+      <CdsOtpInput model-value="12" divider="-" placeholder="0" />
+    </AnatomyDemo>
+
+    <AnatomyDemo :markers="mergedMarkers">
+      <CdsOtpInput model-value="12" merged />
+    </AnatomyDemo>
+  </div>
+</template>
+```
+
+## Вариации
+
+### Длина и тип кода
+
+Свойство `length` задаёт число ячеек, `type` — что можно вводить: `number`
+(по умолчанию) принимает только цифры и открывает цифровую клавиатуру на
+мобильных, `text` — любые символы, `password` дополнительно скрывает введённое
+точками. Тот же эффект без смены типа даёт `masked`.
+
+**Пример — `LengthAndType.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-400">
+    <CdsOtpInput :length="4" model-value="1234" />
+    <CdsOtpInput type="text" model-value="AB12CD" />
+    <CdsOtpInput type="password" model-value="123456" />
+  </div>
+</template>
+```
+
+### Допустимые символы
+
+Свойство `pattern` сужает набор символов: имя готового набора (`numeric`,
+`alpha`, `alphanumeric`, `unicode-alpha`, `unicode-alphanumeric`) или своё
+регулярное выражение. Проверка идёт посимвольно — лишние символы не попадут в
+поле ни с клавиатуры, ни из буфера обмена.
+
+**Пример — `Pattern.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-400">
+    <CdsOtpInput type="text" pattern="alpha" :length="4" placeholder="A" />
+    <CdsOtpInput type="text" pattern="alphanumeric" placeholder="X" />
+    <CdsOtpInput type="text" :pattern="/[0-9A-F]/" placeholder="F" />
+  </div>
+</template>
+```
+
+### Разделитель
+
+Свойство `divider` ставит символ между ячейками — например, дефис в коде вида
+`123-456`. Слот `divider` даёт полную свободу разметки и получает `index` —
+номер ячейки слева от разделителя, так что разделитель можно поставить только
+в нужном месте.
+
+**Пример — `Divider.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsIcon, CdsOtpInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-400">
+    <CdsOtpInput divider="-" model-value="123456" />
+
+    <CdsOtpInput model-value="123456">
+      <template #divider="{ index }">
+        <CdsIcon v-if="index === 2" name="minus" size="sm" />
+      </template>
+    </CdsOtpInput>
+  </div>
+</template>
+```
+
+### Слитный вид
+
+Свойство `merged` убирает промежутки: ячейки становятся одним полем с общей
+рамкой. Такой вид компактнее и меньше дробит форму.
+
+**Пример — `Merged.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsOtpInput merged model-value="1234" />
+  </div>
+</template>
+```
+
+### Заполнитель
+
+Свойство `placeholder` показывает символ в пустых ячейках — подсказку формата
+или просто точку, чтобы ряд не выглядел пустым.
+
+**Пример — `Placeholder.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-400">
+    <CdsOtpInput placeholder="0" />
+    <CdsOtpInput placeholder="•" />
+  </div>
+</template>
+```
+
+### Размеры
+
+Свойство `size` меняет высоту ячеек и размер шрифта. Размер по умолчанию — `md`.
+
+**Пример — `Sizes.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpInput } from '@central-design-system/components';
+
+const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const;
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-400">
+    <CdsOtpInput v-for="size of sizes" :key="size" :size="size" :length="4" model-value="1234" />
+  </div>
+</template>
+```
+
+### Состояния
+
+`disabled` блокирует ввод, `error` подсвечивает весь ряд ошибкой, `loading`
+показывает индикатор поверх ячеек и не стирает набранный код. `focus-all`
+подсвечивает весь ряд, пока поле в фокусе, а не только активную ячейку.
+
+**Пример — `States.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-400">
+    <CdsOtpInput :length="4" model-value="12" disabled />
+    <CdsOtpInput :length="4" model-value="1234" error />
+    <CdsOtpInput :length="4" model-value="1234" loading />
+    <CdsOtpInput :length="4" model-value="12" focus-all />
+  </div>
+</template>
+```
+
+### Слоты
+
+| Слот      | Описание                                                                      |
+| :-------- | :---------------------------------------------------------------------------- |
+| `fields`  | Ряд ячеек целиком — своя разметка из `CdsOtpGroup`, `CdsOtpField` и `CdsOtpSeparator` |
+| `divider` | Разделитель между ячейками, `index` — номер ячейки слева от него               |
+| `loader`  | Свой индикатор загрузки (при `loading`)                                        |
+| `default` | Произвольный контент поверх ячеек                                              |
+
+Слот `fields` нужен, когда ячейки собираются в группы: каждая `CdsOtpField`
+получает свой `index`, а `CdsOtpGroup` объединяет соседние ячейки в общую рамку.
+
+**Пример — `CustomFields.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpField, CdsOtpGroup, CdsOtpInput, CdsOtpSeparator } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsOtpInput model-value="123456">
+      <template #fields>
+        <CdsOtpGroup merged>
+          <CdsOtpField v-for="index of [0, 1, 2]" :key="index" :index="index" />
+        </CdsOtpGroup>
+
+        <CdsOtpSeparator>—</CdsOtpSeparator>
+
+        <CdsOtpGroup merged>
+          <CdsOtpField v-for="index of [3, 4, 5]" :key="index" :index="index" />
+        </CdsOtpGroup>
+      </template>
+    </CdsOtpInput>
+  </div>
+</template>
+```
+
+## Рекомендации
+
+| ✅ Хорошо | ❌ Плохо |
+| --- | --- |
+| Число ячеек равно длине кода — пользователь сразу видит, сколько символов вводить. | Лишние ячейки заставляют гадать, весь ли код набран. |
+| Код целиком набирается в одном поле: вставка из буфера и автозаполнение из SMS работают. | Отдельные текстовые поля ломают вставку кода и заставляют вручную перепрыгивать фокус. |
+| При ошибке поле остаётся доступным, а текст рядом говорит, что делать дальше. | Заблокированное поле без объяснения не даёт исправить код. |
+
+## Сценарии использования
+
+### Подтверждение по SMS
+
+Событие `finish` срабатывает, как только код набран целиком, — отправляйте
+запрос по нему, отдельная кнопка не нужна. На время проверки включите `loading`:
+код остаётся на экране, а поле не выглядит сломанным. Если сервер не принял код,
+`error` подсвечивает ряд, а методы `reset()` и `focus()` через ref очищают поле
+и возвращают в него курсор.
+
+**Пример — `SmsConfirmation.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const otpRef = ref<InstanceType<typeof CdsOtpInput>>();
+
+const code = ref('');
+const loading = ref(false);
+const status = ref<'idle' | 'success' | 'error'>('idle');
+
+// Имитация проверки кода на сервере: верный код — 123456
+function onFinish(value: string) {
+  loading.value = true;
+  status.value = 'idle';
+
+  setTimeout(() => {
+    loading.value = false;
+    status.value = value === '123456' ? 'success' : 'error';
+
+    if (status.value === 'error') {
+      otpRef.value?.reset();
+      otpRef.value?.focus();
+    }
+  }, 1000);
+}
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-300">
+    <p class="text-200 text-content-secondary">Код отправлен на +7 999 000-00-00</p>
+
+    <CdsOtpInput
+      ref="otpRef"
+      v-model="code"
+      :loading="loading"
+      :error="status === 'error'"
+      @finish="onFinish"
+      @update:model-value="status = 'idle'"
+    />
+
+    <p v-if="status === 'success'" class="text-200 text-status-success-content">Код подтверждён</p>
+    <p v-else-if="status === 'error'" class="text-200 text-status-danger-content">
+      Код неверный — введите последние цифры из SMS ещё раз
+    </p>
+    <p v-else class="text-200 text-content-tertiary">Введите 123456, чтобы увидеть подтверждение</p>
+  </div>
+</template>
+```
+
+### Повторная отправка кода
+
+Кнопка «Отправить снова» открывается по таймеру — так пользователь не завалит
+запросами шлюз. Вместе с новым кодом сбрасывайте поле: `reset()` очищает ячейки,
+`focus()` ставит курсор в первую, и старый код не смешивается с новым.
+
+**Пример — `ResendCode.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsOtpInput } from '@central-design-system/components';
+import { onScopeDispose, ref } from 'vue';
+
+const otpRef = ref<InstanceType<typeof CdsOtpInput>>();
+
+const code = ref('');
+const seconds = ref(15);
+
+let timer: ReturnType<typeof setInterval> | undefined;
+
+function countdown() {
+  clearInterval(timer);
+
+  timer = setInterval(() => {
+    seconds.value -= 1;
+
+    if (seconds.value <= 0) clearInterval(timer);
+  }, 1000);
+}
+
+function resend() {
+  seconds.value = 15;
+  countdown();
+
+  otpRef.value?.reset();
+  otpRef.value?.focus();
+}
+
+countdown();
+onScopeDispose(() => clearInterval(timer));
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-300">
+    <CdsOtpInput ref="otpRef" v-model="code" placeholder="•" />
+
+    <CdsButton
+      appearance="tertiary"
+      size="sm"
+      :disabled="seconds > 0"
+      :text="seconds > 0 ? `Отправить снова через ${seconds} с` : 'Отправить код снова'"
+      @click="resend"
+    />
+  </div>
+</template>
+```
+
+### Код в форме
+
+Когда код — часть формы входа, оставьте кнопку подтверждения: она даёт явный
+момент отправки. Кнопка ждёт, пока набраны все символы, — длину кода видно из
+`v-model`, а `disabled` на поле фиксирует уже подтверждённый код.
+
+**Пример — `TwoFactorForm.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsForm, CdsOtpInput } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const code = ref('');
+const loading = ref(false);
+const confirmed = ref(false);
+
+const isComplete = computed(() => code.value.length === 6);
+
+function submit() {
+  loading.value = true;
+
+  setTimeout(() => {
+    loading.value = false;
+    confirmed.value = true;
+  }, 1000);
+}
+</script>
+
+<template>
+  <CdsForm class="flex flex-col items-center gap-300 w-[350px] m-auto" @submit.prevent="submit">
+    <p class="text-200 text-content-secondary">Введите код из приложения-аутентификатора</p>
+
+    <CdsOtpInput v-model="code" :disabled="confirmed" divider="-" />
+
+    <CdsButton type="submit" text="Подтвердить вход" :disabled="!isComplete || confirmed" :loading="loading" block />
+
+    <p v-if="confirmed" class="text-200 text-status-success-content">Вход подтверждён</p>
+  </CdsForm>
+</template>
+```
+
+## API
+
+### CdsOtpInput
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `activeColor` | `string \| undefined` | — | no | Цвет компонента, когда он находится в активном состоянии |
+| `autofocus` | `boolean \| undefined` | — | no | Включает автофокус |
+| `baseColor` | `string \| undefined` | — | no | Цвет неактивного компонента |
+| `bgColor` | `string \| undefined` | — | no | Цвет фона компонента |
+| `color` | `string \| undefined` | — | no | Цвет компонента |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Заблокированное состояние |
+| `divider` | `string \| undefined` | — | no | Символ-разделитель, который ставится между ячейками кода |
+| `error` | `boolean \| undefined` | — | no | Состояние ошибки |
+| `focusAll` | `boolean \| undefined` | — | no | Подсвечивать все ячейки, пока поле находится в фокусе, а не только активную |
+| `focused` | `boolean \| undefined` | — | no | Управляет состоянием фокуса компонента. Когда `true`, компонент считается сфокусированным и может применять соответствующие стили или поведение. |
+| `height` | `string \| number \| undefined` | — | no | Высота компонента |
+| `label` | `string \| undefined` | `'$cds.input.otp'` | no | Доступное имя поля (`aria-label`). Принимает ключ локализации вида `$cds.input.otp` |
+| `length` | `string \| number \| undefined` | `6` | no | Количество ячеек кода |
+| `loading` | `string \| boolean \| undefined` | — | no | Индикатор загрузки для компонента |
+| `masked` | `boolean \| undefined` | — | no | Скрывать введённые символы точками |
+| `maxHeight` | `string \| number \| undefined` | — | no | Максимальная высота компонента |
+| `maxWidth` | `string \| number \| undefined` | — | no | Максимальная ширина компонента |
+| `merged` | `boolean \| undefined` | — | no | Слитный вид: ячейки объединяются в одно поле без промежутков между ними |
+| `minHeight` | `string \| number \| undefined` | — | no | Минимальная высота компонента |
+| `minWidth` | `string \| number \| undefined` | — | no | Минимальная ширина компонента |
+| `modelValue` | `string \| number \| undefined` | — | no | Значение компонента v-model |
+| `pattern` | `RegExp \| "numeric" \| "alpha" \| "alphanumeric" \| "unicode-alpha" \| "unicode-alphanumeric" \| undefined` | — | no | Допустимые символы: имя готового паттерна (`numeric`, `alpha`, `alphanumeric`, `unicode-alpha`, `unicode-alphanumeric`) или собственное регулярное выражение |
+| `placeholder` | `string \| undefined` | — | no | Символ-заполнитель, который показывается в пустой ячейке |
+| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Размер компонента |
+| `textColor` | `string \| undefined` | — | no | Цвет текста компонента |
+| `theme` | `string \| undefined` | — | no | Тема компонента |
+| `type` | `CdsOtpInputType \| undefined` | `'number'` | no | Тип вводимого кода. `number` ограничивает ввод цифрами, `password` скрывает символы |
+| `width` | `string \| number \| undefined` | — | no | Ширина компонента |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `finish` | `[value: string]` | Срабатывает, когда код набран полностью |
+| `update:focused` | `[focused: boolean]` | Срабатывает при получении или потере фокуса |
+| `update:modelValue` | `[value: string]` | Срабатывает при изменении значения компонента |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `any` | Произвольный контент поверх ячеек кода |
+| `divider` | `{ index: number; }` | Разделитель между ячейками. `index` — номер ячейки слева от разделителя |
+| `fields` | `any` | Полностью заменяет ряд ячеек собственной разметкой из `CdsOtpGroup`, `CdsOtpField` и `CdsOtpSeparator` |
+| `loader` | `any` | Пользовательский индикатор загрузки |
+
+**Exposed**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `blur` | `() => void` | Снять фокус с поля |
+| `focus` | `() => void` | Установить фокус на поле |
+| `inputRef` | `HTMLInputElement \| undefined` | Ref-ссылка на скрытый input, который принимает ввод кода |
+| `isFocused` | `boolean \| undefined` | Состояние фокуса поля |
+| `reset` | `() => void` | Очистить введённый код |
+
+### CdsOtpField
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `index` | `number` | — | yes | Порядковый номер ячейки, начиная с нуля |
+
+### CdsOtpGroup
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `merged` | `boolean \| null \| undefined` | — | no | Слитный вид группы. По умолчанию наследуется от родительского `CdsOtpInput` |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `any` | Ячейки кода группы |
+
+### CdsOtpSeparator
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `any` | Содержимое разделителя |
+
+---
+
 # CdsOverlay
 
 _Категория: Content · появился в 4.0.0_