@dxtmisha/wiki 0.39.4 → 0.39.5

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

@@ -0,0 +1,54 @@
+## Кнопка очистки
+
+Свойства `cancel` и `cancelShow` предназначены для управления отображением иконки очистки поля.
+
+**Свойства:**
+
+- `cancel` — режим отображения кнопки очистки (`auto` или `always`)
+- `cancelShow` — условный флаг видимости, используется только в режиме `auto`
+
+Свойства работают совместно: если `cancel` установлен в `auto`, иконка очистки отображается только при выполнении условий `cancelShow = true`, поле активно (не `disabled`/`readonly`) и не включён режим стрелок (`arrowCarousel`/`arrowStepper`). При `cancel = always` иконка отображается принудительно (кроме случаев `disabled`/`readonly` или активных стрелок), значение `cancelShow` игнорируется. Режимы стрелок имеют приоритет над кнопкой очистки — при активной навигации cancel скрывается независимо от настроек.
+
+```html
+<script setup>
+import { ref, computed } from 'vue'
+
+const value = ref('')
+const hasValue = computed(() => value.value.length > 0)
+</script>
+
+<template>
+  <!-- Автоматический режим с условием -->
+  <Field
+    label="Поиск"
+    cancel="auto"
+    :cancel-show="hasValue"
+  >
+    <template #default="{ id, className }">
+      <input :id="id" :class="className" v-model="value" />
+    </template>
+  </Field>
+
+  <!-- Принудительный показ -->
+  <Field
+    label="Фильтр"
+    cancel="always"
+  >
+    <template #default="{ id, className }">
+      <input :id="id" :class="className" v-model="value" />
+    </template>
+  </Field>
+
+  <!-- С обработчиком события -->
+  <Field
+    label="Ввод"
+    cancel="auto"
+    :cancel-show="hasValue"
+    @click="value = ''"
+  >
+    <template #default="{ id, className }">
+      <input :id="id" :class="className" v-model="value" />
+    </template>
+  </Field>
+</template>
+```

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

@@ -0,0 +1,52 @@
+Base container for form controls that composes label, messages, counter, icons, and progress into a unified structure.
+
+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.
+
+**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
+
+**Typical use cases:**
+
+- 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
+
+```html
+<script setup>
+import { ref } from 'vue'
+import { Field } from '@dxtmisha/constructor'
+
+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

@@ -0,0 +1,52 @@
+Базовый контейнер для полей формы, который композирует метку, сообщения, счётчик, иконки и прогресс в единую структуру.
+
+Field централизует управление визуальным представлением полей ввода, обрабатывает состояния фокуса и валидации, координирует расположение вспомогательных элементов и предоставляет согласованный API для построения любых типов инпутов. Является фундаментальной основой для создания консистентных форм с поддержкой слотов, иконок управления и интеграцией подкомпонентов.
+
+**Основные возможности:**
+
+- Композиция подкомпонентов (FieldLabel, FieldMessage, FieldCounter, Progress)
+- Управление состояниями (focus, disabled, readonly, selected, block)
+- Координация слотов (caption, prefix, suffix, leading, trailing)
+- Подсветка валидации на основе validationMessage и forceShowMessage
+- Иконки управления с настраиваемой видимостью (cancel, arrows)
+- Гибкое позиционирование счётчика через counterTop
+- Встроенные помощники для размеров и иконок (FieldSize, FieldIcons)
+- Интеграция прогресса загрузки и скелетон-состояния
+
+**Типичные сценарии использования:**
+
+- Базовый контейнер для Input, Select, Textarea и других полей ввода
+- Построение кастомных компонентов форм с единым стилем
+- Создание полей с валидацией и счётчиками символов
+- Разработка библиотек компонентов с консистентным UI
+
+```html
+<script setup>
+import { ref } from 'vue'
+import { Field } from '@dxtmisha/constructor'
+
+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,10 @@
+- `default(props: FieldControl): any` — Default slot for the main input element.
+- `leading(props: FieldControl): any` — Slot for displaying content before the input area.
+- `trailing(props: FieldControl): any` — Slot for displaying content after the input area.
+
+> **FieldControl:**
+> - `id: string` — unique identifier for binding label and input.
+> - `className: string` — CSS classes for the visible input area.
+> - `classHidden: string` — CSS classes for the hidden native input element.
+> - `classForFocus: string` — CSS classes applied when the field is focused.
+> - `binds: Record<string, any>` — properties bound to the input element.

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

