zidane-ui 9.0.4 → 9.1.3

package/src/workspace/panel-visibility.ts

@@ -1,28 +0,0 @@
-/**
- * Whether the side-panel tab body reading it is on screen. `SidePanel`
- * keeps recently used tabs mounted behind `hidden`; a hidden tab should
- * skip work nobody sees (refreshes on tool results, measuring loops,
- * polling) and catch up when it becomes visible again. Outside the panel
- * (tests, other hosts) the default is visible.
- */
-import { createContext, useContext } from 'react';
-
-/** Whether the tab body below is on screen; `TabParking` provides it per body. Default: visible. */
-export const PanelVisibilityContext = createContext(true);
-
-/** Whether the tab body calling it is on screen (true outside a side panel). */
-export function usePanelVisible(): boolean {
-  return useContext(PanelVisibilityContext);
-}
-
-/**
- * Most recent first, deduplicated, capped at `max`. Returns `list` itself when nothing changes.
- *
- * @param list - The ids, most recent first.
- * @param id - The id just used.
- * @param max - How many to keep.
- */
-export function touchRecent(list: readonly string[], id: string, max: number): readonly string[] {
-  if (list[0] === id) return list;
-  return [id, ...list.filter((x) => x !== id)].slice(0, max);
-}

package/src/workspace/tab-scopes.ts

