import * as React from 'react';
import type { FieldMode, FieldVariant } from '../../components/Field/field-types';
import { type SelectMenuOption } from '../../components/SelectMenu/select-menu';
/**
 * Combobox option schema(2026-05-10 post-Issue-4 audit unify):**explicit extends
 * SelectMenuOption(primitive SSOT)** — 避免重蹈先前 PeoplePicker 改壞的 wrapper schema drift。
 *
 * Why `extends SelectMenuOption`(per user 「全盤檢查避免下次又改壞或是偏移」要求):
 *   原 `interface ComboboxOption { value: string; label: string }` 是 weak schema,跟 Select 的
 *   `ComboboxOption`(同名)雙重宣告但欄位不同 → TypeScript 不抓(同名 interface 在不同 file
 *   各 export,consumer import 到哪個版本看 import path)→ schema drift。
 *   PeoplePicker multi-mode 走 Combobox 路徑,dropdown menu rows lose avatar / description —
 *   user 看到「single mode 有 avatar / multi mode 沒 avatar」inconsistency。
 *
 * Fix(post-Issue-4 follow-up):extend SelectMenuOption → 全 primitive surface 自動繼承。
 * Wrapper-only field 都沒有 → empty body interface(future 加 wrapper-only field 加在此處)。
 * `menuOptions` mapping(below)forward 全 SelectMenuOption surface。
 *
 * 對齊 Polaris ChoiceList / Material Autocomplete / Carbon Dropdown 的 wrapper-vs-primitive
 * schema-extension idiom。Hook `check_wrapper_primitive_schema_drift.sh`(M30 機械強制)。
 */
