import * as React from 'react';
/**
 * Coachmark — 功能介紹 / onboarding tour 的浮層卡片
 *
 * 世界級對照:Apple HIG「Coachmark」(Apple 命名原處)/ Material「Feature Discovery」/
 * Ant Design `<Tour>` / Shepherd.js / react-joyride / Intercom Product Tours。
 *
 * 本元件 = **Popover 的 composition pattern**,consume 相同 overlay-surface SSOT:
 *   - Header(可選,多步驟建議傳 `kind="tips" | "new-features" | 自訂 title`,
 *     single-step 預設無 header 避免視覺過重)
 *   - Media 區(圖 / 截圖 / illustration,full-width 邊緣對齊,由 AspectRatio 管比例)
 *   - Body(SurfaceBody padding):title + description 左對齊
 *   - Footer(SurfaceFooter padding,但 justify-between):step 計數左 / actions 右
 *
 * ── 單 vs 多步驟 canonical(世界級行為規則) ──
 *   1. **Single step**(無 `onPrev` 且 `isLastStep`):CTA 文字 = `doneLabel ?? '知道了'`
 *      (Apple HIG / Intercom 慣例;不用 "Next" 因為沒有下一步)
 *   2. **Multi step 第一步**(無 `onPrev`,有 `onNext`):CTA = "Next",Skip 顯示
 *   3. **Multi step 中間 / 最後步**(有 `onPrev`):**Skip 不顯示**(使用者已投入進度,
 *      再給 Skip 會讓「放棄」入口與「回上一步」衝突 — Linear / Pendo / Shepherd.js
 *      同樣規則)。CTA = `isLastStep ? 'Done' : 'Next'`
 *   4. **抑制開啟時的自動 focus** — `onOpenAutoFocus` preventDefault,連 Radix 預設
 *      focus 第一個 focusable 也一併抑制(焦點停在 trigger),避免使用者還在讀 body 時
 *      按 Enter 誤推進。想推進者自行 tab 到 CTA 再 Enter(對齊 spec「A11y 預設」)。
 *
 * ── 為什麼 Body+Footer 消費 overlay-surface ──
 * 避免 padding token 漂移:Dialog / Popover / Coachmark 三者共用同一套 Header/Body/Footer
 * padding(px-loose / py-tight),改 Dialog 就三邊自動跟進。
 */
interface CoachmarkStep {
    current: number;
    total: number;
}
export interface CoachmarkProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children' | 'title'> {
    /** 控制顯示(controlled mode)*/
    open?: boolean;
    /** 預設打開(uncontrolled initial state)— 2026-05-15 audit Dim 26 V1 fix per user verbatim「A:1」approval */
    defaultOpen?: boolean;
    onOpenChange?: (open: boolean) => void;
    /** 觸發 anchor 元素。通常傳 trigger element;Coachmark 浮層會定位於此 */
    children: React.ReactNode;
    /** 頂部 media 區(圖片 / illustration / video 等);不傳則無 media */
    image?: React.ReactNode;
    /**
     * Media 區域的長寬比(ratio = 寬 / 高)。預設 `16/9`(onboarding feature tour
     * 世界級 convention — Intercom / Pendo / Shepherd.js)。其他常用:`4/3` 產品截圖 /
     * `1/1` 方圖 / `3/4` 直式 portrait。消費獨立的 `AspectRatio` primitive 元件。
     */
    mediaRatio?: number;
    /**
     * 頂部 header 類型(多步驟 tour 建議傳)。
     * - `'tips'` → header title = "使用技巧"
     * - `'new-features'` → header title = "新功能介紹"
     * - `ReactNode` → 自訂 title(string / JSX)
     * - undefined → 無 header(單步驟常用)
     */
    kind?: 'tips' | 'new-features' | React.ReactNode;
    /** 標題(bold) */
    title?: React.ReactNode;
    /** 說明文字(normal weight,多行 OK) */
    description?: React.ReactNode;
    /** 步驟計數(2 of 3);若需多步導覽 consumer 自行管理 current */
    step?: CoachmarkStep;
    /** Skip 按鈕 callback;不傳則不顯示 Skip。多步驟中間 / 最後步自動隱藏(有 onPrev 時) */
    onSkip?: () => void;
    /** Next 按鈕 callback;不傳則不顯示 Next */
    onNext?: () => void;
    /** Previous 按鈕 callback(多步 tour 第 2+ 步顯示);不傳則不顯示 */
    onPrev?: () => void;
    /**
     * 最後一步 flag。影響 primary CTA 文字:
     * - single step(無 onPrev 且 isLastStep):CTA = `doneLabel ?? '知道了'`
     * - multi-step 最後步(有 onPrev 且 isLastStep):CTA = 'Done'
     * - 其他:CTA = 'Next'
     */
    isLastStep?: boolean;
    /** 自訂單步驟完成 CTA 文字(預設 `'知道了'`)。僅 single-step 使用 */
    doneLabel?: string;
    /** 浮層定位(對齊 Popover props) */
    side?: 'top' | 'right' | 'bottom' | 'left';
    align?: 'start' | 'center' | 'end';
    sideOffset?: number;
    /** 外殼寬度(預設 w-80 = 320px,比一般 Popover 寬,因要放 media + 文字) */
    className?: string;
}
declare const Coachmark: React.ForwardRefExoticComponent<CoachmarkProps & React.RefAttributes<HTMLDivElement>>;
export declare const coachmarkMeta: {
    readonly component: "Coachmark";
    readonly family: null;
    readonly variants: {};
    readonly sizes: {};
    readonly states: readonly ["default"];
    readonly tokens: {
        readonly bg: readonly ["bg-muted"];
        readonly fg: readonly ["text-fg-secondary", "text-foreground"];
        readonly ring: readonly [];
    };
};
export { Coachmark };
//# sourceMappingURL=coachmark.d.ts.map