@andreyfedkovich/cozy-ui 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 Формат основан на [Keep a Changelog](https://keepachangelog.com/).
 Версии соответствуют [Semantic Versioning](https://semver.org/) и git-тегам `v*`.
 
+## 0.10.0 - 2026-06-04
+
+- **feat:** New `ShowErrorPolicy` presets — `draftFriendly`, `wizardStep`, `savedInvalid`, `onBlurOrSubmit`. Recommended for ERP/wizard forms; legacy `default` unchanged (shows on `hasValue` alone).
+- **feat:** Extended `FieldMeta` — `stepSubmitted`, `validationPending`, `errorKind`. `resolveDisplayError` suppresses stale `required` when value is non-empty.
+- **feat:** `useFormFields` + `FieldBinding` — replaces per-app binding glue (~188 LOC in erp-hr). `markStepSubmitted`, `markFormSubmitted`, `resetInteraction`.
+- **feat:** `useValidationRequest` — async validate with generation/stale guard and `validationPending`.
+- **feat:** `attemptWizardStep`, `attemptFormSubmit` — validate-on-click for wizard and submit (no `disabled={!isValid}`).
+- **feat:** `suppressError` prop on field components; dev warning when `error={null}` suppresses invalid `fieldMeta`.
+- **feat:** Export `useFieldPresentation`, `FieldErrorCaption`, `FormField`, `hasFieldValue`.
+- **docs:** `docs/validation-recipes.md` — recipes, anti-patterns, erp-hr migration (Задание B), consumer verification snippet.
+
+## 0.9.0 - 2026-06-04
+
+- **feat:** Единый контракт валидации полей — headless API: `FieldMeta`, `ShowErrorPolicy`, `resolveShowError`, `resolveFieldError`, `resolveFieldMessage`, `useFieldState`, `resolveValueChangeHandler`.
+- **feat:** `Input`, `Textarea`, `Checkbox`, `Select`, `DialogSelect`, `TreeDialogSelect`, `Calendar` — пропсы `fieldMeta` и `showErrorPolicy`; явный `error` по-прежнему переопределяет meta. Дефолтная политика: `invalid && (touched || submitted || hasValue)`.
+- **feat:** Общий A11y для полей — `aria-invalid`, `aria-describedby`, стабильные `id` через `useId()`, сообщение об ошибке с `role="alert"`.
+- **feat:** Value picker’ы (`Select`, `DialogSelect`, `TreeDialogSelect`, `Calendar`) — канонический колбэк `onValueChange`; `onChange` оставлен как deprecated alias. На trigger добавлены `onBlur` / `onFocus` для интеграции с формами.
+- **docs:** README — раздел Field validation, две семьи колбэков (native `onChange` vs picker `onValueChange`).
+
 ## 0.8.0 - 2026-06-02
 
 - **feat:** Split published CSS into three entry points for Tailwind v3 host compatibility: `styles.css` (full bundle), `styles.modules.css` (SCSS modules only), and `styles.tailwind.css` (Tailwind v4 utilities). Existing `import "@andreyfedkovich/cozy-ui/styles.css"` is unchanged.

package/README.md

@@ -31,7 +31,7 @@ npm i @andreyfedkovich/cozy-ui
 - [Design tokens](#design-tokens)
 - [Component API](#component-api)
   - [Layout & content](#layout--content) — `BaseBlock`, `Card`, `CollapsableBlock`, `Collapse`, `Carousel`, `EmptyComponent`, `Spinner`
-  - [Inputs & forms](#inputs--forms) — `Button`, `RadioGroupButton`, `Input`, `Textarea`, `Calendar`, `Checkbox`, `Select`, `DialogSelect`, `TreeDialogSelect`, `InputCaption`, `Label`
+  - [Inputs & forms](#inputs--forms) — field validation helpers, `Button`, `RadioGroupButton`, `Input`, `Textarea`, `Calendar`, `Checkbox`, `Select`, `DialogSelect`, `TreeDialogSelect`, `InputCaption`, `Label`
   - [Navigation](#navigation) — `Tabs`, `TabsRounded`, `Stepper`
   - [Overlays](#overlays) — `Popover`, `TooltipDark`, `TooltipLight`
   - [Utility](#utility) — `Tag`, `CopyTextTrigger`
@@ -396,6 +396,64 @@ const [view, setView] = useState<"grid" | "list">("grid");
 />;
 ```
 
+#### Field validation (headless)
+
+Form state stays in your app (React Hook Form, TanStack Form, or `useState`). Cozy UI provides a shared **`FieldMeta`** contract and **`showErrorPolicy`** so all fields resolve “when to show the error” the same way.
+
+| Export | Description |
+| ------ | ----------- |
+| `FieldMeta` | `touched`, `dirty`, `submitted`, `stepSubmitted`, `hasValue`, `invalid`, `errorMessage`, `validationPending`, `errorKind` |
+| `ShowErrorPolicy` | `"default"` (legacy) \| `"draftFriendly"` \| `"wizardStep"` \| `"onBlur"` \| `"onSubmit"` \| custom |
+| `resolveShowError`, `resolveFieldError`, `resolveFieldMessage`, `resolveDisplayError` | Pure functions (SSR-safe) |
+| `useFieldState`, `useFormFields`, `useValidationRequest` | React hooks |
+| `attemptWizardStep`, `attemptFormSubmit` | Validate-on-click helpers |
+
+**Recommended policy for ERP/drafts:** `draftFriendly` — no flash on first keystroke; saved invalid visible on load.
+
+**Legacy `default` policy:** `invalid && (touched || submitted || hasValue)`.
+
+**Props on fields:** `error`, `suppressError`, `fieldMeta`, `showErrorPolicy`.
+
+See [`docs/validation-recipes.md`](docs/validation-recipes.md) for recipes and erp-hr migration.
+
+**Callback families:**
+
+| Family | Components | Value callback | Focus |
+| ------ | ---------- | -------------- | ----- |
+| Native text | `Input`, `Textarea`, `Checkbox` | `onChange(event)` — DOM | `onBlur` / `onFocus` via `...rest` |
+| Value picker | `Select`, `DialogSelect`, `TreeDialogSelect`, `Calendar` | **`onValueChange(value)`** (canonical); `onChange` deprecated alias | `onBlur` / `onFocus` on trigger |
+
+```tsx
+import { Input, resolveFieldError } from "@andreyfedkovich/cozy-ui";
+import { useState } from "react";
+
+const [email, setEmail] = useState("");
+const [touched, setTouched] = useState(false);
+const [submitted, setSubmitted] = useState(false);
+
+const meta = {
+  touched,
+  submitted,
+  hasValue: email.trim().length > 0,
+  invalid: !email.includes("@"),
+  errorMessage: "Enter a valid email.",
+};
+
+// Optional: resolve message before render
+resolveFieldError(meta, "default");
+
+<Input
+  label="Email"
+  value={email}
+  onChange={(e) => setEmail(e.target.value)}
+  onBlur={() => setTouched(true)}
+  fieldMeta={meta}
+  showErrorPolicy="default"
+/>;
+```
+
+**React Hook Form (recipe):** use `register` on `Input`; use `Controller` on `Select` with `onValueChange={(opt) => field.onChange(opt)}`.
+
 #### `Input`
 
 Accessible text field with optional label and validation message for product forms.
@@ -405,7 +463,9 @@ Accessible text field with optional label and validation message for product for
 | `label`                  | `ReactNode`      | —       | Field label above the input.                         |
 | `tooltipContent`         | `ReactNode`      | —       | Help tooltip on the «?» icon next to the label.      |
 | `tooltipPopperClassName` | `string`         | —       | Extra class for the tooltip popper.                  |
-| `error`                  | `string \| null` | —       | Validation message under the input.                  |
+| `error`                  | `string \| null` | —       | Validation message (overrides `fieldMeta`).        |
+| `fieldMeta`              | `FieldMeta`      | —       | Form meta for policy-based error display.          |
+| `showErrorPolicy`        | `ShowErrorPolicy`| `"default"` | When to show `fieldMeta.errorMessage`.         |
 | `disabled`       | `boolean`                               | `false` | Disabled state.                      |
 | `className`      | `string`                                | —       | Wrapper class.                       |
 | `inputClassName` | `string`                                | —       | Native `<input>` class.              |
@@ -477,9 +537,13 @@ Date picker field for forms. Value is stored as `yyyy-MM-dd` (or `null`); the tr
 | `label`                   | `string`                          | —       | Field label.                                             |
 | `required`                | `boolean`                         | `false` | Appends ` *` to the label.                               |
 | `value`                   | `string \| null`                  | —       | Selected date as `yyyy-MM-dd`.                           |
-| `onChange`                | `(value: string \| null) => void` | —       | Called when the user picks or clears a date.             |
+| `onValueChange`           | `(value: string \| null) => void` | —       | Called when the user picks or clears a date.             |
+| `onChange`                | `(value: string \| null) => void` | —       | **Deprecated.** Use `onValueChange`.                     |
+| `onBlur` / `onFocus`      | focus handlers                    | —       | Forwarded to the trigger button.                         |
 | `minDate`                 | `Date`                            | —       | Earliest selectable day (inclusive, local calendar).     |
-| `error`                   | `string \| null`                  | —       | Validation message under the field.                      |
+| `error`                   | `string \| null`                  | —       | Validation message (overrides `fieldMeta`).              |
+| `fieldMeta`               | `FieldMeta`                       | —       | Form meta for policy-based error display.                |
+| `showErrorPolicy`         | `ShowErrorPolicy`                 | `"default"` | When to show `fieldMeta.errorMessage`.             |
 | `disabled`                | `boolean`                         | `false` | Disables the trigger.                                    |
 | `tooltipContent`          | `ReactNode`                       | —       | Help tooltip on the «i» icon next to the label.          |
 | `tooltipPopperClassName`  | `string`                          | —       | Extra class for the tooltip popper.                      |
@@ -500,14 +564,14 @@ const [startDate, setStartDate] = useState<string | null>(null);
   label="Дата начала"
   required
   value={startDate}
-  onChange={setStartDate}
+  onValueChange={setStartDate}
   minDate={todayLocalDay()}
 />;
 
 <Calendar
   label="Дедлайн"
   value={startDate}
-  onChange={setStartDate}
+  onValueChange={setStartDate}
   error="Укажите дату."
   tooltipContent="Дата должна быть не раньше сегодня."
 />;
@@ -557,7 +621,10 @@ Powerful, virtualized-friendly select with `single` and `multiple` modes, search
 | `mode`        | `"single" \| "multiple"`              | —          | Selection mode.                      |
 | `value`       | `CustomOption \| CustomOption[]`      | —          | Current value.                       |
 | `options`     | `CustomOption[]`                      | —          | Available options.                   |
-| `onChange`    | `(option) => void`                    | —          | Selection callback.                  |
+| `onValueChange` | `(option) => void`                  | —          | Selection callback (canonical).      |
+| `onChange`    | `(option) => void`                    | —          | **Deprecated.** Use `onValueChange`. |
+| `onBlur` / `onFocus` | focus handlers on trigger      | —          | For `touched` tracking.              |
+| `fieldMeta` / `showErrorPolicy` | see Field validation   | —          | Policy-based error display.          |
 | `onSearch`    | `(value: string) => void`             | —          | Async search hook.                   |
 | `template`    | `"list" \| "table"`                   | `"list"`   | Dropdown layout.                     |
 | `columns`     | `SelectColumn[]`                      | —          | Required when `template="table"`.    |
@@ -584,7 +651,7 @@ const [value, setValue] = useState<CustomOption<unknown, string> | null>(null);
   placeholder="Pick one"
   value={value}
   options={options}
-  onChange={setValue}
+  onValueChange={setValue}
 />;
 ```
 
@@ -609,7 +676,7 @@ import { DialogSelect } from "@andreyfedkovich/cozy-ui";
     const { items, total } = await res.json();
     return { options: items.map((p) => ({ value: p.id, label: p.name })), total };
   }}
-  onChange={(opt) => console.log(opt)}
+  onValueChange={(opt) => console.log(opt)}
 />;
 ```
 
@@ -634,7 +701,7 @@ import { TreeDialogSelect } from "@andreyfedkovich/cozy-ui";
   })}
   searchNodes={async (search) => ({ matches: await searchTreeWithPath(search) })}
   leafConfirmOnly
-  onChange={(node) => console.log(node)}
+  onValueChange={(node) => console.log(node)}
 />;
 ```
 
@@ -1100,6 +1167,23 @@ const [layout, setLayout] = useState<"agent" | "editor">("agent");
 
 ## Hooks & helpers
 
+### Field validation
+
+```ts
+import {
+  type FieldMeta,
+  type ShowErrorPolicy,
+  resolveFieldError,
+  resolveFieldMessage,
+  resolveDisplayError,
+  resolveShowError,
+  useFieldState,
+  useFormFields,
+  useValidationRequest,
+  attemptWizardStep,
+} from "@andreyfedkovich/cozy-ui";
+```
+
 ### `useMeasureElement`
 
 Tracks the size of a DOM element via `ResizeObserver`.

package/dist-lib/index.d.ts

@@ -25,6 +25,7 @@ import { default as FeedbackIcon } from './feedback.svg?react';
 import { default as FileReloadIcon } from './fileReload.svg?react';
 import { default as FileSync } from './fileSync.svg?react';
 import { default as FilterIcon } from './filter.svg?react';
+import { FocusEventHandler } from 'react';
 import { default as FolderEditIcon } from './folderEdit.svg?react';
 import { ForwardRefExoticComponent } from 'react';
 import { default as GraduateIcon } from './graduate.svg?react';
@@ -112,6 +113,37 @@ export { ArrowDownIcon }
 
 export { ArrowRightIcon }
 
+/** Validate-on-click for form Submit. */
+export declare function attemptFormSubmit<TValidation>(options: AttemptFormSubmitOptions<TValidation>): Promise<AttemptFormSubmitResult<TValidation>>;
+
+export declare type AttemptFormSubmitOptions<TValidation> = {
+    markFormSubmitted: () => void;
+    validate: () => Promise<TValidation> | TValidation;
+    hasErrors: (validation: TValidation) => boolean;
+};
+
+export declare type AttemptFormSubmitResult<TValidation> = {
+    ok: boolean;
+    validation: TValidation;
+};
+
+/**
+ * Validate-on-click for wizard "Next" — does not require disabled={!isValid}.
+ */
+export declare function attemptWizardStep<TValidation>(options: AttemptWizardStepOptions<TValidation>): Promise<AttemptWizardStepResult<TValidation>>;
+
+export declare type AttemptWizardStepOptions<TValidation> = {
+    markStepSubmitted: (step: number) => void;
+    validate: () => Promise<TValidation> | TValidation;
+    step: number;
+    hasStepErrors: (validation: TValidation, step: number) => boolean;
+};
+
+export declare type AttemptWizardStepResult<TValidation> = {
+    ok: boolean;
+    validation: TValidation;
+};
+
 export declare const BaseBlock: FC<BaseBlockProps>;
 
 declare interface BaseBlockProps {
@@ -137,17 +169,17 @@ declare type ButtonSize = "small" | "medium" | "large";
 
 declare type ButtonVariant = "default" | "primary" | "secondary" | "text" | "link" | "danger";
 
-export declare const Calendar: ({ label, required, value, onChange, minDate, error, disabled, tooltipContent, tooltipPopperClassName, className, }: CalendarProps) => JSX.Element;
+export declare const Calendar: ({ label, required, value, onValueChange, onChange, minDate, error, suppressError, fieldMeta, showErrorPolicy, disabled, onBlur, onFocus, tooltipContent, tooltipPopperClassName, className, }: CalendarProps) => JSX.Element;
 
-export declare interface CalendarProps {
+export declare interface CalendarProps extends ValueFieldCallbacks<string | null>, FieldValidationProps {
     label: string;
     required?: boolean;
     value?: string | null;
-    onChange: (value: string | null) => void;
     /** Нижняя граница выбора (включительно), локальный календарный день */
     minDate?: Date;
-    error?: string | null;
     disabled?: boolean;
+    onBlur?: FocusEventHandler<HTMLButtonElement>;
+    onFocus?: FocusEventHandler<HTMLButtonElement>;
     /** Подсказка по наведению на иконку «?» справа от подписи */
     tooltipContent?: ReactNode;
     tooltipPopperClassName?: string;
@@ -203,9 +235,8 @@ export { ChatIcon }
 
 export declare const Checkbox: ForwardRefExoticComponent<CheckboxProps & RefAttributes<HTMLInputElement>>;
 
-export declare interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
+export declare interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type">, FieldValidationProps {
     label?: ReactNode;
-    error?: string | null;
     checkboxClassName?: string;
     /** Подсказка по наведению на иконку «?» справа от подписи */
     tooltipContent?: ReactNode;
@@ -387,8 +418,7 @@ export declare interface CustomOption<T, S = string> {
     meta?: T;
 }
 
-declare type CustomSelectProps<T, S> = {
-    onChange?: (option: CustomOption<T, S>) => void;
+declare type CustomSelectProps<T, S> = ValueFieldCallbacks<CustomOption<T, S>> & FieldValidationProps & {
     options?: CustomOption<T, S>[];
     placeholder: string;
     dropdownRender?: (menu: ReactNode) => ReactNode;
@@ -416,7 +446,8 @@ declare type CustomSelectProps<T, S> = {
     disabled?: boolean;
     onClose?: () => void;
     portalTarget?: Element;
-    error?: string | null;
+    onBlur?: default_2.FocusEventHandler<HTMLDivElement>;
+    onFocus?: default_2.FocusEventHandler<HTMLDivElement>;
     template?: "list" | "table";
     columns?: SelectColumn<T, S>[];
     total?: number;
@@ -483,7 +514,7 @@ export declare interface DetailViewProps {
     id?: string;
 }
 
-export declare const DialogSelect: <T, S extends string | number>({ value, placeholder, loadOptions, onChange, onClear, columns, label, tooltipContent, tooltipPopperClassName, title, searchPlaceholder, selectButtonText, closeButtonText, manualButtonText, onManualAdd, pageSize, debounceMs, disabled, error, className, inputClassName, selectedOptionRender, }: DialogSelectProps<T, S>) => JSX.Element;
+export declare const DialogSelect: <T, S extends string | number>({ value, placeholder, loadOptions, onValueChange, onChange, onBlur, onFocus, onClear, columns, label, tooltipContent, tooltipPopperClassName, title, searchPlaceholder, selectButtonText, closeButtonText, manualButtonText, onManualAdd, pageSize, debounceMs, disabled, error, suppressError, fieldMeta, showErrorPolicy, className, inputClassName, selectedOptionRender, }: DialogSelectProps<T, S>) => JSX.Element;
 
 export declare type DialogSelectColumn<T, S extends string | number> = {
     key: string;
@@ -492,12 +523,13 @@ export declare type DialogSelectColumn<T, S extends string | number> = {
     render: (option: CustomOption<T, S>) => ReactNode;
 };
 
-export declare interface DialogSelectProps<T, S extends string | number> {
+export declare interface DialogSelectProps<T, S extends string | number> extends ValueFieldCallbacks<CustomOption<T, S>>, FieldValidationProps {
     value?: CustomOption<T, S> | null;
     placeholder: string;
     loadOptions: (params: LoadOptionsParams) => Promise<LoadOptionsResult<T, S>>;
-    onChange?: (option: CustomOption<T, S>) => void;
     onClear?: () => void;
+    onBlur?: default_2.FocusEventHandler<HTMLDivElement>;
+    onFocus?: default_2.FocusEventHandler<HTMLDivElement>;
     columns?: DialogSelectColumn<T, S>[];
     label?: ReactNode;
     /** Подсказка по наведению на иконку «?» справа от подписи */
@@ -512,7 +544,6 @@ export declare interface DialogSelectProps<T, S extends string | number> {
     pageSize?: number;
     debounceMs?: number;
     disabled?: boolean;
-    error?: string | null;
     className?: string;
     inputClassName?: string;
     selectedOptionRender?: (option: CustomOption<T, S>) => ReactNode;
@@ -556,14 +587,65 @@ export { EnvelopIcon }
 
 export { FeedbackIcon }
 
+export declare type FieldBinding = {
+    fieldMeta: FieldMeta;
+    showErrorPolicy?: ShowErrorPolicy;
+    onBlur: () => void;
+    onDirty?: () => void;
+};
+
 declare interface FieldComponentProps extends Omit<DetailField, "value"> {
     value?: ReactNode;
     children?: ReactNode;
     className?: string;
 }
 
+export declare function FieldErrorCaption({ id, message }: FieldErrorCaptionProps): ReactNode;
+
+declare type FieldErrorCaptionProps = {
+    id: string;
+    message: string | null;
+};
+
+export declare type FieldErrorKind = "required" | "semantic" | "custom";
+
+/**
+ * Headless field state for policy-based error display.
+ *
+ * - `touched` — user blurred the field
+ * - `dirty` — user changed the value in the current session (any change, not only clear)
+ * - `submitted` — form-level submit failed (`markFormSubmitted`)
+ * - `stepSubmitted` — wizard step "Next" failed (`markStepSubmitted`)
+ * - `hasValue` — non-empty value (trimmed string, number, selected option, etc.)
+ * - `validationPending` — async validate in flight; optionally suppresses display
+ * - `errorKind` — drives `resolveDisplayError` (stale required suppression)
+ */
+export declare type FieldMeta = {
+    touched?: boolean;
+    dirty?: boolean;
+    submitted?: boolean;
+    stepSubmitted?: boolean;
+    hasValue?: boolean;
+    invalid?: boolean;
+    errorMessage?: string | null;
+    validationPending?: boolean;
+    errorKind?: FieldErrorKind;
+};
+
 declare const FieldRow: FC<FieldComponentProps>;
 
+export declare type FieldValidationProps = {
+    /**
+     * Explicit error string overrides `fieldMeta` + policy.
+     * Omit to use `fieldMeta`. Do not pass `null` — use {@link suppressError} instead.
+     */
+    error?: string | null;
+    /** Force-hide any error from `fieldMeta` or explicit `error`. */
+    suppressError?: boolean;
+    fieldMeta?: FieldMeta;
+    showErrorPolicy?: ShowErrorPolicy;
+};
+
 export { FileReloadIcon }
 
 export { FileSync }
@@ -572,12 +654,29 @@ export { FilterIcon }
 
 export { FolderEditIcon }
 
+/**
+ * Optional wrapper that spreads fieldMeta, showErrorPolicy, and onBlur into a field control.
+ */
+export declare function FormField({ bind, children }: FormFieldProps): ReactNode;
+
+export declare type FormFieldProps = {
+    bind: FieldBinding;
+    label?: ReactNode;
+    required?: boolean;
+    children: (props: FieldBinding) => ReactNode;
+};
+
+export declare type FormFieldsApi<TValidation> = ReturnType<typeof useFormFields<TValidation>>;
+
 export { GraduateIcon }
 
 export { GridIcon }
 
 declare const GroupBlock: FC<SettingsGroup>;
 
+/** Whether a field value counts as non-empty for `FieldMeta.hasValue`. */
+export declare function hasFieldValue(value: unknown): boolean;
+
 export { HeartIcon }
 
 export { HelpIcon }
@@ -610,7 +709,7 @@ export declare const Input: ForwardRefExoticComponent<InputProps & RefAttributes
 
 export declare const InputCaption: React_2.FC<PropsWithChildren<InputCaptionProps>>;
 
-declare interface InputCaptionProps {
+declare interface InputCaptionProps extends React_2.HTMLAttributes<HTMLParagraphElement> {
     isFullWidth?: boolean;
     /** Visual tone. Defaults to `error` for backwards compatibility with validation messages. */
     variant?: InputCaptionVariant;
@@ -620,15 +719,16 @@ declare interface InputCaptionProps {
 
 export declare type InputCaptionVariant = "neutral" | "error" | "success";
 
-export declare interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+export declare interface InputProps extends InputHTMLAttributes<HTMLInputElement>, FieldValidationProps {
     label?: ReactNode;
-    error?: string | null;
     inputClassName?: string;
     /** Подсказка по наведению на иконку «?» справа от подписи */
     tooltipContent?: ReactNode;
     tooltipPopperClassName?: string;
 }
 
+export declare function isFieldInvalid(meta: FieldMeta): boolean;
+
 export { IslandIcon }
 
 declare interface ItemComponentProps extends SettingsItem {
@@ -782,6 +882,35 @@ declare interface RadioGroupButtonProps<T extends string | number> {
 
 export { ReloadIcon }
 
+/**
+ * Suppresses stale or in-flight errors before display.
+ * WHY: API may still return "required" while the value is already non-empty.
+ */
+export declare function resolveDisplayError(options: {
+    errorMessage?: string | null;
+    errorKind?: FieldErrorKind;
+    hasValue?: boolean;
+    validationPending?: boolean;
+}): string | null;
+
+export declare function resolveDisplayErrorFromMeta(meta: FieldMeta): string | null;
+
+export declare function resolveFieldError(meta: FieldMeta | undefined, policy?: ShowErrorPolicy): string | null;
+
+/**
+ * Resolves the error message to display: explicit `error` wins over fieldMeta + policy.
+ */
+export declare function resolveFieldMessage(options: {
+    error?: string | null;
+    suppressError?: boolean;
+    fieldMeta?: FieldMeta;
+    showErrorPolicy?: ShowErrorPolicy;
+}): string | null;
+
+export declare function resolveShowError(meta: FieldMeta | undefined, policy?: ShowErrorPolicy): boolean;
+
+export declare function resolveValueChangeHandler<T>(callbacks: ValueFieldCallbacks<T>): ((value: T) => void) | undefined;
+
 export { SchoolIcon }
 
 export { SearchIcon }
@@ -798,7 +927,7 @@ declare interface SectionComponentProps extends Omit<DetailSection, "fields"> {
 declare interface SectionProps extends SideNavSection {
 }
 
-export declare const Select: <T, S extends string | number>({ options, value, mode, placeholder, onChange, dropdownRender, optionRender, selectedOptionRender, dropdownIcon, tagRender, dropDownClassName, optionClassName, inputClassName, deleteIconClassName, onDelete, onClear, label, tooltipContent, tooltipPopperClassName, onSearch, searchClassName, searchPlaceholder, isLoading, disabled, onClose, portalTarget, error, template, columns, total, }: CustomSelectProps<T, S>) => JSX.Element;
+export declare const Select: <T, S extends string | number>({ options, value, mode, placeholder, onValueChange, onChange, onBlur, onFocus, dropdownRender, optionRender, selectedOptionRender, dropdownIcon, tagRender, dropDownClassName, optionClassName, inputClassName, deleteIconClassName, onDelete, onClear, label, tooltipContent, tooltipPopperClassName, onSearch, searchClassName, searchPlaceholder, isLoading, disabled, onClose, portalTarget, error, suppressError, fieldMeta, showErrorPolicy, template, columns, total, }: CustomSelectProps<T, S>) => JSX.Element;
 
 export declare type SelectColumn<T, S> = {
     key: string;
@@ -878,6 +1007,8 @@ export declare interface SettingsViewProps {
     id?: string;
 }
 
+export declare type ShowErrorPolicy = "default" | "onBlur" | "onSubmit" | "always" | "draftFriendly" | "wizardStep" | "savedInvalid" | "onBlurOrSubmit" | ((meta: FieldMeta) => boolean);
+
 export declare const SideNav: SideNavComponent;
 
 declare type SideNavComponent = FC<SideNavProps> & {
@@ -1036,10 +1167,9 @@ export { TaskListIcon }
 
 export declare const Textarea: ForwardRefExoticComponent<TextareaProps & RefAttributes<HTMLTextAreaElement>>;
 
-export declare interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+export declare interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement>, FieldValidationProps {
     label?: ReactNode;
-    error?: string | null;
-    /** Neutral helper text under the textarea (hidden when `error` is set). */
+    /** Neutral helper text under the textarea (hidden when error is shown). */
     hint?: ReactNode;
     hintVariant?: InputCaptionVariant;
     textareaClassName?: string;
@@ -1098,7 +1228,7 @@ export declare type TooltipTrigger = "hover" | "click";
 /** `yyyy-MM-dd` for API / form state */
 export declare const toYmdString: (d: Date) => string;
 
-export declare const TreeDialogSelect: <T, S extends string | number>({ value, placeholder, loadChildren: loadChildrenProp, loadNodes, searchNodes, onChange, onClear, label, tooltipContent, tooltipPopperClassName, title, searchPlaceholder, selectButtonText, closeButtonText, confirmButtonText, debounceMs, disabled, error, className, inputClassName, selectedOptionRender, nodeRender, leafConfirmOnly, }: TreeDialogSelectProps<T, S>) => JSX.Element;
+export declare const TreeDialogSelect: <T, S extends string | number>({ value, placeholder, loadChildren: loadChildrenProp, loadNodes, searchNodes, onValueChange, onChange, onBlur, onFocus, onClear, label, tooltipContent, tooltipPopperClassName, title, searchPlaceholder, selectButtonText, closeButtonText, confirmButtonText, debounceMs, disabled, error, suppressError, fieldMeta, showErrorPolicy, className, inputClassName, selectedOptionRender, nodeRender, leafConfirmOnly, }: TreeDialogSelectProps<T, S>) => JSX.Element;
 
 /** Pass either {@link loadNodes} or {@link loadChildren} (deprecated alias). */
 export declare type TreeDialogSelectProps<T, S extends string | number> = TreeDialogSelectShared<T, S> & ({
@@ -1109,12 +1239,13 @@ export declare type TreeDialogSelectProps<T, S extends string | number> = TreeDi
     loadNodes?: TreeLoader<T, S>;
 });
 
-declare interface TreeDialogSelectShared<T, S extends string | number> {
+declare interface TreeDialogSelectShared<T, S extends string | number> extends ValueFieldCallbacks<TreeNode<T, S>>, FieldValidationProps {
     value?: TreeNode<T, S> | null;
     placeholder: string;
     searchNodes?: (search: string) => Promise<TreeSearchResult<T, S>>;
-    onChange?: (node: TreeNode<T, S>) => void;
     onClear?: () => void;
+    onBlur?: default_2.FocusEventHandler<HTMLDivElement>;
+    onFocus?: default_2.FocusEventHandler<HTMLDivElement>;
     label?: ReactNode;
     /** Подсказка по наведению на иконку «?» справа от подписи */
     tooltipContent?: ReactNode;
@@ -1126,7 +1257,6 @@ declare interface TreeDialogSelectShared<T, S extends string | number> {
     confirmButtonText?: string;
     debounceMs?: number;
     disabled?: boolean;
-    error?: string | null;
     className?: string;
     inputClassName?: string;
     selectedOptionRender?: (node: TreeNode<T, S>) => ReactNode;
@@ -1176,6 +1306,54 @@ declare interface UseDropdownPositionProps {
     onAnchorFrame?: (placement: DropdownPosition) => void;
 }
 
+export declare function useFieldPresentation(options: UseFieldPresentationOptions): {
+    controlId: string;
+    errorId: string;
+    hintId: string | undefined;
+    errorMessage: string | null;
+    showError: boolean;
+    ariaInvalid: boolean | undefined;
+    ariaDescribedBy: string | undefined;
+};
+
+export declare type UseFieldPresentationOptions = {
+    error?: string | null;
+    suppressError?: boolean;
+    fieldMeta?: FieldMeta;
+    showErrorPolicy?: ShowErrorPolicy;
+    /** When set and no error, included in aria-describedby */
+    hintId?: string;
+    idPrefix?: string;
+};
+
+export declare function useFieldState(fieldMeta: FieldMeta | undefined, policy?: ShowErrorPolicy, explicitError?: string | null, suppressError?: boolean): {
+    showError: boolean;
+    errorMessage: string | null;
+    showErrorByPolicy: boolean;
+};
+
+export declare function useFormFields<TValidation>(options?: UseFormFieldsOptions<TValidation>): {
+    bindField: (path: string, value: unknown) => FieldBinding;
+    markFieldTouched: (path: string) => void;
+    markFieldDirty: (path: string) => void;
+    markStepSubmitted: (step: number) => void;
+    markFormSubmitted: () => void;
+    resetInteraction: () => void;
+    formSubmitted: boolean;
+    submittedSteps: Set<number>;
+    showErrorPolicy: ShowErrorPolicy;
+};
+
+export declare type UseFormFieldsOptions<TValidation> = {
+    showErrorPolicy?: ShowErrorPolicy;
+    validation?: TValidation;
+    getFieldError?: (validation: TValidation | undefined, path: string) => string | null;
+    getFieldErrorKind?: (validation: TValidation | undefined, path: string) => FieldErrorKind | undefined;
+    /** Maps field path to wizard step index for stepSubmitted. */
+    stepForField?: (path: string) => number | undefined;
+    validationPending?: boolean;
+};
+
 export declare const useMeasureElement: (element?: HTMLElement | null) => {
     height: number;
     width: number;
@@ -1183,6 +1361,22 @@ export declare const useMeasureElement: (element?: HTMLElement | null) => {
 
 export { UserSwitchIcon }
 
+export declare function useValidationRequest<T>(validateFn: () => Promise<T>): {
+    validate: () => Promise<T>;
+    validationPending: boolean;
+    validationGeneration: number;
+    isStale: (generation: number) => boolean;
+};
+
+export declare type ValidationRequestApi<T> = ReturnType<typeof useValidationRequest<T>>;
+
+/** Picker controls: canonical value callback + deprecated alias. */
+export declare type ValueFieldCallbacks<T> = {
+    onValueChange?: (value: T) => void;
+    /** @deprecated Use {@link onValueChange}. Removed in next major. */
+    onChange?: (value: T) => void;
+};
+
 export { WalletIcon }
 
 export { WarnIcon }