export interface ComboboxOption extends SelectMenuOption {
}
type ComboboxOverflowShape = 'circle' | 'tag';
export interface ComboboxProps {
    mode?: FieldMode;
    /** Field chrome variant. Default = context.variant ?? 'default'. Per-prop override. */
    variant?: FieldVariant;
    error?: boolean;
    size?: 'sm' | 'md' | 'lg';
    options: ComboboxOption[];
    value?: string[];
    onChange?: (value: string[]) => void;
    placeholder?: string;
    className?: string;
    disabled?: boolean;
    wrap?: boolean;
    clearable?: boolean;
    /** 啟用搜尋 */
    searchable?: boolean;
    /** Loading state(2026-05-15 audit B fix per user verbatim「dropdown 隨時可開,讀取在 panel 中間 CircularProgress」)。
     *  Forward 給 SelectMenu primitive SSOT;dropdown 開啟時取代 options 顯 CircularProgress + loadingText。
     *  Trigger 不變(user 隨時可開)。對齊 MUI Autocomplete `loadingText` + Field SSOT + Empty 元件 compose。*/
    loading?: boolean;
    /** 搜尋框位置：menu（浮層內，預設）或 trigger（inline input） */
    searchIn?: 'menu' | 'trigger';
    /** 搜尋框 placeholder（未有選項時顯示)。Default: 「搜尋…」 */
    searchPlaceholder?: string;
    /** 搜尋框 ARIA label。Default: 「搜尋選項」 */
    searchAriaLabel?: string;
    /** Empty-selection placeholder text。Default: 「選擇…」 */
    emptyPlaceholder?: string;
    /** a11y:無 Field wrapper 時提供 role='combobox' 的 accessible name(axe aria-input-field-name) */
    'aria-label'?: string;
    /** Initial open state(uncontrolled)— 對齊 Select.defaultOpen / Radix Popover canonical。
     *  DataTable cell-as-input 1-step open 用 */
    defaultOpen?: boolean;
    /** open state 變更 callback。DataTable cell-as-input 用:open=false → cell exit edit */
    onOpenChange?: (open: boolean) => void;
    /**
     * Selected tag pill 客製 render(2026-05-07 v15.5)。
     *
     * 設了 → 每個 selected tag pill 走 consumer 提供的 ReactNode(收 item={value, label}
     * + onRemove,consumer 自己組 onRemove);沒設 → 走預設 `<Tag>` text-only pill。
     *
     * 用例:PeoplePicker(multi)用此 slot 把 selected tag 換成 avatar + name pill,而非
     * 純文字 Tag。對齊 PeoplePicker = Combobox wrapper SSOT。
     */
    tagRenderer?: (item: {
        value: string;
        label: string;
    }, onRemove: () => void) => React.ReactNode;
    /**
     * 2026-05-14 I4 fix:Optional renderer for hidden items in `+N` overflow popover
     * (對齊 display MultiPersonDisplay overflow popover 含 avatar SSOT)。PeoplePicker stack
     * pass 此 prop 讓 hidden items 顯 avatar + name(同 display path)。Default fallback
     * `<Tag>{label}</Tag>` 純文字 backward-compat。
     */
    renderHiddenTag?: (item: {
        value: string;
        label: string;
    }) => React.ReactNode;
    /**
     * @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer hook)。
     *
     * Optional class merged into each tag's outer measurement wrapper (2026-05-07 v15.13)。
     * Stack avatar 模式用此 hook point 達成 sibling-level overlap (`-ml-0.5`) + group selector
     * (`group/avatar`)— 既保留 Combobox 必要 measurement wrapper,又讓 dismiss/overlap 視覺生效。
     */
    tagWrapperClassName?: string;
    /** @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer hook)。
     *  2026-05-16:overflow chip wrapper 套此 class(對齊 tagWrapperClassName)。Stack 模式
     *  pass `-ml-0.5 first:ml-0` 讓 chip 跟 avatar 同 overlap step,物理上 chip = 1 個 slot 不
     *  外加 24px。Default undefined = chip 不 overlap(text-tag mode 等)。*/
    overflowWrapperClassName?: string;
    /**
     * Tag area gap in px (2026-05-07 v15.13)。預設 4(pill mode 標準 spacing)。
     * Stack avatar 模式傳 0,讓 `tagWrapperClassName` 的 `-ml-0.5` negative margin 生效
     * (CSS `gap` 套在 flex container 上會強制 sibling spacing,蓋過 negative margin)。
     * **Q2 known tradeoff**:0 後 useOverflowCount 仍按 wrapper.offsetWidth 累加(不含 overlap
     * 補償)→ +N 偏保守。當前接受;若需精準可 future 加 `overlapPx` 補償邏輯。
     *
     * @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer hook)。
     */
    tagAreaGapPx?: number;
    /**
     * tagAreaRef container 左 paddingLeft(px,2026-05-12 加,for PeoplePicker Avatar inset)。
     * Default undefined = no extra padding(Field wrapper `tagPadding[size]` calc 公式自然 inset)。
     * 設值時 tagAreaRef 增 `style.paddingLeft`,**useOverflowCount 的 `available = clientWidth -
     * paddingLeft - paddingRight` 自動 include**(`parseFloat(cs.paddingLeft)` 從 container CSS 抓)
     * → width calc 不漂移,無 side-effect。
     *
     * @internal PeoplePicker stack wrapper 內部協議 — 目前無 active consumer(PeoplePicker 傳 undefined),保留供未來精準 padding;新 consumer 請先評估。
     *
     * **2026-05-13 v2 deprecate path**:原 PeoplePicker pass `{8}` 假設「Combobox tagPadding=4px,4+8=12」
     * 但 `tagPadding[size]` 是 density-dependent calc `(field-height - icon-size) / 2`,只在 md size +
     * default density 才 = 4px;其他 size/density 漂 6/8px → 4+8=12 公式破。改 PeoplePicker 直接 inject
     * `!px-3` className 到 Combobox Field wrapper(per people-picker.spec.md:94 v2),`tagAreaPaddingLeftPx`
     * 走 undefined。Future 仍保留此 prop 給其他 consumer 精準調整 padding,但 PeoplePicker 已不再用。
     */
    tagAreaPaddingLeftPx?: number;
    /**
     * Overflow indicator (+N) 形狀(2026-05-12 Round 7,opt-in 給 avatar stack consumer):
     * - `'tag'`(default)— 矩形 chip(Combobox 文字 tag default)
     * - `'circle'`(opt-in)— 圓形 avatar-shape(PeoplePicker stack 用)
     */
    overflowShape?: ComboboxOverflowShape;
    /**
     * @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer override)。
     *
     * 2026-05-15 Bug 3 fix:override visible count via formula-based primitive(opt-in;default 走
     * DOM-based `useOverflowCount`)。PeoplePicker stack mode 用 `avatar-stack-overflow` primitive
     * deterministic formula 計算 visible count,forward 給 Combobox bypass DOM offsetWidth
     * measurement,避免 dual-algorithm drift。對齊 user SSOT「同 cell width 同 overflow 判斷」。
     */
    visibleCountOverride?: number;
    /**
     * Display 是否渲 ChevronDown + Field naked wrapper(D-path opt-in,2026-05-08)
     * — DataTable cell display↔edit 像素級對齊用。預設 false(裸 tag stack,backward compat)。
     * 設 true 時 display 走 fieldWrapperStyles(naked variant)+ ItemSuffix ChevronDown,
     * 與 edit 同 DOM 結構,消除 Layer-B padding mismatch。
     */
    showDisplayEndIcon?: boolean;
}
declare const Combobox: React.ForwardRefExoticComponent<ComboboxProps & React.RefAttributes<HTMLDivElement>>;
export declare const comboboxMeta: {
    readonly component: "Combobox";
    readonly family: 4;
    readonly variants: {};
    readonly sizes: {};
    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
    readonly tokens: {
        readonly bg: readonly ["bg-disabled", "bg-transparent"];
        readonly fg: readonly ["text-fg-disabled", "text-fg-muted"];
        readonly ring: readonly [];
    };
};
export { Combobox };
//# sourceMappingURL=combobox.d.ts.map