@@ -1,245 +0,0 @@
-/**
- * Where "next tab", "previous tab" and "close tab" (⌥⌘→ / ⌥⌘← / ctrl+w) act.
- *
- *   - Files: the open files; close closes the file.
- *   - Diffs: the changed files; close closes the Diffs panel tab.
- *   - Terminals (drawer or panel tab): the terminals; close closes the terminal.
- *   - Anywhere else: the side panel's tabs; close closes the active one.
- *
- * Where focus is decides (`tabTarget`): the scope holding it, else the
- * focus REGION holding it (the side panel, the terminal drawer: `data-tab-region`)
- * and the scope visible in it, else the app (the caller steps spaces, or the
- * side panel). A region never hands the keys to the app: a click on the side
- * panel's tab strip, or between its tab's controls, steps there, not spaces.
- * Regions take focus themselves (`tabIndex={-1}`), so a click on a spot
- * that can't hold focus still moves it into them rather than leaving it in
- * the composer. Focus that falls to the page (the focused editor went with
- * its file) leaves you where you were: the keys act in the region you last
- * clicked or focused (`trackTabRegions`), and focus is put back on it
- * (`keepFocusIn`). Closing goes by the scope holding focus only: ctrl+w from the
- * conversation closes the panel tab, not a file in it.
- *
- * A surface registers its scope on its root element (`data-tab-scope`) and
- * the handlers here. Several of a kind can be mounted (kept-alive panel
- * tabs), so scopes are keyed by element.
- */
-import { useEffect, useRef, type RefObject } from 'react';
-
-/** What a surface does with the tab keys: step, close, find. */
-export interface TabScope {
-  /** `1` next, `-1` previous. Returns false when there was nothing to move to. */
-  step: (direction: 1 | -1) => boolean;
-  /**
-   * Close one thing inside the scope. False when nothing is left to close:
-   * ctrl+w then closes the side-panel tab holding it.
-   */
-  close: () => boolean;
-  /**
-   * ⌘F (`file`: find in the open file or diff) or ⌘⇧F (`files`: search
-   * across files). False when the scope has nothing to search: the app's
-   * own find takes the key.
-   */
-  find?: (mode: 'file' | 'files') => boolean;
-}
-
-const SCOPE_ATTR = 'data-tab-scope';
-const REGION_ATTR = 'data-tab-region';
-
-/** Props for a focus region's root: marked, and focusable by a click (not by Tab). */
-export const TAB_REGION_PROPS = { [REGION_ATTR]: '', tabIndex: -1 } as const;
-const scopes = new WeakMap<Element, TabScope>();
-
-/**
- * Register `scope` on `el` (marks it `data-tab-scope`). Returns the unregister.
- *
- * @param el - The surface's root element.
- * @param scope - What the tab keys do there.
- */
-export function registerTabScope(el: HTMLElement, scope: TabScope): () => void {
-  el.setAttribute(SCOPE_ATTR, '');
-  scopes.set(el, scope);
-  return () => {
-    if (scopes.get(el) === scope) scopes.delete(el);
-    el.removeAttribute(SCOPE_ATTR);
-  };
-}
-
-/** `from` and its ancestors, up through shadow roots too: focus inside pierre's editor sits in one. */
-function* ancestry(from: Element | null): Generator<Element> {
-  for (let el: Element | null = from; el; el = el.parentElement ?? (el.getRootNode() as ShadowRoot).host ?? null) {
-    yield el;
-  }
-}
-
-/**
- * The scope holding focus: from the focused element (or `from`) up to the first registered one.
- * None when that scope is hidden: focus left behind in a kept-alive tab the user switched away
- * from (browsers keep it on a `display: none` element) must not take ctrl+w from the shown tab.
- *
- * @param from - Where to start. Default: the focused element.
- */
-export function focusedTabScope(from: Element | null = document.activeElement): TabScope | null {
-  for (const el of ancestry(from)) {
-    if (el.hasAttribute(SCOPE_ATTR)) {
-      const scope = scopes.get(el);
-      if (scope) return el.closest('[hidden]') ? null : scope;
-    }
-  }
-  return null;
-}
-
-/** The first registered scope shown inside `root` (hidden kept-alive tabs have no boxes). */
-function visibleScopeIn(root: Element): TabScope | null {
-  for (const el of root.querySelectorAll(`[${SCOPE_ATTR}]`)) {
-    const scope = scopes.get(el);
-    if (scope && el.getClientRects().length > 0) return scope;
-  }
-  return null;
-}
-
-/** Where the tab keys act: a scope, and the focus region holding focus. */
-export interface TabTarget {
-  /** Where the tab keys step: the scope holding focus, else the one shown in its region. */
-  scope: TabScope | null;
-  /** The focus region holding focus (side panel, terminal drawer); `null` = the app. */
-  region: HTMLElement | null;
-}
-
-function regionOf(from: Element | null): HTMLElement | null {
-  for (const el of ancestry(from)) {
-    if (el.hasAttribute(REGION_ATTR) && el instanceof HTMLElement) return el;
-  }
-  return null;
-}
-
-/*
- * The region the user is in: where they last clicked or moved focus to
- * (`null` = the rest of the window). Focus that falls to the page (the
- * focused editor went away with its file, a kept-alive tab hid) moves
- * nothing: the keys keep acting there. Set by {@link trackTabRegions}.
- */
-let lastRegion: HTMLElement | null = null;
-
-const shown = (el: HTMLElement | null): el is HTMLElement => !!el && el.isConnected && el.getClientRects().length > 0;
-const onPage = (el: Element | null) => !el || el === document.body || el === document.documentElement;
-
-/** Follow where the user is (pointer down, focus in). Install once per window; returns the uninstall. */
-export function trackTabRegions(): () => void {
-  const note = (event: Event) => {
-    const target = event.composedPath()[0];
-    if (target instanceof Element && !onPage(target)) lastRegion = regionOf(target);
-    else if (event.type === 'pointerdown') lastRegion = null;
-  };
-  document.addEventListener('pointerdown', note, true);
-  document.addEventListener('focusin', note, true);
-  return () => {
-    document.removeEventListener('pointerdown', note, true);
-    document.removeEventListener('focusin', note, true);
-    lastRegion = null;
-  };
-}
-
-/**
- * Where ⌥⌘← / ⌥⌘→ act, from what holds focus (or `from`). Focus on the
- * page itself (it fell there): the region the user was in, if still shown.
- *
- * @param from - Where focus is. Default: the focused element.
- */
-export function tabTarget(from: Element | null = document.activeElement): TabTarget {
-  const region = onPage(from) ? (shown(lastRegion) ? lastRegion : null) : regionOf(from);
-  // Split into groups (the side panel): the focused group's visible tab, not the first group's.
-  const shownIn = region && (region.querySelector('[data-focused-group]') ?? region);
-  const scope = (onPage(from) ? null : focusedTabScope(from)) ?? (shownIn ? visibleScopeIn(shownIn) : null);
-  return { scope, region };
-}
-
-/** How long after a tab key focus is watched: a stepped-to file's editor mounts once its text loads. */
-const KEEP_FOCUS_MS = 1000;
-
-/**
- * After a tab key acted in `region`: whenever the element holding focus goes
- * away with what it showed (a closed file's editor, a stepped-away tab, even
- * a beat later), focus lands back on the region instead of the page, so the
- * next key and the next arrow stay there. Stops once the user is elsewhere.
- *
- * @param region - The region the key acted in; `null` does nothing.
- */
-export function keepFocusIn(region: HTMLElement | null): void {
-  if (!region) return;
-  lastRegion = region;
-  const until = performance.now() + KEEP_FOCUS_MS;
-  const check = () => {
-    if (lastRegion !== region || !shown(region)) return;
-    if (onPage(document.activeElement)) region.focus({ preventScroll: true });
-    if (performance.now() < until) requestAnimationFrame(check);
-  };
-  requestAnimationFrame(check);
-}
-
-/**
- * The scope of the side panel's visible tab (`SidePanel` marks its root
- * `data-side-panel`), if it has one. Hidden kept-alive tabs have no boxes.
- */
-export function panelTabScope(): TabScope | null {
-  // Split into groups: the focused group's visible tab.
-  const panel =
-    document.querySelector('[data-side-panel] [data-focused-group]') ?? document.querySelector('[data-side-panel]');
-  return panel ? visibleScopeIn(panel) : null;
-}
-
-/** The scope under the pointer (the innermost hovered element up). */
-export function hoveredTabScope(): TabScope | null {
-  const hovered = document.querySelectorAll(':hover');
-  return focusedTabScope(hovered[hovered.length - 1] ?? null);
-}
-
-/**
- * The index a step lands on in a list, wrapping; -1 when the list is empty.
- *
- * @param current - The index now (-1: none).
- * @param length - The list's length.
- * @param direction - `1` next, `-1` previous.
- */
-export function steppedIndex(current: number, length: number, direction: 1 | -1): number {
-  if (length === 0) return -1;
-  if (current < 0) return direction === 1 ? 0 : length - 1;
-  return (current + direction + length) % length;
-}
-
-/**
- * Register a tab scope on the element `ref` points at, with handlers that always see the latest render.
- *
- * @param ref - The surface's root element.
- * @param scope - What the tab keys do there.
- */
-export function useTabScope<T extends HTMLElement>(ref: RefObject<T | null>, scope: TabScope): void {
-  const latest = useRef(scope);
-  // eslint-disable-next-line react-hooks/refs -- the latest handlers, read when a key acts
-  latest.current = scope;
-  const registered = useRef<{ el: T; scope: TabScope; release: () => void } | null>(null);
-  // Every commit: the element can appear later (a loading state renders without it).
-  useEffect(() => {
-    const el = ref.current;
-    // Still registered here. Checked in the registry, not just the ref: a hot
-    // reload of this module starts an empty registry while the ref survives.
-    if (registered.current?.el === el && (!el || scopes.get(el) === registered.current.scope)) return;
-    registered.current?.release();
-    if (!el) {
-      registered.current = null;
-      return;
-    }
-    const scope: TabScope = {
-      step: (direction) => latest.current.step(direction),
-      close: () => latest.current.close(),
-      find: (mode) => latest.current.find?.(mode) ?? false,
-    };
-    registered.current = { el, scope, release: registerTabScope(el, scope) };
-  });
-  useEffect(
-    () => () => {
-      registered.current?.release();
-      registered.current = null;
-    },
-    [],
-  );
-}

