import * as React from "react";
import type { LucideIcon } from "lucide-react";
import { type AvatarProps } from "../../components/Avatar/avatar";
export interface InlineActionConfig {
    icon: LucideIcon;
    /** aria-label,同時作為 tooltip 來源 */
    label: string;
    /**
     * 點擊 handler。可選接收 React 事件物件——有需要時可呼叫 `stopPropagation()` 避免
     * 事件冒泡到父層(例如 Select 清除按鈕在 popover trigger 內,不想觸發 popover open)。
     */
    onClick: (e?: React.MouseEvent<HTMLButtonElement>) => void;
}
/**
 * Item Layout — 共用工具與常數
 *
 * 這個檔案不是元件,是 `item-anatomy.spec.md` 的 code-level 實作。
 * 所有 row primitives(`MenuItem` / `TreeItem` / `SidebarMenuButton` /
 * `SelectionItem`)**必須 import 本 module 的 ICON_SIZE 和 helpers**,
 * 不要各自複製常數或 wrapper className——單一 source of truth,避免不一致。
 *
 * 詳細規則見 `item-anatomy.spec.md`。
 */
/** Row primitive 的 size 變體,對齊 `--field-height-*` token family */
export type RowSize = "sm" | "md" | "lg";
/**
 * Icon 尺寸(px)per row size。
 *
 * - sm / md: 16px(標準 row icon)
 * - lg: 20px(對齊 text-body-lg 的視覺重量)
 *
 * **用法**:透過 Lucide icon 的 `size` prop 直接傳入,不要用 CSS `[&>svg]:size-*`
 * selector——當 icon 被包在 `<ItemPrefix>` 的 `h-[1lh]` wrapper 內時,
 * `>` 直接子選擇器會失效,Lucide icon 會 fallback 到預設 24px。
 *
 * ```tsx
 * import { ICON_SIZE } from "../../patterns/element-anatomy/item-anatomy"
 *
 * const iconPx = ICON_SIZE[size]  // size: RowSize
 * <MyLucideIcon size={iconPx} />
 * ```
 */
export declare const ICON_SIZE: Record<RowSize, number>;
/**
 * Avatar 尺寸(px)per row size,分 inline / block 兩種模式。
 *
 * - **inline**(無 description,大宗情境)→ 對齊第一行 label,用 `h-[1lh]` 容器
 *   sm: 20, md: 24, lg: 24
 * - **block**(有 description,avatar 跨越 label + desc 兩行)→ 對齊文字塊中心
 *   sm: 32, md: 32, lg: 40
 *
 * **用法**:所有 row primitive 的 consumer(包含 `asChild` pattern 的 Sidebar / Tree
 * consumer)**必須**從本 module import 這個常數,**不可硬寫 `size={24}`**。
 * 硬寫會讓 sm 變體的 avatar 尺寸錯誤、跟 ICON_SIZE 對齊規則脫鉤。
 *
 * ```tsx
 * import { AVATAR_SIZE } from "../../patterns/element-anatomy/item-anatomy"
 *
 * const { size } = useSidebar()  // RowSize
 * <Avatar size={AVATAR_SIZE.inline[size]} />
 * ```
 *
 * Canonical 實作:`MenuItem` 的內部 `AVATAR_SIZE` 查表(即將 re-export 自此)。
 */
export declare const AVATAR_SIZE: {
    readonly inline: {
        readonly sm: 20;
        readonly md: 24;
        readonly lg: 24;
    };
    readonly block: {
        readonly sm: 32;
        readonly md: 32;
        readonly lg: 40;
    };
};
/**
 * 回傳 uniform prefix slot 的 inline style(CSS variable form)。
 *
 * 用法:Row-primitive 頂層容器(例如 `<SidebarProvider uniformPrefix>` 的 wrapper)
 * 把這個 style 套在 `style` prop 上(預先放在 `--mixed-prefix-slot` 候選位置,
 * 由外層 CSS `:has()` 條件化套到 `--item-prefix-slot`),子樹內所有 `<ItemPrefix>` /
 * `<ItemIcon>` / `<ItemAvatar>` 會自動用固定寬槽對齊。
 *
 * 槽寬 = `AVATAR_SIZE.inline[size]`(20/24/24 @ sm/md/lg)——以最大的 inline
 * prefix(avatar)為基準,icon 在槽內 `justify-center`。
 *
 * ```tsx
 * <ul style={getUniformPrefixSlotStyle(size)}>
 *   <ItemIcon icon={Folder} />      ← 16px icon 在 24px 槽內置中
 *   <ItemAvatar alt="GitHub" />     ← 24px logo 填滿槽
 * </ul>
 * ```
 */
