/**
 * a11y/config.ts
 *
 * 统一无障碍配置（A11yConfig）：把角色推断、状态推断、白/黑名单、自定义属性、
 * 弹窗选择器等配置项收敛为一个对象，并提供：
 * 1. 声明式规则（roles/states）的合并与匹配逻辑
 * 2. 底层的逐元素解析函数（resolveA11yRole/resolveA11yStates/resolveA11yInfo）
 *
 * 运行期读写 API 统一由 ../tool-config.ts 的 getPageAgentToolConfig/setPageAgentToolConfig 提供
 * （a11yConfig 是其中一个字段），这里不再单独维护一套 get/set。
 */
export interface A11yMatcher {
    /**
     * 标准 CSS 选择器。优先使用 selector，仅当选择器表达不了时再写 match。
     * - **states**：用 `closest` 判断自身或祖先是否命中（适合 error/selected 等挂在容器上的状态）
     * - **roles**：用 `matches` 仅判断自身是否命中（避免角色传染给子孙节点）
     * 支持标签/属性/id/组合选择器，也支持字符串数组（任意一个命中即可）。
     */
    selector?: string | string[];
    /** 自定义判断函数，优先级高于 selector，用于读取计算样式、组合条件等选择器表达不了的场景 */
    match?: (el: Element) => boolean;
}
export type A11yStateName = 'checked' | 'selected' | 'pressed' | 'current' | 'expanded' | 'hasPopup' | 'disabled' | 'readonly' | 'required' | 'invalid' | 'busy' | 'error' | 'warning' | (string & {});
export interface A11yRoleRule extends A11yMatcher {
    /** 命中后赋予的 ARIA 角色，如 'tab' | 'tabpanel' | 'switch' | 'treeitem' */
    role: string;
    /** 为 true 时覆盖元素已有的显式 role 属性，默认 false（不覆盖开发者显式设置） */
    force?: boolean;
    /**
     * 可选声明可访问名（不改 DOM）。
     * 用于 landmark / 布局容器等无 aria-label、且子树多为交互节点时，避免被剪枝穿透，
     * 并在 YAML 中输出可读分区名（如 navigation "侧边导航"）。
     */
    name?: string;
}
export interface A11yConfig {
    /** 角色推断规则：用于弥补页面缺失的语义 role（如自定义 Tab 组件没有 role=tab） */
    roles?: A11yRoleRule[];
    /** 状态推断规则：key 为状态名，value 为一条或多条规则（命中任意一条即成立），与标准 aria-* 检测结果取"或" */
    states?: Partial<Record<A11yStateName, A11yMatcher | A11yMatcher[]>>;
    /** 白名单：强制识别为可交互元素并纳入无障碍树。支持 Element 引用或 CSS 选择器字符串（字符串每次动态解析，适配 SPA 重渲染） */
    whitelist?: Array<Element | string>;
    /** 黑名单：强制从无障碍树中排除，规则同上 */
    blacklist?: Array<Element | string>;
    /** 额外暴露的自定义 DOM 属性（作为 token 输出，如 [data-testid="xxx"]） */
    exposedAttributes?: string[];
}
/** 单个元素解析出的完整无障碍信息 */
export interface A11yInfo {
    role: string;
    tokens: string[];
    /** 命中的 role 规则所声明的可访问名（若有） */
    name?: string;
}
/** 标记已与默认值合并并规整过的配置，避免热路径上二次 merge 导致默认规则翻倍 */
declare const RESOLVED_A11Y_BRAND: unique symbol;
/**
 * 合并/规整后的完整无障碍配置：与用户书写的 {@link A11yConfig} 的唯一区别是
 * states 的每个状态名都统一规范化为数组（不再是 `A11yMatcher | A11yMatcher[]`）。
 * resolveA11yInfo 内部与 getPageAgentToolConfig().a11yConfig 读取到的都是这个类型。
 */
