import { type Readable } from '@vielzeug/ripple';
export type ValidationTrigger = 'blur' | 'change' | 'input' | 'submit';
export type ControlValidationMode = ValidationTrigger | undefined;
export type ErrorHelperState = {
    errorText: string;
    helperText: string;
};
export type ErrorHelperOptions = {
    error?: Readable<string | undefined>;
    helper?: Readable<string | undefined>;
};
export declare const createErrorHelperState: (options: ErrorHelperOptions) => Readable<ErrorHelperState>;
/** Counter state for text fields with `maxLength`. */
export type CounterState = {
    counterAtLimit: boolean;
    counterNearLimit: boolean;
    counterText: string;
};
export type CounterOptions = {
    maxLength?: Readable<number | undefined>;
    value: Readable<string | undefined>;
};
/**
 * Creates a reactive counter state signal for text fields with `maxLength`.
 * Only call this when `maxLength` may be set — the state is genuinely opt-in.
 *
 * @example
 * ```ts
 * const counter = createCounterState({ value: tf.value, maxLength: props.maxlength });
 * ```
 */
export declare const createCounterState: (options: CounterOptions) => Readable<CounterState>;
/**
 * The single implementation of "which modifier class does this counter state map to" —
 * every field with a character counter (`ore-input`, `ore-textarea`, `ore-message-composer`)
 * renders the identical near-limit/at-limit styling, so this is the one place that decides it.
 *
 * @example
 * ```ts
 * html`<span class="${() => counterClassName(counter?.value)}">...</span>`
 * ```
 */
export declare const counterClassName: (counter: CounterState | undefined, base?: string) => string;
/**
 * Tracks whether a control's value has ever been changed by user interaction.
 *
 * Backs the "two-state reset()" pattern used by `createCheckable` (`checked`/
 * `indeterminate`) and `createChoiceField` (`selectedValues`): before the first
 * interaction, the live prop is still a reliable "current default" to resync from
 * (e.g. an async-loaded value arriving after mount); after it, the prop is
 * contaminated by interaction-driven attribute reflection, so only a snapshot taken
 * at creation still represents "the default" in the native sense. `reset()` callers
 * check `isDirty` to decide which source to revert to, then call `clear()`.
 */
export type DirtyTracker = {
    clear: () => void;
    readonly isDirty: boolean;
    markDirty: () => void;
};
export declare function createDirtyTracker(): DirtyTracker;
export type LabelPlacement = 'inset' | 'outside' | undefined;
/**
 * A field's error/helper/disabled/validation-trigger state — everything an input
 * needs *except* a visible `<label>`. Split out from label state (below) because
 * not every field has one: `ore-message-composer` names itself via `aria-label`
 * (a chat composer's accessible name conventionally comes from context/placeholder,
 * not a floating `<label>`), so it composes this directly instead of pulling in
 * label plumbing it can't use. `createField()` composes both for fields that do
 * render a `<label>`.
 */
