@chancestv/tv-focus 0.1.0

package/src/engine/types.ts

@@ -0,0 +1,85 @@
+/**
+ * @shell/core/focus 公共类型
+ */
+
+export type Direction = 'up' | 'down' | 'left' | 'right'
+
+export type Restrict = 'self-first' | 'self-only' | 'none'
+
+export type EnterTo = '' | 'last-focused' | 'default-element'
+
+/**
+ * <extSelector>
+ * - 'querySelectorAll' 字符串
+ * - NodeList / Element 数组
+ * - 单个 Element
+ * - '@<sectionId>' / '@'（指定 section）
+ */
+export type ExtSelector =
+  | string
+  | Element
+  | Element[]
+  | NodeListOf<Element>
+  | ArrayLike<Element>
+
+export interface LeaveFor {
+  left?: ExtSelector
+  right?: ExtSelector
+  up?: ExtSelector
+  down?: ExtSelector
+}
+
+export interface SectionConfig {
+  /** querySelectorAll 字符串、NodeList、Element 数组、单个 Element（不接受 "@" 语法）*/
+  selector?: ExtSelector
+  /** 是否只允许严格方向（不允许斜向重叠） */
+  straightOnly?: boolean
+  /** 重叠判定阈值 [0, 1] */
+  straightOverlapThreshold?: number
+  /** 离开 section 时记住焦点来源（再返回时可复焦） */
+  rememberSource?: boolean
+  /** section 整体禁用 */
+  disabled?: boolean
+  /** 进入 section 时默认聚焦的元素 */
+  defaultElement?: ExtSelector
+  /** 进入 section 时的策略 */
+  enterTo?: EnterTo
+  /** 跨方向跳转规则 */
+  leaveFor?: LeaveFor | null
+  /** 边界策略 */
+  restrict?: Restrict
+  /** 不自动加 tabindex 的元素选择器 */
+  tabIndexIgnoreList?: string
+  /** 自定义元素可导航过滤器 */
+  navigableFilter?: ((elem: Element, sectionId?: string) => boolean) | null
+  /** section id（add 时可显式指定） */
+  id?: string
+}
+
+export type GlobalConfig = SectionConfig
+
+/**
+ * SpatialNavigation 公开 API（薄类型，主体实现来自 fork 源码）。
+ * 详见 spatial-navigation.ts。
+ */
+export interface SpatialNavigationAPI {
+  init(): void
+  uninit(): void
+  clear(): void
+  reset(): void
+  set(config: SectionConfig): void
+  set(sectionId: string, config: SectionConfig): void
+  add(config: SectionConfig): string
+  add(sectionId: string, config: SectionConfig): string
+  remove(sectionId: string): boolean
+  disable(sectionId: string): boolean
+  enable(sectionId: string): boolean
+  pause(): void
+  resume(): void
+  focus(): boolean
+  focus(silent: boolean): boolean
+  focus(selector: ExtSelector, silent?: boolean): boolean
+  move(direction: Direction, selector?: ExtSelector): boolean
+  makeFocusable(sectionId?: string): void
+  setDefaultSection(sectionId?: string): void
+}

package/src/focus-layer-context.ts

@@ -0,0 +1,11 @@
+/**
+ * FocusLayer 通过 provide 注入的上下文。
+ * 内部 useFocusSection 通过 inject 拿到本对象，并把自己的 sectionId 注册进来，
+ * 避免被 layer onMounted 时一并禁用。
+ */
+export interface FocusLayerContext {
+  layerId: string
+  registerInnerSection(sectionId: string): void
+}
+
+export const FOCUS_LAYER_KEY: symbol = Symbol('dwy:focus-layer')

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @shell/core/focus
+ *
+ * TV 焦点系统：空间导航引擎（./engine，fork 自 luke-chang/js-spatial-navigation, MPL 2.0）
+ * + Vue 3 适配层（组件 / composable / 原生按键 adapter）。
+ *
+ * 业务层禁止直连本入口，请用 @shell/tv-ui 的 EPage/ERow/EColumn/EFocusGroup 等组件。
+ */
+export { setupFocus, SpatialNavigation } from './core'
+export type { SetupFocusOptions } from './core'
+
+export { nativeKeyAdapter } from './key-source/native-event'
+
+export { useFocusable } from './useFocusable'
+export type { UseFocusableOptions, UseFocusableResult } from './useFocusable'
+
+export { useFocusSection, FOCUS_SECTION_KEY } from './useFocusSection'
+export type { UseFocusSectionOptions, FocusSectionContext } from './useFocusSection'
+
+export { useKeepAliveFocus } from './keep-alive-bridge'
+export { hasOpenLayer } from './layer-stack'
+
+export { default as Focusable } from './Focusable.vue'
+export { default as FocusSection } from './FocusSection.vue'
+export { default as FocusLayer } from './FocusLayer.vue'
+
+export type {
+  Direction,
+  Restrict,
+  EnterTo,
+  LeaveFor,
+  SectionConfig,
+  ExtSelector,
+} from './engine'

