@andreyfedkovich/cozy-ui 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 Формат основан на [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.

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,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.
@@ -405,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.              |
@@ -477,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.                      |
@@ -500,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="Дата должна быть не раньше сегодня."
 />;
@@ -557,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"`.    |
@@ -584,7 +646,7 @@ const [value, setValue] = useState<CustomOption<unknown, string> | null>(null);
   placeholder="Pick one"
   value={value}
   options={options}
-  onChange={setValue}
+  onValueChange={setValue}
 />;
 ```
 
@@ -609,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)}
 />;
 ```
 
@@ -634,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)}
 />;
 ```
 
@@ -1100,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`.

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 }