zidane-ui 0.0.0-stage → 9.0.2

package/src/workspace/testing/index.ts

@@ -0,0 +1,140 @@
+/**
+ * `zidane-ui/workspace/testing`: a `WorkspaceHost` that runs in memory
+ * (`createFixtureWorkspaceHost`) and demo data, for docs, demos, galleries
+ * and an app's own tests. Not for production hosts.
+ */
+import type { PanelContent } from 'zidane/chat/pure';
+
+import type { WorkspaceHost, WorkspaceLayout, WorkspacePanelChange, WorkspacePanelSummary } from '../headless/host';
+import { createMemoryLayouts, EMPTY_WORKSPACE_LAYOUT } from '../headless/layouts';
+import { panelTreeOf, splitTab } from '../headless/panel-tree';
+import type { WorkspaceTab } from '../headless/view';
+
+/** Options of {@link createFixtureWorkspaceHost}. */
+export interface FixtureWorkspaceOptions {
+  /** The layouts stored per scope key. */
+  layouts?: Readonly<Record<string, WorkspaceLayout>>;
+  /** What a scope with nothing stored reads. Default: closed, no tab. */
+  initial?: WorkspaceLayout;
+  /** Extension panels, per folder. `false`: no `panels` member. Default: none offered. */
+  panels?:
+    | {
+        /** The panels offered per folder. */
+        catalog: Readonly<Record<string, readonly WorkspacePanelSummary[]>>;
+        /** Each panel's content, by id; a panel missing here fails to load. */
+        content: Readonly<Record<string, PanelContent>>;
+        /** Actions that fail, keyed `panelId/actionId`, with the extension's words. */
+        failing?: Readonly<Record<string, string>>;
+      }
+    | false;
+}
+
+/** Changes the fixture from outside, as another window or an extension would. */
+export interface FixtureWorkspaceControl {
+  /** Stores `layout` for the scope `key`, as another window would. */
+  setLayout(key: string, layout: WorkspaceLayout): void;
+  /** Replaces a panel's content and announces the change. */
+  setContent(cwd: string, panelId: string, content: PanelContent): void;
+  /** Announces that a panel changed. */
+  changePanel(cwd: string, panelId: string): void;
+  /** Replaces a folder's catalog and announces it. */
+  setCatalog(cwd: string, panels: readonly WorkspacePanelSummary[]): void;
+  /** The actions run so far, oldest first. */
+  actions(): readonly { cwd: string; panelId: string; actionId: string; payload: unknown }[];
+  /** The panels watched now, as `cwd/panelId`. */
+  watching(): readonly string[];
+}
+
+/** The {@link WorkspaceHost} {@link createFixtureWorkspaceHost} returns, with its control. */
+export interface FixtureWorkspaceHost extends WorkspaceHost {
+  /** Changes the fixture from outside. */
+  control: FixtureWorkspaceControl;
+}
+
+/**
+ * Creates a {@link WorkspaceHost} held in memory: layouts per scope key and, unless `panels: false`, extension panels
+ * per folder.
+ *
+ * @param options - The stored layouts and the extension panels.
+ */
+export function createFixtureWorkspaceHost(options: FixtureWorkspaceOptions = {}): FixtureWorkspaceHost {
+  const initial = options.initial ?? EMPTY_WORKSPACE_LAYOUT;
+  const layouts = createMemoryLayouts({ initial: () => initial });
+  for (const [key, layout] of Object.entries(options.layouts ?? {})) layouts.set(key, layout);
+  const spec = options.panels === false ? null : (options.panels ?? { catalog: {}, content: {} });
+  const catalog = new Map(Object.entries(spec?.catalog ?? {}));
+  const content = new Map(Object.entries(spec?.content ?? {}));
+  const changeListeners = new Set<(change: WorkspacePanelChange) => void>();
+  const catalogListeners = new Set<() => void>();
+  const ran: { cwd: string; panelId: string; actionId: string; payload: unknown }[] = [];
+  const watched = new Map<string, number>();
+  const offers = (cwd: string, panelId: string) => catalog.get(cwd)?.some((p) => p.id === panelId) === true;
+
+  const control: FixtureWorkspaceControl = {
+    setLayout: (key, layout) => layouts.set(key, layout),
+    setContent(cwd, panelId, next) {
+      content.set(panelId, next);
+      control.changePanel(cwd, panelId);
+    },
+    changePanel(cwd, panelId) {
+      for (const listener of [...changeListeners]) listener({ cwd, panelId });
+    },
+    setCatalog(cwd, panels) {
+      catalog.set(cwd, panels);
+      for (const listener of [...catalogListeners]) listener();
+    },
+    actions: () => ran,
+    watching: () => [...watched].filter(([, n]) => n > 0).map(([k]) => k),
+  };
+
+  return {
+    layouts,
+    ...(spec
+      ? {
+          panels: {
+            list: async (cwd) => (catalog.get(cwd) ?? []).map((p) => ({ ...p })),
+            load: async (cwd, panelId) => {
+              const found = offers(cwd, panelId) ? content.get(panelId) : undefined;
+              if (!found) throw new Error(`No panel ${panelId} in ${cwd}`);
+              return found;
+            },
+            action: async (cwd, panelId, actionId, payload) => {
+              ran.push({ cwd, panelId, actionId, payload });
+              const failed = spec.failing?.[`${panelId}/${actionId}`];
+              return failed === undefined ? { ok: true } : { ok: false, error: { code: 'failed', message: failed } };
+            },
+            watch: (cwd, panelId) => {
+              const key = `${cwd}/${panelId}`;
+              watched.set(key, (watched.get(key) ?? 0) + 1);
+              return () => void watched.set(key, (watched.get(key) ?? 1) - 1);
+            },
+            subscribe: (onChange) => {
+              changeListeners.add(onChange);
+              return () => changeListeners.delete(onChange);
+            },
+            subscribeCatalog: (onChange) => {
+              catalogListeners.add(onChange);
+              return () => catalogListeners.delete(onChange);
+            },
+          },
+        }
+      : {}),
+    control,
+  };
+}
+
+/** The tabs the demos offer: an app's own kinds, as the desktop app's catalog lists them. */
+export const DEMO_WORKSPACE_TABS: readonly WorkspaceTab[] = [
+  { id: 'files', label: 'Files', icon: { gui: 'i-ph-folder-simple' }, builtin: true },
+  { id: 'diffs', label: 'Diffs', icon: { gui: 'i-ph-git-diff' }, builtin: true },
+  { id: 'todos', label: 'Todos', icon: { gui: 'i-ph-check-square' }, builtin: true },
+  { id: 'terminal', label: 'Terminal', icon: { gui: 'i-ph-terminal-window' }, builtin: true },
+];
+
+/** A demo layout: open, Files and Todos in one group, Diffs split off to the right. */
+export const DEMO_WORKSPACE_LAYOUT: WorkspaceLayout = {
+  open: true,
+  tree: splitTab(panelTreeOf(['files', 'todos', 'diffs'], 'files'), 'diffs', 'right'),
+  width: null,
+  share: null,
+};

