@silo-code/sdk 0.51.0 → 0.53.0

package/src/use-panel-entry-focus.test.ts

@@ -0,0 +1,244 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { retryFocus } from "./use-panel-entry-focus";
+
+// The retry is the whole substance of `usePanelEntryFocus` — the hook around it
+// is two subscriptions and a guard. Per the repo testing guide we drive the
+// logic directly rather than rendering React: `requestAnimationFrame` is
+// replaced with a hand-pumped queue so every frame is deterministic. This file
+// opts into jsdom (the SDK's suite is node by default) because the retry reads
+// the live `document.activeElement` to decide whether focus fell to nothing or
+// moved somewhere it must not be yanked back from.
+describe("retryFocus", () => {
+  let queue: FrameRequestCallback[] = [];
+  let origRaf: typeof globalThis.requestAnimationFrame;
+
+  beforeEach(() => {
+    queue = [];
+    origRaf = globalThis.requestAnimationFrame;
+    globalThis.requestAnimationFrame = ((cb: FrameRequestCallback) =>
+      queue.push(cb)) as typeof globalThis.requestAnimationFrame;
+    document.body.innerHTML = "";
+  });
+  afterEach(() => {
+    globalThis.requestAnimationFrame = origRaf;
+  });
+
+  /** Run exactly one scheduled frame (ticks queued during it run on the next flush). */
+  function flushFrame() {
+    const due = queue;
+    queue = [];
+    for (const cb of due) cb(0);
+  }
+
+  it("stops re-grabbing focus once it is no longer wanted (the region-cycle race)", () => {
+    const focus = vi.fn();
+    let wanted = true;
+    // Never reports focused, so without the guard it would grab every frame.
+    retryFocus(
+      focus,
+      () => false,
+      () => wanted,
+    );
+
+    flushFrame(); // wanted → grabs once
+    expect(focus).toHaveBeenCalledTimes(1);
+
+    wanted = false; // a newer focus intent superseded us
+    flushFrame(); // must bail BEFORE grabbing
+    flushFrame();
+    expect(focus).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-grabs each frame until focus lands, then stops grabbing", () => {
+    const focus = vi.fn();
+    let focused = false;
+    retryFocus(
+      focus,
+      () => focused,
+      () => true,
+    );
+
+    flushFrame(); // not focused → grab
+    flushFrame(); // still not focused → grab
+    expect(focus).toHaveBeenCalledTimes(2);
+
+    focused = true;
+    flushFrame(); // landed → no further grab
+    expect(focus).toHaveBeenCalledTimes(2);
+  });
+
+  // Regression guard for symptom 1 (ADR 0034): a panel that merely re-mounts
+  // in the background — which happens to every panel of a workspace whose dock
+  // becomes visible again — must not grab focus from the tab the user actually
+  // left active. `stillWanted` is required precisely so a mount-time caller
+  // can't silently omit it and grab unconditionally.
+  it("never grabs on mount when the panel is not the active tab", () => {
+    const focus = vi.fn();
+    let isActive = false; // this panel re-mounted in the background
+    retryFocus(
+      focus,
+      () => false, // never reports focused → would grab every frame if unguarded
+      () => isActive,
+    );
+
+    flushFrame();
+    flushFrame();
+    expect(focus).not.toHaveBeenCalled();
+
+    // …and it stays bailed even if the panel becomes active later: the loop
+    // ended, so activation focus is the active tab's own concern, not a
+    // stale mount-time retry's.
+    isActive = true;
+    flushFrame();
+    expect(focus).not.toHaveBeenCalled();
+  });
+
+  it("never grabs when superseded before the first frame", () => {
+    const focus = vi.fn();
+    retryFocus(
+      focus,
+      () => false,
+      () => false,
+    );
+    flushFrame();
+    expect(focus).not.toHaveBeenCalled();
+  });
+
+  it("gives up after the frame cap so it never loops forever", () => {
+    const focus = vi.fn();
+    retryFocus(
+      focus,
+      () => false, // focus can never land (panel hidden, content disabled, …)
+      () => true,
+      3,
+    );
+
+    for (let i = 0; i < 10; i++) flushFrame();
+    expect(focus).toHaveBeenCalledTimes(3);
+    expect(queue).toHaveLength(0);
+  });
+
+  it("re-grabs after landing only when focus fell to nothing", () => {
+    const focus = vi.fn();
+    let focused = true; // landed on the first frame
+    retryFocus(
+      focus,
+      () => focused,
+      () => true,
+    );
+
+    flushFrame(); // landed → no grab
+    expect(focus).not.toHaveBeenCalled();
+
+    // dockview's show/hide shuffle bounced focus off the content onto nothing.
+    focused = false;
+    flushFrame();
+    expect(focus).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not yank focus back from another real element after it landed", () => {
+    const other = document.createElement("input");
+    document.body.append(other);
+    other.focus();
+
+    const focus = vi.fn();
+    let focused = true;
+    retryFocus(
+      focus,
+      () => focused,
+      () => true,
+    );
+
+    flushFrame(); // landed
+    focused = false; // the user moved on to `other` — not "lost to nothing"
+    flushFrame();
+    flushFrame();
+    expect(focus).not.toHaveBeenCalled();
+  });
+
+  describe("open menus", () => {
+    /** Focus a menu-like element and run one frame of a never-landing retry. */
+    function grabsWhileFocusedIn(menu: HTMLElement): boolean {
+      document.body.append(menu);
+      menu.tabIndex = -1;
+      menu.focus();
+      const focus = vi.fn();
+      retryFocus(
+        focus,
+        () => false,
+        () => true,
+      );
+      flushFrame();
+      return focus.mock.calls.length > 0;
+    }
+
+    // Right-clicking an *inactive* panel activates it, which starts the retry;
+    // without this guard the per-frame `focus()` steals focus from the menu
+    // that same click just opened and the menu flashes shut.
+    it("stands down for a Silo menu (ctx.ui.showMenu)", () => {
+      const menu = document.createElement("div");
+      menu.setAttribute("data-silo-menu", "tree-1");
+      menu.setAttribute("role", "menu");
+      expect(grabsWhileFocusedIn(menu)).toBe(false);
+    });
+
+    it("stands down for a Monaco context menu", () => {
+      const menu = document.createElement("div");
+      menu.className = "context-view";
+      expect(grabsWhileFocusedIn(menu)).toBe(false);
+    });
+
+    // Monaco renders its context menu into a shadow root, so from the light DOM
+    // `document.activeElement` is only the host element — the menu nodes live
+    // one level down, which is why a plain `closest` isn't enough.
+    it("stands down for a menu inside a shadow root", () => {
+      const host = document.createElement("div");
+      document.body.append(host);
+      const shadow = host.attachShadow({ mode: "open" });
+      const menu = document.createElement("div");
+      menu.className = "monaco-menu";
+      shadow.append(menu);
+      host.tabIndex = -1;
+      host.focus();
+
+      const focus = vi.fn();
+      retryFocus(
+        focus,
+        () => false,
+        () => true,
+      );
+      flushFrame();
+      expect(focus).not.toHaveBeenCalled();
+    });
+
+    it("ends the loop rather than resuming once the menu closes", () => {
+      const menu = document.createElement("div");
+      menu.setAttribute("data-silo-menu", "tree-1");
+      menu.tabIndex = -1;
+      document.body.append(menu);
+      menu.focus();
+
+      const focus = vi.fn();
+      retryFocus(
+        focus,
+        () => false,
+        () => true,
+      );
+      flushFrame(); // bails
+      expect(queue).toHaveLength(0);
+
+      // Nothing rescheduled: the menu's owner restores content focus itself.
+      menu.remove();
+      flushFrame();
+      expect(focus).not.toHaveBeenCalled();
+    });
+
+    it("still grabs when focus is merely on the body, not a menu", () => {
+      const plain = document.createElement("div");
+      expect(grabsWhileFocusedIn(plain)).toBe(true);
+    });
+  });
+});

