import * as React from 'react';
import type { FieldMode, FieldVariant } from './field-types';
export type { FieldMode, FieldVariant };
export type FieldOrientation = 'vertical' | 'horizontal';
export type FieldSize = 'sm' | 'md' | 'lg';
export type FieldControlLayout = 'inline' | 'block';
/**
 * Field surface(2026-05-12 codex Q2 verdict — Stream C 4-issues Cluster B fix):
 * 替代散落的 `variant === 'naked'` 判 cell heuristic,讓 Field family components
 * 顯式 query「我在哪 surface」derive cell-specific padding / alignment / overflow。
 *
 * - `'form'`(default)— Standalone Field control(對齊 Polaris / Material Form idiom)
 * - `'toolbar'`— Toolbar / Action bar inline Field(future,目前無 consumer)
 * - `'table-cell'`— DataTable cell-as-input substrate(取代 variant='naked' cell-detection
 *   heuristic;canonical metrics 由 surface 推導,不再 hardcode in Field consumer)
 */
type FieldSurface = 'form' | 'toolbar' | 'table-cell';
export interface FieldContextValue {
    id: string;
    /** a11y(2026-04-25):FieldLabel 渲染時若元素為 div-based role(combobox/slider
     * 等非 native form control),`<label for>` 無效,需 aria-labelledby 指向 labelId。
     * FieldLabel 自動設 id={labelId},下游 control 可讀此值寫入 aria-labelledby。 */
    labelId: string;
    descriptionId: string;
    errorId: string;
    mode: FieldMode;
    /** 視覺外殼透傳(2026-05-05)。default = 含 border+bg;bare = 透明 variant,hover/focus reveal。
     *  child Field control 自動繼承,per-control prop override 可覆寫。詳 field-types.ts。 */
    variant: FieldVariant;
    disabled: boolean;
    required: boolean;
    invalid: boolean;
    size: FieldSize;
    orientation: FieldOrientation;
    controlLayout: FieldControlLayout;
    hasFieldWrapper: true;
    /** 2026-05-12 Stream C Cluster B fix:surface 上下文(form / toolbar / table-cell)
     *  從 host(Field wrapper / DataTable cell registry)propagate 給 child controls。
     *  Optional — 未設視同 `'form'`(backward compat)。 */
    surface?: FieldSurface;
}
export declare const FieldContext: React.Context<FieldContextValue | null>;
/** 讓 primitive（Checkbox/Switch/Radio/Button/Input 等）讀 Field context */
export declare function useFieldContext(): FieldContextValue | null;
/**
 * Helper: 取當前 surface,fall back 'form'。
 *
 * Stream C Cluster B canonical entry point — Field family controls 用此 helper 替代
 * 散落的 `variant === 'naked'` cell heuristic。對齊 codex Q2 verdict「surface context」
 * canonical(替代「inCellContext per-prop」反 pattern)。
 *
 * 優先順序:FieldSurfaceContext(host-provided) → FieldContext.surface(Field-wrapper-provided)
 *           → fallback 'form'。
 */
export declare function useFieldSurface(): FieldSurface;
/**
 * Standalone FieldSurface provider — 給 host(non-Field-wrapper, 如 DataTable cell)
 * **僅**設 surface signal,**不**污染 FieldContext。
 *
 * Usage(per cell-registry.tsx,2026-05-12):
 *   <FieldSurfaceProvider surface="table-cell"><Field control /></FieldSurfaceProvider>
 *
 * 與 FieldContext.Provider 差別:
 *   - FieldContext.Provider — 完整 Field wrapper 用,provides mode/variant/disabled/...
 *   - FieldSurfaceProvider — host **僅**注 surface signal,Field controls 透過
 *     `useFieldSurface()` 讀;`useFieldContext()` 仍 returns null(沒被假冒)。
 */
