import * as React from 'react';
/**
 * Field — 表單欄位佈局容器（shadcn Field 風格）
 *
 * ── 定位 ────────────────────────────────────────────────────────────────
 * Field 只負責 **佈局 + 狀態 context**，不擁有任何資料型別邏輯。
 * 每個資料型別對應的 Control（Input、NumberInput、Checkbox、Switch 等）
 * 維持自己的 edit / readonly / disabled 三態，Field 透過 context 把
 * mode / disabled / required / invalid / id 傳給子元件，由子元件決定
 * 如何反映。
 *
 * ── 結構 ────────────────────────────────────────────────────────────────
 *   <Field orientation="vertical | horizontal" labelWidth="120px">
 *     <FieldLabel>姓名</FieldLabel>
 *     <Input value={...} onChange={...} />         ← Control（任何非 label/desc/error 的 child）
 *     <FieldDescription>...</FieldDescription>
 *     <FieldError>{errors.name}</FieldError>
 *   </Field>
 *
 *   Control 會自動包在 control area slot（min-h-field-* + items-center），
 *   確保 Checkbox / Switch / Radio 等高度 < field-height 的 primitive
 *   垂直對齊 Input 中線；Input 等自身為 field-height 的 primitive 填滿。
 *
 * ── Horizontal mode 的 label 垂直對齊 ───────────────────────────────────
 * FieldLabel 在 horizontal 模式下使用公式：
 *     padding-top: calc((var(--field-height-{size}) - 1lh) / 2)
 *
 * 單行 label → 文字第一行與 input 中線對齊（視覺置中）
 * 多行 label → 第一行仍與 input 中線對齊，其餘行往下流（label 高度超過
 *              input 時視覺上仍保持與 input 內容同一基準線）
 *
 * 此公式 tracks field-height 和 line-height 的變動，size 切換或字體
 * 調整時自動連動，不需 JS 測量。
 *
 * ── Horizontal mode 的 label 寬度 ───────────────────────────────────────
 * 透過 labelWidth prop → --field-label-width CSS variable，可以是任何
 * CSS length（"120px"、"10rem"、"30%" 等）。預設 "auto" 由 label 內容撐開。
 *
 * ── Required 星號 ──────────────────────────────────────────────────────
 * Field 的 required prop 會透過 context 傳給 FieldLabel 自動渲染 *，
 * 星號為 neutral-7（fg-muted），貼齊 label 文字（無 gap），disabled
 * 時降為 fg-disabled。也可在個別 FieldLabel 覆寫。
 */
import type { FieldMode, FieldVariant, FieldOrientation, FieldSize, FieldControlLayout } from './field-context';
export interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'id'> {
    id?: string;
    mode?: FieldMode;
    /**
     * 視覺外殼(2026-05-05)。
     * - `default`(預設)— 含 border + bg(一般 form input)
     * - `bare` — 透明 variant,hover/focus reveal(cell-as-input substrate;VS Code/Figma toolbar idiom)
     *
     * 透傳機制:Field 一次宣告,所有 child Field control 自動繼承(per-control prop override 可覆寫)。
     */
    variant?: FieldVariant;
    orientation?: FieldOrientation;
    size?: FieldSize;
    required?: boolean;
    disabled?: boolean;
    invalid?: boolean;
    /**
     * Horizontal mode 的 label 欄寬度。支援任何 CSS length 值（"120px"、"10rem"、"30%"...）。
     * 預設 'auto' 由 label 內容撐開。
     */
    labelWidth?: string;
    /**
     * Control area 佈局模型(逃生艙)。
     *
     * 預設由 Field 自動偵測——迭代全部 control child 的 `type.fieldLayout` static 屬性,
     * 任一宣告為 `'block'` 即整個 area 切 block(first-block-wins);全部缺宣告時視為 `'inline'`。
     *
     * 只有兩種情況需要手動指定:
     * 1. consumer 把自己手寫的 JSX(`<div>` / 函式元件)當 control,系統無法偵測——強制 `'block'`
     * 2. 想覆寫 primitive 的預設(如把 RadioGroup 強制 inline 呈現,罕見)
     */
    controlLayout?: FieldControlLayout;
}
declare const Field: React.ForwardRefExoticComponent<FieldProps & React.RefAttributes<HTMLDivElement>>;
export interface FieldLabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {
    /**
     * 強制渲染 required 星號（覆寫 Field context 的 required）。
     * 若未設定，預設讀 context。
     */
    required?: boolean;
    /**
     * 在 label 文字後方顯示 info icon (ℹ)，hover 出現 tooltip 說明。
     * 傳 string → tooltip 內容。
     *
     * Info icon 用 inline action pattern（補充工具，視覺退後），
     * 因為 label 的 primary interaction 是 input，info 是補充說明。
     */
    info?: string;
}
declare const FieldLabel: React.ForwardRefExoticComponent<FieldLabelProps & React.RefAttributes<HTMLLabelElement>>;
declare const FieldDescription: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
declare const FieldError: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
export interface FieldGroupProps extends React.HTMLAttributes<HTMLDivElement> {
    /** Field 之間的垂直間距，預設 'normal'（gap-4） */
    gap?: 'compact' | 'normal' | 'loose';
    /**
     * 同一 group 內所有 horizontal Field 共用的 label 欄寬度。
     *
     * 支援任何 CSS length(`"140px"` / `"10rem"` / `"30%"` 等)。預設不指定——
     * 每個 Field 自動以 label 內容撐開(容易歪七扭八)。
     *
     * 世界級 idiom:macOS System Settings / iOS Settings / GitHub Settings 的
     * setting list 一律 label 固定寬、control 右對齊,列與列整齊對齊。
     *
     * 單一 Field 可以用自己的 `labelWidth` prop 覆寫 cascade 值。
     */
    horizontalLabelWidth?: string;
}
declare const FieldGroup: React.ForwardRefExoticComponent<FieldGroupProps & React.RefAttributes<HTMLDivElement>>;
export declare const fieldMeta: {
    readonly component: "Field";
    readonly family: null;
    readonly variants: {};
    readonly sizes: {};
    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
    readonly tokens: {
        readonly bg: readonly [];
        readonly fg: readonly ["text-error-text", "text-fg-disabled", "text-fg-muted", "text-fg-secondary", "text-foreground"];
        readonly ring: readonly [];
    };
};
export { Field, FieldLabel, FieldDescription, FieldError, FieldGroup };
//# sourceMappingURL=field.d.ts.map