package/src/keep-alive-bridge.ts

@@ -0,0 +1,17 @@
+import { getCurrentInstance, onActivated, onDeactivated } from 'vue'
+import SpatialNavigation from './engine'
+
+/**
+ * 在 Vue KeepAlive 缓存页面中使用：被切走时暂停 SpatialNavigation，被切回时恢复。
+ *
+ * 用法：在被 KeepAlive 包裹的 view 组件 setup 顶部调用一次。
+ */
+export function useKeepAliveFocus(): void {
+  if (!getCurrentInstance()) return
+  onActivated(() => {
+    ;(SpatialNavigation as any).resume()
+  })
+  onDeactivated(() => {
+    ;(SpatialNavigation as any).pause()
+  })
+}

package/src/key-source/native-event.ts

@@ -0,0 +1,124 @@
+/**
+ * 把 OTT 原生方向键事件（CustomEvent）转发为标准 keydown，
+ * 让 @shell/core/focus 内置的 keydown 监听透明响应原生遥控器。
+ *
+ * 使用：在 main.ts 调一次即可：
+ *
+ *   import { nativeKeyAdapter } from '@shell/core/focus'
+ *   nativeKeyAdapter('ott:native-keydown')
+ *
+ * 期望 CustomEvent.detail 形如 { key?, keyCode?, keyCodeString? } 之一。
+ */
+
+interface NativeKeyDetail {
+  key?: string
+  keyCode?: number
+  keyCodeString?: string
+}
+
+// Android KeyEvent → DOM key 映射（覆盖最常见键）
+const ANDROID_TO_KEY: Record<number, string> = {
+  19: 'ArrowUp',
+  20: 'ArrowDown',
+  21: 'ArrowLeft',
+  22: 'ArrowRight',
+  23: 'Enter',
+  66: 'Enter',
+  4: 'Escape',
+  67: 'Backspace',
+}
+const KEY_STR_TO_KEY: Record<string, string> = {
+  KEYCODE_DPAD_UP: 'ArrowUp',
+  KEYCODE_DPAD_DOWN: 'ArrowDown',
+  KEYCODE_DPAD_LEFT: 'ArrowLeft',
+  KEYCODE_DPAD_RIGHT: 'ArrowRight',
+  KEYCODE_DPAD_CENTER: 'Enter',
+  KEYCODE_ENTER: 'Enter',
+  KEYCODE_BACK: 'Escape',
+  KEYCODE_DEL: 'Backspace',
+}
+const KEY_TO_CODE: Record<string, number> = {
+  ArrowUp: 38,
+  ArrowDown: 40,
+  ArrowLeft: 37,
+  ArrowRight: 39,
+  Enter: 13,
+  Escape: 27,
+  Backspace: 8,
+}
+
+function normalize(detail: NativeKeyDetail): { key: string; keyCode: number } | null {
+  let key = detail.key
+  if (!key && typeof detail.keyCodeString === 'string') {
+    key = KEY_STR_TO_KEY[detail.keyCodeString]
+  }
+  if (!key && typeof detail.keyCode === 'number') {
+    key = ANDROID_TO_KEY[detail.keyCode]
+  }
+  if (!key) return null
+  const keyCode = KEY_TO_CODE[key] ?? 0
+  return { key, keyCode }
+}
+
+let attachedEventName: string | null = null
+let handler: ((e: Event) => void) | null = null
+
+/**
+ * 构造一个等价的 KeyboardEvent。
+ *
+ * 为什么不在构造器里传 keyCode/which：Blink 全版本（含 Chromium 53 / Chrome 66）的
+ * KeyboardEvent 构造器都不读 KeyboardEventInit 里的 keyCode/which（它们是只读 legacy 属性，
+ * 不在 init 字典内），构造产物 evt.keyCode 恒为 0。而 SpatialNavigation.onKeyDown/onKeyUp
+ * 完全靠 evt.keyCode（37/38/39/40/13）路由方向键与确定键，keyCode=0 会导致全部失效。
+ * 必须构造后用 Object.defineProperty 在实例上加 own 属性 shadow 掉原型 getter，强制写入 keyCode/which。
+ */
+function makeKbEvent(type: 'keydown' | 'keyup', key: string, keyCode: number): KeyboardEvent {
+  let evt: any
+  try {
+    evt = new KeyboardEvent(type, { key, bubbles: true, cancelable: true })
+  } catch {
+    // 极旧内核无 KeyboardEvent 构造器时兜底
+    evt = document.createEvent('Event')
+    evt.initEvent(type, true, true)
+    Object.defineProperty(evt, 'key', { value: key, configurable: true })
+  }
+  Object.defineProperty(evt, 'keyCode', { value: keyCode, configurable: true })
+  Object.defineProperty(evt, 'which', { value: keyCode, configurable: true })
+  return evt as KeyboardEvent
+}
+
+/**
+ * 注册原生事件名监听器（如 'ott:native-keydown'），把它转为 keydown + keyup 派发到 window。
+ *
+ * 为什么成对派发：Android 壳 dispatchKeyEvent 只在 ACTION_DOWN 透传 onNativeKeyDown，
+ * 不发 ACTION_UP。但 focus-core 的 'enter-up' 事件挂在原生 keyup 上（spatial-navigation.ts onKeyUp），
+ * EButton/useFocusable 又只监听 'sn:enter-up'。只派 keydown 会导致 OK 键完全失活。
+ * 这里同步补一个 keyup，让 OTT 链路对外契约与浏览器键盘一致："按一次 = down+up 成对"。
+ *
+ * 重复调用会先卸载上一个监听。
+ */
+export function nativeKeyAdapter(eventName: string): () => void {
+  if (typeof window === 'undefined') return () => undefined
+  // 卸载旧的
+  if (attachedEventName && handler) {
+    window.removeEventListener(attachedEventName, handler as EventListener)
+  }
+  attachedEventName = eventName
+  handler = (e: Event) => {
+    const detail = ((e as CustomEvent).detail || {}) as NativeKeyDetail
+    const n = normalize(detail)
+    if (!n) return
+    window.dispatchEvent(makeKbEvent('keydown', n.key, n.keyCode))
+    window.dispatchEvent(makeKbEvent('keyup', n.key, n.keyCode))
+  }
+  window.addEventListener(eventName, handler as EventListener)
+  return () => {
+    if (attachedEventName && handler) {
+      window.removeEventListener(attachedEventName, handler as EventListener)
+      attachedEventName = null
+      handler = null
+    }
+  }
+}
+
+export default nativeKeyAdapter

