@opentiny/next-sdk 0.4.1 → 0.4.3

package/page-tools/a11y/search.ts

@@ -1,129 +0,0 @@
-/**
- * a11y/search.ts
- *
- * 在无障碍树内执行基于文本或引用的搜索操作。
- */
-
-import type { SearchA11yTreeOptions, SearchA11yTreeResult, A11ySearchMatch } from './types'
-import { buildA11yTree } from './build'
-
-/**
- * 在无障碍树中按关键词搜索，返回带行号的匹配结果和上下文
- *
- * 支持的搜索维度（均对同一个 query 字符串做包含匹配）：
- *   - role：如 `button`、`link`、`heading`
- *   - accessible name：节点的语义化名称（引号内文本）
- *   - state token：如 `checked`、`disabled`、`expanded`
- *   - ref 索引：如 `#5`
- *
- * @example
- *   searchA11yTree('button')    // 找全部按钮
- *   searchA11yTree('提交')      // 找名称含"提交"的节点
- *   searchA11yTree('#3')        // 找 ref #3
- */
-export function searchA11yTree(
-  query: string,
-  root: Element = document.body,
-  blacklist: Element[] = [],
-  whitelist: Element[] = [],
-  options?: SearchA11yTreeOptions,
-): SearchA11yTreeResult {
-  const {
-    contextLines = 2,
-    caseInsensitive = true,
-    maxMatches = 20,
-    ...treeOptions
-  } = options ?? {}
-
-  const safeContextLines = Math.max(0, contextLines)
-  const safeMaxMatches = Math.max(1, maxMatches)
-
-  // 复用 buildA11yTree 生成完整树，直接取 lines 数组（不重复构建 DOM 遍历）
-  const { lines, refMap, yaml } = buildA11yTree(root, blacklist, whitelist, treeOptions)
-
-  const needle = caseInsensitive ? query.toLowerCase() : query
-  const totalLines = lines.length
-
-  const isRefQuery = /^#\d+$/.test(query)
-  const refRegex = isRefQuery ? new RegExp(`\\s${query}(?:\\s|[\\[]|$)`) : null
-
-  // 找出所有命中行的下标（0-based）
-  const hitIndices: number[] = []
-  for (let i = 0; i < lines.length; i++) {
-    let matched = false
-    if (refRegex) {
-      matched = refRegex.test(lines[i])
-    } else {
-      const haystack = caseInsensitive ? lines[i].toLowerCase() : lines[i]
-      matched = haystack.includes(needle)
-    }
-    if (matched) {
-      hitIndices.push(i)
-    }
-  }
-
-  // 合并重叠的上下文区间，避免重复输出行
-  const mergedRanges: Array<{ start: number; end: number; hits: number[] }> = []
-  let isTruncated = false
-  for (const idx of hitIndices) {
-    const start = Math.max(0, idx - safeContextLines)
-    const end = Math.min(totalLines - 1, idx + safeContextLines)
-    const last = mergedRanges[mergedRanges.length - 1]
-    if (last && start <= last.end + 1) {
-      // 区间重叠或紧邻，合并
-      last.end = Math.max(last.end, end)
-      last.hits.push(idx)
-    } else {
-      if (mergedRanges.length >= safeMaxMatches) {
-        isTruncated = true
-        break
-      }
-      mergedRanges.push({ start, end, hits: [idx] })
-    }
-  }
-
-  // 构建结构化结果
-  const matches: A11ySearchMatch[] = mergedRanges.map((range) => ({
-    lineNumber: range.hits[0] + 1,
-    line: lines[range.hits[0]],
-    context: Array.from({ length: range.end - range.start + 1 }, (_, k) => ({
-      lineNumber: range.start + k + 1,
-      line: lines[range.start + k],
-    })),
-  }))
-
-  // 格式化为可读文本（模仿 grep -n -C 风格，便于 LLM 直接理解）
-  const textParts: string[] = [
-    `无障碍树搜索结果 — 关键词: "${query}" | 总行数: ${totalLines} | 命中: ${hitIndices.length} 行 | 返回分组: ${matches.length}`,
-    '',
-  ]
-
-  if (matches.length === 0) {
-    textParts.push('（未找到匹配项）')
-  } else {
-    matches.forEach((match, m) => {
-      const range = mergedRanges[m]
-      textParts.push(`── 分组 ${m + 1}（第 ${range.start + 1}–${range.end + 1} 行）──`)
-      match.context.forEach(({ lineNumber, line }) => {
-        const isHit = range.hits.includes(lineNumber - 1)
-        const ln = String(lineNumber).padStart(4)
-        // 命中行用 >>> 标记，上下文行用普通行号前缀
-        textParts.push(isHit ? `>>>${ln} | ${line}` : `   ${ln} | ${line}`)
-      })
-      textParts.push('')
-    })
-    if (isTruncated) {
-      textParts.push(`⚠️ 命中过多，已截断至前 ${safeMaxMatches} 个分组，建议缩小搜索范围`)
-    }
-    textParts.push(`提示：如需操作命中元素，使用其 #N 索引；如需查看完整树，请使用 browserState。`)
-  }
-
-  return {
-    text: textParts.join('\n'),
-    matches,
-    totalLines,
-    matchCount: hitIndices.length,
-    refMap,
-    yaml,
-  }
-}