@@ -0,0 +1,10 @@
+- `default(props: FieldControl): any` — Слот по умолчанию для основного элемента ввода (input, select, textarea).
+- `leading(props: FieldControl): any` — Слот для отображения контента перед областью ввода.
+- `trailing(props: FieldControl): any` — Слот для отображения контента после области ввода.
+
+> **FieldControl:**
+> - `id: string` — уникальный идентификатор элемента для связывания label и input.
+> - `className: string` — CSS-классы для видимой зоны ввода.
+> - `classHidden: string` — CSS-классы для скрытого нативного элемента ввода.
+> - `classForFocus: string` — CSS-классы, применяемые при фокусировке на поле.
+> - `binds: Record<string, any>` — свойства, привязанные к элементу ввода.

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

@@ -0,0 +1,49 @@
+## 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

@@ -0,0 +1,49 @@
+## Состояние значения
+
+Свойства `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

@@ -0,0 +1,28 @@
+````markdown
+## Field width
+
+Property `width` defines the horizontal size of the Field container.
+
+**Possible values:**
+
+- 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)
+
+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" />
+
+<!-- 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

@@ -0,0 +1,26 @@
+## Ширина поля
+
+Свойство `width` определяет горизонтальный размер контейнера Field.
+
+**Возможные значения:**
+
+- любое валидное CSS-значение (`'320px'`, `'48rem'`, `'50%'`, `'min(100%,320px)'`, `'clamp(240px,40vw,480px)'`)
+- дизайн-токены системы (например, `'sm'`, `'md'`, `'lg'` при поддержке)
+- `'custom'` — внутренняя техническая метка (не используется напрямую)
+
+Контролирует фиксированную или относительную ширину поля, применяя значение напрямую без дополнительных обёрток. При отсутствии свойства ширина остаётся гибкой и зависит от родительского контейнера. При активном свойстве `block` (установлено в `true`) поле занимает 100% ширины независимо от заданного значения `width`, приоритет имеет блочный режим.
+
+```html
+<!-- Автоматическая ширина -->
+<Field label="auto" />
+
+<!-- Фиксированная ширина -->
+<Field width="320px" label="320px" />
+
+<!-- Относительная ширина -->
+<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

@@ -0,0 +1,49 @@
+import type { StorybookComponentsMdxItem } from '../../../types/storybookTypes'
+
+import fieldEn from './field.en.mdx'
+import fieldRu from './field.ru.mdx'
+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 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
+ *
+ * MDX файлы для компонента Field
+ */
+export const wikiMdxField: StorybookComponentsMdxItem = {
+  name: 'Field',
+  descriptions: {
+    arrows: {
+      en: arrowsEn,
+      ru: arrowsRu
+    },
+    cancel: {
+      en: cancelEn,
+      ru: cancelRu
+    },
+    field: {
+      en: fieldEn,
+      ru: fieldRu
+    },
+    slots: {
+      en: slotsEn,
+      ru: slotsRu
+    },
+    value: {
+      en: valueEn,
+      ru: valueRu
+    },
+    width: {
+      en: widthEn,
+      ru: widthRu
+    }
+  }
+}

package/src/media/mdx/FieldCounter/fieldCounter.en.mdx

@@ -0,0 +1,34 @@
+Component for displaying character count and input limits in form fields with customizable formatting templates.
+
+FieldCounter provides visual feedback about the number of entered characters, automatically formats display depending on the presence of a maximum limit, and supports flexible customization through templates with placeholders. The component integrates with text fields and text areas, providing users with information about restrictions and remaining input space.
+
+**Key features:**
+
+- Display current number of entered characters
+- Automatic maximum limit display when present
+- Flexible formatting templates with [c] and [m] placeholders
+- Automatic format detection (50 / 100 or just 50)
+- Support for string and numeric counter and maxlength values
+- Smart visibility management via counterShow property
+- Compact display for space efficiency
+
+**Common use cases:**
+
+- Text fields with character count limits
+- Multi-line text areas (textarea) for descriptions
+- Comment input fields with limits
+- Forms with minimum/maximum length requirements
+- SMS editors with character counting
+
+```html
+<template>
+  <!-- Basic counter -->
+  <Component :counter="10" />
+
+  <!-- With limit -->
+  <Component :counter="10" :maxlength="100" />
+
+  <!-- Custom template -->
+  <Component :counter="5" :maxlength="50" template="[c] of [m]" />
+</template>
+```