package/src/layer-stack.ts

@@ -0,0 +1,18 @@
+/**
+ * 模态层计数器：FocusLayer 挂载 +1、卸载 -1。
+ * 供 @shell/core 的 useBackButton 判断「当前有无打开的模态层」，
+ * 有则把 Back 交给最上层弹层自己关，避免全局返回键误触发路由后退/退出。
+ */
+let openCount = 0
+
+export function pushLayer(): void {
+  openCount += 1
+}
+
+export function popLayer(): void {
+  openCount = Math.max(0, openCount - 1)
+}
+
+export function hasOpenLayer(): boolean {
+  return openCount > 0
+}

package/src/section-registry.ts

@@ -0,0 +1,21 @@
+/**
+ * 维护当前所有活跃 FocusSection 的 id 集合。
+ * 上游 SpatialNavigation 未暴露 listSections，FocusLayer 进入/离开时需要批量 disable/enable
+ * section，依赖此 registry 提供"哪些 section 当前存在"的信息。
+ */
+
+const activeSectionIds = new Set<string>()
+
+export function registerSection(id: string): void {
+  activeSectionIds.add(id)
+}
+
+export function unregisterSection(id: string): void {
+  activeSectionIds.delete(id)
+}
+
+export function listSections(): string[] {
+  const out: string[] = []
+  activeSectionIds.forEach((id) => out.push(id))
+  return out
+}

package/src/useFocusSection.ts