export declare function getUniformPrefixSlotStyle(size: RowSize): React.CSSProperties;
/**
 * Inline action(suffix 裡的 hover-action icon button)hover 背景尺寸(px)。
 * 規則:icon size + 2px(每邊 +1px,用 absolute positioning 溢出不影響排版)。
 * 對齊 `item-anatomy.spec.md`「Inline Action 設計規格」節。
 */
export declare const INLINE_ACTION_HOVER_BG_SIZE: Record<RowSize, number>;
/**
 * `ROW_PADDING_BY_SIZE` — Family 1+2 row primitive 的 size → padding + typography 公式 SSOT
 *
 * Formula(canonical):`py = (field-height - 1lh) / 2`,對齊 1em text 到 field-height center。
 *
 * **消費者**:menuItemVariants / sidebarMenuButtonVariants / treeItemVariants / 未來 row primitive
 * **Rationale**:前先 3 cva 各自寫同一公式 → drift risk(item-anatomy.spec 有明文「SidebarMenuButton
 * 獨立實作風險」)。抽本 export 後改**一處全同步**,risk 消失(對齊 Meta-Pattern M17「SSOT 必可傳播」)。
 *
 * 2026-04-24 D Phase 1+2 consolidation 建立。
 */
export declare const ROW_PADDING_BY_SIZE: Record<RowSize, string>;
/**
 * `<ItemPrefix>` — Row primitive 的 prefix slot wrapper。
 *
 * 把 prefix(icon / avatar / checkbox / indicator)包進 `h-[1lh]` 容器,
 * 強制對齊第一行文字中線。這是 item-layout 的底層規則(詳見 spec「Prefix 垂直對齊」)。
 *
 * **為什麼**:
 * - Row primitive 的 outer flex 是 `items-start`(多行 label 時 prefix 不飄移)
 * - 單行時 prefix 透過這個 wrapper 強制對齊第一行中線,視覺效果 = `items-center`
 * - 不同尺寸的 prefix(icon 16、Avatar 24、Checkbox 20)都能穩定置中
 *
 * 用法:
 * ```tsx
 * <div className="flex items-start gap-2">
 *   <ItemPrefix>
 *     <Avatar size={24} />
 *   </ItemPrefix>
 *   <span className="min-w-0 flex-1 truncate">{label}</span>
 * </div>
 * ```
 *
 * asChild 的 consumer(例如 `<SidebarMenuButton asChild>`)**必須自己**用這個 wrapper
 * 包 prefix,不能省略。
 */
export declare const ItemPrefix: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLSpanElement> & React.RefAttributes<HTMLSpanElement>>;
/**
 * `itemPrefixAlignVariants` — Prefix 對齊高度的 cva SSOT(for 複雜 prefix 結構)。
 *
 * ── 存在的理由 ──
 * `<ItemPrefix>` primitive 預設單一 child(icon / avatar 任一)+ inline 對齊。
 * 但**複雜 prefix 結構**(e.g. MenuItem 可同時含 checkbox + icon/avatar 多 child)
 * 或**block mode**(大 prefix + description 對齊塊中心)需要自建 wrapper cva。
 * 本 cva 把 block formula SSOT 化,讓 MenuItem 等 consumer 共用,
 * 改值一處(token or cva)→ 所有 block-prefix consumer 同步。
 *
 * ── Align 變體(對齊 item-anatomy.spec.md「24px 閾值對齊規則」) ──
 * - `"inline"`:`h-[1lh]`,小 prefix(≤ 24px)對齊 label 第一行
 * - `"block-sm"` / `"block-md"`:大 prefix + scanning desc(sm/md menu),
 *   高度 = label(1lh) + gap(token) + desc(caption × 1.3)
 * - `"block-lg"`:大 prefix + scanning desc(lg menu),desc 改為 body × 1.3
 *
 * ── Consumer ──
 * MenuItem(inline / block-sm / block-md / block-lg)。其他 row primitive 簡單情境
 * 直接用 `<ItemPrefix>` 就好,不需此 cva。
 *
 * ── SSOT 傳播 ──
 * gap 用 `var(--item-gap-label-desc)` token;font-size 用 token-awareness
 * (`var(--font-caption-size)` / `var(--font-body-size)`)。改 token → 公式同步。
 */
