import "./form_field.css";
import type * as React from "react";
import { Field } from "@base-ui/react/field";
import { type StyleProps } from "./style_props";
/** Where the control sits relative to the words. `stacked` keeps a row of fields
 *  level in a grid; `control-first` leads with a boolean that reads as "this is
 *  on", centred on the label until a description gives the text a second line. */
export type FormFieldLayout = "stacked" | "control-first";
export interface FormFieldProps extends StyleProps {
    label: string;
    /** Whether this field may be left empty. The FACT, whichever side the form
     *  marks — {@link FormMarksContext} decides which of the two gets the word. */
    optional?: boolean;
    description?: string;
    /** A consequence the user should WEIGH before acting — amber, one tone between
     *  the muted `description` and the danger `error`. Same name/meaning on
     *  `DetailRow`. */
    warning?: string;
    error?: string;
    /** See {@link FormFieldLayout}. Default `stacked`. */
    layout?: FormFieldLayout;
    /** TAKES THE WHOLE ROW of the form grid it sits in. The FIELD states it because
     *  the grid knows nothing about what its children hold; inert outside one. */
    span?: boolean;
    /** The marker's word, where the pack's ("Optional" / "Required") is not the
     *  one this field wants. Which of the two is drawn — and whether one is drawn
     *  at all — is still {@link FormMarksContext}'s answer. */
    markLabel?: string;
    testID?: string;
    ref?: React.Ref<HTMLDivElement>;
    render?: React.ComponentProps<typeof Field.Root>["render"];
}
/** Binding emitted to the single input a `FormField` wraps, so a screen reader
 *  ties the label, description, warning and error to it. A Base UI-backed control
 *  needs only `inputId`: `Field` wires the rest off the same parts. */
export interface FormFieldBinding {
    inputId: string;
    labelId: string;
    descriptionId: string | undefined;
    warningId: string | undefined;
    errorId: string | undefined;
    invalid: boolean;
}
/** Which side of a form is MARKED — see {@link FormMarksContext}. */
export type FormMarks = "optional" | "required";
/**
 * WHICH SIDE THE FORM MARKS, stated once for the whole form. MARK THE MINORITY:
 * "Required" beside ten of twelve labels is a page the reader stops reading, and
 * `optional` is the default.
 *
 * It marks and nothing else: whether a field MAY be empty is `FormField`'s own
 * `optional`, and validation is the caller's.
 */
export declare const FormMarksContext: React.Context<FormMarks>;
/** Which side the enclosing form marks. `optional` unless a form says otherwise. */
export declare function useFormMarks(): FormMarks;
/** The association ids set by the nearest enclosing `FormField`, or `null`
 *  outside one — where the caller owes an `accessibilityLabel`. */
export declare function useFormField(): FormFieldBinding | null;
/** THROWS on an interactive control with no accessible name — the one a11y
 *  failure with nothing to see, since it renders and operates correctly. Called
 *  at render, after the caller's hooks. */
export declare function assertNamedControl(component: string, binding: FormFieldBinding | null, accessibilityLabel: string | undefined): void;
/** The labelled field wrapper — label, optional marker and the three annotation
 *  tones around ANY control. A styled Base UI `Field`, so a control that is
 *  itself a Base UI part wires itself up with nothing passed down. */
export declare function FormField(props: FormFieldProps & {
    children: React.ReactNode;
}): React.JSX.Element;