import { ArrowDefinition, BoundaryDefinition, ClipDefinition, CompiledNodeLayout, CompositeDefinition, IRAnimationTrack, IRScene, IRViewBox, LowerTex, PathGeneratorDefinition, PathKindDefinition, PatternDefinition, RibbonWidthProfileDefinition, ShapeDefinition } from '@retikz/core';
import { AnimationControls, AnimationPropertyRegistry, EasingRegistry } from '@retikz/render/animation';
import { HydrationHandlers } from '@retikz/render/hydration';
import { CSSProperties, FC, ReactNode, Ref } from 'react';
import { EmbeddableTier2Adapter, ScopeStyleProps } from '../protocol';
/**
 * @description 含 {@link ScopeStyleProps} 级联样式子集——设任一样式 prop 时把 children 包进合成根 `<Scope>`，
 *   等价于用户手写一层根 `<Scope>`（编译产物同一 IR）。内层 `<Scope>` / 图元显式属性照常级联覆盖。
 *   与直接传 `ir` prop 并用时样式 props 被忽略（dev 警告）
 */
export type LayoutProps = ScopeStyleProps & {
    /** 直接喂 IR JSON（持久化 / AI / 编辑器场景），与 children 二选一 */
    ir?: IRScene;
    /** Kernel/Sugar JSX children */
    children?: ReactNode;
    /**
     * `ir` prop 模式下按图元 id 提供的水合 handler 注册表（无 JSX children 可收集时用）
     * @description JSX 模式经组件 `on<Event>` props 收集，无需此 prop；直接传 `ir` 时无组件 props，
     *   改由此 prop 按 `{ [id]: { click, ... } }` 提供。两路结果经 `createHydrationController` 绑到 figure root
     *   （svg root 或 `<canvas>`），svg / canvas 双模共用同一注册表与分发
     */
    handlers?: HydrationHandlers;
    /** SVG 元素宽度（CSS 长度或数字） */
    width?: number | string;
    /** SVG 元素高度（CSS 长度或数字） */
    height?: number | string;
    /**
     * 显式视框 `{ x, y, width, height }`，覆盖自动算的范围（固定尺寸 / 裁剪 / 多图对齐）
     * @description 注入构造出的 IR 根（`ir.viewBox`）；设值时 `<svg viewBox>` 用它、忽略 padding。
     *   与直接传 `ir` prop 自带的 viewBox 冲突时，本 prop 优先；都缺省时回退自动 AABB
     */
    viewBox?: IRViewBox;
    /** 透传到 svg 元素的 className */
    className?: string;
    /** 透传到 svg 元素的内联样式 */
    style?: CSSProperties;
    /** 渲染目标；缺省为 SVG，设为 canvas 时用同一份图形数据绘制到 `<canvas>` */
    renderer?: 'svg' | 'canvas';
    /**
     * 是否播放动画；未传时跟随系统减少动态效果偏好，显式 `true` / `false` 强制开关
     * @description SVG 模式：`load` track 经内联 `<style>` CSS 自播、交互 track 经 WAAPI 桥按 trigger 驱动；
     *   `animate={false}` 走 settled 静态。显式 `true` 会覆盖 `prefers-reduced-motion`；祖先
     *   `AnimationModeProvider` 存在时由最近的 Provider 统一覆盖本属性
     */
    animate?: boolean;
    /**
     * 静态截帧时刻（毫秒）；给定时渲染「定格在该时刻」的静态图
     * @description SVG：各 track 在该时刻的值烘焙成静态属性 / transform；Canvas：按该时刻画一帧、不起 rAF。覆盖 `animate`
     */
    snapshotAt?: number;
    /**
     * 命令式动画句柄出口：传一个 ref，挂载后写入 `AnimationControls`（`play` / `pause` / `seek`）
     * @description 与 vanilla `view.animation` 对等——SVG 控制交互（`manual` / `visible` / `{onEvent}`）track 的 WAAPI
     *   句柄；Canvas 控制 rAF 时钟。无动画 / 降级时为 `null`。供组件外命令式控制（按钮播放 / 暂停 / 跳帧）
     */
    animationRef?: Ref<AnimationControls | null>;
    /**
     * 全图时间轴动画 tracks（如 `viewBox` 镜头动画）
     * @description 配 `cameraTo()` preset：`<Layout animations={[cameraTo({ from, to })]}>`。元素级动画写在各元素
     *   的 `animations` prop 上；与直接传 `ir` prop 并用时，本 prop 追加到整张图
     */
    animations?: Array<IRAnimationTrack>;
    /**
     * 自定义缓动注册表（兑现动画扩展口）：名 → cubic-bezier 四元组 / 缓动函数
     * @description preset / track 的 `easing` 写注册名（如 `fadeIn({ easing: 'spring' })`）即生效。cubic-bezier
     *   形式 SVG（CSS）+ Canvas 都支持；函数形式仅 Canvas（SVG 退 linear 并告警）
     */
    easings?: EasingRegistry;
    /**
     * 自定义动画属性通道插值器：通道名 → { interpolate, applyCanvas }
     * @description 让 `property` 用内置之外的名字（如 `blur`）。**当前仅 Canvas 生效**（`renderer="canvas"`）；
     *   SVG 无内置映射 → 告警并跳过该 track（渲染 base）
     */
    animationProperties?: AnimationPropertyRegistry;
    /**
     * SVG `<defs>` 资源 id 前缀，覆盖默认的 `useId()` 派生值
     * @description marker / paint / clip 的 id 与 `url(#...)` 引用共用此前缀确保多实例不撞。缺省使用 React 生成的稳定 id。
     *   SSR 到客户端水合需要 id 逐字一致时，服务端渲染和客户端 `<Layout idPrefix>` 传同一前缀即可对齐
     */
    idPrefix?: string;
    /**
     * 节点相对定位（`Node.position = { direction, of }`）的默认距离，单位 user units
     * @description 节点 position 自带 `distance` 时优先用自带值，都缺省时回退到 24
     */
    nodeDistance?: number;
    /**
     * 默认字号
     * @description 透传给 `CompileOptions.fontSize`；`font.size` 缺省时使用此值，同时作为 preset 与 rem 的根字号
     * @default DEFAULT_FONT_SIZE (16)
     */
    fontSize?: number;
    /**
     * 运行时注入的第三方 / 自定义节点形状
     * @description `<Node shape="...">` 写 shape 名字或 `{ type, params }`，具体形状定义通过本 prop 注册。
     *   与内置或自定义同名会报错；引用未注册形状也会报错
     */
    shapes?: ReadonlyArray<ShapeDefinition>;
    /**
     * 运行时注入的第三方 / 自定义连接面
     * @description `<Node boundary="...">` 写 boundary 名字或 `{ type, params }`，具体连接面定义通过本 prop 注册。
     *   未注册时会回退到同名 shape 边界
     */
    boundaries?: ReadonlyArray<BoundaryDefinition>;
    /** 运行时注入的第三方 / 自定义裁剪区；`<Scope clip={{ kind: '...' }}>` 可引用这些定义 */
    clips?: ReadonlyArray<ClipDefinition>;
    /**
     * 运行时注入的第三方 / 自定义箭头
     * @description `<Path arrowDetail={{ shape: '...' }}>` 写箭头名，具体箭头定义通过本 prop 注册。
     *   与内置或自定义同名会报错；引用未注册箭头也会报错
     */
    arrows?: ReadonlyArray<ArrowDefinition>;
    /**
     * 运行时注入的第三方 / 自定义填充图案
     * @description `fill={{ kind: 'pattern', shape: '...' }}` 写 pattern 名，具体图案定义通过本 prop 注册。
     *   与内置或自定义同名会报错；引用未注册 pattern 也会报错
     */
    patterns?: ReadonlyArray<PatternDefinition>;
    /**
     * 运行时注入的第三方 / 自定义路径生成器
     * @description `<Step kind="generator" name="...">` 写生成器名，具体生成逻辑通过本 prop 注册。
     *   未注册名会报错；`params` 必须是 JSON 可序列化对象
     */
    pathGenerators?: ReadonlyArray<PathGeneratorDefinition>;
    /**
     * 运行时注入的第三方 / 自定义 Path kind
     * @description `<Path kind="...">` 写路径类型名，具体整条路径的生成逻辑通过本 prop 注册
     */
    pathKinds?: ReadonlyArray<PathKindDefinition>;
    /** 运行时注入的 ribbon 宽度 profile；ribbon path 可按名称引用这些宽度曲线 */
    ribbonWidthProfiles?: ReadonlyArray<RibbonWidthProfileDefinition>;
    /**
     * 运行时注入的 Tier 2 composite 展开逻辑
     * @description 带 `namespace` / `type` 的高层节点通过本 prop 注册并展开；未注册时会发出 warning 并跳过
     */
    composites?: ReadonlyArray<CompositeDefinition>;
    /**
     * 运行时注入的公式渲染能力
     * @description `<Node>` 文本中的 `$...$`、`$$...$$` 或显式 tex run 会通过它转成可渲染字形。
     *   通常由 `@retikz/tex` 提供；缺省时公式内容会按降级规则处理并发出 warning
     */
    lowerTex?: LowerTex;
    /**
     * 节点 layout 完成后的批量观测回调
     * @description React 在 commit 后通过 effect 通知本次 compile 产出的节点布局，避免在 render 阶段触发用户副作用
     */
    onNodeLayouts?: (layouts: Array<CompiledNodeLayout>) => void;
    /**
     * 可选：显式注入的可嵌入 Tier2 适配器列表（逃生舱）
     * @description 主路径是子组件静态属性（Component.isTier2Embeddable + embeddableAdapter）自动识别；
     *   本 prop 用于测试注入 / 显式控制 / 未挂静态属性的 domain。按 adapter.displayName 匹配子组件，覆盖静态属性
     */
    embeddables?: Array<EmbeddableTier2Adapter>;
};
/**
 * <Layout> 顶层容器
 * @description children 模式写 Kernel / Sugar JSX；`ir` 模式直接传入 JSON IR。组件负责计算图形尺寸、
 *   选择 SVG 或 Canvas 输出、绑定事件水合和动画控制
 */
export declare const Layout: FC<LayoutProps>;
//# sourceMappingURL=Layout.d.ts.map