package/src/media/mdx/FieldCounter/fieldCounter.ru.mdx

@@ -0,0 +1,34 @@
+Компонент для отображения счетчика символов и лимитов ввода в полях форм с поддержкой настраиваемых шаблонов форматирования.
+
+FieldCounter обеспечивает визуальную обратную связь о количестве введенных символов, автоматически форматирует отображение в зависимости от наличия максимального лимита и поддерживает гибкую настройку через шаблоны с плейсхолдерами. Компонент интегрируется с текстовыми полями и областями ввода, предоставляя пользователю информацию об ограничениях и оставшемся месте для ввода.
+
+**Основные возможности:**
+
+- Отображение текущего количества введенных символов
+- Автоматический показ максимального лимита при его наличии
+- Гибкие шаблоны форматирования с плейсхолдерами [c] и [m]
+- Автоматическое определение формата (50 / 100 или просто 50)
+- Поддержка строковых и числовых значений counter и maxlength
+- Умное управление видимостью через свойство counterShow
+- Компактное отображение для экономии пространства
+
+**Типичные сценарии использования:**
+
+- Текстовые поля с ограничением по количеству символов
+- Многострочные текстовые области (textarea) для описаний
+- Поля ввода комментариев с лимитами
+- Формы с требованиями к минимальной/максимальной длине
+- SMS-редакторы с подсчетом символов
+
+```html
+<template>
+  <!-- Базовый счетчик -->
+  <Component :counter="10" />
+
+  <!-- С лимитом -->
+  <Component :counter="10" :maxlength="100" />
+
+  <!-- Кастомный шаблон -->
+  <Component :counter="5" :maxlength="50" template="[c] / [m]" />
+</template>
+```

package/src/media/mdx/FieldCounter/templates.en.mdx

@@ -0,0 +1,39 @@
+## Custom Display Templates
+
+The `template` property allows you to customize the counter display format using placeholders.
+
+**Available placeholders:**
+
+- `[c]` — current number of entered characters
+- `[m]` — maximum character limit
+
+Uses string interpolation to replace placeholders with actual counter values. Supports HTML markup inside the template for customizing styles of individual parts. When no template is provided, the component automatically determines the format: displays "50 / 100" when `maxlength` is present or just "50" when it's absent.
+
+```html
+<!-- Descriptive format -->
+<FieldCounter
+  :counter="75"
+  :maxlength="150"
+  template="Characters: [c] of [m]"
+/>
+
+<!-- Compact format -->
+<FieldCounter
+  :counter="42"
+  :maxlength="100"
+  template="[c]/[m]"
+/>
+
+<!-- With HTML for styling -->
+<FieldCounter
+  :counter="75"
+  :maxlength="150"
+  template="<b>[c]</b> of <i>[m]</i> characters"
+/>
+
+<!-- Current counter only with text -->
+<FieldCounter
+  :counter="42"
+  template="Characters entered: [c]"
+/>
+```

package/src/media/mdx/FieldCounter/templates.ru.mdx

@@ -0,0 +1,39 @@
+## Настраиваемые шаблоны отображения
+
+Свойство `template` позволяет настроить формат отображения счетчика символов с использованием плейсхолдеров.
+
+**Доступные плейсхолдеры:**
+
+- `[c]` — текущее количество введенных символов
+- `[m]` — максимальный лимит символов
+
+Использует строковую интерполяцию для замены плейсхолдеров на актуальные значения счетчика. Поддерживает HTML-разметку внутри шаблона для кастомизации стилей отдельных частей. При отсутствии шаблона компонент автоматически определяет формат: отображает "50 / 100" при наличии `maxlength` или просто "50" при его отсутствии.
+
+```html
+<!-- Описательный формат -->
+<FieldCounter
+  :counter="75"
+  :maxlength="150"
+  template="Символов: [c] из [m]"
+/>
+
+<!-- Компактный формат -->
+<FieldCounter
+  :counter="42"
+  :maxlength="100"
+  template="[c]/[m]"
+/>
+
+<!-- С HTML для стилизации -->
+<FieldCounter
+  :counter="75"
+  :maxlength="150"
+  template="<b>[c]</b> из <i>[m]</i> символов"
+/>
+
+<!-- Только текущий счетчик с текстом -->
+<FieldCounter
+  :counter="42"
+  template="Введено символов: [c]"
+/>
+```

