@dxtmisha/wiki 0.24.2 → 0.25.1

package/src/media/mdx/Field/slots.en.mdx

@@ -0,0 +1,138 @@
+### `default`
+
+Slot for placing the main input element (input, select, textarea, etc.). Required slot.
+
+**Parameters:**
+- `props: FieldControl` — object with data for binding the input element
+
+
+## FieldControl
+
+`FieldControl` — object passed to Field component slots, containing data for proper integration of input elements.
+
+### Type structure
+
+```typescript
+type FieldControl = {
+  /** Unique element identifier for binding label and input */
+  id: string
+
+  /** CSS classes for the visible input area */
+  className: string
+
+  /** CSS classes for the hidden native input element */
+  classHidden: string
+}
+```
+
+### Properties
+
+- **`id`** — unique identifier generated by the component to link `<label>` with the input element via the `for` attribute
+- **`className`** — CSS classes for styling the visible input element (applied to input, textarea, select, etc.)
+- **`classHidden`** — CSS classes for the hidden native input (used in custom components like Checkbox, Radio)
+
+### Property purposes
+
+#### `id`
+Ensures accessibility and proper label functionality:
+- Allows clicking on the label to focus the field
+- Links descriptions with the input element for screen readers
+- Generated automatically, must be used
+
+#### `className`
+Applies Field component styles to the input element:
+- Ensures visual consistency
+- Adds states (focus, disabled, validation)
+- Integrates skeleton states
+
+#### `classHidden`
+Used for native inputs in custom components:
+- Hides the original input visually
+- Preserves functionality and accessibility
+- Applied in Checkbox, Radio, Switch
+
+### Usage example
+
+```html
+<script setup>
+import { ref } from 'vue'
+
+const email = ref('')
+const password = ref('')
+const showPassword = ref(false)
+const error = ref('')
+
+const validateEmail = (value) => {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+  if (!emailRegex.test(value)) {
+    error.value = 'Invalid email'
+  } else {
+    error.value = ''
+  }
+}
+</script>
+
+<template>
+  <div class="form">
+    <!-- Simple field with search icon -->
+    <Field label="Email" :validation-message="error">
+      <template #leading>
+        <Icon name="email" />
+      </template>
+      <template #default="{ id, className }">
+        <input
+          :id="id"
+          :class="className"
+          type="email"
+          v-model="email"
+          @blur="validateEmail(email)"
+        />
+      </template>
+    </Field>
+
+    <!-- Field with password visibility toggle -->
+    <Field label="Password">
+      <template #default="{ id, className }">
+        <input
+          :id="id"
+          :class="className"
+          :type="showPassword ? 'text' : 'password'"
+          v-model="password"
+        />
+      </template>
+      <template #trailing>
+        <button
+          type="button"
+          @click="showPassword = !showPassword"
+          aria-label="Show password"
+        >
+          <Icon :name="showPassword ? 'visibility_off' : 'visibility'" />
+        </button>
+      </template>
+    </Field>
+
+    <!-- Field with custom element -->
+    <Field label="Select option">
+      <template #leading>
+        <Icon name="tune" />
+      </template>
+      <template #default="{ id, className }">
+        <select :id="id" :class="className" v-model="selectedOption">
+          <option value="1">Option 1</option>
+          <option value="2">Option 2</option>
+          <option value="3">Option 3</option>
+        </select>
+      </template>
+      <template #trailing>
+        <Icon name="expand_more" />
+      </template>
+    </Field>
+  </div>
+</template>
+```
+
+In this example:
+- Each field uses `id` and `className` from `FieldControl`
+- `leading` slot adds icons to the left of the input
+- `trailing` slot adds interactive elements to the right
+- All elements are properly integrated into the Field structure

package/src/media/mdx/Field/slots.ru.mdx

