@yodaos-pkg/ink 0.16.0 → 0.16.1

package/README.md

@@ -297,7 +297,11 @@ Binds common DOM events to the current `InkView`.
   - The keyboard event target, defaulting to `window` when available
 - `options.focusTarget?: HTMLElement | HTMLCanvasElement | null`
   - Optional
-  - The target used for focus and blur events, defaulting to the canvas
+  - The target used for focus synchronization when `syncFocus` is enabled, defaulting to the canvas
+- `options.syncFocus?: boolean`
+  - Optional
+  - Controls whether DOM `focus` / `blur` and click-to-focus are synchronized into Ink host focus
+  - Defaults to `false`
 - `options.preventWheelDefault?: boolean`
   - Optional
   - Controls whether wheel default behavior is prevented
@@ -308,7 +312,7 @@ Binds common DOM events to the current `InkView`.
 - Binds `pointerdown` / `pointermove` / `pointerup` / `pointercancel`
 - Binds `wheel`
 - Binds `keydown` / `keyup`
-- Binds `focus` / `blur`
+- Optionally binds `focus` / `blur` when `syncFocus` is enabled
 - Automatically forwards these browser events into the Ink runtime
 
 **Returns**

package/index.d.ts

@@ -310,8 +310,50 @@ export interface BindDomEventsOptions {
   canvas?: HTMLCanvasElement;
   /** Keyboard event target, typically `window`, `document`, or a focusable element. */
   keyboardTarget?: EventTarget | null;
-  /** Element that should receive focus/blur synchronization for the Ink instance. */
+  /**
+   * DOM element used as the focus signal source when `syncFocus` is enabled.
+   *
+   * When enabled, Ink listens to this element's native `focus` and `blur`
+   * events and forwards them to `inkView.focus()` and `inkView.blur()`.
+   * `pointerdown` on the canvas also attempts to call `focus()` on this target.
+   *
+   * This option is useful when the host does not want the canvas itself to be
+   * the browser-focused element. For example, a host may keep keyboard focus on
+   * an outer wrapper element while still rendering Ink inside a nested canvas.
+   *
+   * Important: this follows the target element's own `focus` / `blur` state,
+   * not a container-style "focus within" semantic. If focus moves from this
+   * element to another focusable node, such as an external `<input>`, Ink will
+   * observe that blur when `syncFocus` is enabled.
+   *
+   * Defaults to the currently bound canvas.
+   */
   focusTarget?: HTMLElement | HTMLCanvasElement | null;
+  /**
+   * Enables automatic synchronization from browser DOM focus to Ink host focus.
+   *
+   * When set to `true`, `bindDomEvents()` treats the browser focus state as the
+   * source of truth for host focus:
+   * - listens to `focusTarget`'s `focus` / `blur` events
+   * - calls `inkView.focus()` / `inkView.blur()` automatically
+   * - attempts click-to-focus on `pointerdown`
+   * - makes the `focusTarget` focusable with `tabindex="0"` when needed
+   *
+   * When set to `false`, `bindDomEvents()` still binds pointer, wheel, and
+   * keyboard events, but it does not change Ink host focus automatically. In
+   * that mode, the host should call `inkView.focus()` and `inkView.blur()`
+   * explicitly based on product-level lifecycle or visibility state.
+   *
+   * Recommended usage:
+   * - Use `true` only when the host really wants DOM focus to directly control
+   *   Ink host focus.
+   * - Keep `false` when browser focus may temporarily move to another element,
+   *   such as a sibling or external `<input>`, while the Ink instance should
+   *   still remain host-focused.
+   *
+   * Defaults to `false`.
+   */
+  syncFocus?: boolean;
   /** Whether wheel events should call `preventDefault()` before forwarding. */
   preventWheelDefault?: boolean;
 }

package/index.js

@@ -1929,6 +1929,7 @@ export class InkView {
 
     const keyboardTarget = options.keyboardTarget || globalThis.window || canvas;
     const focusTarget = options.focusTarget || canvas;
+    const syncFocus = options.syncFocus === true;
     const listeners = [];
     const addListener = (target, type, listener, listenerOptions) => {
       if (!target || typeof target.addEventListener !== 'function') {
@@ -1938,7 +1939,12 @@ export class InkView {
       listeners.push(() => target.removeEventListener(type, listener, listenerOptions));
     };
 
-    if (focusTarget && typeof focusTarget.setAttribute === 'function' && focusTarget.tabIndex < 0) {
+    if (
+      syncFocus &&
+      focusTarget &&
+      typeof focusTarget.setAttribute === 'function' &&
+      focusTarget.tabIndex < 0
+    ) {
       focusTarget.setAttribute('tabindex', '0');
     }
 
@@ -1955,7 +1961,7 @@ export class InkView {
     addListener(canvas, 'pointerdown', (event) => {
       const { x, y } = getPointerPosition(canvas, event);
       this.notifyUserInteraction();
-      if (focusTarget && typeof focusTarget.focus === 'function') {
+      if (syncFocus && focusTarget && typeof focusTarget.focus === 'function') {
         focusTarget.focus();
       }
       this.#rawView.dispatchPointer(
@@ -2039,12 +2045,14 @@ export class InkView {
       );
       this.requestRender();
     });
-    addListener(focusTarget, 'focus', () => {
-      this.focus();
-    });
-    addListener(focusTarget, 'blur', () => {
-      this.blur();
-    });
+    if (syncFocus) {
+      addListener(focusTarget, 'focus', () => {
+        this.focus();
+      });
+      addListener(focusTarget, 'blur', () => {
+        this.blur();
+      });
+    }
 
     this.#domCleanup = () => {
       for (const dispose of listeners.splice(0)) {

package/package.json

@@ -10,7 +10,7 @@
     "access": "public",
     "registry": "https://registry.npmjs.com/"
   },
-  "version": "0.16.0",
+  "version": "0.16.1",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",