@chancestv/tv-focus 0.3.0 → 0.4.1

package/README.md

@@ -1,51 +1,15 @@
 # @chancestv/tv-focus
 
-面向低版本 WebView（Chromium 53+）的 Vue 3 TV 端空间导航焦点系统。遥控器方向键在 DOM 元素间按几何位置移动焦点，支持 section 分区、模态层栈、记忆焦点。
+面向低版本 WebView（Chromium 53+）的 Vue 3 TV 端空间导航焦点系统。遥控器方向键按屏幕几何位置在元素间移动焦点，支持 section 分区、模态层栈、记忆焦点。
 
-核心导航引擎 fork 自 [luke-chang/js-spatial-navigation](https://github.com/luke-chang/js-spatial-navigation)（MPL-2.0）。
+> 业务层通常不直接使用本包，而是通过 [`@chancestv/tv-ui`](https://www.npmjs.com/package/@chancestv/tv-ui) 的组件使用。
 
-## 安装
+## 文档
 
-```bash
-pnpm add @chancestv/tv-focus vue
-```
+完整文档、安装、用法、API 与在线 Demo 见 GitHub 仓库（npm 页不再维护文档，以仓库为准）：
 
-## 用法
-
-```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`。
+- 仓库与文档：https://github.com/danweiyuancircle/chances-tv-kit
+- 在线 Demo（遥控器方向键操作）：https://danweiyuancircle.github.io/chances-tv-kit/
 
 ## License
 

package/dist/index.js

@@ -64,278 +64,172 @@ function getRect(elem) {
   rect.center.top = rect.center.bottom = rect.center.y;
   return rect;
 }
-function partition(rects, targetRect, straightOverlapThreshold) {
-  var groups = [[], [], [], [], [], [], [], [], []];
-  for (var i = 0; i < rects.length; i++) {
-    var rect = rects[i];
-    var center = rect.center;
-    var x, y, groupId;
-    if (center.x < targetRect.left) {
-      x = 0;
-    } else if (center.x <= targetRect.right) {
-      x = 1;
-    } else {
-      x = 2;
-    }
-    if (center.y < targetRect.top) {
-      y = 0;
-    } else if (center.y <= targetRect.bottom) {
-      y = 1;
-    } else {
-      y = 2;
-    }
-    groupId = y * 3 + x;
-    groups[groupId].push(rect);
-    if ([0, 2, 6, 8].indexOf(groupId) !== -1) {
-      var threshold = straightOverlapThreshold;
-      if (rect.left <= targetRect.right - targetRect.width * threshold) {
-        if (groupId === 2) {
-          groups[1].push(rect);
-        } else if (groupId === 8) {
-          groups[7].push(rect);
-        }
-      }
-      if (rect.right >= targetRect.left + targetRect.width * threshold) {
-        if (groupId === 0) {
-          groups[1].push(rect);
-        } else if (groupId === 6) {
-          groups[7].push(rect);
-        }
-      }
-      if (rect.top <= targetRect.bottom - targetRect.height * threshold) {
-        if (groupId === 6) {
-          groups[3].push(rect);
-        } else if (groupId === 8) {
-          groups[5].push(rect);
-        }
-      }
-      if (rect.bottom >= targetRect.top + targetRect.height * threshold) {
-        if (groupId === 0) {
-          groups[3].push(rect);
-        } else if (groupId === 2) {
-          groups[5].push(rect);
-        }
-      }
-    }
+function snMajorAxisDistanceRaw(direction, source, dest) {
+  switch (direction) {
+    case "left":
+      return source.left - dest.right;
+    case "right":
+      return dest.left - source.right;
+    case "up":
+      return source.top - dest.bottom;
+    case "down":
+      return dest.top - source.bottom;
+    default:
+      return 0;
   }
-  return groups;
 }
-function generateDistanceFunction(targetRect) {
-  return {
-    nearPlumbLineIsBetter: function(rect) {
-      var d;
-      if (rect.center.x < targetRect.center.x) {
-        d = targetRect.center.x - rect.right;
-      } else {
-        d = rect.left - targetRect.center.x;
-      }
-      return d < 0 ? 0 : d;
-    },
-    nearHorizonIsBetter: function(rect) {
-      var d;
-      if (rect.center.y < targetRect.center.y) {
-        d = targetRect.center.y - rect.bottom;
-      } else {
-        d = rect.top - targetRect.center.y;
-      }
-      return d < 0 ? 0 : d;
-    },
-    nearTargetLeftIsBetter: function(rect) {
-      var d;
-      if (rect.center.x < targetRect.center.x) {
-        d = targetRect.left - rect.right;
-      } else {
-        d = rect.left - targetRect.left;
-      }
-      return d < 0 ? 0 : d;
-    },
-    nearTargetTopIsBetter: function(rect) {
-      var d;
-      if (rect.center.y < targetRect.center.y) {
-        d = targetRect.top - rect.bottom;
-      } else {
-        d = rect.top - targetRect.top;
-      }
-      return d < 0 ? 0 : d;
-    },
-    topIsBetter: function(rect) {
-      return rect.top;
-    },
-    bottomIsBetter: function(rect) {
-      return -1 * rect.bottom;
-    },
-    leftIsBetter: function(rect) {
-      return rect.left;
-    },
-    rightIsBetter: function(rect) {
-      return -1 * rect.right;
-    }
-  };
+function snMajorAxisDistance(direction, source, dest) {
+  return Math.max(0, snMajorAxisDistanceRaw(direction, source, dest));
 }
-function prioritize(priorities) {
-  var destPriority = null;
-  for (var i = 0; i < priorities.length; i++) {
-    if (priorities[i].group.length) {
-      destPriority = priorities[i];
-      break;
-    }
+function snMajorAxisDistanceToFarEdgeRaw(direction, source, dest) {
+  switch (direction) {
+    case "left":
+      return source.left - dest.left;
+    case "right":
+      return dest.right - source.right;
+    case "up":
+      return source.top - dest.top;
+    case "down":
+      return dest.bottom - source.bottom;
+    default:
+      return 0;
   }
-  if (!destPriority) {
-    return null;
+}
+function snMajorAxisDistanceToFarEdge(direction, source, dest) {
+  return Math.max(1, snMajorAxisDistanceToFarEdgeRaw(direction, source, dest));
+}
+function snMinorAxisDistance(direction, source, dest) {
+  switch (direction) {
+    case "left":
+    case "right":
+      return Math.abs(source.center.y - dest.center.y);
+    case "up":
+    case "down":
+      return Math.abs(source.center.x - dest.center.x);
+    default:
+      return 0;
   }
-  var destDistance = destPriority.distance;
-  destPriority.group.sort(function(a, b) {
-    for (var i2 = 0; i2 < destDistance.length; i2++) {
-      var distance = destDistance[i2];
-      var delta = distance(a) - distance(b);
-      if (delta) {
-        return delta;
-      }
-    }
-    return 0;
-  });
-  return destPriority.group;
+}
+function snGetWeightedDistanceFor(major, minor) {
+  return 13 * major * major + minor * minor;
+}
+function snIsToDirectionOf(direction, source, dest) {
+  switch (direction) {
+    case "left":
+      return source.left >= dest.right;
+    case "right":
+      return source.right <= dest.left;
+    case "up":
+      return source.top >= dest.bottom;
+    case "down":
+      return source.bottom <= dest.top;
+    default:
+      return false;
+  }
+}
+function snIsCandidate(source, dest, direction) {
+  switch (direction) {
+    case "left":
+      return (source.right > dest.right || source.left >= dest.right) && source.left > dest.left;
+    case "right":
+      return (source.left < dest.left || source.right <= dest.left) && source.right < dest.right;
+    case "up":
+      return (source.bottom > dest.bottom || source.top >= dest.bottom) && source.top > dest.top;
+    case "down":
+      return (source.top < dest.top || source.bottom <= dest.top) && source.bottom < dest.bottom;
+    default:
+      return false;
+  }
+}
+function snBeamsOverlap(direction, rect1, rect2) {
+  switch (direction) {
+    case "left":
+    case "right":
+      return rect2.bottom >= rect1.top && rect2.top <= rect1.bottom;
+    case "up":
+    case "down":
+      return rect2.right >= rect1.left && rect2.left <= rect1.right;
+    default:
+      return false;
+  }
+}
+function snBeamBeats(direction, source, rect1, rect2) {
+  var r1In = snBeamsOverlap(direction, source, rect1);
+  var r2In = snBeamsOverlap(direction, source, rect2);
+  if (r2In || !r1In) {
+    return false;
+  }
+  if (!snIsToDirectionOf(direction, source, rect2)) {
+    return true;
+  }
+  if (direction === "left" || direction === "right") {
+    return true;
+  }
+  return snMajorAxisDistance(direction, source, rect1) < snMajorAxisDistanceToFarEdge(direction, source, rect2);
+}
+function snIsBetterCandidate(direction, source, rect1, rect2) {
+  if (!snIsCandidate(source, rect1, direction)) {
+    return false;
+  }
+  if (!snIsCandidate(source, rect2, direction)) {
+    return true;
+  }
+  if (snBeamBeats(direction, source, rect1, rect2)) {
+    return true;
+  }
+  if (snBeamBeats(direction, source, rect2, rect1)) {
+    return false;
+  }
+  return snGetWeightedDistanceFor(
+    snMajorAxisDistance(direction, source, rect1),
+    snMinorAxisDistance(direction, source, rect1)
+  ) < snGetWeightedDistanceFor(
+    snMajorAxisDistance(direction, source, rect2),
+    snMinorAxisDistance(direction, source, rect2)
+  );
 }
 function navigate(target, direction, candidates, config, preferNearest) {
   if (!target || !direction || !candidates || !candidates.length) {
     return null;
   }
+  var targetRect = getRect(target);
+  if (!targetRect) {
+    return null;
+  }
   var rects = [];
   for (var i = 0; i < candidates.length; i++) {
-    var rect = getRect(candidates[i]);
-    if (rect) {
-      rects.push(rect);
+    var r = getRect(candidates[i]);
+    if (!r) {
+      continue;
+    }
+    if (!snIsCandidate(targetRect, r, direction)) {
+      continue;
+    }
+    if (config.straightOnly && !snBeamsOverlap(direction, targetRect, r)) {
+      continue;
     }
+    rects.push(r);
   }
   if (!rects.length) {
     return null;
   }
-  var targetRect = getRect(target);
-  if (!targetRect) {
-    return null;
-  }
-  var distanceFunction = generateDistanceFunction(targetRect);
-  var groups = partition(
-    rects,
-    targetRect,
-    config.straightOverlapThreshold
-  );
-  var internalGroups = partition(
-    groups[4],
-    targetRect.center,
-    config.straightOverlapThreshold
-  );
-  var priorities;
-  var df = distanceFunction;
-  var internalGroup, straightGroup, diagonalGroups;
-  var internalDist, straightDist, diagonalDist, mergedDist;
-  switch (direction) {
-    case "left":
-      internalGroup = internalGroups[0].concat(internalGroups[3]).concat(internalGroups[6]);
-      straightGroup = groups[3];
-      diagonalGroups = groups[0].concat(groups[6]);
-      internalDist = [df.nearPlumbLineIsBetter, df.topIsBetter];
-      straightDist = [df.nearPlumbLineIsBetter, df.topIsBetter];
-      diagonalDist = [
-        df.nearHorizonIsBetter,
-        df.rightIsBetter,
-        df.nearTargetTopIsBetter
-      ];
-      mergedDist = [
-        df.nearPlumbLineIsBetter,
-        df.nearHorizonIsBetter,
-        df.topIsBetter
-      ];
-      break;
-    case "right":
-      internalGroup = internalGroups[2].concat(internalGroups[5]).concat(internalGroups[8]);
-      straightGroup = groups[5];
-      diagonalGroups = groups[2].concat(groups[8]);
-      internalDist = [df.nearPlumbLineIsBetter, df.topIsBetter];
-      straightDist = [df.nearPlumbLineIsBetter, df.topIsBetter];
-      diagonalDist = [
-        df.nearHorizonIsBetter,
-        df.leftIsBetter,
-        df.nearTargetTopIsBetter
-      ];
-      mergedDist = [
-        df.nearPlumbLineIsBetter,
-        df.nearHorizonIsBetter,
-        df.topIsBetter
-      ];
-      break;
-    case "up":
-      internalGroup = internalGroups[0].concat(internalGroups[1]).concat(internalGroups[2]);
-      straightGroup = groups[1];
-      diagonalGroups = groups[0].concat(groups[2]);
-      internalDist = [df.nearHorizonIsBetter, df.leftIsBetter];
-      straightDist = [df.nearHorizonIsBetter, df.leftIsBetter];
-      diagonalDist = [
-        df.nearPlumbLineIsBetter,
-        df.bottomIsBetter,
-        df.nearTargetLeftIsBetter
-      ];
-      mergedDist = [
-        df.nearHorizonIsBetter,
-        df.nearPlumbLineIsBetter,
-        df.leftIsBetter
-      ];
-      break;
-    case "down":
-      internalGroup = internalGroups[6].concat(internalGroups[7]).concat(internalGroups[8]);
-      straightGroup = groups[7];
-      diagonalGroups = groups[6].concat(groups[8]);
-      internalDist = [df.nearHorizonIsBetter, df.leftIsBetter];
-      straightDist = [df.nearHorizonIsBetter, df.leftIsBetter];
-      diagonalDist = [
-        df.nearPlumbLineIsBetter,
-        df.topIsBetter,
-        df.nearTargetLeftIsBetter
-      ];
-      mergedDist = [
-        df.nearHorizonIsBetter,
-        df.nearPlumbLineIsBetter,
-        df.leftIsBetter
-      ];
-      break;
-    default:
-      return null;
-  }
-  if (preferNearest) {
-    priorities = [
-      { group: internalGroup, distance: internalDist },
-      {
-        group: config.straightOnly ? straightGroup : straightGroup.concat(diagonalGroups),
-        distance: mergedDist
-      }
-    ];
-  } else {
-    priorities = [
-      { group: internalGroup, distance: internalDist },
-      { group: straightGroup, distance: straightDist },
-      { group: diagonalGroups, distance: diagonalDist }
-    ];
-    if (config.straightOnly) {
-      priorities.pop();
+  var best = rects[0];
+  for (var k = 1; k < rects.length; k++) {
+    if (snIsBetterCandidate(direction, targetRect, rects[k], best)) {
+      best = rects[k];
     }
   }
-  var destGroup = prioritize(priorities);
-  if (!destGroup) {
-    return null;
-  }
-  var dest = null;
   if (config.rememberSource && config.previous && config.previous.destination === target && config.previous.reverse === direction) {
-    for (var j = 0; j < destGroup.length; j++) {
-      if (destGroup[j].element === config.previous.target) {
-        dest = destGroup[j].element;
+    for (var j = 0; j < rects.length; j++) {
+      if (rects[j].element === config.previous.target) {
+        if (!snIsBetterCandidate(direction, targetRect, best, rects[j])) {
+          return rects[j].element;
+        }
         break;
       }
     }
   }
-  if (!dest) {
-    dest = destGroup[0].element;
-  }
-  return dest;
+  return best.element;
 }
 function generateId() {
   var id;
@@ -615,7 +509,7 @@ function getScrollScope(elem) {
 }
 function navigateWithinScrollScope(target, direction, candidates, config, preferNearest) {
   if (!candidates || candidates.length < 2) {
-    return navigate(target, direction, candidates, config, preferNearest);
+    return navigate(target, direction, candidates, config);
   }
   var targetScope = getScrollScope(target);
   var inScope = [];
@@ -628,9 +522,60 @@ function navigateWithinScrollScope(target, direction, candidates, config, prefer
     }
   }
   if (inScope.length && outScope.length) {
-    return navigate(target, direction, inScope, config, preferNearest) || navigate(target, direction, outScope, config, preferNearest);
+    return navigate(target, direction, inScope, config) || navigate(target, direction, outScope, config);
+  }
+  return navigate(target, direction, candidates, config);
+}
+function filterCandidatesByDirection(source, direction, sectionNavMap, excludeSectionId) {
+  var srcRect = getRect(source);
+  var kept = [];
+  for (var id in sectionNavMap) {
+    if (id === excludeSectionId) {
+      continue;
+    }
+    var elems = sectionNavMap[id];
+    if (!elems || !elems.length) {
+      continue;
+    }
+    var left = Infinity, top = Infinity, right = -Infinity, bottom = -Infinity;
+    var rects = [];
+    for (var i = 0; i < elems.length; i++) {
+      var r = getRect(elems[i]);
+      if (!r) {
+        continue;
+      }
+      rects.push(r);
+      if (r.left < left) {
+        left = r.left;
+      }
+      if (r.top < top) {
+        top = r.top;
+      }
+      if (r.right > right) {
+        right = r.right;
+      }
+      if (r.bottom > bottom) {
+        bottom = r.bottom;
+      }
+    }
+    if (!rects.length) {
+      continue;
+    }
+    var unionRect = {
+      left,
+      top,
+      right,
+      bottom,
+      width: right - left,
+      height: bottom - top
+    };
+    if (snIsCandidate(srcRect, unionRect, direction)) {
+      for (var j = 0; j < rects.length; j++) {
+        kept.push(rects[j].element);
+      }
+    }
   }
-  return navigate(target, direction, candidates, config, preferNearest);
+  return kept;
 }
 function focusNext(direction, currentFocusedElement, currentSectionId) {
   var extSelector = currentFocusedElement.getAttribute("data-sn-" + direction);
@@ -658,12 +603,23 @@ function focusNext(direction, currentFocusedElement, currentSectionId) {
       config
     );
     if (!next && config.restrict == "self-first") {
+      var prunedCandidates = filterCandidatesByDirection(
+        currentFocusedElement,
+        direction,
+        sectionNavigableElements,
+        currentSectionId
+      );
+      if (!prunedCandidates.length) {
+        prunedCandidates = exclude(
+          allNavigableElements,
+          currentSectionNavigableElements
+        );
+      }
       next = navigateWithinScrollScope(
         currentFocusedElement,
         direction,
-        exclude(allNavigableElements, currentSectionNavigableElements),
-        config,
-        true
+        prunedCandidates,
+        config
       );
     }
   } else {
@@ -671,8 +627,7 @@ function focusNext(direction, currentFocusedElement, currentSectionId) {
       currentFocusedElement,
       direction,
       exclude(allNavigableElements, currentFocusedElement),
-      config,
-      false
+      config
     );
   }
   if (next) {