@andreyfedkovich/cozy-ui 0.7.7 → 0.9.0

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 Формат основан на [Keep a Changelog](https://keepachangelog.com/).
 Версии соответствуют [Semantic Versioning](https://semver.org/) и git-тегам `v*`.
 
+## 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.
+- **build:** `build:lib` now publishes all three files; `verify-lib-styles.mjs` validates each file and the structural bundle concat.
+
 ## 0.7.0 - 2026-05-26
 
 - **feat:** `SettingsView` — composition-first layout for settings pages (`SettingsView.Section`, `.Group`, `.Item`, `.Divider`), declarative `sections`, variants `classic` / `elevated`, densities `comfortable` / `compact`, collapsible sections, left icon badges, row badges (e.g. New/Beta), link rows (`href`, `external`), danger styling, and `render` for full row customization.

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`
@@ -78,7 +78,7 @@ yarn add @andreyfedkovich/cozy-ui
 
 Peer dependencies: **React ≥ 18** and **react-dom ≥ 18** (React 19 supported).
 
-Import the stylesheet **once** at your app root:
+Import the stylesheet **once** at your app root. Which file depends on your host setup — see [Styling in host apps](#styling-in-host-apps) below.
 
 ```ts
 import "@andreyfedkovich/cozy-ui/styles.css";
@@ -86,6 +86,46 @@ import "@andreyfedkovich/cozy-ui/styles.css";
 
 Sizing uses CSS `rem` against the browser’s default root font size (commonly **16px**). You **do not** need to set `html { font-size: … }` for components to match the library demo.
 
+### Styling in host apps
+
+The library publishes three CSS entry points:
+
+| Import | Contents |
+|--------|----------|
+| `@andreyfedkovich/cozy-ui/styles.css` | Full bundle (SCSS modules + Tailwind v4 utilities) |
+| `@andreyfedkovich/cozy-ui/styles.modules.css` | SCSS modules only — safe alongside Tailwind v3 |
+| `@andreyfedkovich/cozy-ui/styles.tailwind.css` | Tailwind v4 utilities and shadcn design tokens |
+
+**A. Host without Tailwind** (greenfield, demo apps):
+
+```ts
+import "@andreyfedkovich/cozy-ui/styles.css";
+```
+
+**B. Host with Tailwind v3 + shadcn** (e.g. existing product apps):
+
+```ts
+// App entry (main.tsx / _app.tsx) — NOT inside your @tailwind index.css
+import "@andreyfedkovich/cozy-ui/styles.modules.css";
+```
+
+Covers SCSS-native components: `SettingsView`, `Switch`, `SideNav`, `Input`, `Select`, `Stepper`, and most other “cozy-native” UI. The modules bundle does not include Tailwind v4 preflight and will not override your host’s Tailwind reset.
+
+**C. You also need Tailwind-based cozy components** (`Calendar`, shadcn wrappers):
+
+```ts
+import "@andreyfedkovich/cozy-ui/styles.modules.css";
+import "@andreyfedkovich/cozy-ui/styles.tailwind.css"; // intentional — may conflict with Tailwind v3
+```
+
+Use this only when you need components that rely on prebuilt Tailwind utilities. **Do not** import `styles.css` or `styles.tailwind.css` in a Tailwind v3 host unless you accept the risk of duplicate preflight and utility conflicts.
+
+**Notes:**
+
+- Several public components combine SCSS with shadcn primitives — `Button`, `Label`, `Calendar`, `Popover`, and dialog-based components (`DialogSelect`, `ApprovalRoute`, …). In scenario B your host shadcn setup may already style them; if classes or tokens differ, use scenario C.
+- shadcn CSS variables (`--primary`, `--background`, …) live in `styles.tailwind.css`, not in `styles.modules.css`. Tailwind v3 + shadcn hosts usually already define these in `:root`.
+- Import cozy styles at your **app entry**, not inside your Tailwind `@tailwind` CSS file.
+
 ### Typography (host application)
 
 Cozy UI **does not ship font files** and **does not hardcode** a brand typeface. Text components inherit the font from your app (`font-family: inherit` / `var(--cozy-font-family, inherit)`).
@@ -117,16 +157,18 @@ The library demo uses the system / Inter stack from your app shell — that is e
 
 ### Tailwind-powered components
 
-Most Cozy UI styles come from SCSS modules bundled into `styles.css`. Components built on shadcn use Tailwind class names in JS; those utilities are **prebuilt into the same** `@andreyfedkovich/cozy-ui/styles.css` when the package is published. You do **not** need Tailwind CSS in your application.
+Most Cozy UI styles come from SCSS modules bundled into `styles.modules.css`. Components built on shadcn use Tailwind class names in JS; those utilities are **prebuilt into** `styles.tailwind.css` (and included in the full `styles.css` bundle). You do **not** need Tailwind CSS in your application unless you choose scenario B above.
+
+If your app already uses **Tailwind v4** and you prefer to generate utilities yourself, you may add `@source` pointing at the library bundle — optional, not required.
 
-If your app already uses Tailwind v4 and you prefer to generate utilities yourself, you may add `@source` pointing at the library bundle — optional, not required.
+If your app uses **Tailwind v3**, import `styles.modules.css` only (scenario B) or add `styles.tailwind.css` when needed (scenario C). Do not import the full `styles.css` bundle — it includes Tailwind v4 preflight that conflicts with v3 hosts.
 
 ### Adding a new Tailwind-based component (library authors)
 
 1. Primitive in `src/components/ui/<name>.tsx` (Tailwind + Radix as needed).
 2. Public API in `src/lib/components/<Name>/` (field label, errors, value; SCSS optional for the trigger shell).
 3. Ensure paths are covered by `@source` in `src/lib/tailwind.css` (`../lib/**/*`, `../components/ui/**/*`).
-4. Run `npm run build:lib` before publish; verify `dist-lib/styles.css` includes the new classes.
+4. Run `npm run build:lib` before publish; verify `dist-lib/styles.css` (and split files) include the new classes.
 
 ---
 
@@ -354,6 +396,59 @@ 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`, `hasValue`, `invalid`, `errorMessage` |
+| `ShowErrorPolicy` | `"default"` \| `"onBlur"` \| `"onSubmit"` \| `"always"` \| custom `(meta) => boolean` |
+| `resolveShowError`, `resolveFieldError`, `resolveFieldMessage` | Pure functions (SSR-safe) |
+| `useFieldState` | React hook wrapping the resolvers |
+
+**Default policy:** `invalid && (touched || submitted || hasValue)`.
+
+**Props on fields:** `error` (explicit override), `fieldMeta`, `showErrorPolicy`.
+
+**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.
@@ -363,7 +458,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.              |
@@ -435,9 +532,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.                      |
@@ -458,14 +559,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="Дата должна быть не раньше сегодня."
 />;
@@ -515,7 +616,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"`.    |
@@ -542,7 +646,7 @@ const [value, setValue] = useState<CustomOption<unknown, string> | null>(null);
   placeholder="Pick one"
   value={value}
   options={options}
-  onChange={setValue}
+  onValueChange={setValue}
 />;
 ```
 
@@ -567,7 +671,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)}
 />;
 ```
 
@@ -592,7 +696,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)}
 />;
 ```
 
@@ -1058,6 +1162,19 @@ const [layout, setLayout] = useState<"agent" | "editor">("agent");
 
 ## Hooks & helpers
 
+### Field validation
+
+```ts
+import {
+  type FieldMeta,
+  type ShowErrorPolicy,
+  resolveFieldError,
+  resolveFieldMessage,
+  resolveShowError,
+  useFieldState,
+} from "@andreyfedkovich/cozy-ui";
+```
+
 ### `useMeasureElement`
 
 Tracks the size of a DOM element via `ResizeObserver`.
@@ -1151,7 +1268,7 @@ For per-component overrides, every component accepts a `className` prop and uses
 ```bash
 bun install
 bun run dev          # demo playground at http://localhost:5173