@@ -0,0 +1,138 @@
+### `default`
+
+Слот для размещения основного элемента ввода (input, select, textarea и т.д.). Обязательный слот.
+
+**Параметры:**
+- `props: FieldControl` — объект с данными для связывания элемента ввода
+
+
+## FieldControl
+
+`FieldControl` — объект, передаваемый в слоты компонента Field, содержащий данные для корректной интеграции элементов ввода.
+
+### Структура типа
+
+```typescript
+type FieldControl = {
+  /** Уникальный идентификатор элемента для связывания label и input */
+  id: string
+
+  /** CSS-классы для видимой зоны ввода */
+  className: string
+
+  /** CSS-классы для скрытого нативного элемента ввода */
+  classHidden: string
+}
+```
+
+### Свойства
+
+- **`id`** — уникальный идентификатор, генерируемый компонентом для связывания `<label>` с элементом ввода через атрибут `for`
+- **`className`** — CSS-классы для стилизации видимого элемента ввода (применяются к input, textarea, select и т.д.)
+- **`classHidden`** — CSS-классы для скрытого нативного input (используется в кастомных компонентах типа Checkbox, Radio)
+
+### Назначение свойств
+
+#### `id`
+Обеспечивает доступность (accessibility) и корректную работу label:
+- Позволяет кликать на метку для фокуса на поле
+- Связывает описания с элементом ввода для скринридеров
+- Генерируется автоматически, использовать обязательно
+
+#### `className`
+Применяет стили компонента Field к элементу ввода:
+- Обеспечивает визуальное единообразие
+- Добавляет состояния (focus, disabled, validation)
+- Интегрирует скелетон-состояния
+
+#### `classHidden`
+Используется для нативных input в кастомных компонентах:
+- Скрывает оригинальный input визуально
+- Сохраняет функциональность и доступность
+- Применяется в Checkbox, Radio, Switch
+
+### Пример использования
+
+```html
+<script setup>
+import { ref } from 'vue'
+
+const email = ref('')
+const password = ref('')
+const showPassword = ref(false)
+const error = ref('')
+
+const validateEmail = (value) => {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+  if (!emailRegex.test(value)) {
+    error.value = 'Некорректный email'
+  } else {
+    error.value = ''
+  }
+}
+</script>
+
+<template>
+  <div class="form">
+    <!-- Простое поле с иконкой поиска -->
+    <Field label="Email" :validation-message="error">
+      <template #leading>
+        <Icon name="email" />
+      </template>
+      <template #default="{ id, className }">
+        <input
+          :id="id"
+          :class="className"
+          type="email"
+          v-model="email"
+          @blur="validateEmail(email)"
+        />
+      </template>
+    </Field>
+
+    <!-- Поле с переключением видимости пароля -->
+    <Field label="Пароль">
+      <template #default="{ id, className }">
+        <input
+          :id="id"
+          :class="className"
+          :type="showPassword ? 'text' : 'password'"
+          v-model="password"
+        />
+      </template>
+      <template #trailing>
+        <button
+          type="button"
+          @click="showPassword = !showPassword"
+          aria-label="Показать пароль"
+        >
+          <Icon :name="showPassword ? 'visibility_off' : 'visibility'" />
+        </button>
+      </template>
+    </Field>
+
+    <!-- Поле с кастомным элементом -->
+    <Field label="Выберите опцию">
+      <template #leading>
+        <Icon name="tune" />
+      </template>
+      <template #default="{ id, className }">
+        <select :id="id" :class="className" v-model="selectedOption">
+          <option value="1">Опция 1</option>
+          <option value="2">Опция 2</option>
+          <option value="3">Опция 3</option>
+        </select>
+      </template>
+      <template #trailing>
+        <Icon name="expand_more" />
+      </template>
+    </Field>
+  </div>
+</template>
+```
+
+В этом примере:
+- Каждое поле использует `id` и `className` из `FieldControl`
+- Слот `leading` добавляет иконки слева от ввода
+- Слот `trailing` добавляет интерактивные элементы справа
+- Все элементы корректно интегрированы в структуру Field

package/src/media/mdx/Field/value.en.mdx