export interface ResolvedA11yConfig {
    roles: A11yRoleRule[];
    states: Partial<Record<A11yStateName, A11yMatcher[]>>;
    whitelist: Array<Element | string>;
    blacklist: Array<Element | string>;
    exposedAttributes: string[];
    readonly [RESOLVED_A11Y_BRAND]?: true;
}
/** 是否为 {@link mergeA11yConfig}/{@link mergeA11yConfigs} 产出的已规整配置 */
export declare function isResolvedA11yConfig(config?: A11yConfig | ResolvedA11yConfig | null): config is ResolvedA11yConfig;
/** 默认生效的无障碍配置：零配置即可覆盖 ARIA 标准 + 主流 UI 框架的常见错误/警告/选中态检测 */
export declare const DEFAULT_A11Y_CONFIG: ResolvedA11yConfig;
/**
 * 从 roles 规则中提取指定角色的所有 CSS 选择器（展平为一维 string[]）。
 * 供 DOM 检测函数（detectPageDialog / getVisibleTooltipElements）复用：
 * 这些函数需要选择器字符串做 deepQuerySelectorAll，而非 matches 判断。
 */
export declare function getSelectorsForRole(roles: A11yRoleRule[], targetRole: string): string[];
/** 从状态规则中提取纯 CSS 选择器列表（忽略只有 match 函数、没有 selector 的规则；数组 selector 会被展开），供页面级选择器扫描场景复用 */
export declare function extractSelectors(rules?: A11yMatcher | A11yMatcher[]): string[];
/** 合并两份 A11yConfig：数组类字段拼接（additive，不丢失 base 中已有的规则），states 按 key 独立合并 */
export declare function mergeA11yConfigs(base: A11yConfig, patch: A11yConfig): ResolvedA11yConfig;
/**
 * 将用户配置与默认配置合并（additive），得到最终生效的完整配置。
 * 若入参已是 {@link ResolvedA11yConfig}，直接返回（幂等，避免默认规则被再次拼接）。
 */
export declare function mergeA11yConfig(user?: A11yConfig | ResolvedA11yConfig): ResolvedA11yConfig;
/**
 * 保证拿到已与默认值合并的配置：已规整则原样返回（同引用，零开销），否则与默认配置合并。
 * buildA11yTree / resolveA11yInfo 热路径应优先走此函数，避免对运行期配置反复 merge。
 */
export declare function ensureResolvedA11yConfig(config?: A11yConfig | ResolvedA11yConfig): ResolvedA11yConfig;
/** 恒等函数，仅用于书写配置时获得 TS 类型提示/校验（风格对齐 defineConfig） */
export declare function defineA11yConfig(config: A11yConfig): A11yConfig;
/**
 * 判断元素是否为编辑宿主（自身声明 contenteditable，而非从祖先继承）。
 * HTML-AAM：无显式 role 时隐式角色为 textbox。
 * `contenteditable="false"` / `inherit` 不算。
 */
export declare function isEditingHost(el: Element): boolean;
export declare function resolveA11yRole(el: Element, config?: A11yConfig | ResolvedA11yConfig): string;
export declare function resolveA11yStates(el: Element, config?: A11yConfig | ResolvedA11yConfig): string[];
/**
 * 统一入口（供用户直接调用的底层函数）：读取配置 -> 依据 roles/states 规则计算出该元素的
 * 完整无障碍信息（角色 + 状态 token）。buildA11yTree 内部对每个 DOM 节点也是调用这一个函数，
 * 是声明式规则与树生成结果之间唯一的桥接点；用户也可以直接调用它来调试/复用同一套解析逻辑。
 *
 * 若传入已是 {@link ResolvedA11yConfig}（如 getPageAgentToolConfig().a11yConfig），则跳过合并，
 * 避免在整树遍历时对每个节点重复 array spread / 默认规则翻倍。
 */
export declare function resolveA11yInfo(el: Element, config?: A11yConfig | ResolvedA11yConfig): A11yInfo;
export {};