Experimental: Quick Focus — Vimium-style keyboard shortcut overlay for focusable widgets

[AlphaFoxz]

Experimental: Quick Focus — Vimium-style Keyboard Shortcut Overlay

Concept

When no widget is currently focused, double-tapping the Space key activates a Quick Focus overlay — a Vimium-style shortcut hint rendered on top of each focusable widget. Pressing the displayed key instantly focuses that widget. This gives users a fast, keyboard-only way to jump to any focusable element without Tab-cycling.

Interaction Flow

1. No widget is focused → user double-taps Space (within ~300ms)
2. Plugin enumerates all focusable widgets in the scene
3. Each focusable widget gets a floating label (single character: a-z, 0-9) rendered at its top-left corner with a semi-transparent background
4. User presses the displayed key → corresponding widget receives focus, overlay disappears
5. Press Escape or any unmapped key → cancel overlay without focusing

Key Assignment Strategy

• Assign keys in order: a-z (26) + 0-9 (10) = 36 slots
• Assignment follows widget mount order (or tabIndex if available, depends on Focus infrastructure — focusable widget enumeration, tabIndex, and Tab/Shift+Tab navigation #32)
• If more than 36 focusable widgets exist, only label the first 36 (or paginate)
• Consider scoping to visible area only to reduce clutter

Rendering

• The overlay widget uses the highest zIndex in the scene to render on top
• Each label: drawRect (dim/inverse background) + drawText (single character)
• Terminal does not support true alpha — use ANSI dim/inverse styles to simulate semi-transparency
• Activating the overlay adds ~2 draw commands per focusable widget, negligible overhead

Architecture

extensions/src/widgets/quick-focus/
  ├── QuickFocusWidget.ts    # Main widget: state machine, overlay rendering
  └── types.ts               # Options type definitions

• Extension widget, imported via @buntui/extensions/quick-focus
• Listens to KeyboardEvent via event bus
• Maintains internal state: inactive | active | cancelled
• Reads focusable widget list from scene API (requires widget enumeration capability)

API

<script setup>
import QuickFocus from '@buntui/extensions/quick-focus'
</script>
<template>
  <QuickFocus trigger="double-space" />
</template>

Or programmatically:

import { createQuickFocus } from '@buntui/extensions/quick-focus'
const qf = createQuickFocus()
scene.mount(qf)

Dependencies

• Focus infrastructure — focusable widget enumeration, tabIndex, and Tab/Shift+Tab navigation #32 (Tab/Shift+Tab focus navigation): Quick Focus relies on the focusable widget list and tabIndex infrastructure that Focus infrastructure — focusable widget enumeration, tabIndex, and Tab/Shift+Tab navigation #32 will introduce. The scene must be able to enumerate focusable widgets in order.
• Scene API: Needs access to mounted widget list, widget positions, and focus state.

Sub-path Export

{
  "./quick-focus": {
    "types": "./dist/quick-focus.d.ts",
    "default": "./dist/quick-focus.js"
  }
}

---

实验性设想：Quick Focus — Vimium 风格的键盘快捷键覆盖层

概念

当没有任何 widget 获得焦点时，双击空格键激活 Quick Focus 覆盖层——在每个可聚焦 widget 上方渲染一个 Vimium 风格的快捷键标签。按下标签中显示的按键即可直接聚焦该 widget，无需 Tab 循环。

交互流程

1. 无 widget 获得焦点 → 用户双击空格（300ms 内）
2. 插件枚举 scene 中所有可聚焦 widget
3. 每个可聚焦 widget 在其左上角渲染一个浮动标签（单字符：a-z、0-9），带半透明背景
4. 用户按下显示的按键 → 对应 widget 获得焦点，覆盖层消失
5. 按 Escape 或未映射的按键 → 取消覆盖层

按键分配策略

• 分配顺序：a-z（26）+ 0-9（10）= 36 个槽位
• 按 widget 挂载顺序分配（若有 tabIndex 则按其排序，依赖 Focus infrastructure — focusable widget enumeration, tabIndex, and Tab/Shift+Tab navigation #32）
• 超过 36 个可聚焦 widget 时，只标记前 36 个（或分页）
• 可考虑仅标记可见区域内的 widget 以减少杂乱

渲染

• 覆盖层 widget 使用最高 zIndex 确保渲染在最上层
• 每个标签：drawRect（dim/inverse 背景）+ drawText（单字符）
• 终端不支持真正的透明度——使用 ANSI dim/inverse 样式模拟半透明效果
• 激活覆盖层时每个可聚焦 widget 增加约 2 条 draw command，开销可忽略

依赖

• Focus infrastructure — focusable widget enumeration, tabIndex, and Tab/Shift+Tab navigation #32（Tab/Shift+Tab 焦点导航）：Quick Focus 依赖 Focus infrastructure — focusable widget enumeration, tabIndex, and Tab/Shift+Tab navigation #32 引入的可聚焦 widget 列表和 tabIndex 基础设施。Scene 需要能够按顺序枚举可聚焦 widget。
• Scene API：需要访问已挂载 widget 列表、widget 位置和焦点状态。