/**
 * @file Field.tsx
 * @input Uses React, HTMLAttributes, ReactNode, FieldLabel, IconType
 * @output Exports Field component, FieldProps
 * @position Core implementation; consumed by index.ts, tested by Field.test.tsx
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/Field/Field.doc.mjs (props table, features, implementation notes)
 * - /packages/core/src/Field/Field.test.tsx (tests for new/changed behavior)
 * - /packages/core/src/Field/index.ts (exports if types change)
 * - /apps/storybook/stories/Field.stories.tsx (storybook stories)
 * - /packages/cli/assets/templates/blocks/components/Field/ (showcase blocks)
 */
import { type ReactNode } from 'react';
import type { BaseProps } from '../BaseProps';
import type { SizeValue } from '../utils/types';
import type { FieldStatusVariant } from '../FieldStatus/FieldStatus';
import type { IconType } from '../Icon';
export type { SizeValue } from '../utils/types';
export type FieldStatusType = 'warning' | 'error' | 'success';
export interface FieldStatusInput {
    /**
     * The type of status to display.
     */
    type: FieldStatusType;
    /**
     * Optional message to display below the input.
     */
    message?: string;
    /**
     * ID for the status message element (use for aria-describedby on the input).
     */
    messageID?: string;
}
export interface FieldProps extends Omit<BaseProps<HTMLDivElement>, 'children'> {
    /** Ref forwarded to the root element */
    ref?: React.Ref<HTMLDivElement>;
    /**
     * Label text for the field (always rendered for accessibility).
     */
    label: string;
    /**
     * Whether to visually hide the label and description (still accessible to screen readers).
     * @default false
     */
    isLabelHidden?: boolean;
    /**
     * Description text displayed between the label and input.
     * Hidden when isLabelHidden is true.
     */
    description?: string;
    /**
     * ID of the input element this label points AT (used as the label's
     * `htmlFor`). This is the id of the *control*, not of the label element —
     * see `labelID` for the latter.
     */
    inputID: string;
    /**
     * The `id` applied TO the label element itself (distinct from `inputID`,
     * which is the control the label points at). A grouping control
     * (radiogroup, checkbox group) references this via `aria-labelledby` to take
     * the label as its accessible name. Pair with `isGroupLabel`.
     */
    labelID?: string;
    /**
     * When the field wraps a group of controls rather than a single input, set
     * this so the label renders as a non-`<label>` element (a `<span>`): a
     * `<label>` semantically names one control and can't be associated with a
     * group. Pair with `labelID` + `aria-labelledby` on the group.
     * @default false
     */
    isGroupLabel?: boolean;
    /**
     * ID for the description element (use for aria-describedby on the input).
     */
    descriptionID?: string;
    /**
     * Whether the field is optional. Mutually exclusive with isRequired.
     * @default false
     */
    isOptional?: boolean;
    /**
     * Whether the field is required. Mutually exclusive with isOptional.
     * @default false
     */
    isRequired?: boolean;
    /**
     * Whether the associated input is disabled.
     * @default false
     */
    isDisabled?: boolean;
    /**
     * Icon to display before the label text.
     */
    labelIcon?: ReactNode | IconType;
    /**
     * Status indicator for the field.
     * When set with a message, displays a colored message box below the input.
     */
    status?: FieldStatusInput;
    /**
     * Tooltip text to display in an info icon at the end of the label.
     */
    labelTooltip?: string;
    /**
     * How the status message is rendered relative to the input.
     * - 'attached': Status sits directly below the input (default, for bordered inputs)
     * - 'detached': Status is a separate element below the field (for checkboxes, switches, sliders)
     * - 'tooltip': No message box; the input surfaces status through a tooltip on its on-field icon
     * @default 'attached'
     */
    statusVariant?: FieldStatusVariant;
    /**
     * Width of the field. Numbers are treated as pixels, strings are used as-is
     * (e.g. `'100%'`). Sizes the whole field — label, control, and status — so
     * the control and its surrounding chrome stay aligned. Prefer this over
     * setting `width` via `xstyle`/`className`/`style`, which only size the inner
     * control box and leave the label and status at their natural width.
     */
    width?: SizeValue;
    /**
     * The input or control to render inside the field.
     */
    children: ReactNode;
}
/**
 * A form field wrapper that provides label and description.
 *
 * @example
 * ```
 * const id = useId();
 * const descID = useId();
 * <Field label="Email" description="We'll never share your email" inputID={id} descriptionID={descID}>
 *   <input id={id} aria-describedby={descID} />
 * </Field>
 * ```
 */
export declare function Field({ label, isLabelHidden, description, inputID, labelID, isGroupLabel, descriptionID, isOptional, isRequired, isDisabled, labelIcon, status, labelTooltip, statusVariant, width, xstyle, children, className, style, ref, ...props }: FieldProps): import("react").JSX.Element;
export declare namespace Field {
    var displayName: string;
}
//# sourceMappingURL=Field.d.ts.map