import type * as React from 'react';
import type { FieldCharacterCountOptions, FieldMode, FieldSnapshot, FieldValidator } from '../utils/field-core.js';
import type { PolymorphicTag, PrimitivePropsWithRef } from '../utils/primitive.js';
export type { FieldCharacterCountOptions, FieldMode, FieldValidationResult, FieldValidator, } from '../utils/field-core.js';
/** The state a `Field` reports through {@link FieldOwnProps.onValidityChange}. */
export type FieldValidityDetail = Omit<FieldSnapshot, 'controlId'>;
/** Imperative Field contract for programmatic validation and reset. */
export interface FieldValidateHandle {
    /** Runs validation now, covering server errors, custom validation, native constraints, and character count. */
    checkValidity(): Promise<boolean>;
    /** Clears messages and touched/dirty state, and re-derives filled/count from the control. */
    reset(): void;
}
/** What {@link Field}'s forwarded ref carries: the root `<div>` plus the validate handle's methods. */
export type FieldHandle = HTMLDivElement & FieldValidateHandle;
/** What {@link Fieldset}'s forwarded ref carries: the `<fieldset>` plus the validate handle's methods. */
export type FieldsetHandle = FieldValidateHandle & HTMLFieldSetElement;
/** The validation-model props shared by {@link FieldProps} and {@link FieldsetProps}. */
export interface FieldOwnProps {
    /**
     * Validator for this field; may be async, returning a message (or none) for the current value.
     * @default undefined — only the `errors` prop and native constraint validation produce messages.
     */
    validate?: FieldValidator | undefined;
    /**
     * When validation first runs; a field that has already failed re-validates on every input.
     * @default 'blur'
     */
    mode?: FieldMode | undefined;
    /**
     * Server-injected errors, always shown and listed before anything `validate` produces.
     * @default undefined
     */
    errors?: string | string[] | undefined;
    /**
     * Value handed to `validate`; omitted, the Field reads the wrapped control's `checked`/`value` instead.
     * @default undefined — read from the control.
     */
    value?: unknown;
    /**
     * Field name, used as the `FormErrorSummary` link text when no `FieldError` is rendered.
     * @default undefined
     */
    name?: string | undefined;
    /**
     * Whether an answer is mandatory, reflected as native `required` or `aria-required="true"` on the control.
     * @default false
     */
    required?: boolean | undefined;
    /**
     * Whether the field is unavailable, applied as native `disabled` or `aria-disabled="true"` and mirrored as `data-disabled`.
     * @default false
     */
    disabled?: boolean | undefined;
    /**
     * Fires whenever the field's validity or interaction state changes.
     * @default undefined
     */
    onValidityChange?: ((detail: FieldValidityDetail) => void) | undefined;
    /**
     * Words all character-count copy: rendered text, announced message, and over-limit error.
     * @default undefined
     */
    getCharacterCountMessage?: ((remaining: number) => string) | undefined;
    /**
     * Message shown when the control fails native constraint validation with no message of its own.
     * @default undefined — 'This field is invalid.'
     */
    invalidMessage?: string | undefined;
    /**
     * Milliseconds `mode="change"` waits after the last keystroke before validating; a blur runs it immediately.
     * @default 0 — no debounce.
     */
    validationDebounceTime?: number | undefined;
    /**
     * Spacing rung the skin packs the field by, mirrored to `data-density`.
     * @default undefined — the skin's own default spacing.
     */
    density?: 'compact' | (string & {}) | undefined;
}
/** Props for {@link FieldRoot}: {@link FieldProps} minus the derived-anatomy-only props. */
export type FieldRootProps = Omit<FieldProps, 'label' | 'description'> & Pick<PrimitivePropsWithRef<'div'>, 'asChild'>;
/** Props for {@link Field}, which wires one control to its label, description and error text. */
export interface FieldProps extends Omit<PrimitivePropsWithRef<'div'>, 'value' | 'asChild'>, FieldOwnProps {
    /**
     * The control's label, rendered into a derived `FieldLabel` whose `htmlFor` points at the found control.
     * @default undefined — no label is rendered, and the control is unnamed.
     */
    label?: React.ReactNode | undefined;
    /**
     * Help text, rendered into a derived `FieldDescription` joined to the control's `aria-describedby`.
     * @default undefined — no description is rendered.
     */
    description?: React.ReactNode | undefined;
}
/** Props for {@link Fieldset}, a {@link FieldRoot} that groups several controls under a `<legend>`. */
export interface FieldsetProps extends Omit<PrimitivePropsWithRef<'fieldset'>, 'value' | 'name'>, FieldOwnProps {
    /**
     * Derives the first legend; omit when composing FieldLabel manually.
     * @default undefined
     */
    legend?: React.ReactNode | undefined;
}
/** Props for {@link FieldLabel}, which renders a `<label>` — or a `<legend>` inside a {@link Fieldset}. */
export interface FieldLabelProps extends PrimitivePropsWithRef<'label'> {
}
/** Props for {@link FieldRequiredIndicator}, the "this one is mandatory" marker inside a {@link FieldLabel}. */
export interface FieldRequiredIndicatorProps extends PrimitivePropsWithRef<'span'> {
    /**
     * Overrides the default `*` marker; rendered inside the accessible name, so words read better than a symbol.
     * @default undefined — renders `*`.
     */
    children?: React.ReactNode | undefined;
}
/** Props for {@link FieldDescription}, help text announced with the control. */
export interface FieldDescriptionProps extends PrimitivePropsWithRef<'span'> {
    /**
     * Element tag to render instead of the default, from the library's allowlist of tags.
     * @default 'span'
     */
    as?: PolymorphicTag | undefined;
}
/** Props for {@link FieldError}, rendered only while the field is invalid. */
export interface FieldErrorProps extends PrimitivePropsWithRef<'span'> {
    /**
     * Element tag to render instead of the default, from the library's allowlist of tags.
     * @default 'span'
     */
    as?: PolymorphicTag | undefined;
}
/** Props for {@link FieldCharacterCount}, the running "N characters remaining" count. */
export interface FieldCharacterCountProps extends PrimitivePropsWithRef<'span'> {
    /** The soft limit; not the control's native `maxlength`, which truncates instead of warning. */
    maxLength: number;
    /**
     * Percentage of `maxLength` typed before the count appears.
     * @default 0 — visible from the first render.
     */
    threshold?: number | undefined;
}
/** @internal Field identity and state distributed to the Label/Description/Error parts. */
export interface FieldContextValue {
    labelId: string;
    descriptionId: string;
    errorId: string;
    /** The id the control actually carries; `undefined` until the Field has connected to one. */
    controlId?: string | undefined;
    errors: string[];
    grouped: boolean;
    /** Whether the Field is required, so `FieldRequiredIndicator` knows whether to render at all. */
    required: boolean;
    count: number;
    setCharacterCount: (options: FieldCharacterCountOptions | null) => void;
    /** The root's `getCharacterCountMessage`, so the rendered count uses the same wording as the announced one. */
    getCharacterCountMessage?: ((remaining: number) => string) | undefined;
}