@dxtmisha/wiki 0.24.1 → 0.24.3

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

@@ -1,22 +1,52 @@
-Field is the base container for form controls that composes label, messages, counter, icons, and progress. It provides a unified skeleton and classes for consistent layout.
+Base container for form controls that composes label, messages, counter, icons, and progress into a unified structure.
 
-### Purpose
+Field centralizes the visual representation management of input fields, handles focus and validation states, coordinates auxiliary element positioning, and provides a consistent API for building any type of inputs. It serves as the fundamental foundation for creating consistent forms with slot support, control icons, and subcomponent integration.
 
-- **Composition of subcomponents** — FieldLabel, FieldMessage, FieldCounter, Progress, icons
-- **Unified scaffold** — Wrapper template for the input area and helper zones (caption/prefix/suffix)
-- **State styles** — Manages focus, disabled, readonly, selected, block
-- **Slot support** — Integrates caption, prefix, suffix at the container level
+**Core capabilities:**
 
-### Core capabilities
+- Subcomponent composition (FieldLabel, FieldMessage, FieldCounter, Progress)
+- State management (focus, disabled, readonly, selected, block)
+- Slot coordination (caption, prefix, suffix, leading, trailing)
+- Validation highlighting based on validationMessage and forceShowMessage
+- Control icons with customizable visibility (cancel, arrows)
+- Flexible counter positioning via counterTop
+- Built-in helpers for sizing and icons (FieldSize, FieldIcons)
+- Loading progress integration and skeleton state
 
-- **Validation highlighting** — Based on `validationMessage` and a force show flag
-- **Character counter** — Position toggle via `counterTop`
-- **Control icons** — Cancel and navigation (arrows) with visibility flags
-- **Sizing helpers** — Built-in FieldSize and FieldIcons
-- **Progress integration** — Compact static progress for loading/status
+**Typical use cases:**
 
-### Integration
+- Base container for Input, Select, Textarea, and other form controls
+- Building custom form components with unified styling
+- Creating fields with validation and character counters
+- Developing component libraries with consistent UI
 
-Use Field as a foundation for constructing any input fields. It easily integrates labels, icons, messages, and progress. The component handles markup, classes, and consistency; concrete inputs provide the input logic.
+```html
+<script setup>
+import { ref } from 'vue'
+import { Field } from '@dxtmisha/constructor'
 
-> Field is a constructor wrapper: it doesn’t input data by itself, it organizes structure and auxiliary visuals.
+const value = ref('')
+
+// Field provides structure and management
+</script>
+
+<template>
+  <Field
+    label="Username"
+    helper-message="Enter your name"
+    :counter="value.length"
+    counter-max="50"
+  >
+    <template #default="{ id, className }">
+      <input
+        :id="id"
+        :class="className"
+        v-model="value"
+        maxlength="50"
+      />
+    </template>
+  </Field>
+</template>
+```
+
+> Field is a constructor container: it does not handle data input directly, but organizes structure, classes, and auxiliary element display for any type of input fields.

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

@@ -1,22 +1,52 @@
-Field — базовый контейнер для полей формы, который собирает метку, сообщения, счётчик, иконки и прогресс. Обеспечивает единый каркас и классы для консистентной верстки.
+Базовый контейнер для полей формы, который композирует метку, сообщения, счётчик, иконки и прогресс в единую структуру.
 
-### Назначение
+Field централизует управление визуальным представлением полей ввода, обрабатывает состояния фокуса и валидации, координирует расположение вспомогательных элементов и предоставляет согласованный API для построения любых типов инпутов. Является фундаментальной основой для создания консистентных форм с поддержкой слотов, иконок управления и интеграцией подкомпонентов.
 
-- **Композиция подкомпонентов** — FieldLabel, FieldMessage, FieldCounter, Progress, иконки
-- **Единый каркас** — Шаблон обёртки для поля ввода и вспомогательных зон (caption/prefix/suffix)
-- **Стили состояния** — Управление состояниями: focus, disabled, readonly, selected, block
-- **Поддержка слотов** — Встраивание caption, prefix, suffix на уровне контейнера
+**Основные возможности:**
 
-### Основные возможности
+- Композиция подкомпонентов (FieldLabel, FieldMessage, FieldCounter, Progress)
+- Управление состояниями (focus, disabled, readonly, selected, block)
+- Координация слотов (caption, prefix, suffix, leading, trailing)
+- Подсветка валидации на основе validationMessage и forceShowMessage
+- Иконки управления с настраиваемой видимостью (cancel, arrows)
+- Гибкое позиционирование счётчика через counterTop
+- Встроенные помощники для размеров и иконок (FieldSize, FieldIcons)
+- Интеграция прогресса загрузки и скелетон-состояния
 
-- **Подсветка валидации** — На основе validationMessage и флага принудительного показа
-- **Счетчик символов** — Переключение позиции счётчика через `counterTop`
-- **Иконки управления** — Отмена и навигация (стрелки) с флагами видимости
-- **Интеграция размеров** — Встроенные помощники FieldSize и FieldIcons
-- **Интеграция прогресса** — Компактный статичный прогресс для загрузок/состояний
+**Типичные сценарии использования:**
 
-### Интеграция
+- Базовый контейнер для Input, Select, Textarea и других полей ввода
+- Построение кастомных компонентов форм с единым стилем
+- Создание полей с валидацией и счётчиками символов
+- Разработка библиотек компонентов с консистентным UI
 
-Используйте Field как основу для конструирования любых полей ввода. В него легко интегрируются подписи, иконки, сообщения и прогресс. Компонент отвечает за разметку, классы и согласованность, а логику ввода реализуют конкретные инпуты.
+```html
+<script setup>
+import { ref } from 'vue'
+import { Field } from '@dxtmisha/constructor'
 
-> Field — это оболочка-конструктор: он не вводит данные сам по себе, а организует структуру и отображение вспомогательных элементов.
+const value = ref('')
+
+// Field предоставляет структуру и управление
+</script>
+
+<template>
+  <Field
+    label="Имя пользователя"
+    helper-message="Введите ваше имя"
+    :counter="value.length"
+    counter-max="50"
+  >
+    <template #default="{ id, className }">
+      <input
+        :id="id"
+        :class="className"
+        v-model="value"
+        maxlength="50"
+      />
+    </template>
+  </Field>
+</template>
+```
+
+> Field — это контейнер-конструктор: он не обрабатывает ввод данных напрямую, а организует структуру, классы и отображение вспомогательных элементов для любых типов полей ввода.

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

@@ -0,0 +1,151 @@
+### `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
+
+### `leading`
+
+Slot for placing content at the start of the interactive field area, before the main input element.
+
+**Parameters:**
+- `props: FieldControl` — object with data for binding
+
+### `trailing`
+
+Slot for placing content at the end of the interactive field area, after the main input element.
+
+**Parameters:**
+- `props: FieldControl` — object with data for binding
+
+## 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,151 @@
+### `default`
+
+Слот для размещения основного элемента ввода (input, select, textarea и т.д.). Обязательный слот.
+
+**Параметры:**
+- `props: FieldControl` — объект с данными для связывания элемента ввода
+
+### `leading`
+
+Слот для размещения контента в начале интерактивной области поля, перед основным элементом ввода.
+
+**Параметры:**
+- `props: FieldControl` — объект с данными для связывания
+
+### `trailing`
+
+Слот для размещения контента в конце интерактивной области поля, после основного элемента ввода.
+
+**Параметры:**
+- `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(...)" />
+```
 ````