@elcrm/form 0.1.3 → 0.1.5

package/dist/fields/Options.d.ts

@@ -1,31 +1,50 @@
 import { ReactNode } from 'react';
 import { UseFormApi } from '../hooks/use';
 import { TValue } from './type';
-interface Input {
+/**
+ * Выбор через модалку приложения (`Form.Init.onModal`).
+ *
+ * **В форме:** зависит от `outFormat`: строка ключей, массив или объект-флаги.
+ *
+ * **Элементы:** капсула-колонка выбранных подписей (`options[id].label`). Клик открывает модалку
+ * `modal` вида `"module.name"` (или `module` + `modal`).
+ *
+ * Нужен {@link Form.Init}.
+ *
+ * @example
+ * <OptionsField name="users" form={form} label="Сотрудники" modal="crm.pickUser" outFormat="string" />
+ */
+export type TOptions = {
     value?: string;
-    form?: UseFormApi;
+    form?: UseFormApi<any>;
     onValue?: (data: TValue) => void | Promise<void>;
     name: string;
     placeholder?: string;
-    /** Подпись поля */
     label?: string;
     error?: string;
     hidden?: boolean;
-    /** true — блок выбора не открывается */
     disabled?: boolean;
     after?: ReactNode;
     before?: ReactNode;
     view?: string;
     className?: string;
+    /** Имя модуля модалки, если `modal` без точки */
     module?: string;
+    /** `"module.modalName"` или имя модалки вместе с `module` */
     modal?: string;
+    /** Подписи выбранных ключей: `{ [id]: { label } }` */
     options?: Record<string, {
         label?: string;
     }>;
+    /** Как писать выбор в форму. @default зависит от текущего value */
     outFormat?: "array" | "string" | "object";
+    /** Разделитель ключей при `outFormat="string"`. @default "," */
     separator?: string;
-}
-declare function OptionsField({ value, form, onValue, name, placeholder, separator, label, error, hidden, disabled, outFormat, after, before, modal, options, className, }: Input): import("react/jsx-runtime").JSX.Element;
+};
+/**
+ * Список выбранных значений; клик по капсуле открывает модалку приложения.
+ */
+declare function OptionsField({ value, form, onValue, name, placeholder, separator, label, error, hidden, disabled, outFormat, after, before, modal, options, className, }: TOptions): import("react/jsx-runtime").JSX.Element;
 declare namespace OptionsField {
     var displayName: string;
 }

package/dist/fields/Password.d.ts

@@ -1,4 +1,15 @@
 import { TPasswordField } from './type';