package/src/workspace/use-split-drag.ts

@@ -0,0 +1,73 @@
+/**
+ * Dragging the line between two children of a split (`tree.ts`): the side
+ * panel's tab groups. The new shares go to `onMove` on every pointer move (the caller paints its boxes straight
+ * to the DOM) and to `onCommit` once on release, so nothing re-renders
+ * mid-drag. A double-click evens the split out.
+ *
+ *   const drag = useSplitDrag({ divider, sizes, areaRef, minPx: 240, onMove: paint, onCommit: save });
+ *   <div role="separator" data-active={drag.active} {...drag.handleProps} />
+ */
+import { useState, type PointerEvent as ReactPointerEvent, type RefObject } from 'react';
+
+import type { Divider } from './headless/tree';
+
+export interface SplitDragOptions {
+  divider: Divider;
+  /** The split's shares now. */
+  sizes: readonly number[];
+  /** The element the boxes are fractions of. */
+  areaRef: RefObject<HTMLElement | null>;
+  /** The smallest either neighbour gets (px along the split). */
+  minPx: number;
+  onMove: (sizes: readonly number[]) => void;
+  onCommit: (sizes: readonly number[]) => void;
+}
+
+/** `sizes` with the two neighbours of divider `index` sharing their room as `first` and the rest. */
+export function shiftShares(sizes: readonly number[], index: number, first: number): number[] {
+  const share = sizes[index]! + sizes[index + 1]!;
+  return sizes.map((s, j) => (j === index ? first : j === index + 1 ? share - first : s));
+}
+
+export function useSplitDrag({ divider, sizes, areaRef, minPx, onMove, onCommit }: SplitDragOptions) {
+  const [active, setActive] = useState(false);
+  const row = divider.dir === 'row';
+  const onPointerDown = (e: ReactPointerEvent<HTMLElement>) => {
+    const area = areaRef.current;
+    const i = divider.index;
+    if (e.button !== 0 || !area || sizes.length < i + 2) return;
+    e.preventDefault();
+    const rect = area.getBoundingClientRect();
+    const extent = (row ? rect.width * divider.box.w : rect.height * divider.box.h) || 1;
+    const share = sizes[i]! + sizes[i + 1]!;
+    const minShare = Math.min(minPx / extent, share / 2);
+    const start = row ? e.clientX : e.clientY;
+    const start0 = sizes;
+    let next = sizes;
+    const handle = e.currentTarget;
+    handle.setPointerCapture(e.pointerId);
+    setActive(true);
+    const move = (ev: PointerEvent) => {
+      const delta = ((row ? ev.clientX : ev.clientY) - start) / extent;
+      next = shiftShares(start0, i, Math.max(minShare, Math.min(share - minShare, start0[i]! + delta)));
+      onMove(next);
+    };
+    const end = (ev: PointerEvent) => {
+      handle.removeEventListener('pointermove', move);
+      handle.removeEventListener('pointerup', end);
+      handle.removeEventListener('pointercancel', end);
+      setActive(false);
+      if (next === start0) return;
+      // A cancelled drag (the system took the pointer) puts everything back.
+      if (ev.type === 'pointercancel') onMove(start0);
+      else onCommit(next);
+    };
+    handle.addEventListener('pointermove', move);
+    handle.addEventListener('pointerup', end);
+    handle.addEventListener('pointercancel', end);
+  };
+  return {
+    active,
+    handleProps: { onPointerDown, onDoubleClick: () => onCommit(sizes.map(() => 1)) },
+  };
+}