package/src/use-panel-entry-focus.ts

@@ -0,0 +1,237 @@
+import { useCallback, useEffect, useRef } from "react";
+import type { DockPanelApi } from "./types";
+
+// Entry focus for a dock panel — landing the caret in the panel's content when
+// the user enters it.
+//
+// A freshly-mounted or newly-activated dock panel does NOT reliably inherit DOM
+// focus: dockview runs its own focus shuffle when panels mount/activate, and
+// rich content (Monaco, xterm) only accepts focus once its internal textarea
+// has been laid out with non-zero dimensions. A single `focus()` call loses
+// these races, which is why a panel would otherwise need a second click before
+// you can type. We retry across animation frames until the target actually
+// reports focus, the panel is no longer the one we wanted to focus, or we hit a
+// frame cap (~330ms) so we never loop forever when focus legitimately can't be
+// grabbed (panel hidden, content disabled, etc.).
+
+const DEFAULT_CAP = 20;
+
+// Every menu implementation whose open state must suppress the retry: Silo's
+// own menus (`ctx.ui.showMenu`, which renders `[data-silo-menu]` with
+// `role="menu"`), a third-party menu that follows the same ARIA role, and
+// Monaco's context menu (`.context-view` / `.monaco-menu`).
+const MENU_SELECTOR =
+  '[data-silo-menu], [role="menu"], .context-view, .monaco-menu';
+
+/**
+ * Whether focus currently sits inside an open floating menu. Monaco renders its
+ * context menu into a shadow root, where `document.activeElement` resolves only
+ * to the open `shadow-root-host` and the menu nodes hang off its `shadowRoot` —
+ * hence the shadow peek, not just a light-DOM `closest`.
+ */
+function focusInMenu(active: Element | null): boolean {
+  if (!active) return false;
+  if (active.closest(MENU_SELECTOR)) return true;
+  return active.shadowRoot?.querySelector(MENU_SELECTOR) != null;
+}
+
+/**
+ * Repeatedly call `focus()` on successive animation frames until `isFocused()`
+ * returns true, `stillWanted()` returns false, or `cap` frames have elapsed.
+ *
+ * `stillWanted` is **required**, and must express "this panel is still the one
+ * that should hold focus" — normally `() => api.isActive`, or the center
+ * dock's focus-intent token (`focusGen`). It is deliberately not optional: a
+ * retry loop without it keeps grabbing focus for its entire frame budget no
+ * matter what else happened meanwhile. That matters most on *mount*, because
+ * re-entering a workspace re-mounts its panels — so an unguarded mount-time
+ * grab in a background tab yanks focus away from the tab the user actually
+ * left active. And because DOM focus landing inside a dockview panel makes
+ * dockview mark that panel's group active
+ * (`contentContainer.onDidFocus → doSetGroupActive`), stealing focus silently
+ * changes the visible active tab too. That was symptom 1 in ADR 0034.
+ *
+ * Panel content should reach for {@link usePanelEntryFocus} instead, which
+ * supplies the guard and both entry subscriptions for you. This raw form is
+ * host/`core.*` plumbing for the non-React callers that can't.
+ *
+ * @internal
+ */
+export function retryFocus(
+  focus: () => void,
+  isFocused: () => boolean,
+  stillWanted: () => boolean,
+  cap = DEFAULT_CAP,
+): void {
+  let attempts = 0;
+  let landed = false;
+  const tick = () => {
+    // Bail before touching focus if we're no longer wanted — a newer focus
+    // intent superseded us (e.g. the user kept pressing the region-cycle chord).
+    // Checked here, not just after the grab below, so a stale retry can't yank
+    // focus back from the area the user actually moved to.
+    if (!stillWanted()) return;
+    attempts += 1;
+    if (isFocused()) {
+      landed = true;
+    } else {
+      // Before focus first lands, grab aggressively each frame — Monaco/xterm
+      // only accept focus once their textarea is laid out, so early calls lose.
+      // After it has landed, only re-grab if focus fell to NOTHING (<body>/null):
+      // dockview's show/hide shuffle can bounce focus off the just-focused
+      // content a frame or two later (the "keystrokes dropped after a switch"
+      // symptom). We watch the full frame budget to catch that — but never yank
+      // focus away from another real element the user may have moved to.
+      const active = document.activeElement;
+      // Focus legitimately moved into an open context menu — don't yank it
+      // back, or the menu's focus-out dismiss fires and it flashes shut.
+      // Right-clicking an *inactive* panel activates it, which starts this
+      // retry; without the guard the per-frame `focus()` steals focus from the
+      // just-opened menu (the focused case never starts the retry, which is why
+      // the bug only shows when the panel was unfocused). End the loop: the
+      // menu's owner restores content focus itself once the menu closes.
+      if (focusInMenu(active)) return;
+      const lostToNothing = active === null || active === document.body;
+      if (!landed || lostToNothing) focus();
+    }
+    if (attempts >= cap || !stillWanted()) return;
+    requestAnimationFrame(tick);
+  };
+  requestAnimationFrame(tick);
+}
+
+/**
+ * The content {@link usePanelEntryFocus} drives — how to focus it, how to tell
+ * whether it already has focus, and optionally how to release it.
+ *
+ * All three are called through a latest-ref, so inline closures over props or
+ * state are always current; you never need to memoize them.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface PanelEntryFocusTarget {
+  /**
+   * Imperatively focus the panel's content — e.g. `() => inputRef.current?.focus()`
+   * or `() => editor.focus()`. Safe to make a no-op while the content isn't
+   * ready to take focus; the retry simply expires.
+   */
+  focus: () => void;
+  /**
+   * Whether the content holds DOM keyboard focus **right now**, so the retry
+   * can stop as soon as it lands instead of burning the whole frame budget.
+   *
+   * Read the live `document.activeElement` — e.g.
+   * `() => document.activeElement === inputRef.current`. Don't trust a
+   * library's own tracker flag (Monaco's `hasTextFocus()`, say): those go
+   * stale-true when a blur is dropped during dockview's show/hide shuffle,
+   * which stops the retry believing focus landed when it didn't.
+   */
+  isFocused: () => boolean;
+  /**
+   * Release the content's focus when the panel's tab is deactivated. Only
+   * needed for content that tracks its own focus state internally — a Monaco
+   * editor or an xterm terminal is kept alive (hidden) while its tab is
+   * inactive, and if its tracker stays stuck believing it has focus it will
+   * steal keystrokes meant for the tab you switched to. A plain input needs
+   * nothing here.
+   */
+  blur?: () => void;
+}
+
+/**
+ * Land keyboard focus in a dock panel's content whenever the user enters the
+ * panel, winning dockview's focus shuffle — and, symmetrically, release it when
+ * the panel's tab is deactivated.
+ *
+ * A panel that puts the cursor somewhere on entry (a chat composer, a search
+ * box, an editor) needs three things that are easy to get individually wrong,
+ * and this hook is all three in one call:
+ *
+ * 1. **Both entry signals.** {@link DockPanelApi.onDidActiveChange} covers real
+ *    activations. {@link DockPanelApi.onDidRequestFocus} covers a click on a
+ *    tab that was *already* active — dockview treats that as a complete no-op
+ *    and fires no active-change event, even though it is the commonest way a
+ *    user asks for the cursor back (they were typing in a side panel, clicked
+ *    the status bar, then clicked your tab).
+ * 2. **A guard.** Focus is only ever taken while the panel is the active one.
+ *    Mount is not "the user just created this panel" — re-entering a workspace
+ *    re-mounts every panel in its dock — and DOM focus landing in a panel makes
+ *    dockview activate its group, so an unguarded grab silently changes the
+ *    visible tab (ADR 0034).
+ * 3. **A retry.** A single `focus()` loses dockview's shuffle, and rich content
+ *    only accepts focus once its internal textarea is laid out. The hook
+ *    retries across frames until focus lands, standing down if the panel stops
+ *    being active or focus moves into an open context menu.
+ *
+ * ```tsx
+ * function AcmeChatPanel({ api }: DockPanelProps) {
+ *   const input = useRef<HTMLTextAreaElement | null>(null);
+ *
+ *   usePanelEntryFocus(api, {
+ *     focus: () => input.current?.focus(),
+ *     isFocused: () => document.activeElement === input.current,
+ *   });
+ *
+ *   return <textarea ref={input} />;
+ * }
+ * ```
+ *
+ * The returned function runs the same guarded retry on demand, for content that
+ * becomes focusable at a moment that is neither a mount nor an activation — a
+ * session finishing its connect, an editor finishing its own mount. It is
+ * referentially stable, so it is safe in a dependency array:
+ *
+ * ```tsx
+ * const focusComposer = usePanelEntryFocus(api, { focus, isFocused });
+ *
+ * useEffect(() => {
+ *   if (ready) focusComposer();
+ * }, [ready, focusComposer]);
+ * ```
+ *
+ * @param api - The surrounding panel's api ({@link DockPanelProps.api}).
+ * @param target - How to focus, test, and release the panel's content.
+ * @returns A stable callback that runs the guarded focus retry on demand.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function usePanelEntryFocus(
+  api: DockPanelApi,
+  target: PanelEntryFocusTarget,
+): () => void {
+  // Read the callbacks through a ref rather than closing over them: the
+  // subscription effect depends on `api` alone (re-subscribing every render
+  // would be worse), so a captured `target` would freeze at its first render
+  // and an author's inline `() => { if (enabled) … }` would go stale.
+  const latest = useRef(target);
+  useEffect(() => {
+    latest.current = target;
+  });
+
+  const focusNow = useCallback(() => {
+    if (!api.isActive) return;
+    retryFocus(
+      () => latest.current.focus(),
+      () => latest.current.isFocused(),
+      () => api.isActive,
+    );
+  }, [api]);
+
+  useEffect(() => {
+    const subActive = api.onDidActiveChange(() => {
+      if (api.isActive) focusNow();
+      else latest.current.blur?.();
+    });
+    // `focusNow` guards on `isActive` itself: a Focus Request says only that
+    // the user asked, never that this panel became active.
+    const subRequest = api.onDidRequestFocus(focusNow);
+    return () => {
+      subActive.dispose();
+      subRequest.dispose();
+    };
+  }, [api, focusNow]);
+
+  return focusNow;
+}