package/page-tools/a11y/types.ts

@@ -1,108 +0,0 @@
-/**
- * a11y/types.ts
- *
- * 定义无障碍树模块（A11y Tree）的核心接口和类型。
- */
-
-/** ref 索引 → HTMLElement 映射，供 click/fill/select 操作使用 */
-export type RefMap = Map<number, HTMLElement>
-
-/** 内部中间态节点，与 DOM 解耦，便于剪枝和序列化 */
-export interface VNode {
-  /** 节点的 ARIA 角色 (如 'button', 'link', 'textbox') */
-  role: string
-  /** W3C AccName 算法计算出的语义化名称 */
-  name: string
-  /** 元素相关的状态和属性标记 (如 'checked', 'disabled', 'value="xxx"') */
-  tokens: string[]
-  /** 只有交互节点才有 ref (内部索引，用于标识可在其上执行交互动作的元素) */
-  ref?: number
-  /** 关联的 DOM 元素实例 */
-  el: HTMLElement
-  /** 包含的子节点列表 */
-  children: VNode[]
-}
-
-/** 构建无障碍树时的配置选项 */
-export interface A11yTreeOptions {
-  /**
-   * 是否启用剪枝：无 ref 且无 accessible name 的节点透明穿透
-   * 默认 true（推荐）
-   */
-  pruneUnnamed?: boolean
-  /**
-   * 强制保留的角色列表，即使无 name 也不穿透（优先级最高）
-   * 例如：['table', 'row'] 用于保留表格结构
-   */
-  preserveRoles?: string[]
-  /**
-   * 允许在无障碍树节点中作为 token 额外输出的 DOM 属性白名单
-   * 包含这些属性的节点会被自动视为需要暴露/交互的节点（分配 ref 并保留），
-   * 且属性及其值会显示在节点的 token 列表中，如 [cf-uba="cloudShell"]
-   */
-  exposedAttributes?: string[]
-  /**
-   * 校验错误元素 CSS 选择器（逗号分隔或选择器数组），用于在 token 中标记 [error]
-   * 默认覆盖 ARIA 标准 + 主流 UI 框架
-   */
-  errorSelectors?: string | string[]
-  /**
-   * 校验警告元素 CSS 选择器（逗号分隔或选择器数组）
-   */
-  warningSelectors?: string | string[]
-}
-
-/** 构建无障碍树的返回结果 */
-export interface A11yTreeResult {
-  /** 语义化 YAML 文本（供 AI 阅读和 Diff 计算） */
-  yaml: string
-  /** ref 索引 → HTMLElement 映射（供后续操作使用） */
-  refMap: RefMap
-  /** 可交互元素总数 */
-  interactiveCount: number
-  /** 原始行数组（不含 yaml 代码块包裹），供搜索使用 */
-  lines: string[]
-}
-
-/** 关键词搜索选项 */
-export interface SearchA11yTreeOptions extends A11yTreeOptions {
-  /**
-   * 每个匹配行前后保留的上下文行数（类似 grep -C N）
-   * 默认 2
-   */
-  contextLines?: number
-  /**
-   * 是否大小写不敏感，默认 true
-   */
-  caseInsensitive?: boolean
-  /**
-   * 最大返回匹配分组数（防止命中过多撑爆上下文），默认 20
-   */
-  maxMatches?: number
-}
-
-/** 单个搜索匹配的分组结构 */
-export interface A11ySearchMatch {
-  /** 主命中行行号（1-based） */
-  lineNumber: number
-  /** 主命中行内容 */
-  line: string
-  /** 含上下文的行列表（带行号） */
-  context: Array<{ lineNumber: number; line: string }>
-}
-
-/** searchA11yTree 函数的返回结果 */
-export interface SearchA11yTreeResult {
-  /** 格式化后可直接发给 LLM 的文本 */
-  text: string
-  /** 结构化匹配列表 */
-  matches: A11ySearchMatch[]
-  /** 无障碍树总行数 */
-  totalLines: number
-  /** 原始命中行数（去重前） */
-  matchCount: number
-  /** 返回搜索时的 ref 映射 */
-  refMap: RefMap
-  /** 返回搜索时的 yaml 状态，用于更新缓存 */
-  yaml: string
-}