package/src/media/mdx/FieldCounter/wikiMdxFieldCounter.ts

@@ -0,0 +1,25 @@
+import type { StorybookComponentsMdxItem } from '../../../types/storybookTypes'
+
+import fieldCounterEn from './fieldCounter.en.mdx'
+import fieldCounterRu from './fieldCounter.ru.mdx'
+import templatesEn from './templates.en.mdx'
+import templatesRu from './templates.ru.mdx'
+
+/**
+ * MDX files for FieldCounter component
+ *
+ * MDX файлы для компонента FieldCounter
+ */
+export const wikiMdxFieldCounter: StorybookComponentsMdxItem = {
+  name: 'FieldCounter',
+  descriptions: {
+    fieldCounter: {
+      en: fieldCounterEn,
+      ru: fieldCounterRu
+    },
+    templates: {
+      en: templatesEn,
+      ru: templatesRu
+    }
+  }
+}

package/src/media/mdx/FieldLabel/fieldLabel.en.mdx

@@ -0,0 +1,39 @@
+Component for displaying input field labels with support for required indicator, character counter, and progress indicator.
+
+FieldLabel provides uniform display of form field captions, automatically integrates with FieldCounter for character counting and Progress for loading indication. The component supports skeleton loading, customizable slots, and ensures consistent visual styling of form elements.
+
+**Key features:**
+
+- Text label display for input fields
+- Required field indicator (required marker)
+- FieldCounter integration for character counting
+- Built-in Progress indicator support
+- Skeleton loading support for pending states
+- Flexible customization via slots (leading, trailing)
+- Consistent spacing and styles within forms
+
+**Common use cases:**
+
+- Labels for text fields and textareas
+- Forms with required fields
+- Fields with character count limits
+- Forms with file upload progress indication
+- Dynamic forms with skeleton loading
+
+```html
+<template>
+  <!-- Basic label -->
+  <Component label="Username" />
+
+  <!-- Required field label -->
+  <Component label="Email" required />
+
+  <!-- With progress and counter -->
+  <Component
+    label="Loading"
+    :progress="45"
+    :counter="10"
+    :maxlength="100"
+  />
+</template>
+```

package/src/media/mdx/FieldLabel/fieldLabel.ru.mdx

@@ -0,0 +1,39 @@
+Компонент для отображения меток полей ввода с поддержкой индикатора обязательности, счетчика символов и прогресс-индикатора.
+
+FieldLabel предоставляет единообразное отображение подписей к полям форм, автоматически интегрируется с FieldCounter для подсчета символов и Progress для индикации загрузки. Компонент поддерживает скелетон-загрузку, настраиваемые слоты и обеспечивает согласованное визуальное оформление элементов формы.
+
+**Основные возможности:**
+
+- Отображение текстовой метки для полей ввода
+- Индикатор обязательности поля (required marker)
+- Интеграция со счетчиком символов FieldCounter
+- Встроенная поддержка прогресс-индикатора Progress
+- Поддержка скелетон-загрузки для состояния ожидания
+- Гибкая настройка через слоты (leading, trailing)
+- Единообразные отступы и стили в составе форм
+
+**Типичные сценарии использования:**
+
+- Подписи к текстовым полям и textarea
+- Формы с обязательными полями
+- Поля с ограничением количества символов
+- Формы с индикацией процесса загрузки файлов
+- Динамические формы со скелетон-загрузкой
+
+```html
+<template>
+  <!-- Базовая метка -->
+  <Component label="Username" />
+
+  <!-- Обязательное поле -->
+  <Component label="Email" required />
+
+  <!-- С прогрессом и счетчиком -->
+  <Component
+    label="Загрузка"
+    :progress="45"
+    :counter="10"
+    :maxlength="100"
+  />
+</template>
+```