@opentiny/next-sdk 0.4.0 → 0.4.1

package/page-tools/a11y/utils.ts

@@ -0,0 +1,266 @@
+/**
+ * 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
+}

package/page-tools/a11y/vnode.ts

@@ -0,0 +1,229 @@
+/**
+ * a11y/vnode.ts
+ *
+ * 处理无障碍树节点 (VNode) 的构建、剪枝与序列化逻辑。
+ */
+
+import { computeAccessibleName } from 'dom-accessibility-api'
+import { isFocusable, isTabbable } from 'tabbable'
+import type { VNode, RefMap, A11yTreeOptions } from './types'
+import { isHidden, inferRole, getStateTokens, collectDescendantText, getComposedChildren } from './utils'
+
+/**
+ * 递归将 DOM 元素转换为 VNode 中间表示
+ * @param el 当前 DOM 元素
+ * @param refCounter 引用计数器（使用对象引用避免全局可变状态）
+ * @param refMap ref 索引 → 元素映射
+ * @param blacklistSet 用户自定义黑名单
+ * @param whitelistSet 用户自定义白名单
+ * @param exposedAttributes 需要暴露的自定义属性
+ * @param errorSelectors 错误选择器
+ * @param warningSelectors 警告选择器
+ */
+export function buildVNode(
+  el: Element,
+  refCounter: { value: number },
+  refMap: RefMap,
+  blacklistSet: Set<Element>,
+  whitelistSet: Set<Element>,
+  exposedAttributes?: string[],
+  errorSelectors?: string | string[],
+  warningSelectors?: string | string[],
+  /** 祖先节点是否已是可交互节点（已分配 ref）。为 true 时，纯 CSS 继承的 cursor=pointer 不再额外分配 ref */
+  ancestorIsInteractive = false,
+): VNode | null {
+  if (isHidden(el) || blacklistSet.has(el)) return null
+
+  const role = inferRole(el)
+  const tokens = getStateTokens(el, exposedAttributes, errorSelectors, warningSelectors)
+  
+  let name = computeAccessibleName(el as HTMLElement)
+  const isTrulyInteractive = isTabbable(el as HTMLElement)
+  const isVisuallyClickable = tokens.includes('cursor=pointer')
+  // 包含白名单属性的节点也视为白名单节点（确保不被剪枝并分配 ref 操作索引）
+  const isWhitelisted = whitelistSet.has(el) || (exposedAttributes?.some(attr => el.hasAttribute(attr)) ?? false)
+  // <label for="..."> 原生可点击：浏览器将点击转发到关联的表单控件（checkbox/radio 等）
+  // Angular/React 自定义组件常隐藏原生 input，仅暴露 label 文本和自定义 skin
+  const isLabelFor = el.tagName.toLowerCase() === 'label' && el.hasAttribute('for')
+
+  // 兜底方案：如果 AccName 计算结果为空，但该节点具有明显的交互性或属于结构性列表项，
+  // 我们从其子树收集纯文本作为其 fallback name，以防 AI 丢失可读上下文。
+  // 注意：不要对 <select> / combobox / listbox 等下拉组件进行文本兜底，以防它们吸收所有子选项文本导致极其嘈杂。
+  if (!name.trim()) {
+    const tag = el.tagName.toLowerCase()
+    const isDropdown = tag === 'select' || role === 'combobox' || role === 'listbox'
+    if (!isDropdown) {
+      const isInteractiveTag = ['button', 'a', 'input', 'textarea', 'li', 'label'].includes(tag)
+      if (isTrulyInteractive || isWhitelisted || isVisuallyClickable || isInteractiveTag || role === 'listitem' || role === 'option') {
+        name = collectDescendantText(el)
+      }
+    }
+  }
+
+  // 最终兜底：非交互元素（如错误提示 ti-error-msg、状态信息）的纯文本捕获。
+  // 仅当元素没有有价值的子元素时触发，避免与子节点文本重复：
+  // - 叶子 span（只有文本节点）→ 捕获文本作为 name
+  // - 容器元素（有 element 子节点）→ 不触发，由子节点各自捕获
+  if (!name.trim()) {
+    const hasElementChildren = getComposedChildren(el).length > 0
+    if (!hasElementChildren) {
+      const text = collectDescendantText(el)
+      if (text) {
+        name = text
+      }
+    }
+  }
+
+  // generic 无 name 时，即使有 cursor=pointer 也不分配 ref：
+  // cursor 通常是 CSS 继承传播的，这类 div 本身无法被有意义地操作。
+  // 此外，当祖先节点已是可交互节点时，子节点仅凭 isVisuallyClickable（CSS 继承）
+  // 不再额外分配 ref，避免父节点 cursor:pointer 传染给所有子孙导致高亮泛滥。
+  //
+  // 例外：<a>/<button>/<input> 等语义性交互标签，无论祖先是否已有 ref，
+  // 始终强制分配 ref，因为它们在 HTML 语义上就是独立的操作单元。
+  const tagName = el.tagName.toLowerCase()
+  const isSemanticInteractiveTag =
+    (tagName === 'a' && el.hasAttribute('href')) ||
+    (['button', 'input', 'select', 'textarea'].includes(tagName) && !el.hasAttribute('disabled'))
+
+  // 虽然有些元素有 tabindex="0" (isTrulyInteractive)，但如果它是 generic 且没有 cursor:pointer，
+  // 往往是开发者加的结构化 focus 容器（如 tp-card），而非真正的可交互按钮，我们在此过滤掉它们。
+  const isMeaningfullyInteractive = isTrulyInteractive && !(role === 'generic' && !isVisuallyClickable)
+
+  const interactive =
+    isMeaningfullyInteractive ||
+    isWhitelisted ||
+    isLabelFor ||
+    isSemanticInteractiveTag ||
+    (!ancestorIsInteractive && isVisuallyClickable && (role !== 'generic' || name !== ''))
+
+  let ref: number | undefined
+  if (interactive) {
+    ref = refCounter.value
+    refMap.set(ref, el as HTMLElement)
+    refCounter.value++
+  }
+
+  const children: VNode[] = []
+  for (const child of getComposedChildren(el)) {
+    const childVNode = buildVNode(
+      child,
+      refCounter,
+      refMap,
+      blacklistSet,
+      whitelistSet,
+      exposedAttributes,
+      errorSelectors,
+      warningSelectors,
+      // 将当前节点的交互性向下传递，子节点据此决定是否抑制 cursor=pointer
+      interactive || ancestorIsInteractive,
+    )
+    if (childVNode) children.push(childVNode)
+  }
+
+  return { role, name, tokens, ref, el: el as HTMLElement, children }
+}
+
+/**
+ * 判断 VNode 子树是否包含任何有价值的节点（有 ref 或有 accessible name）
+ * 用于过滤空容器子树，避免输出无内容的嵌套层级
+ */
+export function hasValue(vnode: VNode): boolean {
+  if (vnode.ref !== undefined || vnode.name.trim() !== '') return true
+  return vnode.children.some(hasValue)
+}
+
+/**
+ * 检查节点子树中是否存在任何有 ref 的可交互子节点。
+ * 用于判断父节点是否可以安全省略其子节点输出。
+ */
+function hasInteractiveDescendant(vnode: VNode): boolean {
+  return vnode.children.some(c => c.ref !== undefined || hasInteractiveDescendant(c))
+}
+
+/**
+ * 找到子树中恰好唯一一个有 ref 的节点，若有多个则返回 null。
+ * 用于判断是否可将该子节点与父节点合并输出。
+ */
+function findSingleRefDescendant(vnode: VNode): VNode | null {
+  const refs: VNode[] = []
+  const collect = (v: VNode) => {
+    if (v.ref !== undefined) refs.push(v)
+    if (refs.length > 1) return  // 超过一个就提前退出
+    v.children.forEach(collect)
+  }
+  vnode.children.forEach(collect)
+  return refs.length === 1 ? refs[0] : null
+}
+
+/**
+ * 判断节点是否需要透明穿透（跳过本节点但保留子节点）
+ *
+ * 统一规则：无 ref（非交互）且无 accessible name → 穿透
+ * 这样可以同时：
+ * - 去掉 generic/list/listitem 等纯布局噪音（无 name 时穿透）
+ * - 保留有 name 的 listitem（有 name 时保留，兼顾内容理解场景）
+ */
+export function shouldPassThrough(vnode: VNode, opts: Required<A11yTreeOptions>): boolean {
+  if (!opts.pruneUnnamed) return false
+  // preserveRoles 中的角色强制保留
+  if (opts.preserveRoles.includes(vnode.role)) return false
+  // 有 ref（交互节点）→ 永远保留
+  if (vnode.ref !== undefined) return false
+  // 有 accessible name → 保留（兼顾内容理解场景）
+  if (vnode.name.trim() !== '') return false
+  // 无 ref 且无 name → 透明穿透
+  return true
+}
+
+/**
+ * 将 VNode 序列化为 YAML 行数组
+ * 穿透节点时，子节点在当前 depth 平铺输出（不增加缩进层级）
+ */
+export function serializeVNode(
+  vnode: VNode,
+  depth: number,
+  opts: Required<A11yTreeOptions>,
+): string[] {
+  if (shouldPassThrough(vnode, opts)) {
+    // 透明穿透：跳过本节点，子节点保持当前 depth（层级不增加）
+    // 同时过滤掉整棵子树都无价値的空容器，避免输出无意义的嵌套
+    return vnode.children
+      .filter(c => hasValue(c))
+      .flatMap(c => serializeVNode(c, depth, opts))
+  }
+
+  const indent = '  '.repeat(depth)
+  const refStr = vnode.ref !== undefined ? ` #${vnode.ref}` : ''
+  const safeTokens = vnode.tokens.map(t => t.replace(/[\r\n]+/g, ' ').replace(/"/g, '\\"'))
+  const tokenStr = safeTokens.length > 0 ? ` [${safeTokens.join(' ')}]` : ''
+
+  if (vnode.ref !== undefined) {
+    if (!hasInteractiveDescendant(vnode)) {
+      // 子树无任何 ref 节点 → 直接省略子节点
+      // 父节点的 name 已由 computeAccessibleName 汇总了子树文本，信息不会丢失
+      const safeName = vnode.name ? vnode.name.replace(/[\r\n]+/g, ' ').replace(/"/g, '\\"') : ''
+      const nameStr = safeName ? ` "${safeName}"` : ''
+      return [`${indent}- ${vnode.role}${refStr}${tokenStr}${nameStr}`]
+    }
+
+    // 子树中唯一一个 ref 节点且是无子 ref 的 generic 时，将其 name 提升到父节点，省略子节点输出。
+    // 场景：`listitem #22 [active]` 内部只有 `generic #23 "总览"`，
+    //       点击意义相同时，就展示为一行 `- listitem #22 [active] "总览"`。
+    const singleChild = findSingleRefDescendant(vnode)
+    if (singleChild && singleChild.role === 'generic' && !hasInteractiveDescendant(singleChild)) {
+      const mergedName = (vnode.name.trim() || singleChild.name.trim())
+        .replace(/[\r\n]+/g, ' ')
+        .replace(/"/g, '\\"')
+      const nameStr = mergedName ? ` "${mergedName}"` : ''
+      return [`${indent}- ${vnode.role}${refStr}${tokenStr}${nameStr}`]
+    }
+  }
+
+  const safeName = vnode.name ? vnode.name.replace(/[\r\n]+/g, ' ').replace(/"/g, '\\"') : ''
+  const nameStr = safeName ? ` "${safeName}"` : ''
+  const line = `${indent}- ${vnode.role}${refStr}${tokenStr}${nameStr}`
+
+  const childLines = vnode.children.flatMap(c => serializeVNode(c, depth + 1, opts))
+  return [line, ...childLines]
+}