export declare function FieldSurfaceProvider({ surface, children, }: {
    surface: FieldSurface;
    children: React.ReactNode;
}): React.ReactElement;
export declare function useTableIsScrolling(): boolean;
export declare function TableScrollProvider({ isScrolling, children, }: {
    isScrolling: boolean;
    children: React.ReactNode;
}): React.ReactElement;
/**
 * Resolve Field control size — 控件用此 helper 取代散落的 `sizeProp ?? fieldCtx?.size ?? 'md'`。
 * 優先序:prop(caller 顯式)> FieldContext.size(真 <Field> wrapper)> surface-size(host 如 cell)> 'md'。
 * 真 <Field> 永遠勝 host surface(安全序);cell 無 Field wrapper(fieldCtx=null)→ 自動接 surface-size,
 * 漏傳 size 的新 cell 也字級一致。
 */
export declare function useResolvedFieldSize<T extends string = FieldSize>(sizeProp?: T | null, fallback?: T): T;
/**
 * Resolve Field control 的 **disabled** — 取代散落的 `disabledProp ?? fieldCtx?.disabled`(2026-06-08 SSOT)。
 * 優先序:顯式 prop > FieldContext.disabled(`<Field disabled>` / `<Field mode="disabled">`)> false。
 * **caller 必傳「未預設」的原始 prop**(沒傳 = undefined),否則 `disabled=false` 預設會吃掉 `??` fallback。
 * DataTable cell 無 FieldContext(fieldCtx=null)→ 回 prop 或 false,行為與現況完全一致(inert)。
 */
export declare function useResolvedFieldDisabled(disabledProp?: boolean | null): boolean;
/**
 * Resolve Field control 的 **mode**(display / readonly / disabled / edit)— 2026-06-08 SSOT,統一兩派散落:
 *   舊 Input 派 `modeProp ?? fieldCtx?.mode ?? (...)` → `<Field disabled>` 時 ctx.mode 仍 'edit',漏 disabled chrome。
 *   舊 picker 派 `disabled ? 'disabled' : mode`(mode 預設 'edit')→ 完全不讀 fieldCtx.mode,`<Field mode="display">` 失效。
 * 統一優先序(world-class:MUI FormControl disabled 完整 cascade + 顯式 prop 永遠最優先):
 *   1. 顯式 mode prop(caller / DataTable cell 的 displayOrDisabled)→ **永遠最優先**,故表格等顯式場景 inert
 *   2. 有效 disabled(prop 或 `<Field disabled>`)→ 'disabled'(完整 disabled chrome)
 *   3. FieldContext.mode(`<Field mode="display"/"readonly">`)→ 讓 mode cascade 真正生效
 *   4. 本地 readOnly → 'readonly'
 *   5. 'edit'
 * cell:mode prop 必有 → step 1 命中、fieldCtx=null → 完全 inert(Δ=0)。`disabled` 傳已 resolve 的 boolean 或未預設 prop。
 */
export declare function useResolvedFieldMode({ mode, disabled, readOnly, }: {
    mode?: FieldMode | null;
    disabled?: boolean | null;
    readOnly?: boolean;
}): FieldMode;
/**
 * Resolve Field control 的 **variant**(default / bare / naked 視覺外殼)— 2026-06-08 SSOT。
 * 優先序:顯式 prop > FieldContext.variant > 'default'。與既有各控件公式一字不差(Δ=0),統一以利 gate 強制。
 */
export declare function useResolvedFieldVariant(variantProp?: FieldVariant | null): FieldVariant;
/**
 * Resolve Field control 的 **error/invalid** — 取代散落的 `errorProp || (fieldCtx?.invalid ?? false)`(2026-06-08 SSOT)。
 * 自身 error prop **或** FieldContext.invalid(`<Field invalid>`)任一為真即 error。與既有公式一致(Δ=0)。
 */
export declare function useResolvedFieldInvalid(errorProp?: boolean): boolean;
/**
 * Host(non-Field-wrapper,如 DataTable cell)注 surface density size 給 child Field controls。
 * 僅注 size 視覺訊號,不污染 FieldContext。Usage:cell-registry buildCellWithSurface。
 */
export declare function FieldSurfaceSizeProvider({ size, children, }: {
    size: FieldSize;
    children: React.ReactNode;
}): React.ReactElement;
//# sourceMappingURL=field-context.d.ts.map