@@ -1,28 +1,49 @@
-## Value state (value & isValue)
-
-`Field` separates actual input content from the *visual filled state*.
-
-### Properties
-
-- **value** – Actual content (string / number, etc.) you pass into the inner `<input>` via the default slot. `Field` does not manage (no `v-model`) or mutate / validate it, **but** it reads it reactively through a computed `focusValue` purely for visual purposes: displaying the current textual snapshot near the caption (scoreboardInput) and harmonizing layout with caption + extra controls. Priority when deriving `focusValue`: element with `[data-length]` → main `<input>` → `props.value` (string). This read does not drive business rules.
-- **isValue** (`boolean`) – Forces the visual “filled” state (floating / collapsed label + classes) even if the actual input is empty.
-
-### Interaction
-
-1. Non‑empty real input ⇒ filled appearance regardless of `isValue`.
-2. Empty real input + `isValue = true` ⇒ visually filled (preload, mask, delayed prefill cases).
-3. Empty real input + no / false `isValue` ⇒ visually empty.
-4. `focusValue` is used only to render inline mirrored text when caption zone is active and optionally to read length from `[data-length]` element; do not rely on it for validation or domain logic.
-5. Validation, helper messages, counters (implemented externally) must use the real input value, not `isValue`.
-
-### When to use `isValue`
-
-- Preload “as if filled” look while fetching data.
-- Masked / templated inputs needing a permanently floated label.
-- Visual demos / stories without binding a real value yet.
-
-### Recommendations
-
-- Don’t overload `isValue` for logic; it’s strictly visual.
-- Keep reactive value handling outside (wrapper with `v-model`), treat `Field` as structural shell.
-- For length-sensitive styling add an attribute `[data-length]` to an inner element; priority: `[data-length]` → `<input>` → `props.value`.
+## Value state
+
+Properties `value` and `isValue` are designed to control the visual filled state of the field independently of the actual content.
+
+**Properties:**
+
+- `value` — actual field content (string/number) passed to the inner element via slot
+- `isValue` — forcibly activates the visual "filled" state even when the value is empty
+
+Properties work together: `Field` reads `value` reactively through `focusValue` for visual purposes (displaying text in scoreboard, caption handling), but does not manage it directly or validate it. If the real value is non-empty, the field automatically receives the visual "filled" state regardless of `isValue`. When the value is empty, the `isValue = true` flag forcibly activates the visual filled mode (floating label, corresponding classes), which is useful for preloads, masks, or delayed data insertion.
+
+```html
+<script setup>
+import { ref } from 'vue'
+
+const value = ref('')
+const isLoading = ref(true)
+</script>
+
+<template>
+  <!-- Normal behavior -->
+  <Field label="Name">
+    <template #default="{ id, className }">
+      <input :id="id" :class="className" v-model="value" />
+    </template>
+  </Field>
+
+  <!-- Forced "filled" state -->
+  <Field
+    label="Email"
+    :value="value"
+    :is-value="true"
+  >
+    <template #default="{ id, className }">
+      <input :id="id" :class="className" v-model="value" />
+    </template>
+  </Field>
+
+  <!-- Preload with visual state -->
+  <Field
+    label="Data"
+    :is-value="isLoading"
+  >
+    <template #default="{ id, className }">
+      <input :id="id" :class="className" v-model="value" />
+    </template>
+  </Field>
+</template>
+```

package/src/media/mdx/Field/value.ru.mdx

@@ -1,28 +1,49 @@
-## Состояние значения (value и isValue)
-
-`Field` отделяет фактическое содержимое ввода от *визуального состояния заполненности*.
-
-### Свойства
-
-- **value** – Фактическое содержимое (строка/число и т.п.), которое вы передаёте во внутренний `<input>` через слот. `Field` не управляет значением (нет `v-model` и мутаций) и не валидирует его, **но** считывает его ОДИН раз реактивно через вычисление `focusValue` для чисто визуальных целей: вывода «текущего» текста рядом с caption (scoreboardInput) и корректной работы комбинированной зоны caption/доборных элементов. Если передан `props.value` (строка) – используется он; иначе ищется реальный `<input>` или элемент с `[data-length]`. Это чтение не влияет на логику валидации и не изменяет значение.
-- **isValue** (`boolean`) – Принудительно включает «режим заполненности» (плавающая / сжатая метка, соответствующие классы), даже если реальный `value` пуст.
-
-### Взаимодействие
-
-1. Реальное непустое значение (через слот) всегда включает визуальное состояние «заполнено» независимо от `isValue`.
-2. Пустое значение + `isValue = true` ⇒ поле выглядит заполненным (прелоад, маска, отложенная подстановка).
-3. Пустое значение + отсутствие/`false` у `isValue` ⇒ визуально пусто.
-4. `focusValue` используется только для отображения текста в зоне scoreboard при активном caption и (опционально) для считывания длины из элемента с `[data-length]`; не применять его для бизнес‑логики.
-5. Валидация, helper‑сообщения и счётчик символов (если реализованы вовне) должны опираться на фактическое значение input, а не на `isValue`.
-
-### Когда использовать `isValue`
-
-- Предварительный показ «как будто заполнено», пока грузятся данные.
-- Маскированные / шаблонные поля, где нужно зафиксировать плавающий label.
-- Демо/сторис без передачи реального значения.
-
-### Рекомендации
-
-- Не подменяйте бизнес‑логику через `isValue`; он только про визуал.
-- Если требуется реактивная работа с данными — управляйте значением во внешнем компоненте с `v-model`, а `Field` используйте как каркас.
-- Для корректного подсчёта длины можно пометить внутренний элемент атрибутом `data-length`; приоритет чтения: элемент с `[data-length]` → основной `<input>` → `props.value`.
+## Состояние значения
+
+Свойства `value` и `isValue` предназначены для управления визуальным состоянием заполненности поля независимо от фактического содержимого.
+
+**Свойства:**
+
+- `value` — фактическое содержимое поля (строка/число), передаваемое во внутренний элемент через слот
+- `isValue` — принудительно активирует визуальное состояние "заполнено" даже при пустом значении
+
+Свойства работают совместно: `Field` считывает `value` реактивно через `focusValue` для визуальных целей (отображение текста в scoreboard, работа с caption), но не управляет им напрямую и не валидирует. Если реальное значение непустое, поле автоматически получает визуальное состояние "заполнено" независимо от `isValue`. При пустом значении флаг `isValue = true` принудительно активирует визуальный режим заполненности (плавающая метка, соответствующие классы), что полезно для прелоадов, масок или отложенной подстановки данных.
+
+```html
+<script setup>
+import { ref } from 'vue'
+
+const value = ref('')
+const isLoading = ref(true)
+</script>
+
+<template>
+  <!-- Обычное поведение -->
+  <Field label="Имя">
+    <template #default="{ id, className }">
+      <input :id="id" :class="className" v-model="value" />
+    </template>
+  </Field>
+
+  <!-- Принудительное состояние "заполнено" -->
+  <Field
+    label="Email"
+    :value="value"
+    :is-value="true"
+  >
+    <template #default="{ id, className }">
+      <input :id="id" :class="className" v-model="value" />
+    </template>
+  </Field>
+
+  <!-- Прелоад с визуальным состоянием -->
+  <Field
+    label="Данные"
+    :is-value="isLoading"
+  >
+    <template #default="{ id, className }">
+      <input :id="id" :class="className" v-model="value" />
+    </template>
+  </Field>
+</template>
+```