package/src/workspace/useScopeLayout.ts

@@ -0,0 +1,26 @@
+/**
+ * `useScopeLayout(memory, scope)`: a scope's layout from a `LayoutMemory`
+ * (`createLayoutMemory`, `zidane-ui/workspace/headless`) in a component.
+ */
+import { useCallback, useEffect, useSyncExternalStore } from 'react';
+
+import type { LayoutMemory, LayoutScope, SessionLayout } from './headless/layout-memory';
+
+/**
+ * Live layout for a scope (`EMPTY_LAYOUT` without one). A scope on screen owns its layout from then on
+ * (`adoptScopeLayout`; the draft excepted): what it shows stays put while other sessions of its project
+ * change theirs.
+ *
+ * @param memory - The window's layout memory.
+ * @param scope - The scope; keyed by its identity, not its object (callers may rebuild it per render).
+ */
+export function useScopeLayout(memory: LayoutMemory, scope: LayoutScope | null): SessionLayout {
+  const ref = scope ? memory.scopeLayoutId(scope) : '';
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const get = useCallback(() => memory.getScopeLayout(scope), [memory, ref]);
+  useEffect(() => {
+    if (scope) memory.adoptScopeLayout(scope);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- per scope identity (see above)
+  }, [memory, ref]);
+  return useSyncExternalStore(memory.subscribeLayouts, get, get);
+}

package/src/workspace/useViewport.ts

@@ -0,0 +1,22 @@
+/** Window width, updated at most once per animation frame while resizing. */
+import { useEffect, useState } from 'react';
+
+export function useViewportWidth(): number {
+  const [width, setWidth] = useState(() => window.innerWidth);
+  useEffect(() => {
+    let frame: number | null = null;
+    const onResize = () => {
+      if (frame !== null) return;
+      frame = requestAnimationFrame(() => {
+        frame = null;
+        setWidth(window.innerWidth);
+      });
+    };
+    window.addEventListener('resize', onResize);
+    return () => {
+      window.removeEventListener('resize', onResize);
+      if (frame !== null) cancelAnimationFrame(frame);
+    };
+  }, []);
+  return width;
+}

package/src/workspace/useWorkspaceLabels.ts

@@ -0,0 +1,14 @@
+/**
+ * The workspace's labels: the defaults, overridable through
+ * `<LabelsProvider>` or `WorkspaceProvider`'s `labels`.
+ */
+import { useMemo } from 'react';
+
+import { useLabels } from '../labels';
+import { DEFAULT_WORKSPACE_LABELS, type WorkspaceLabels } from './headless/labels';
+
+/** Returns the side panel's strings: the defaults merged with any overrides given to `WorkspaceProvider` or `LabelsProvider`. */
+export function useWorkspaceLabels(): WorkspaceLabels {
+  const overrides = useLabels() as Partial<WorkspaceLabels>;
+  return useMemo(() => ({ ...DEFAULT_WORKSPACE_LABELS, ...overrides }), [overrides]);
+}

package/src/workspace/workspace-key-commands.ts