export declare const itemPrefixAlignVariants: (props?: ({
    align?: "inline" | "block-sm" | "block-md" | "block-lg" | null | undefined;
} & import("class-variance-authority/types").ClassProp) | undefined) => string;
/**
 * `<ItemLabel>` — Row primitive 的 label span。
 *
 * 預設 `min-w-0 flex-1 truncate`——單行截斷,佔滿剩餘 flex 空間。
 * 加 `data-sidebar="menu-label"` attribute 讓 sidebar icon 模式的 CSS selector 能命中。
 *
 * 用法:
 * ```tsx
 * <ItemLabel>{label}</ItemLabel>
 * ```
 */
export declare const ItemLabel: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLSpanElement> & React.RefAttributes<HTMLSpanElement>>;
/**
 * `<ItemContent>` — Row primitive 的 label + optional description 內容區(SSOT)。
 *
 * ── 存在的唯一理由 ──
 * 封裝「flex-col + label + description + `mt-[var(--item-gap-label-desc)]` gap」結構,
 * 避免 13+ 消費者各自 hard-code `mt-0.5`。改 token 一處,全 DS 同步。
 *
 * ── Consumer 偏離 canonical ──
 * 消費端若有**確切合理理由**不用 `<ItemContent>` / 需自訂 label/desc 行為,必在
 * 該元件 `spec.md` 明文寫下 rationale(對齊 item-anatomy canonical「偏離必明文」)。
 * 合法偏離範例:
 *   - MenuItem 的 `leading-compact + text-caption` scanning-mode typography
 *     → MenuItem spec 明文 rationale + 消費 `--item-gap-label-desc` token 直接用
 *   - SelectionItem 的 control slot 跟 block formula 綁定
 *     → SelectionItem spec 明文 rationale
 *
 * ── Props ──
 * - `label`:label 內容(ReactNode,必填)
 * - `description`:description 內容(ReactNode,optional)
 * - `mode`:typography tier(scanning vs reading,世界級對齊 Material `dense` / Carbon `size` / Ant `size`)
 *   - `"reading"`(預設):繼承 parent `text-body`(14px / 1.5 leading),舒適閱讀(Family 2 / Material body-large 派)
 *   - `"scanning"`:desc 縮為 `text-caption`(12px)+ `leading-compact`(1.3),緊湊掃視
 *     (Family 1 Menu item / Material body-medium dense 派)
 * - `descriptionTone`:desc 顏色語意
 *   - `"secondary"`(預設):`text-fg-secondary`
 *   - `"error"`:`text-error-text`
 *   - `"muted"`:`text-fg-muted`
 *   - `"disabled"`:`text-fg-disabled`(對齊 M24 state precedence:disabled > muted > emphasis)
 * - `descriptionWrap`:desc 多行 wrap(預設 true)/ false = truncate
 * - `labelClassName` / `descriptionClassName`:escape hatches(明文 rationale 才用)
 *
 * ── World-class benchmark ──
 * 6 家 DS(Material / Polaris / Atlassian / Apple HIG / Carbon / Ant)一致用
 * 14/20 vs 16/24 兩擋 body 表達 scanning vs reading。API 兩派:(A)密度 prop
 * Material `dense` / Carbon `size` / Ant `size`(本 DS 採 A 派);(B)typography
 * token 手選 Polaris / Atlassian / Apple。
 */