package/src/media/mdx/Field/width.en.mdx

@@ -1,26 +1,28 @@
 ````markdown
-## Width (width)
+## Field width
 
-Property to control the horizontal size of the Field.
+Property `width` defines the horizontal size of the Field container.
 
-### Property
-- **width** (`string`) — Accept ANY valid CSS value: "320px", "48rem", "50%", "min(100%,320px)", "clamp(240px,40vw,480px)" or a design token (e.g. "sm") if your design system resolves it. The value "custom" is an internal technical marker (normally not used directly).
+**Possible values:**
 
-### Behavior
-- Not set: fluid (depends on container).
-- With `block`: always 100% width.
-- Any explicit value: applied directly (no extra wrapper logic).
+- any valid CSS value (`'320px'`, `'48rem'`, `'50%'`, `'min(100%,320px)'`, `'clamp(240px,40vw,480px)'`)
+- design system tokens (e.g., `'sm'`, `'md'`, `'lg'` if supported)
+- `'custom'` — internal technical marker (not used directly)
 
-### Examples
-```vue
-<DesignField label="auto" />
-<DesignField width="320px" label="320px" />
-<DesignField width="50%" label="50%" />
-<DesignField width="min(100%,320px)" label="min(...)" />
-```
+Controls the fixed or relative width of the field, applying the value directly without additional wrappers. When the property is not set, the width remains flexible and depends on the parent container. When the `block` property is active (set to `true`), the field takes 100% width regardless of the specified `width` value, with block mode taking priority.
+
+```html
+<!-- Automatic width -->
+<Field label="auto" />
+
+<!-- Fixed width -->
+<Field width="320px" label="320px" />
 
-### Notes
-- Prefer parent layout (flex / grid) for responsiveness; use `width` for quick explicit sizing.
-- Complex expressions (calc / min / clamp) are fine if valid CSS.
-- `block` can override or take precedence if style specificity is higher.
+<!-- Relative width -->
+<Field width="50%" label="50%" />
+
+<!-- CSS functions -->
+<Field width="min(100%, 320px)" label="min(...)" />
+<Field width="clamp(240px, 40vw, 480px)" label="clamp(...)" />
+```
 ````

package/src/media/mdx/Field/width.ru.mdx

@@ -1,24 +1,26 @@
-## Ширина (width)
+## Ширина поля
 
-Свойство для управления горизонтальным размером Field.
+Свойство `width` определяет горизонтальный размер контейнера Field.
 