@@ -0,0 +1,61 @@
+import { inject, onMounted, onUnmounted, provide } from 'vue'
+import SpatialNavigation from './engine'
+import type { Restrict, EnterTo, LeaveFor, ExtSelector } from './engine'
+import { registerSection, unregisterSection } from './section-registry'
+import { FOCUS_LAYER_KEY, type FocusLayerContext } from './focus-layer-context'
+
+let sectionCounter = 0
+
+export interface UseFocusSectionOptions {
+  /** section id；未提供时自动生成 */
+  id?: string
+  /** 边界策略；默认 'self-first' */
+  restrict?: Restrict
+  /** 进入策略；默认 'last-focused' */
+  enterTo?: EnterTo
+  /** 跨方向跳转规则 */
+  leaveFor?: LeaveFor | null
+  /** 严格方向（无重叠时不跳）*/
+  straightOnly?: boolean
+  /** 离开后记忆来源焦点，默认 true */
+  rememberSource?: boolean
+  /** 进入 section 时默认聚焦的元素（CSS selector / Element） */
+  defaultElement?: ExtSelector
+}
+
+export interface FocusSectionContext {
+  sectionId: string
+  selectorAttr: string
+}
+
+export const FOCUS_SECTION_KEY: symbol = Symbol('dwy:focus-section')
+
+export function useFocusSection(options: UseFocusSectionOptions = {}): FocusSectionContext {
+  const sectionId = options.id ?? `dwy-section-${++sectionCounter}`
+  const selectorAttr = sectionId
+  const enclosingLayer = inject<FocusLayerContext | null>(FOCUS_LAYER_KEY, null)
+
+  onMounted(() => {
+    ;(SpatialNavigation as any).add(sectionId, {
+      selector: `[data-sn-section="${selectorAttr}"]`,
+      restrict: options.restrict ?? 'self-first',
+      enterTo: options.enterTo ?? 'last-focused',
+      leaveFor: options.leaveFor ?? null,
+      straightOnly: options.straightOnly ?? false,
+      rememberSource: options.rememberSource ?? true,
+      defaultElement: options.defaultElement,
+    })
+    registerSection(sectionId)
+    // 在 FocusLayer 内的 section 标记自己，避免被 layer 一并禁用
+    if (enclosingLayer) enclosingLayer.registerInnerSection(sectionId)
+  })
+
+  onUnmounted(() => {
+    ;(SpatialNavigation as any).remove(sectionId)
+    unregisterSection(sectionId)
+  })
+
+  const ctx: FocusSectionContext = { sectionId, selectorAttr }
+  provide(FOCUS_SECTION_KEY, ctx)
+  return ctx
+}

package/src/useFocusable.ts

@@ -0,0 +1,82 @@
+import { getCurrentInstance, inject, onMounted, onUnmounted, ref, shallowRef } from 'vue'
+import type { Ref } from 'vue'
+import { FOCUS_SECTION_KEY, type FocusSectionContext } from './useFocusSection'
+
+export interface UseFocusableOptions {
+  /** 业务侧 key，会写到 data-focus-key，便于调试与脚本聚焦 */
+  focusKey?: string
+  /** Enter/OK 键回调 */
+  onEnter?: () => void
+  /** 获得焦点 */
+  onFocus?: () => void
+  /** 失去焦点 */
+  onBlur?: () => void
+}
+
+export interface UseFocusableResult {
+  /** 绑定到 DOM 元素的 ref，必须接到 v-bind 或 ref="elRef" 上 */
+  elRef: Ref<HTMLElement | null>
+  /** 响应式焦点状态 */
+  focused: Ref<boolean>
+}
+
+/**
+ * 把当前 DOM 元素注册为可聚焦项，自动归属到最近的 useFocusSection。
+ *
+ * 必须在 useFocusSection 提供的 provide 作用域内调用——
+ * 通常表示组件树外层有 <FocusSection> 或调用过 useFocusSection。
+ */
+export function useFocusable(options: UseFocusableOptions = {}): UseFocusableResult {
+  const elRef = shallowRef<HTMLElement | null>(null)
+  const focused = ref(false)
+  const ctx = inject<FocusSectionContext | null>(FOCUS_SECTION_KEY, null)
+
+  function handleFocused() {
+    focused.value = true
+    if (options.onFocus) options.onFocus()
+  }
+  function handleUnfocused() {
+    focused.value = false
+    if (options.onBlur) options.onBlur()
+  }
+  function handleEnter() {
+    if (options.onEnter) options.onEnter()
+  }
+
+  onMounted(() => {
+    const el = elRef.value
+    if (!el) {
+      if (getCurrentInstance()) {
+        console.warn('[dwy:focus] useFocusable 的 elRef 未绑定到任何元素')
+      }
+      return
+    }
+    if (ctx) {
+      el.setAttribute('data-sn-section', ctx.selectorAttr)
+    } else {
+      console.warn('[dwy:focus] useFocusable 未找到外层 FocusSection；当前元素不会被纳入任何导航区域')
+    }
+    if (options.focusKey) {
+      el.setAttribute('data-focus-key', options.focusKey)
+    }
+    if (el.tabIndex < 0 && !el.getAttribute('tabindex')) {
+      el.setAttribute('tabindex', '-1')
+    }
+    el.addEventListener('sn:focused', handleFocused)
+    el.addEventListener('sn:unfocused', handleUnfocused)
+    el.addEventListener('sn:enter-up', handleEnter)
+    // 注：子 Focusable 的 onMounted 早于父 FocusSection 的 onMounted，
+    // 这里不再主动调用 makeFocusable —— tabindex 已在上一句自己加好，
+    // SpatialNavigation 在 navigate 时会按 selector 重新 query 到本元素。
+  })
+
+  onUnmounted(() => {
+    const el = elRef.value
+    if (!el) return
+    el.removeEventListener('sn:focused', handleFocused)
+    el.removeEventListener('sn:unfocused', handleUnfocused)
+    el.removeEventListener('sn:enter-up', handleEnter)
+  })
+
+  return { elRef, focused }
+}