export interface ItemContentProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
    label: React.ReactNode;
    description?: React.ReactNode;
    /**
     * Typography mode — **leading 行為**(跟 size 正交的另一維):
     * - `"reading"`(預設):default leading(1.5)— Family 2 List item 舒適閱讀
     * - `"scanning"`:`leading-compact`(1.3)+ desc 降一 tier —— Menu item / Step 掃視
     */
    mode?: "reading" | "scanning";
    /**
     * Size tier — **label 字級**(跟 mode 正交的另一維):
     * - `"md"`(預設):label `text-body`(14)
     * - `"lg"`:label `text-body-lg`(16)— desc 永遠比 label 小一 tier(body)
     *
     * 2 × 2 = 4 typography 組合,對應 4 tokens:
     * - md + reading  → body(14/1.5) + body(14/1.5)
     * - md + scanning → body(14/1.3) + caption(12/1.3)
     * - lg + reading  → body-lg(16/1.5) + body(14/1.5)
     * - lg + scanning → body-lg(16/1.3) + body(14/1.3)
     */
    size?: "md" | "lg";
    descriptionTone?: "secondary" | "error" | "muted" | "disabled";
    descriptionWrap?: boolean;
    /**
     * Description 多行截斷(line-clamp-N)。undefined = 不 clamp(自由 wrap)。
     * Tailwind line-clamp utilities 支援 1-6。
     */
    descriptionClamp?: number;
    /**
     * Description `break-words`(default `false`,僅在 consumer 需要時 opt-in)。
     * 使用情境:SelectionItem / Steps 這類 description 可能塞長英文 token 需 break。
     */
    descriptionBreakWords?: boolean;
    /**
     * Label truncate (default `true`, 對齊 row-item 大宗 idiom)。
     * Opt-out(`false`)for card-like consumers(e.g. ProfileCard label 允許 wrap)。
     * World-class 對照:Material `ListItemText primaryTypographyProps.noWrap` default true。
     */
    labelTruncate?: boolean;
    labelClassName?: string;
    descriptionClassName?: string;
}
export declare const ItemContent: React.ForwardRefExoticComponent<ItemContentProps & React.RefAttributes<HTMLDivElement>>;
/** @internal — L3 row-size primitive;app code 不直接 import,由 MenuItem/Row/Field 等內部消費(inline-action.spec.md)。 */
export declare const RowSizeProvider: React.Provider<RowSize | null>;
/**
 * 讀取當前 row size。在 row primitive 子樹外呼叫會回 fallback(預設 "md")。
 * Row primitive 實作者不該呼叫這個——你們已經知道自己的 size。
 * 這個 hook 是給 `<ItemIcon>` / `<ItemAvatar>` 和 asChild consumer 的逃生艙用。
 */
export declare function useRowSize(fallback?: RowSize): RowSize;
export interface ItemIconProps extends Omit<React.SVGAttributes<SVGSVGElement>, "children"> {
    /** Lucide icon 元件(不是 JSX element) */
    icon: LucideIcon;
}
/**
 * `<ItemIcon icon={Folder} />` — 自動查 `ICON_SIZE[rowSize]`,包在 `ItemPrefix` 內。
 * 永遠對齊第一行 label(item-layout 的 icon 永遠 inline)。
 */
export declare const ItemIcon: React.ForwardRefExoticComponent<ItemIconProps & React.RefAttributes<SVGSVGElement>>;
export interface ItemAvatarProps extends Omit<AvatarProps, "size"> {
    /**
     * 對齊模式(選填,預設 `"inline"`):
     * - `"inline"`:視覺重量輕的 avatar,對齊第一行 label(20/24/24 @ sm/md/lg)
     * - `"block"`:視覺重量重的 avatar,對齊 label + description 文字塊(32/32/40 @ sm/md/lg)
     *
     * 預設 inline——大宗情境(扁平 row、footer user、主清單)都用這個。
     * 只有 avatar 是 item 主體(人物卡、顯著身份辨識)才用 block。
     *
     * 詳見 `item-anatomy.spec.md`「Avatar 尺寸選擇」節,含 24px 對齊模式閾值規則。
     */
    mode?: "inline" | "block";
}
/**
 * `<ItemAvatar alt="Alan" color="blue" />` — 自動查 `AVATAR_SIZE[mode][rowSize]`,
 * 包在 `ItemPrefix` 內。
 *
 * asChild consumer 的標準用法——不需知道 size,不需 import AVATAR_SIZE,
 * 不可能硬寫錯誤尺寸。
 */
