@chancestv/tv-focus 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 chances
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The spatial-navigation engine in src/engine/ is forked from
+luke-chang/js-spatial-navigation and licensed under the Mozilla Public
+License 2.0. See src/engine/LICENSE and src/engine/ATTRIBUTION.md.

package/README.md

@@ -0,0 +1,52 @@
+# @chancestv/tv-focus
+
+面向低版本 WebView（Chromium 53+）的 Vue 3 TV 端空间导航焦点系统。遥控器方向键在 DOM 元素间按几何位置移动焦点，支持 section 分区、模态层栈、记忆焦点。
+
+核心导航引擎 fork 自 [luke-chang/js-spatial-navigation](https://github.com/luke-chang/js-spatial-navigation)（MPL-2.0）。
+
+## 安装
+
+```bash
+pnpm add @chancestv/tv-focus vue
+```
+
+## 用法
+
+```ts
+import { setupFocus, nativeKeyAdapter } from '@chancestv/tv-focus'
+
+// 应用入口调用一次
+setupFocus({ defaults: { rememberSource: true } })
+// 把 OTT 原生遥控器按键透传为合成 keydown/keyup
+nativeKeyAdapter('your-native-key-event-name')
+```
+
+```vue
+<script setup lang="ts">
+import { FocusSection, Focusable } from '@chancestv/tv-focus'
+</script>
+
+<template>
+  <FocusSection id="home">
+    <Focusable v-slot="{ focused }">
+      <div :class="{ active: focused }">item</div>
+    </Focusable>
+  </FocusSection>
+</template>
+```
+
+## 导出
+
+- 初始化：`setupFocus` / `nativeKeyAdapter` / `SpatialNavigation`
+- 组件：`Focusable` / `FocusSection` / `FocusLayer`
+- 组合式：`useFocusable` / `useFocusSection` / `useKeepAliveFocus`
+- 工具：`hasOpenLayer`
+- 类型：`Direction` / `Restrict` / `EnterTo` / `LeaveFor` / `SectionConfig` 等
+
+## 兼容目标
+
+产物语法降级到 `chrome53`。
+
+## License
+
+MIT AND MPL-2.0

package/dist/FocusLayer.vue.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 模态层：挂载时 disable layer 之外的所有 section、保存焦点；
+ * 卸载时 enable 回来并恢复焦点。
+ *
+ * 通过 provide 暴露 FocusLayerContext，子树中的 useFocusSection 会
+ * 把 sectionId 注册进来——避免子 section 被一并禁用。
+ *
+ * 子 section 的 mount 早于本组件 onMounted，因此 innerSectionIds 在
+ * 我们 onMounted 时已经收集齐全。
+ */
+interface Props {
+    id?: string;
+    tag?: string;
+}
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<Props> & Readonly<{}>, {
+    tag: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/FocusSection.vue.d.ts

@@ -0,0 +1,36 @@
+import { Restrict, EnterTo, LeaveFor } from './engine';
+interface Props {
+    id?: string;
+    restrict?: Restrict;
+    enterTo?: EnterTo;
+    leaveFor?: LeaveFor | null;
+    straightOnly?: boolean;
+    rememberSource?: boolean;
+    tag?: string;
+}
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {
+            sectionId: string;
+        }): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<Props> & Readonly<{}>, {
+    straightOnly: boolean;
+    rememberSource: boolean;
+    enterTo: EnterTo;
+    leaveFor: LeaveFor | null;
+    restrict: Restrict;
+    tag: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/Focusable.vue.d.ts

@@ -0,0 +1,42 @@
+interface Props {
+    /** 业务侧 key，便于调试和脚本聚焦（写到 data-focus-key） */
+    focusKey?: string;
+    /** 包装元素 tag，默认 div */
+    tag?: string;
+}
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {
+            focused: boolean;
+        }): any;
+    };
+    refs: {
+        elRef: unknown;
+    };
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<Props, {
+    elRef: import('vue').Ref<HTMLElement | null, HTMLElement | null>;
+    focused: import('vue').Ref<boolean, boolean>;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    blur: () => any;
+    focus: () => any;
+    enter: () => any;
+}, string, import('vue').PublicProps, Readonly<Props> & Readonly<{
+    onBlur?: (() => any) | undefined;
+    onFocus?: (() => any) | undefined;
+    onEnter?: (() => any) | undefined;
+}>, {
+    tag: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    elRef: unknown;
+}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/core.d.ts

@@ -0,0 +1,12 @@
+import { default as SpatialNavigation, SectionConfig } from './engine';
+export interface SetupFocusOptions {
+    /** 应用到 GlobalConfig 的默认配置（每个 section 可单独覆盖）*/
+    defaults?: Partial<SectionConfig>;
+}
+/**
+ * 初始化全局 SpatialNavigation。多次调用幂等。
+ *
+ * 在应用启动（main.ts）调用一次即可。
+ */
+export declare function setupFocus(options?: SetupFocusOptions): void;
+export { SpatialNavigation };

package/dist/engine/index.d.ts

@@ -0,0 +1,5 @@
+import { SpatialNavigationAPI } from './types';
+declare const SpatialNavigation: SpatialNavigationAPI;
+export default SpatialNavigation;
+export { SpatialNavigation };
+export * from './types';

package/dist/engine/spatial-navigation.d.ts

@@ -0,0 +1,19 @@
+/*******************/
+/*******************/
+declare var SpatialNavigation: {
+    init: () => void;
+    uninit: () => void;
+    clear: () => void;
+    set: () => void;
+    add: () => any;
+    remove: (sectionId: any) => boolean;
+    disable: (sectionId: any) => boolean;
+    enable: (sectionId: any) => boolean;
+    pause: () => void;
+    resume: () => void;
+    focus: (elem: any, silent: any) => boolean;
+    move: (direction: any, selector: any) => boolean;
+    makeFocusable: (sectionId: any) => void;
+    setDefaultSection: (sectionId: any) => void;
+};
+export default SpatialNavigation;

package/dist/engine/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @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/dist/focus-layer-context.d.ts

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

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @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';