@andreyfedkovich/cozy-ui 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 Формат основан на [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 draft-friendly and 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 typical per-app binding glue. `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, migration guide and consumer verification checklist.
+
 ## 0.9.0 - 2026-06-04
 
 - **feat:** Единый контракт валидации полей — headless API: `FieldMeta`, `ShowErrorPolicy`, `resolveShowError`, `resolveFieldError`, `resolveFieldMessage`, `useFieldState`, `resolveValueChangeHandler`.

package/README.md

@@ -37,6 +37,7 @@ npm i @andreyfedkovich/cozy-ui
   - [Utility](#utility) — `Tag`, `CopyTextTrigger`
   - [Workflow](#workflow) — `ApprovalRoute`, `CommentFeed`, `DetailView`, `SideNav`, `SettingsView`, `Switch`, `ImageSegmented`
 - [Hooks & helpers](#hooks--helpers)
+- [Validation recipes](https://github.com/AndreyFedkovich/cozy-ui-components/blob/main/docs/validation-recipes.md)
 - [Icons](#icons)
 - [TypeScript](#typescript)
 - [SSR & framework support](#ssr--framework-support)
@@ -402,14 +403,19 @@ Form state stays in your app (React Hook Form, TanStack Form, or `useState`). Co
 
 | 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 |
+| `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 |
 
-**Default policy:** `invalid && (touched || submitted || hasValue)`.
+**Recommended policy for draft-friendly forms:** `draftFriendly` — no flash on first keystroke; saved invalid visible on load.
 
-**Props on fields:** `error` (explicit override), `fieldMeta`, `showErrorPolicy`.
+**Legacy `default` policy:** `invalid && (touched || submitted || hasValue)`.
+
+**Props on fields:** `error`, `suppressError`, `fieldMeta`, `showErrorPolicy`.
+
+See [Validation recipes](https://github.com/AndreyFedkovich/cozy-ui-components/blob/main/docs/validation-recipes.md) for step-by-step recipes and expected form behavior.
 
 **Callback families:**
 
@@ -1170,8 +1176,12 @@ import {
   type ShowErrorPolicy,
   resolveFieldError,
   resolveFieldMessage,
+  resolveDisplayError,
   resolveShowError,
   useFieldState,
+  useFormFields,
+  useValidationRequest,
+  attemptWizardStep,
 } from "@andreyfedkovich/cozy-ui";
 ```
 

package/dist-lib/index.d.ts

@@ -113,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 {
@@ -138,7 +169,7 @@ declare type ButtonSize = "small" | "medium" | "large";
 
 declare type ButtonVariant = "default" | "primary" | "secondary" | "text" | "link" | "danger";
 
-export declare const Calendar: ({ label, required, value, onValueChange, onChange, minDate, error, fieldMeta, showErrorPolicy, disabled, onBlur, onFocus, 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 extends ValueFieldCallbacks<string | null>, FieldValidationProps {
     label: string;
@@ -483,7 +514,7 @@ export declare interface DetailViewProps {
     id?: string;
 }
 
-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 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;
@@ -556,26 +587,61 @@ 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 overrides {@link fieldMeta} + policy when set. */
+    /**
+     * 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;
 };
@@ -588,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 }
@@ -799,6 +882,19 @@ 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;
 
 /**
@@ -806,6 +902,7 @@ export declare function resolveFieldError(meta: FieldMeta | undefined, policy?:
  */
 export declare function resolveFieldMessage(options: {
     error?: string | null;
+    suppressError?: boolean;
     fieldMeta?: FieldMeta;
     showErrorPolicy?: ShowErrorPolicy;
 }): string | null;
@@ -830,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, 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 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;
@@ -910,7 +1007,7 @@ export declare interface SettingsViewProps {
     id?: string;
 }
 
-export declare type ShowErrorPolicy = "default" | "onBlur" | "onSubmit" | "always" | ((meta: FieldMeta) => boolean);
+export declare type ShowErrorPolicy = "default" | "onBlur" | "onSubmit" | "always" | "draftFriendly" | "wizardStep" | "savedInvalid" | "onBlurOrSubmit" | ((meta: FieldMeta) => boolean);
 
 export declare const SideNav: SideNavComponent;
 
@@ -1131,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, 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;
+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> & ({
@@ -1209,12 +1306,54 @@ declare interface UseDropdownPositionProps {
     onAnchorFrame?: (placement: DropdownPosition) => void;
 }
 
-export declare function useFieldState(fieldMeta: FieldMeta | undefined, policy?: ShowErrorPolicy, explicitError?: string | null): {
+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;
@@ -1222,6 +1361,15 @@ 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;