+/**
+ * Пароль с переключателем видимости (кнопка-глаз в слоте `after`).
+ *
+ * **В форме:** `string`.
+ *
+ * **Элементы:** капсула + `<input type="password"|text>` + кнопка глаза.
+ * Проп `native` **скрывает весь компонент** (не делает input) — см. {@link TPasswordField}.
+ *
+ * @example
+ * <PasswordField name="password" form={form} label="Пароль" autoComplete="current-password" />
+ */
 declare function PasswordField({ value, form, onValue, name, placeholder, label, error, hidden, disabled, onBlur: onBlurField, className, after, before, native, maxLength, eyes, id, size, }: TPasswordField): import("react/jsx-runtime").JSX.Element | "";
 declare namespace PasswordField {
     var displayName: string;

package/dist/fields/Percent.d.ts

@@ -1,11 +1,12 @@
 import { TInput } from './type';
-/** PercentField — процент как **number** в форме (не строка).
+/**
+ * Процент как **`number`** в форме (не строка).
  *
- * Отличия от NumberField:
- * - значение: `number` (или `""` / пусто), не строка цифр;
- * - `min`/`max` — границы **числа** (по умолчанию 0–100), clamp на blur;
- * - `decimals` — дробная часть;
- * - справа по умолчанию аффикс `%`.
+ * Отличия от {@link NumberField}: значение `number`; `min`/`max` — границы числа (по умолчанию 0–100);
+ * `decimals` — дробная часть; справа по умолчанию аффикс `%`.
+ *
+ * @example
+ * <PercentField name="vat" form={form} label="НДС" min={0} max={100} decimals={2} />
  */
 export type TPercent = TInput & {
     min?: number;
@@ -13,6 +14,9 @@ export type TPercent = TInput & {
     /** Допускать дробную часть */
     decimals?: number;
 };
+/**
+ * Поле процента. Не путать с {@link NumberField} (там строка цифр).
+ */
 declare function PercentField({ value, form, onValue, onBlur: onBlurField, name, placeholder, label, error, hidden, disabled, className, after, before, min, max, decimals, inputmode, }: TPercent): import("react/jsx-runtime").JSX.Element | null;
 declare namespace PercentField {
     var displayName: string;

package/dist/fields/Phone.d.ts

@@ -1,5 +1,17 @@
 import { TInput } from './type';
-/** PhoneField — телефон с маской; полный каталог стран подгружается при фокусе. */
+/**
+ * Телефон с маской по стране. В форму пишутся **только цифры** (без `+` и скобок).
+ *
+ * **В форме:** `string` цифр.
+ *
+ * **Элементы:** капсула, contentEditable по шаблону; полный каталог масок — lazy при фокусе.
+ * Копирование может вызвать `Form.Init.onNotice`.
+ *
+ * Пропы — {@link TInput}.
+ *
+ * @example
+ * <PhoneField name="phone" form={form} label="Телефон" />
+ */
 declare function PhoneField({ value, form, onValue, onBlur: onBlurField, name, placeholder, label, error, hidden, disabled, className, after, before, inputmode, id, }: TInput): import("react/jsx-runtime").JSX.Element | null;
 declare namespace PhoneField {
     var displayName: string;

package/dist/fields/Radio.d.ts

@@ -10,6 +10,17 @@ type RadioOptionArrayItem = {
     s?: number;
 };
 type RadioOptions = RadioOptionObject | RadioOptionArrayItem[];
+/**
+ * Группа радиокнопок.
+ *
+ * **В форме:** `string | number` (id выбранного пункта).
+ *
+ * **Элементы:** капсула-`radiogroup` → кнопки `role="radio"`.
+ * Опции как у Select: `{ n, s }` / `{ i|id, n }`. `inline` — в ряд. `align` — кружок vs текст.
+ *
+ * @example
+ * <RadioField name="sex" form={form} label="Пол" options={[{ i: "m", n: "М" }, { i: "f", n: "Ж" }]} />
+ */
 export type TRadio = TInput & {
     options?: RadioOptions;
     /** Горизонтальный ряд вместо колонки */
@@ -17,6 +28,9 @@ export type TRadio = TInput & {
     /** Кружок: top | center | bottom относительно текста. По умолчанию center */
     align?: "top" | "center" | "bottom";
 };
+/**
+ * Радиогруппа. Один выбранный id в форме.
+ */
 declare function RadioField({ value, form, onValue, onBlur: onBlurField, name, placeholder, label, error, hidden, disabled, className, after, before, options, inline, align, }: TRadio): import("react/jsx-runtime").JSX.Element | null;
 declare namespace RadioField {
     var displayName: string;

package/dist/fields/Range.d.ts

@@ -1,7 +1,14 @@
 import { TInput } from './type';
 /** `bar` — толстая «таблетка» с заливкой; `line` — тонкая линия и круглый thumb */
 export type TRangeVariant = "bar" | "line";
-/** Поле «диапазон»: кастомный трек (div), без нативного range */
+/**
+ * Слайдер. **В форме:** `number`.
+ *
+ * **Элементы:** капсула как у Input → трек (`bar` таблетка / `line` + thumb). Не нативный `<input type="range">`.
+ *
+ * @example
+ * <RangeField name="vol" form={form} label="Громкость" min={0} max={100} variant="bar" />
+ */
 export type TRange = TInput & {
     min?: number;
     max?: number;
@@ -12,6 +19,9 @@ export type TRange = TInput & {
      */
     variant?: TRangeVariant;
 };
+/**
+ * Диапазон. Клавиши стрелок при фокусе на треке.
+ */
 declare function RangeField({ value, form, onValue, onBlur: onBlurField, name, placeholder, label, error, hidden, disabled, className, after, before, min, max, step, variant, }: TRange): import("react/jsx-runtime").JSX.Element | null;
 declare namespace RangeField {
     var displayName: string;

package/dist/fields/Rating.d.ts

@@ -1,10 +1,22 @@
 import { TInput } from './type';
-/** RatingField — оценка звёздами. Значение: число 0…max. */
+/**
+ * Оценка звёздами.
+ *
+ * **В форме:** `number` `0…max` (`0` = пусто).
+ *
+ * **Элементы:** капсула → `role="slider"` + кнопки звёзд. Стрелки меняют значение.
+ *
+ * @example
+ * <RatingField name="rate" form={form} label="Оценка" max={5} allowClear />
+ */
 export type TRating = TInput & {
     max?: number;
     /** Разрешить сброс повторным кликом по текущей оценке */
     allowClear?: boolean;
 };
+/**
+ * Звёздный рейтинг.
+ */
 declare function RatingField({ value, form, onValue, onBlur: onBlurField, name, placeholder, label, error, hidden, disabled, className, after, before, max, allowClear, }: TRating): import("react/jsx-runtime").JSX.Element | null;
 declare namespace RatingField {
     var displayName: string;

package/dist/fields/RichText.d.ts

@@ -1,12 +1,20 @@
 import { TInput } from './type';
 /**
- * RichTextField — простой WYSIWYG без внешних библиотек.
- * Значение: HTML-строка. Панель: жирный / курсив / подчёркивание / списки.
+ * Простой WYSIWYG (`document.execCommand`). **В форме:** HTML-строка.
+ *
+ * **Элементы:** капсула как textarea → опциональный `toolbar` (B/I/U/списки) + редактор.
+ * Санитизацию HTML делайте в приложении.
+ *
+ * @example
+ * <RichTextField name="bio" form={form} label="Описание" toolbar />
  */
 export type TRichText = TInput & {
     /** Показать панель форматирования */
     toolbar?: boolean;
 };
+/**
+ * Rich-текст. Значение — HTML, не plain text.
+ */
 declare function RichTextField({ value, form, onValue, onBlur: onBlurField, name, placeholder, label, error, hidden, disabled, className, after, before, maxLength, spellCheck, toolbar, }: TRichText): import("react/jsx-runtime").JSX.Element | null;
 declare namespace RichTextField {
     var displayName: string;

package/dist/fields/Select.d.ts

@@ -11,10 +11,31 @@ type SelectOptionArrayItem = {
     s?: number;
 };
 type SelectOptions = SelectOptionObject | SelectOptionArrayItem[];
+/**
+ * Выпадающий список (портал в `document.body`).
+ *
+ * **В форме:** `number` (id опции; `0` часто = «не выбрано»).
+ *
+ * **Элементы:** капсула-`combobox` + список `listbox` (li = option).
+ * Формат опций: `{ [id]: { n: "Подпись", s: 1 } }` или `[{ i, n, s }]`.
+ * `s === 0` — скрыть пункт. `order` — порядок id.
+ *
+ * @example
+ * const ROLES = { 1: { n: "Админ", s: 1 }, 2: { n: "Юзер", s: 1 } };
+ * <SelectField name="role" form={form} label="Роль" options={ROLES} placeholder="Выберите" />
+ */
 export type TSelect = TInput & {
+    /**
+     * Пункты: объект `{ id: { n, s } }` или массив `{ id|i, n, s? }`.
+     * `n` — текст, `s` — видимость (`0` = скрыт).
+     */
     options?: SelectOptions;
+    /** Порядок ключей, если `options` — объект. */
     order?: number[];
 };
+/**
+ * Селект: клик по капсуле открывает список, привязанный к полю при скролле.
+ */
 declare function SelectField({ value, form, onValue, name, placeholder, label, error, hidden, disabled, className, after, before, options, order, size, }: TSelect): import("react/jsx-runtime").JSX.Element | "";
 declare namespace SelectField {
     var displayName: string;

package/dist/fields/Tabs.d.ts

@@ -15,6 +15,18 @@ type TabsOptionArrayItem = {
     icon?: ReactNode;
 };
 type TabsOptions = TabsOptionObject | TabsOptionArrayItem[];
+/**
+ * Сегменты (вкладки-переключатель).
+ *
+ * **В форме:** `string | number` (id активного сегмента).
+ *
+ * **Элементы:** капсула без внутреннего padding → кнопки-сегменты.
+ * `options[].icon` — слот слева в сегменте. `s === 0` — сегмент виден, но disabled.
+ * `equal` — равная ширина (по умолчанию true).
+ *
+ * @example
+ * <TabsField name="tab" form={form} options={[{ i: "a", n: "А" }, { i: "b", n: "Б" }]} />
+ */
 export type TTabs = TInput & {
     options?: TabsOptions;
     /**
@@ -23,6 +35,9 @@ export type TTabs = TInput & {
      */
     equal?: boolean;
 };
+/**
+ * Сегмент-контрол. Фокус на сегменте, не на всей капсуле.
+ */
 declare function TabsField({ value, form, onValue, onBlur: onBlurField, name, placeholder, label, error, hidden, disabled, className, after, before, options, equal, size, }: TTabs): import("react/jsx-runtime").JSX.Element | null;
 declare namespace TabsField {
     var displayName: string;

package/dist/fields/Tags.d.ts

@@ -1,10 +1,22 @@
 import { TInput } from './type';
-/** TagsField — чипы / метки. Значение: `string[]`. */
+/**
+ * Чипы / теги.
+ *
+ * **В форме:** `string[]`.
+ *
+ * **Элементы:** капсула → чипы + однострочный ввод. Enter / `separators` создают чип.
+ *
+ * @example
+ * <TagsField name="tags" form={form} label="Метки" maxTags={8} />
+ */
 export type TTags = TInput & {
     maxTags?: number;
     /** Разделители при вводе (по умолчанию Enter / запятая) */
     separators?: string[];
 };
+/**
+ * Поле тегов. Backspace на пустом вводе удаляет последний чип.
+ */
 declare function TagsField({ value, form, onValue, onBlur: onBlurField, name, placeholder, label, error, hidden, disabled, className, after, before, maxTags, maxLength, separators, }: TTags): import("react/jsx-runtime").JSX.Element | null;
 declare namespace TagsField {
     var displayName: string;

package/dist/fields/Textarea.d.ts

@@ -1,5 +1,14 @@
 import { TInput } from './type';
-/** TextareaField — многострочное поле (contentEditable). */
+/**
+ * Многострочный текст (`contentEditable`).
+ *
+ * **В форме:** `string` (могут быть `\n`).
+ *
+ * **Элементы:** `label` + высокая капсула (`--field-note-height`) + `before` / `after`.
+ *
+ * @example
+ * <TextareaField name="comment" form={form} label="Комментарий" placeholder="Текст…" />
+ */
 declare function TextareaField({ value, form, onValue, name, placeholder, label, hidden, disabled, onBlur: onBlurField, className, after, before, error, size, inputmode, maxLength, spellCheck, }: TInput): import("react/jsx-runtime").JSX.Element | null;
 declare namespace TextareaField {
     var displayName: string;

package/dist/fields/Time.d.ts

@@ -1,5 +1,15 @@
 import { TInput } from './type';
-/** Значение в форме: строка `HH:mm` или пустая строка */
+/**
+ * Время `HH:mm` (два contentEditable: часы и минуты).
+ *
+ * **В форме:** `string` `"14:30"` или `""`.
+ *
+ * **Элементы:** капсула → [часы] `:` [минуты] + опционально кнопка picker (`after` по умолчанию — часы).
+ * `step` — шаг минут в **секундах** (`300` = 5 мин). `align`: `start` | `center`.
+ *
+ * @example
+ * <TimeField name="at" form={form} label="Время" step={300} picker />
+ */
 export type TTime = TInput & {
     /** Шаг для минут в секундах (`60` — любая минута; `300` — кратно 5 мин) */
     step?: number;
@@ -22,9 +32,8 @@ export type TTime = TInput & {
     presets?: string[];
 };
 /**
- * Время: два contentEditable по образцу Mask (каретка через queueMicrotask + setCursorPosition).
- * Пока фокус в группе — в DOM только введённые цифры без ведущих нулей; в форму значение
- * уходит при уходе фокуса с группы (snap минут, clamp, формат `HH:mm`).
+ * Поле времени. Пока фокус в группе — в DOM сырые цифры; в форму `HH:mm` уходит на blur.
+ * Popup слотов — при `picker` / `presets`.
  */
 declare function TimeField({ value, form, onValue, onBlur: onBlurField, name, placeholder, label, hidden, disabled, error, className, after, before, step, min, max, id, spellCheck, align, picker, presets, }: TTime): import("react/jsx-runtime").JSX.Element | null;
 declare namespace TimeField {

package/dist/fields/TimePicker.d.ts

@@ -1,15 +1,24 @@
 import { default as React } from 'react';
+/**
+ * Попап слотов {@link TimeField} (портал, якорь к капсуле).
+ * Не публичный API пакета.
+ */
 export type TTimePickerProps = {
+    /** getBoundingClientRect капсулы. */
     parent: DOMRect;
+    /** Список `HH:mm`. */
     slots: string[];
+    /** Текущее значение поля. */
     current: string;
+    /** Подсветка пункта (клавиатура). */
     activeIndex: number;
     listId: string;
     className?: string;
     setOpen: React.Dispatch<React.SetStateAction<boolean>>;
     setActiveIndex: React.Dispatch<React.SetStateAction<number>>;
+    /** Выбор слота → коммит в форму. */
     onPick: (slot: string) => void;
 };
-/** Попап со слотами времени (портал). */
+/** Список времени `role="listbox"`. */
 declare function TimePicker({ parent, slots, current, activeIndex, listId, className, setOpen, setActiveIndex, onPick, }: TTimePickerProps): import("react/jsx-runtime").JSX.Element;
 export default TimePicker;

package/dist/fields/Url.d.ts

@@ -1,7 +1,17 @@
 import { default as React } from 'react';
 import { TInput } from './type';
-/** UrlField — нативный input type=url. */
+/**
+ * Сайт / ссылка. Нативный `<input type="url">`.
+ *
+ * **В форме:** `string`. Пропы — {@link TInput}.
+ *
+ * @example
+ * <UrlField name="site" form={form} label="Сайт" placeholder="https://" />
+ */
 export type TUrl = TInput;
+/**
+ * Поле URL (автозаполнение `url`, клавиатура `inputMode="url"`).
+ */
 declare function UrlField(props: TUrl): import("react/jsx-runtime").JSX.Element;
 declare namespace UrlField {
     var displayName: string;

package/dist/fields/emit.d.ts

@@ -6,4 +6,4 @@ import { UseFormApi } from '../hooks/use';
  * реально изменилось — иначе blur перерисовывал бы поле зря.
  * Во время ввода (`commit=false`) — только `onValue` без notify.
  */
-export declare function createFieldEmit(form: UseFormApi | undefined, name: string, onValue?: (data: TValue) => void | Promise<void>): (value: unknown, commit?: boolean) => void;
+export declare function createFieldEmit(form: UseFormApi<any> | undefined, name: string, onValue?: (data: TValue) => void | Promise<void>): (value: unknown, commit?: boolean) => void;

package/dist/fields/type.d.ts

@@ -1,83 +1,153 @@
 import { ReactNode } from 'react';
 import { UseFormApi } from '../hooks/use';
-/** Связь с формой и колбэки значения */
+/**
+ * Связь поля с `useForm` и колбэки значения.
+ *
+ * Типичная схема:
+ * 1. `form` + `name` — значение живёт в форме (`form.getValue(name)`).
+ * 2. `value` — начальное / внешнее значение, если форма ещё не знает ключ.
+ * 3. `onValue` — вызывается при каждом изменении `{ value, name }`.
+ * 4. `onBlur` — коммит (не нативный `FocusEvent`).
+ */
 export type TFieldFormBindings = {
+    /**
+     * Значение снаружи (controlled / начальное).
+     * Если передан `form` + `name`, источником правды становится форма.
+     */
     value?: unknown;
-    form?: UseFormApi;
+    /** API `useForm()` — подписка только на это `name`, без ререндера всей формы. */
+    form?: UseFormApi<any>;
+    /**
+     * Колбэк изменения. Аргумент всегда `{ value, name }`, не DOM-событие.
+     * Во время набора часто вызывается без bump версии формы.
+     */
     onValue?: (data: TValue) => void | Promise<void>;
-    /** Колбэк при потере фокуса (коммит значения), не нативный `FocusEvent` */
+    /**
+     * Потеря фокуса / коммит.
+     * @example onBlur={({ value, name }) => validate(name, value)}
+     */
     onBlur?: (data: TValue) => void | Promise<void>;
+    /**
+     * Ключ в `form`. Обязателен, если используете `useForm`.
+     * По нему поле подписывается и пишет `setValue` / `onValue`.
+     */
     name?: string;
 };
-/** Подпись, доступность, видимость */
+/**
+ * Внешний вид и доступность. Рендер у всех `*Field` одинаковый каркас:
+ *
+ * ```
+ * [data-field]          — корень (`.l`)
+ *   label.t             — подпись (`label`), htmlFor → контрол
+ *   капсула .f          — рамка, padding `--field-padding`, `data-disabled`
+ *     before            — слот слева (иконка, бейдж карты)
+ *     контрол           — input / contentEditable / combobox / …
+ *     after             — слот справа (глаз пароля, %, ошибка)
+ *   [role=alert]        — текст `error`
+ * ```
+ */
 export type TFieldPresentation = {
-    /** Подпись поля (визуально в `.t`) */
+    /** Подпись над капсулой. Связана с контролом через `htmlFor` / `id`. */
     label?: string;
+    /**
+     * Подсказка внутри пустого контрола.
+     * У Check — текст справа от квадрата (не `label`).
+     */
     placeholder?: string;
-    /** true — только просмотр, без ввода (аналог нативного disabled) */
+    /**
+     * Только просмотр: нет фокуса, нет ввода, капсула `data-disabled="true"`.
+     * Не путать с `hidden`.
+     */
     disabled?: boolean;
     /**
-     * true — если значение поля **пустое**, поле не рендерится;
-     * при непустом значении поле показывается.
+     * Не рендерить поле, **только если значение пустое**.
+     * Непустое значение всё равно показывается (удобно для «скрытых, пока нет данных»).
      */
     hidden?: boolean;
+    /** Текст ошибки под капсулой (`role="alert"`). Капсула получает класс ошибки. */
     error?: string;
+    /**
+     * Слот **справа** внутри капсулы (иконка, кнопка, `%`).
+     * Не путать с кнопкой «Set» снаружи в dev-стенде.
+     */
     after?: ReactNode;
+    /** Слот **слева** внутри капсулы (иконка бренда карты, превью цвета). */
     before?: ReactNode;
+    /** Свободный маркер вида (редко используется полями). */
     view?: string;
+    /**
+     * id контрола. Если не задан — генерируется.
+     * Нужен, чтобы `label htmlFor` указывал на input / contentEditable.
+     */
     id?: string;
+    /** Доп. класс на корне `[data-field]`, не на капсуле. */
     className?: string;
     /**
-     * Высота: `"s"` | `"m"` | `"l"` — как у кнопки и поиска.
-     * Единая шкала с button/search: `"s"` | `"m"` | `"l"`.
-     * `"sm"` / `"md"` — устаревшие алиасы (`elcrm migrate size-sml`).
+     * Высота капсулы: `s` | `m` | `l` (как кнопка/поиск).
+     * Меняет `--field-height` → padding пересчитывается.
+     * `sm` / `md` — устаревшие алиасы (`elcrm migrate size-sml`).
+     * @default "m"
      */
     size?: "s" | "m" | "l" | "sm" | "md";
+    /** Зарезервировано (копирование); у Phone работает через `Form.Init` / notice. */
     isCopy?: boolean;
+    /** Макс. длина текста / цифр (нативный `maxLength` или логика CE). */
     maxLength?: number;
     /**
-     * Проверка орфографии для **текстового** ввода (`Input`, `Textarea`).
-     * Для полей только с цифрами в компонентах выставляется **`false`**.
+     * Орфография. У цифр/телефона/маски в компонентах обычно `false`.
      */
     spellCheck?: boolean;
     /**
-     * Подсказка клавиатуры на мобильных (`inputMode`).
-     * Для **чисел** — `numeric`, для **денег** — `decimal`, **телефон** — `tel` (по умолчанию в полях).
+     * `inputMode` мобильной клавиатуры.
+     * Number → `numeric`, Money → `decimal`, Phone → `tel`.
      */
     inputmode?: "text" | "email" | "none" | "tel" | "url" | "search" | "numeric" | "decimal";
     /**
-     * Нативный `<input>` вместо **contentEditable** (`StringField`).
-     * Нужен для **автозаполнения логина/почты** (менеджеры паролей работают с нативными полями).
-     * У **`PasswordField`** свой проп **`native`** (см. **`TPasswordField`**).
+     * `StringField`: нативный `<input>` вместо contentEditable.
+     * Нужен для автозаполнения логина. У `PasswordField` свой смысл `native` — см. {@link TPasswordField}.
      */
     native?: boolean;
     /**
-     * Атрибут **`autocomplete`** (например **`username`**, **`email`**, **`off`**).
-     * Осмысленно при **`native`**; у `contentEditable` браузеры почти не применяют автозаполнение.
+     * HTML `autocomplete` (`username`, `email`, `off`). Имеет смысл при `native`.
      */
     autoComplete?: string;
     /**
-     * Тип нативного поля при **`native`** (по умолчанию **`text`**).
-     * Для почты удобно **`email`** + **`autoComplete="email"`**.
+     * `type` нативного input при `native` (`text` | `email` | …).
      */
     inputType?: "text" | "email" | "search" | "tel" | "url";
 };
-/** Базовые пропы текстовых и составных полей */
+/**
+ * Базовые пропы почти всех `*Field`.
+ * Специфичные (`options`, `format`, `min`/`max`) — в типе конкретного поля (`TSelect`, `TDate`, …).
+ *
+ * @example
+ * <StringField name="login" form={form} label="Логин" />
+ */
 export type TInput = TFieldFormBindings & TFieldPresentation;
+/**
+ * Полезная нагрузка `onValue` / `onBlur` / `form.setValue`.
+ * Это не `ChangeEvent`.
+ */
 export type TValue = {
+    /** Новое значение поля (тип зависит от компонента: string, number, boolean, File, …). */
     value: unknown;
+    /** Имя поля (`name`). */
     name: string;
     id?: string;
 };
 /**
- * Поле пароля: **`native`** из `TInput` убран — здесь свой **`native`** = «не рендерить поле».
+ * Пропы {@link PasswordField}.
+ * `native` здесь **не** «сделать `<input>`», а «не рисовать поле» (пароль снаружи).
  */
 export type TPasswordField = Omit<TInput, "native"> & {
-    /** true — компонент не рендерится (пустая строка), пароль отдаётся нативному `<input>` снаружи */
+    /**
+     * `true` — компонент не рендерится (пустая строка).
+     * Для настоящего `<input type="password">` оставьте `native={false}` (по умолчанию).
+     */
     native?: boolean;
     /**
-     * Свои иконки переключателя **[показать пароль, скрыть пароль]** (когда ввод скрыт / виден).
-     * Если не задано — используются встроенные SVG.
+     * Свои иконки переключателя видимости: `[показать, скрыть]`.
+     * Слот — кнопка в `after` капсулы.
      */
     eyes?: [React.ReactNode?, React.ReactNode?];
 };