-### Свойство
-- **width** (`string`) — Передавайте ЛЮБОЕ валидное CSS‑значение: `"320px"`, `"48rem"`, `"50%"`, `"min(100%,320px)"`, `"clamp(240px,40vw,480px)"`, либо дизайн‑токен (например `"sm"`, если поддержан системой). Значение `"custom"` — внутренняя тех. метка (обычно не использовать).
+**Возможные значения:**
 
-### Поведение
-- Не задано: ширина «резиновая» (зависит от контейнера).
-- С `block`: всегда 100%.
-- Любое конкретное значение: применяется напрямую без доп. обёрток.
+- любое валидное CSS-значение (`'320px'`, `'48rem'`, `'50%'`, `'min(100%,320px)'`, `'clamp(240px,40vw,480px)'`)
+- дизайн-токены системы (например, `'sm'`, `'md'`, `'lg'` при поддержке)
+- `'custom'` — внутренняя техническая метка (не используется напрямую)
 
-### Примеры
-```vue
-<DesignField label="auto" />
-<DesignField width="320px" label="320px" />
-<DesignField width="50%" label="50%" />
-<DesignField width="min(100%,320px)" label="min(...)" />
-```
+Контролирует фиксированную или относительную ширину поля, применяя значение напрямую без дополнительных обёрток. При отсутствии свойства ширина остаётся гибкой и зависит от родительского контейнера. При активном свойстве `block` (установлено в `true`) поле занимает 100% ширины независимо от заданного значения `width`, приоритет имеет блочный режим.
+
+```html
+<!-- Автоматическая ширина -->
+<Field label="auto" />
+
+<!-- Фиксированная ширина -->
+<Field width="320px" label="320px" />
 
-### Заметки
-- Предпочтительнее управлять адаптивностью через родительский layout (flex / grid) и использовать width точечно.
-- Сложные выражения (calc / min / clamp) поддерживаются, если валидны для CSS.
-- `block` может переопределить индивидуально заданную ширину при конфликте приоритетов стилей.
+<!-- Относительная ширина -->
+<Field width="50%" label="50%" />
+
+<!-- CSS-функции -->
+<Field width="min(100%, 320px)" label="min(...)" />
+<Field width="clamp(240px, 40vw, 480px)" label="clamp(...)" />
+```

package/src/media/mdx/Field/wikiMdxField.ts

@@ -6,16 +6,12 @@ import cancelEn from './cancel.en.mdx'
 import cancelRu from './cancel.ru.mdx'
 import arrowsEn from './arrows.en.mdx'
 import arrowsRu from './arrows.ru.mdx'
-import slotDefaultEn from './slot.default.en.mdx'
-import slotDefaultRu from './slot.default.ru.mdx'
-import slotLeadingEn from './slot.leading.en.mdx'
-import slotLeadingRu from './slot.leading.ru.mdx'
-import slotTrailingEn from './slot.trailing.en.mdx'
-import slotTrailingRu from './slot.trailing.ru.mdx'
 import valueEn from './value.en.mdx'
 import valueRu from './value.ru.mdx'
 import widthEn from './width.en.mdx'
 import widthRu from './width.ru.mdx'
+import slotsEn from './slots.en.mdx'
+import slotsRu from './slots.ru.mdx'
 
 /**
  * MDX files for Field component
@@ -25,35 +21,27 @@ import widthRu from './width.ru.mdx'
 export const wikiMdxField: StorybookComponentsMdxItem = {
   name: 'Field',
   descriptions: {
-    'field': {
-      en: fieldEn,
-      ru: fieldRu
-    },
-    'cancel': {
-      en: cancelEn,
-      ru: cancelRu
-    },
-    'arrows': {
+    arrows: {
       en: arrowsEn,
       ru: arrowsRu
     },
-    'slot.default': {
-      en: slotDefaultEn,
-      ru: slotDefaultRu
+    cancel: {
+      en: cancelEn,
+      ru: cancelRu
     },
-    'slot.leading': {
-      en: slotLeadingEn,
-      ru: slotLeadingRu
+    field: {
+      en: fieldEn,
+      ru: fieldRu
     },
-    'slot.trailing': {
-      en: slotTrailingEn,
-      ru: slotTrailingRu
+    slots: {
+      en: slotsEn,
+      ru: slotsRu
     },
-    'value': {
+    value: {
       en: valueEn,
       ru: valueRu
     },
-    'width': {
+    width: {
       en: widthEn,
       ru: widthRu
     }