export declare const ItemAvatar: React.ForwardRefExoticComponent<ItemAvatarProps & React.RefAttributes<HTMLDivElement>>;
export interface ItemInlineActionButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
    /** Lucide icon 元件 */
    icon: LucideIcon;
    /** 可選:額外加在 icon 上的 className(例如 rotate transition) */
    iconClassName?: string;
    /**
     * Size 明確覆寫(用於 fields / Tag 等**不在 `RowSizeProvider` 樹內**的 host):
     * 傳了就以此為準,否則從 `RowSizeContext` 讀(fallback "md")。
     *
     * 使用時機:
     * - Row primitive 子樹(Sidebar / TreeView / SelectMenu / DropdownMenu)→ **不傳**,吃 context
     * - Field / Tag(自有 size 系統,沒包 RowSizeProvider)→ **必傳** `size={hostSize}`
     */
    size?: RowSize;
    /**
     * Hover / active bg className override(chromatic host 專用,如 Tag solid variant)。
     *
     * 預設 `group-hover/action:bg-neutral-hover group-active/action:bg-neutral-active`。
     * 提供後**完全取代** hover + active 雙態 className,但**不影響** rest 態(永遠 bg-transparent)
     * 與 overlay-trigger 態(`group-data-[state=open]/action:bg-neutral-hover` — 維持 host hover bg)。
     *
     * Consumer 須**同時**包含 hover + active 兩態 selector,例:
     * `'group-hover/action:bg-[var(--my-hover)] group-active/action:bg-[var(--my-active)]'`
     *
     * Use case:Tag solid(blue/green/red 等)需 hover bg 跟 host 色相一致(非 neutral)。
     */
    hoverBgClassName?: string;
    /**
     * 標記本 button 是 **overlay trigger**(DropdownMenu / Popover / Tooltip 透過 `asChild` 包覆)。
     *
     * `true` 時:Radix overlay open 期間(`data-state="open"`)button 維持 host hover 樣式
     * — 視覺鎖,讓 user 追溯 floating panel 來源(對齊 shadcn / Radix Themes / Material)。
     *
     * `false` 時(default):無 data-state=open 樣式 — 適用 in-place 互動如 `Collapsible.Trigger`
     * (展開內容接在 trigger 下方,不需追溯)、drag handle、dismiss X 等。
     *
     * Canonical 詳 `inline-action.spec.md`「Overlay trigger canonical」段。
     *
     * @default false
     */
    overlayTrigger?: boolean;
}
/** @internal — L3 inline-action primitive;app code 禁直接 import,經 MenuItem/Row endActions 消費(inline-action.spec.md)。 */
export declare const ItemInlineActionButton: React.ForwardRefExoticComponent<ItemInlineActionButtonProps & React.RefAttributes<HTMLButtonElement>>;
export interface ItemInlineActionProps {
    action: InlineActionConfig;
    /** Size 覆寫(見 `ItemInlineActionButtonProps.size`)——Field Controls / Tag 必傳 */
    size?: RowSize;
}
/** @internal — L3 inline-action primitive;app code 禁直接 import,經 row 元件消費(inline-action.spec.md)。 */
export declare const ItemInlineAction: React.ForwardRefExoticComponent<ItemInlineActionProps & React.RefAttributes<HTMLButtonElement>>;
declare const SUFFIX_HOVER_REVEAL_BY_GROUP: {
    readonly "menu-item": "opacity-0 group-hover/menu-item:opacity-100 group-has-[:focus-visible]/menu-item:opacity-100 transition-opacity duration-150";
    readonly "tree-item": "opacity-0 group-hover/tree-item:opacity-100 group-has-[:focus-visible]/tree-item:opacity-100 transition-opacity duration-150";
    readonly row: "opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100 transition-opacity duration-150";
};
export type ItemSuffixHoverGroup = keyof typeof SUFFIX_HOVER_REVEAL_BY_GROUP;
export interface ItemSuffixProps extends React.HTMLAttributes<HTMLSpanElement> {
    /**
     * Hover-reveal:預設隱藏,父層 row hover / keyboard focus-visible 時才淡入。
     * 對齊 TreeView / SidebarMenuButton inline action 行為。預設 false(永遠顯示,如 Badge)。
     *
     * 用 `group-has-[:focus-visible]` 而非 `group-focus-within`——後者會被 mouse click 觸發,
     * 導致 click 後 suffix 永久顯示直到焦點移走。focus-visible 只在鍵盤 tab 時啟動。
     */
    hoverReveal?: boolean;
    /**
     * 父層 row 的 group selector(consumer 必加 `group/<name>` 到 row wrapper)。
     * 預設 `'menu-item'`(對齊 MenuItem / Sidebar)。其他 row primitive:
     * `'tree-item'`(TreeView)/ `'row'`(DataTable / FileItem)。
     *
     * 加新 row primitive(且需 hover-reveal)時:在 `SUFFIX_HOVER_REVEAL_BY_GROUP`
     * 加 entry,Tailwind JIT 才能 scan 到 static class。
     */
    hoverGroup?: ItemSuffixHoverGroup;
}
export declare const ItemSuffix: React.ForwardRefExoticComponent<ItemSuffixProps & React.RefAttributes<HTMLSpanElement>>;
export {};
//# sourceMappingURL=item-anatomy.d.ts.map