package/src/workspace/testing/contract.ts

@@ -1,282 +0,0 @@
-/**
- * What every `WorkspaceHost` implementation does alike, as a vitest suite: the in-memory fixture
- * (`createFixtureWorkspaceHost`), browser storage (`createBrowserWorkspaceHost`), the desktop app's IPC host.
- *
- * An implementation's test calls {@link describeWorkspaceHostContract} with a harness factory. The contract hands
- * it a {@link WorkspaceHostContractBackend}: the layouts stored per scope key and the extension panels of one
- * folder. The harness builds the host over a backend that holds them, maps a scope key to the scope its host takes
- * (`scope`), and returns a {@link WorkspaceHostContractControl} that changes the backend from outside (another
- * window wrote a layout, a panel's content changed, an extension loaded). The capabilities list says which optional
- * members the host offers: the suite checks the others are left out (undefined, never a throwing stub) and skips
- * the behaviours that need them.
- *
- *   describeWorkspaceHostContract('createFixtureWorkspaceHost', (backend) => ({ host, scope, control }), [
- *     'layouts', 'panels', 'panels.watch', 'panels.subscribe', 'panels.subscribeCatalog',
- *   ]);
- */
-import type { PanelContent } from 'zidane/chat/pure';
-import { afterEach, describe, expect, it, vi } from 'vitest';
-
-import type { WorkspaceHost, WorkspaceLayout, WorkspacePanelSummary, WorkspaceScope } from '../headless/host';
-import { panelTreeOf, pickTab, splitTab } from '../headless/panel-tree';
-import { treeTabs } from '../headless/tree';
-
-/** An optional `WorkspaceHost` member, by its path. */
-export type WorkspaceHostCapability =
-  'layouts' | 'panels' | 'panels.watch' | 'panels.subscribe' | 'panels.subscribeCatalog';
-
-const CAPABILITIES: readonly WorkspaceHostCapability[] = [
-  'layouts',
-  'panels',
-  'panels.watch',
-  'panels.subscribe',
-  'panels.subscribeCatalog',
-];
-
-/** What the backend behind the host holds. */
-export interface WorkspaceHostContractBackend {
-  /** The layouts stored per scope key (a key missing here has nothing stored). */
-  layouts: Readonly<Record<string, WorkspaceLayout>>;
-  /** The folder the extension panels are offered in (no other folder offers any). */
-  cwd: string;
-  /** The extension panels offered in `cwd`. */
-  panels: readonly WorkspacePanelSummary[];
-  /** Each panel's content, by id; a panel missing here fails to load. */
-  content: Readonly<Record<string, PanelContent>>;
-  /** The one action that fails, with the extension's words; every other action succeeds. */
-  failingAction: { panelId: string; actionId: string; message: string };
-}
-
-/** Changes the backend from outside and announces it as the backend does. */
-export interface WorkspaceHostContractControl {
-  /** Another window stored `layout` for the scope `key`. */
-  writeLayout(key: string, layout: WorkspaceLayout): void;
-  /** A panel's content changed in `cwd`. */
-  changePanel(cwd: string, panelId: string): void;
-  /** An extension loaded or left: the catalog may have changed. */
-  changeCatalog(): void;
-}
-
-/** A host built over a backend, the backend's control, and how to tear them down. */
-export interface WorkspaceHostHarness<S extends WorkspaceScope = WorkspaceScope> {
-  /** The host under test. */
-  host: WorkspaceHost<S>;
-  /** The scope the host takes for a scope key. */
-  scope(key: string): S;
-  /** Changes the backend from outside. */
-  control: WorkspaceHostContractControl;
-  /** Closes connections and timers after each test. */
-  dispose?(): void;
-}
-
-/** Builds a fresh host (and its backend) for one test. */
-export type WorkspaceHostHarnessFactory<S extends WorkspaceScope = WorkspaceScope> = (
-  backend: WorkspaceHostContractBackend,
-) => WorkspaceHostHarness<S> | Promise<WorkspaceHostHarness<S>>;
-
-const STORED: WorkspaceLayout = {
-  open: true,
-  tree: splitTab(panelTreeOf(['files', 'diffs'], 'diffs'), 'diffs', 'right'),
-  width: 520,
-  share: null,
-};
-
-function contractBackend(): WorkspaceHostContractBackend {
-  return {
-    layouts: { 's-1': STORED },
-    cwd: '/repo',
-    panels: [
-      { id: 'ext.git', label: 'Git', owner: 'git', icon: { gui: 'i-ph-git-branch' }, scope: 'both' },
-      { id: 'ext.ci', label: 'CI', owner: 'ci', scope: 'session' },
-    ],
-    content: {
-      'ext.git': { badge: 2, sections: [] },
-      'ext.ci': { sections: [], empty: 'No runs' },
-    },
-    failingAction: { panelId: 'ext.ci', actionId: 'rerun', message: 'CI is down' },
-  };
-}
-
-function member(host: WorkspaceHost, capability: WorkspaceHostCapability): unknown {
-  const [head, tail] = capability.split('.') as [keyof WorkspaceHost, string | undefined];
-  const value = host[head] as Record<string, unknown> | undefined;
-  return tail ? value?.[tail] : value;
-}
-
-const waitFor = <T>(check: () => T) => vi.waitFor(check, { timeout: 3000, interval: 2 });
-
-/**
- * Declares the shared `WorkspaceHost` suite for one implementation.
- *
- * @param name - The implementation's name, shown in the suite title.
- * @param makeHarness - Builds a fresh host over a backend that holds what it is given, once per test.
- * @param capabilities - The optional members the host offers. Every other optional member must be undefined.
- */
-export function describeWorkspaceHostContract<S extends WorkspaceScope>(
-  name: string,
-  makeHarness: WorkspaceHostHarnessFactory<S>,
-  capabilities: readonly WorkspaceHostCapability[],
-): void {
-  const has = (...needed: WorkspaceHostCapability[]) => needed.every((c) => capabilities.includes(c));
-
-  describe(`WorkspaceHost contract: ${name}`, () => {
-    const cleanup: (() => void)[] = [];
-    afterEach(() => {
-      for (const done of cleanup.splice(0).reverse()) done();
-    });
-
-    const setup = async () => {
-      const harness = await makeHarness(contractBackend());
-      cleanup.push(() => harness.dispose?.());
-      return harness;
-    };
-
-    it('offers exactly its capabilities; the members it leaves out are undefined', async () => {
-      const { host } = await setup();
-      for (const capability of CAPABILITIES) {
-        const value = member(host as WorkspaceHost, capability);
-        if (!has(capability)) {
-          expect(value, capability).toBeUndefined();
-          continue;
-        }
-        expect(typeof value, capability).toBe(capability.includes('.') ? 'function' : 'object');
-      }
-      if (has('layouts')) {
-        expect(typeof host.layouts?.get).toBe('function');
-        expect(typeof host.layouts?.update).toBe('function');
-        expect(typeof host.layouts?.subscribe).toBe('function');
-      }
-      if (has('panels')) {
-        expect(typeof host.panels?.list).toBe('function');
-        expect(typeof host.panels?.load).toBe('function');
-        expect(typeof host.panels?.action).toBe('function');
-      }
-    });
-
-    describe.skipIf(!has('layouts'))('layouts', () => {
-      it('reads the stored layout, the same object while it is unchanged', async () => {
-        const { host, scope } = await setup();
-        const layouts = host.layouts!;
-        const first = layouts.get(scope('s-1'));
-        expect(first.open).toBe(true);
-        expect(first.width).toBe(520);
-        expect(treeTabs(first.tree.root).sort()).toEqual(['diffs', 'files']);
-        expect(layouts.get(scope('s-1'))).toBe(first);
-      });
-
-      it('reads a valid layout for a scope with nothing stored', async () => {
-        const { host, scope } = await setup();
-        const layout = host.layouts!.get(scope('s-new'));
-        expect(typeof layout.open).toBe('boolean');
-        expect(layout.tree.root).toBeTruthy();
-        expect(host.layouts!.get(scope('s-new'))).toBe(layout);
-      });
-
-      it('applies a change to what is stored now and tells subscribers', async () => {
-        const { host, scope } = await setup();
-        const layouts = host.layouts!;
-        const heard = vi.fn();
-        cleanup.push(layouts.subscribe(heard));
-        layouts.update(scope('s-1'), (stored) => ({ open: !stored.open, tree: pickTab(stored.tree, 'terminal') }));
-        await waitFor(() => expect(heard).toHaveBeenCalled());
-        const after = layouts.get(scope('s-1'));
-        expect(after.open).toBe(false);
-        expect(treeTabs(after.tree.root)).toContain('terminal');
-        expect(after.width).toBe(520);
-        // Other scopes keep theirs.
-        expect(layouts.get(scope('s-2')).open).toBe(layouts.get(scope('s-new')).open);
-      });
-
-      it('writes nothing and tells no one for a change that changes nothing', async () => {
-        const { host, scope } = await setup();
-        const layouts = host.layouts!;
-        const before = layouts.get(scope('s-1'));
-        const heard = vi.fn();
-        cleanup.push(layouts.subscribe(heard));
-        layouts.update(scope('s-1'), (stored) => ({ open: stored.open, width: stored.width }));
-        expect(heard).not.toHaveBeenCalled();
-        expect(layouts.get(scope('s-1'))).toBe(before);
-      });
-
-      it("hears another window's write, and the next change applies to it (read-modify-write)", async () => {
-        const { host, scope, control } = await setup();
-        const layouts = host.layouts!;
-        const heard = vi.fn();
-        cleanup.push(layouts.subscribe(heard));
-        layouts.get(scope('s-1'));
-        control.writeLayout('s-1', { open: false, tree: panelTreeOf(['inbox']), width: 300, share: null });
-        await waitFor(() => expect(layouts.get(scope('s-1')).width).toBe(300));
-        expect(heard).toHaveBeenCalled();
-        layouts.update(scope('s-1'), (stored) => ({ tree: pickTab(stored.tree, 'files') }));
-        expect(treeTabs(layouts.get(scope('s-1')).tree.root).sort()).toEqual(['files', 'inbox']);
-      });
-
-      it('stops telling a subscriber once it unsubscribes', async () => {
-        const { host, scope } = await setup();
-        const heard = vi.fn();
-        const off = host.layouts!.subscribe(heard);
-        off();
-        host.layouts!.update(scope('s-1'), () => ({ open: false }));
-        await Promise.resolve();
-        expect(heard).not.toHaveBeenCalled();
-      });
-    });
-
-    describe.skipIf(!has('panels'))('panels', () => {
-      it('lists the panels offered in a folder, none elsewhere', async () => {
-        const { host } = await setup();
-        const list = await host.panels!.list('/repo');
-        expect(list.map((p) => [p.id, p.label, p.scope])).toEqual([
-          ['ext.git', 'Git', 'both'],
-          ['ext.ci', 'CI', 'session'],
-        ]);
-        expect(list[0]!.icon?.gui).toBe('i-ph-git-branch');
-        expect(await host.panels!.list('/elsewhere')).toEqual([]);
-      });
-
-      it("loads a panel's content, and rejects for one that fails", async () => {
-        const { host } = await setup();
-        const content = await host.panels!.load('/repo', 'ext.git', { sessionId: 's-1' });
-        expect(content.badge).toBe(2);
-        await expect(host.panels!.load('/repo', 'ext.missing', {})).rejects.toBeTruthy();
-      });
-
-      it("runs an action, and answers a failed one with the extension's words", async () => {
-        const { host } = await setup();
-        expect(await host.panels!.action('/repo', 'ext.git', 'refresh', null, {})).toEqual({ ok: true });
-        expect(await host.panels!.action('/repo', 'ext.ci', 'rerun', { id: 1 }, { sessionId: 's-1' })).toEqual({
-          ok: false,
-          error: { code: 'failed', message: 'CI is down' },
-        });
-      });
-
-      it.skipIf(!has('panels.watch'))('watches a shown panel and stops', async () => {
-        const { host } = await setup();
-        const stop = host.panels!.watch!('/repo', 'ext.git');
-        expect(typeof stop).toBe('function');
-        stop();
-      });
-
-      it.skipIf(!has('panels.subscribe'))('tells subscribers which panel changed, until they unsubscribe', async () => {
-        const { host, control } = await setup();
-        const heard = vi.fn();
-        const off = host.panels!.subscribe!(heard);
-        control.changePanel('/repo', 'ext.git');
-        await waitFor(() => expect(heard).toHaveBeenCalledWith({ cwd: '/repo', panelId: 'ext.git' }));
-        off();
-        heard.mockClear();
-        control.changePanel('/repo', 'ext.ci');
-        await Promise.resolve();
-        expect(heard).not.toHaveBeenCalled();
-      });
-
-      it.skipIf(!has('panels.subscribeCatalog'))('tells subscribers the catalog may have changed', async () => {
-        const { host, control } = await setup();
-        const heard = vi.fn();
-        cleanup.push(host.panels!.subscribeCatalog!(heard));
-        control.changeCatalog();
-        await waitFor(() => expect(heard).toHaveBeenCalled());
-      });
-    });
-  });
-}