export type AssistiveStateHandle = {
    /** `aria-describedby` value. Non-null when helper or error text is present. */
    ariaDescribedBy: Readable<string | null>;
    /** `aria-errormessage` value. Non-null when error text is present. */
    ariaErrorMessage: Readable<string | null>;
    /** `aria-invalid` value. `'true'` when error text is present, otherwise `null`. */
    ariaInvalid: Readable<'true' | null>;
    /**
     * The stable `id` used for `aria-describedby` on the input. Points at the
     * assistive-text region (covers both helper text and error text per WAI-ARIA).
     */
    assistiveId: string;
    /**
     * Registers the real form field handle (the return value of `useField()`) so that
     * `triggerValidation()` can call its `reportValidity()`. See `TextFieldHandle.attachFormField`
     * for why this is a post-hoc call instead of a constructor option — the same forward
     * reference applies here for choice fields.
     */
    attachFormField: (formField: {
        reportValidity(): void;
    }) => void;
    disabled: Readable<boolean>;
    /** Stable `id` for the inline error message element (`aria-errormessage`). */
    errorId: string;
    /** Reactive error text. Empty string when no error is set. */
    errorText: Readable<string>;
    /** Reactive helper text. Empty string when no helper is set. */
    helperText: Readable<string>;
    triggerValidation: (on: Extract<ValidationTrigger, 'blur' | 'change'>) => void;
};
export type AssistiveStateOptions = {
    disabled?: Readable<boolean | undefined>;
    error?: Readable<string | undefined>;
    helper?: Readable<string | undefined>;
    validateOn?: Readable<ControlValidationMode>;
};
export declare const createAssistiveState: (options: AssistiveStateOptions) => AssistiveStateHandle;
export type LabelStateHandle = {
    /** `aria-labelledby` value. Non-null when a label is visible. */
    ariaLabelledBy: Readable<string | null>;
    /** Stable `id` for the underlying form control — the `<label for="...">` target. */
    fieldId: string;
    /** Stable `id` for the label element. Stamp this on your `<label id="...">`. */
    labelId: string;
    /** Whether the label should be visible. Use to toggle `hidden` on the `<label>`. */
    labelVisible: Readable<boolean>;
};
export type LabelStateOptions = {
    /**
     * Override for label visibility that takes precedence over deriving it from
     * the `label` text signal. Pass a computed signal that checks both prop and
     * slot presence to enable slot-first composition.
     *
     * @example
     * ```ts
     * const hasLabel = computed(() => !!props.label.value || slots.has('label').value);
     * const label = createLabelState({ ...options, hasLabel });
     * ```
     */
    hasLabel?: Readable<boolean>;
    /**
     * When provided, used directly as `fieldId` instead of generating one via
     * `createStableId`. Useful in tests for deterministic ID assertions.
     */
    id?: string;
    /**
     * Label text signal. When provided, `labelVisible` and `ariaLabelledBy` are
     * computed reactively from this value (see `hasLabel` for the slot-first override).
     */
    label?: Readable<string | undefined>;
    /**
     * Label placement signal. Defaults to `'inset'`.
     *
     * Not consumed by `createLabelState()` itself — visibility is driven solely by
     * `hasLabel`/`label`. Threaded through so component authors can apply
     * placement-specific styling (`label-placement` attribute) without a second
     * option; if placement-dependent visibility is ever needed, wire it into
     * `labelVisible` here instead of adding a new option.
     */
    labelPlacement?: Readable<LabelPlacement>;
    prefix?: string;
};
export declare const createLabelState: (options: LabelStateOptions) => LabelStateHandle;
/**
 * Common handle returned by `createField` — the base for both `TextFieldHandle`
 * and `ChoiceFieldHandle`. Composes `createAssistiveState` + `createLabelState`;
 * call those directly instead if a field has no visible `<label>` (see
 * `createAssistiveState`'s doc comment).
 *
 * ARIA signals and label state are flat on the handle — no nested `aria` or
 * `label` sub-objects. `labelId`/`labelVisible`/`ariaLabelledBy` are always
 * present but only meaningful when `label`/`hasLabel` was passed — omit both
 * and they resolve to an always-hidden, unreferenced label.
 *
 * @example
 * ```html
 * <label id="${labelId}" ?hidden="${() => !labelVisible.value}">...</label>
 * <input
 *   aria-labelledby="${ariaLabelledBy}"
 *   aria-describedby="${ariaDescribedBy}"
 *   aria-invalid="${ariaInvalid}" />
 * ```
 */
export type FieldHandle = AssistiveStateHandle & LabelStateHandle;
/** Options shared by both `createTextField` and `createChoiceField`. */
export type FieldOptions = AssistiveStateOptions & LabelStateOptions;
export declare const createField: (options: FieldOptions) => FieldHandle;
//# sourceMappingURL=field-base.d.ts.map