-bun run build:lib    # dist-lib/ (ESM + CJS + .d.ts + styles.css with SCSS + Tailwind)
+bun run build:lib    # dist-lib/ (ESM + CJS + .d.ts + styles.css / styles.modules.css / styles.tailwind.css)
 bun run lint
 bun run format
 ```

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';
@@ -137,17 +138,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, 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 +204,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 +387,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 +415,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 +483,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, fieldMeta, showErrorPolicy, className, inputClassName, selectedOptionRender, }: DialogSelectProps<T, S>) => JSX.Element;
 
 export declare type DialogSelectColumn<T, S extends string | number> = {
     key: string;
@@ -492,12 +492,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 +513,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;
@@ -562,8 +562,24 @@ declare interface FieldComponentProps extends Omit<DetailField, "value"> {
     className?: string;
 }
 
+export declare type FieldMeta = {
+    touched?: boolean;
+    dirty?: boolean;
+    submitted?: boolean;
+    hasValue?: boolean;
+    invalid?: boolean;
+    errorMessage?: string | null;
+};
+
 declare const FieldRow: FC<FieldComponentProps>;
 
+export declare type FieldValidationProps = {
+    /** Explicit error overrides {@link fieldMeta} + policy when set. */
+    error?: string | null;
+    fieldMeta?: FieldMeta;
+    showErrorPolicy?: ShowErrorPolicy;
+};
+
 export { FileReloadIcon }
 
 export { FileSync }
@@ -610,7 +626,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 +636,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 +799,21 @@ declare interface RadioGroupButtonProps<T extends string | number> {
 
 export { ReloadIcon }
 
+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;
+    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 +830,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, fieldMeta, showErrorPolicy, template, columns, total, }: CustomSelectProps<T, S>) => JSX.Element;
 
 export declare type SelectColumn<T, S> = {
     key: string;
@@ -878,6 +910,8 @@ export declare interface SettingsViewProps {
     id?: string;
 }
 
+export declare type ShowErrorPolicy = "default" | "onBlur" | "onSubmit" | "always" | ((meta: FieldMeta) => boolean);
+
 export declare const SideNav: SideNavComponent;
 
 declare type SideNavComponent = FC<SideNavProps> & {
@@ -1036,10 +1070,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 +1131,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, 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 +1142,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 +1160,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 +1209,12 @@ declare interface UseDropdownPositionProps {
     onAnchorFrame?: (placement: DropdownPosition) => void;
 }
 
+export declare function useFieldState(fieldMeta: FieldMeta | undefined, policy?: ShowErrorPolicy, explicitError?: string | null): {
+    showError: boolean;
+    errorMessage: string | null;
+    showErrorByPolicy: boolean;
+};
+
 export declare const useMeasureElement: (element?: HTMLElement | null) => {
     height: number;
     width: number;
@@ -1183,6 +1222,13 @@ export declare const useMeasureElement: (element?: HTMLElement | null) => {
 
 export { UserSwitchIcon }
 
+/** 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 }