@@ -0,0 +1,108 @@
+/**
+ * The side panel's key commands: show or hide the panel (`openArtifacts`),
+ * the Todos tab (`openTodos`), cycle its tabs (`panelNext` / `panelPrev`),
+ * close the tab in reach (`closeTab`) and step through tabs where the focus
+ * is (`tabNext` / `tabPrev`).
+ *
+ * ⌥⌘←/→ act where the focus is (`tabTarget`, `tab-scopes.ts`):
+ *   - in a scope (open files in Files, changed files in Diffs, terminals), or
+ *     a focus region showing one (the side panel, the terminal drawer): its items;
+ *   - in the side panel otherwise (Todos, its tab strip): the panel's tabs;
+ *   - anywhere else: the next / previous space while spaces are on, else the
+ *     side panel's visible tab, then its tabs (⌃⇧[ / ⌃⇧] always cycle those).
+ * A region never falls through to spaces: a key pressed in the side panel or
+ * a terminal stays there, and so does focus (`keepFocusIn`).
+ */
+import { useCallback, useEffect, useMemo } from 'react';
+import { TODOS_PANEL_ID } from 'zidane/chat/pure';
+
+import type { KeyCommands } from '../keybindings/headless/commands';
+import { focusedTabScope, keepFocusIn, panelTabScope, tabTarget, trackTabRegions } from './tab-scopes';
+import { useWorkspaceActions, useWorkspaceView, type WorkspaceActions } from './WorkspaceProvider';
+
+/** Options for {@link useWorkspaceKeyCommands}. */
+export interface WorkspaceKeyCommandsOptions {
+  /** A scope is on screen (a session or a folder): the panel keys act. */
+  scope: boolean;
+  /** A session is on screen: the Todos tab, the tab keys. */
+  session: boolean;
+  /** Offer `openArtifacts` (toggling the panel). Default: with a scope. */
+  toggle?: boolean;
+  /** The actions to run. Default: the `WorkspaceProvider`'s (an app may wrap them, relaying to another window). */
+  actions?: WorkspaceActions;
+  /** The spaces the tab keys step through outside the panel, while `on`. */
+  spaces?: { on: boolean; step(direction: 1 | -1): void };
+  /**
+   * `closeTab` with nothing to close in the focused scope: return `true` when the app closed something itself (a
+   * standalone window), before the panel's visible tab closes.
+   */
+  closeOutside?(): boolean;
+}
+
+/**
+ * The side panel's key commands for the {@link WorkspaceProvider} above. Each is present only while it can act.
+ *
+ * @param options - What is on screen, and the app's hooks.
+ */
+export function useWorkspaceKeyCommands(options: WorkspaceKeyCommandsOptions): KeyCommands {
+  const { scope, session, spaces, closeOutside } = options;
+  const kit = useWorkspaceActions();
+  const actions = options.actions ?? kit;
+  const { state, activeTab } = useWorkspaceView();
+  const panelOpen = state.open;
+  const toggle = options.toggle ?? scope;
+  const spacesOn = spaces?.on === true;
+  const stepSpace = spaces?.step;
+
+  useEffect(() => trackTabRegions(), []);
+
+  const tabStep = useCallback(
+    (direction: 1 | -1) => {
+      const { scope: target, region } = tabTarget();
+      if (target || region) {
+        if (!target?.step(direction) && region?.hasAttribute('data-side-panel')) actions.cycle(direction);
+        keepFocusIn(region);
+        return;
+      }
+      if (spacesOn && stepSpace) {
+        stepSpace(direction);
+        return;
+      }
+      if (panelOpen && panelTabScope()?.step(direction)) return;
+      if (panelOpen) actions.cycle(direction);
+    },
+    [actions, panelOpen, spacesOn, stepSpace],
+  );
+
+  const activeId = panelOpen ? (activeTab?.id ?? null) : null;
+  const closeTab = useCallback(() => {
+    // Inside Files or a terminal, ctrl+w closes there first (the file, the
+    // terminal); once nothing is left inside, the panel tab around it.
+    const { region } = tabTarget();
+    if (focusedTabScope()?.close()) {
+      keepFocusIn(region);
+      return;
+    }
+    if (closeOutside?.()) return;
+    if (activeId) actions.closeTab(activeId);
+  }, [actions, activeId, closeOutside]);
+
+  return useMemo<KeyCommands>(
+    () => ({
+      ...(toggle ? { openArtifacts: () => actions.toggle() } : {}),
+      // Shows the Todos tab, or closes the panel when it is already the visible tab.
+      ...(session
+        ? {
+            openTodos: () => {
+              if (activeId === TODOS_PANEL_ID) actions.close();
+              else actions.pick(TODOS_PANEL_ID);
+            },
+          }
+        : {}),
+      ...(scope ? { panelNext: () => actions.cycle(1), panelPrev: () => actions.cycle(-1), closeTab } : {}),
+      // Spaces switch without an open chat too.
+      ...(session || spacesOn ? { tabNext: () => tabStep(1), tabPrev: () => tabStep(-1) } : {}),
+    }),
+    [actions, toggle, session, scope, activeId, closeTab, spacesOn, tabStep],
+  );
+}