package/page-tools/a11y/utils.ts

@@ -1,266 +0,0 @@
-/**
- * a11y/utils.ts
- *
- * 存放生成无障碍树时的通用工具函数：节点解析、状态获取、角色推断及纯文本兜底等。
- */
-
-import { isFocusable, isTabbable } from 'tabbable'
-import { TAG_ROLE_MAP, INPUT_TYPE_ROLE, DEFAULT_ERROR_SELECTORS, DEFAULT_WARNING_SELECTORS } from './constants'
-
-/**
- * 获取元素的 ARIA 角色
- * 优先级：显式 role 属性 > 标签隐式角色 > 'generic'
- */
-export function inferRole(el: Element): string {
-  const explicit = el.getAttribute('role')
-  if (explicit && explicit !== 'presentation' && explicit !== 'none') {
-    return explicit
-  }
-  const tag = el.tagName.toLowerCase()
-  if (tag === 'input') {
-    const inputType = (el as HTMLInputElement).type?.toLowerCase() ?? 'text'
-    return INPUT_TYPE_ROLE[inputType] ?? 'textbox'
-  }
-  return TAG_ROLE_MAP[tag] ?? 'generic'
-}
-
-/**
- * 收集节点的 ARIA 状态 token
- * 格式：[checked] [selected] [disabled] [hasPopup] [cursor=pointer] [value="..."]
- */
-export function getStateTokens(
-  el: Element,
-  exposedAttributes?: string[],
-  errorSelectors?: string | string[],
-  warningSelectors?: string | string[],
-): string[] {
-  const tokens: string[] = []
-  const aria = (k: string) => el.getAttribute(k)
-
-  // 选中状态：优先 aria-checked，其次原生 input.checked
-  // 对 <label for="X"> 检测关联 checkbox/radio 的选中状态，帮助 AI 识别复选框当前状态
-  const ariaChecked = aria('aria-checked')
-  if (ariaChecked === 'true') {
-    tokens.push('checked')
-  } else if (ariaChecked === 'false') {
-    tokens.push('unchecked')
-  } else {
-    const elTag = el.tagName.toLowerCase()
-    let nativeChecked: boolean | undefined
-    if (elTag === 'input' && ((el as HTMLInputElement).type === 'checkbox' || (el as HTMLInputElement).type === 'radio')) {
-      nativeChecked = (el as HTMLInputElement).checked
-    } else if (elTag === 'label' && el.hasAttribute('for')) {
-      const target = document.getElementById(el.getAttribute('for')!)
-      if (target instanceof HTMLInputElement && (target.type === 'checkbox' || target.type === 'radio')) {
-        nativeChecked = target.checked
-      }
-    }
-    if (nativeChecked !== undefined) {
-      tokens.push(nativeChecked ? 'checked' : 'unchecked')
-    }
-  }
-
-  if (aria('aria-selected') === 'true') tokens.push('selected')
-
-  const disabled = aria('aria-disabled') === 'true' || (el as HTMLInputElement).disabled
-  if (disabled) tokens.push('disabled')
-
-  const hasPopup = aria('aria-haspopup')
-  if (hasPopup && hasPopup !== 'false') tokens.push('hasPopup')
-
-  if (aria('aria-expanded') === 'true') tokens.push('expanded')
-
-  // heading level（h1-h6）
-  const headingMatch = el.tagName.match(/^H([1-6])$/)
-  if (headingMatch) tokens.push(`level=${headingMatch[1]}`)
-  const ariaLevel = aria('aria-level')
-  if (ariaLevel && !headingMatch) tokens.push(`level=${ariaLevel}`)
-
-  // cursor=pointer 表示"视觉上可点击"
-  try {
-    const style = window.getComputedStyle(el as HTMLElement)
-    if (style.cursor === 'pointer') tokens.push('cursor=pointer')
-  } catch {
-    // 某些元素 getComputedStyle 可能抛异常，忽略
-  }
-
-  // 记录输入元素的值，以便在 fill/输入后在 A11y 树中显示并产生 Diff
-  const tag = el.tagName.toLowerCase()
-  if (tag === 'input' || tag === 'textarea' || tag === 'select') {
-    const val = (el as HTMLInputElement).value
-    if (val !== undefined && val !== '') {
-      tokens.push(`value="${val}"`)
-    }
-  }
-  const valuenow = el.getAttribute('aria-valuenow')
-  if (valuenow) {
-    tokens.push(`valuenow="${valuenow}"`)
-  }
-
-  // link 元素：检测 target=_blank，提示 Agent 该链接会在新标签页打开
-  if (el.tagName.toLowerCase() === 'a' && el.getAttribute('target') === '_blank') {
-    tokens.push('opens-new-tab')
-  }
-
-  // 检测 CSS 激活/选中状态类名（用于未使用标准 ARIA 的 Tab/选项组件，如华为云镜像选择）
-  // 若元素携带常见激活类名，输出 [active] token，帮助 Agent 判断当前选中项
-  const cls = typeof el.className === 'string' ? el.className : ''
-  const ACTIVE_CLASS_PATTERNS = [
-    'is-active', 'isActive',
-    'is-selected', 'isSelected',
-    'is-current', 'isCurrent',
-    'active-item', 'activeItem',
-    'tab-active', 'tabActive',
-    // 仅当作为独立 class 词或有连字符前缀时匹配 "active"，避免误匹配 "interactive" 等
-    /\bactive\b/,
-    /\bselected\b/,
-    /\bcurrent\b/,
-  ]
-  const hasActiveClass = ACTIVE_CLASS_PATTERNS.some(p =>
-    typeof p === 'string' ? cls.split(/\s+/).includes(p) : p.test(cls)
-  )
-  // 只对有 cursor=pointer 或明确角色的元素输出 active token，避免太多噪音
-  const roleForActive = el.getAttribute('role') || el.tagName.toLowerCase()
-  const roles = roleForActive.split(/\s+/)
-  const isTabLike = roles.some(r => ['button', 'option', 'a', 'li', 'generic'].includes(r) || r.startsWith('tab'))
-  if (hasActiveClass && isTabLike && !tokens.includes('checked') && !tokens.includes('selected')) {
-    tokens.push('active')
-  }
-
-  // 检测校验错误/警告状态（ARIA 标准 + 主流 UI 框架，可配置）
-  // 输出 [error] / [warning] token，让 AI 能区分校验错误与普通说明文字
-  // 使用 closest() 向上查找，确保嵌套在错误容器内的子元素也能获得 error 语义
-  const errorSelector = Array.isArray(errorSelectors)
-    ? errorSelectors.join(', ')
-    : (errorSelectors || DEFAULT_ERROR_SELECTORS.join(', '))
-  const warningSelector = Array.isArray(warningSelectors)
-    ? warningSelectors.join(', ')
-    : (warningSelectors || DEFAULT_WARNING_SELECTORS.join(', '))
-  let errorAncestor = null
-  if (errorSelector) {
-    try {
-      errorAncestor = el.closest(errorSelector)
-    } catch {
-      // ignore
-    }
-  }
-  
-  if (errorAncestor) {
-    tokens.push('error')
-  } else {
-    let warningAncestor = null
-    if (warningSelector) {
-      try {
-        warningAncestor = el.closest(warningSelector)
-      } catch {
-        // ignore
-      }
-    }
-    if (warningAncestor) {
-      tokens.push('warning')
-    }
-  }
-
-  // 额外暴露的自定义属性白名单
-  if (exposedAttributes) {
-    for (const attr of exposedAttributes) {
-      const val = el.getAttribute(attr)
-      if (val !== null) {
-        tokens.push(`${attr}="${val}"`)
-      }
-    }
-  }
-
-  return tokens
-}
-
-/** 判断元素是否应被跳过（不可见或在黑名单中） */
-export function isHidden(el: Element): boolean {
-  if (el.getAttribute('aria-hidden') === 'true') return true
-  if ((el as HTMLElement).hidden) return true
-  try {
-    const style = window.getComputedStyle(el as HTMLElement)
-    if (style.display === 'none' || style.visibility === 'hidden') return true
-    // opacity:0 是常见的视觉隐藏方式，元素对用户不可见
-    if (style.opacity === '0') return true
-    // 宽或高为 0 且有 overflow 裁剪时，子内容实际不可见（如折叠的侧边栏 width:0 !important）
-    // 若 overflow 为 visible，子内容仍然溢出可见，不能过滤
-    const isClipX = style.overflowX !== 'visible'
-    const isClipY = style.overflowY !== 'visible'
-    if (parseFloat(style.width) === 0 && isClipX) return true
-    if (parseFloat(style.height) === 0 && isClipY) return true
-  } catch {
-    // 忽略跨域 iframe 等无法访问 style 的场景
-  }
-  return false
-}
-
-
-/**
- * 收集子孙节点的文本内容，用作无障碍名字的兜底。
- * 当普通计算无法提取文本时，遍历后代并拼接可见文本。
- */
-export function collectDescendantText(el: Element): string {
-  let text = ''
-  const walk = (node: Node) => {
-    if (node.nodeType === Node.TEXT_NODE) {
-      text += (node.textContent ?? '') + ' '
-    } else if (node.nodeType === Node.ELEMENT_NODE) {
-      const element = node as Element
-      if (isHidden(element)) return
-
-      // 如果遇到嵌套的列表项或其他交互/语义节点，停止向下遍历该子树，避免兜底文本重复吸收
-      if (element !== el) {
-        const tag = element.tagName.toLowerCase()
-        const role = inferRole(element)
-        const isInteractiveTag = ['button', 'a', 'input', 'select', 'textarea', 'li', 'option'].includes(tag)
-        const isInteractiveRole = ['button', 'link', 'checkbox', 'radio', 'textbox', 'listitem', 'option', 'combobox', 'listbox'].includes(role)
-        const isTrulyInteractive = isTabbable(element as HTMLElement)
-        let isCursorPointer = false
-        try {
-          isCursorPointer = window.getComputedStyle(element as HTMLElement).cursor === 'pointer'
-        } catch { /* ignore */ }
-        const isMeaningfullyInteractive = isTrulyInteractive && !(role === 'generic' && !isCursorPointer)
-        
-        if (isMeaningfullyInteractive || isInteractiveTag || isInteractiveRole) {
-          return
-        }
-      }
-
-      for (const child of Array.from(element.childNodes)) {
-        walk(child)
-      }
-    }
-  }
-  walk(el)
-  return text.trim().replace(/\s+/g, ' ')
-}
-
-/**
- * 获取元素在 composed tree（组合树）中的有效子元素
- *
- * Shadow DOM 场景下，简单拼接 el.children + el.shadowRoot.children 不符合浏览器
- * 实际渲染和无障碍树使用的组合树语义：slotted 节点应出现在 <slot> 的位置而非
- * host 下，<slot> 本身不应作为噪音节点出现，未被任何 slot 接收的 light children
- * 在组合树中不可见。
- *
- * 因此：有 shadowRoot 时遍历 shadow tree，遇到 <slot> 用 assignedElements 替换；
- * 无 shadowRoot 时直接遍历 light DOM children。
- */
-export function getComposedChildren(el: Element): Element[] {
-  // <slot> 可嵌套在 shadow tree 的任意层级（如 <div><slot/></div>），递归时
-  // wrapper 节点无 shadowRoot 走 light 分支，因此两个分支都需解析 <slot>。
-  // light DOM 中不会出现 <slot>，检查无副作用。
-  const source = el.shadowRoot ? el.shadowRoot.children : el.children
-  const result: Element[] = []
-  for (const node of Array.from(source)) {
-    if (node instanceof HTMLSlotElement) {
-      const assigned = node.assignedElements({ flatten: true })
-      // 有分配节点时用 slotted 内容；否则用 slot 的 fallback content
-      result.push(...(assigned.length > 0 ? assigned : Array.from(node.children)))
-    } else {
-      result.push(node)
-    }
-  }
-  return result
-}