zidane-ui 9.0.4 → 9.1.3

package/src/workspace/WorkspaceProvider.tsx

@@ -1,554 +0,0 @@
-/**
- * The side panel's state for one scope on screen:
- *
- *   layout   = the scope's stored layout (`WorkspaceHost.layouts`): panel
- *              open, the tab groups and the focused one. Read straight from
- *              the store, changed only by the actions (`createWorkspaceOps`),
- *              each a read-modify-write of what is stored right now. Nothing
- *              mirrors it, so a scope switch shows the new scope's layout in
- *              the same render.
- *   catalog  = the tabs the app offers here (`tabs`): its own kinds and the
- *              extension panels (`useExtensionPanels`).
- *   content  = per-binding cache of extension panel content
- *              (`createPanelContents`): the visible panel is loaded and
- *              watched, hidden ones turn pending when they change.
- *   badges   = attention per scope and tab (`setAttention`).
- *
- * Split into four contexts so a content load or a badge change re-renders
- * only what reads content; `useWorkspace()` composes all four.
- *
- *   <WorkspaceProvider host={host} scope={{ key: sessionId }} tabs={tabs}>
- *     <SidePanel registry={registry} … />
- *   </WorkspaceProvider>
- */
-import { DIFFS_PANEL_ID, FILES_PANEL_ID, type PanelLoadContextInput, type PanelState } from 'zidane/chat/pure';
-import {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-  useSyncExternalStore,
-  type ReactNode,
-} from 'react';
-
-import { LabelsProvider } from '../labels';
-import { bindingKey, createPanelContents, EMPTY_CONTENT_ENTRY } from './headless/contents';
-import type {
-  WorkspaceHost,
-  WorkspaceHostError,
-  WorkspaceLayout,
-  WorkspaceLayouts,
-  WorkspacePanels,
-  WorkspacePanelSummary,
-  WorkspaceScope,
-} from './headless/host';
-import type { WorkspaceLabels } from './headless/labels';
-import { createMemoryLayouts, EMPTY_WORKSPACE_LAYOUT } from './headless/layouts';
-import { createWorkspaceOps, type WorkspaceOps } from './headless/ops';
-import { activeTabOf } from './headless/panel-tree';
-import {
-  groupViews,
-  sameAttention,
-  viewOf,
-  type PanelContentEntry,
-  type PanelViewNode,
-  type TabAttention,
-  type WorkspaceTab,
-} from './headless/view';
-import { useWorkspaceLabels } from './useWorkspaceLabels';
-
-/** Every panel action; one object whose identity never changes for the provider's lifetime. */
-export interface WorkspaceActions extends Omit<WorkspaceOps, 'requestAttention'> {
-  /** Set or clear (`null`) a tab's attention for a scope (by its key). Idempotent. */
-  setAttention(scopeKey: string, id: string, value: TabAttention | null): void;
-  /**
-   * The agent is waiting on the user in `id`: pin the tab into the strip
-   * and, unless `open` is false, show it (regardless of earlier user picks:
-   * a blocked run outranks a badge). `focus` asks the tab body to move
-   * keyboard focus to its first control once shown (`takeFocusRequest`);
-   * it is only recorded when the tab is being shown.
-   */
-  requestAttention(id: string, opts?: { open?: boolean; focus?: boolean }): void;
-  /** The user asked for a tab (a bar, an indicator): pin, open as a pick, hand focus to its body. */
-  focusTab(id: string): void;
-  /** The tab body took the focus request. */
-  takeFocusRequest(): void;
-  /**
-   * Show `absPath` in the Files tab (opens the panel on Files, a user pick): a file opens in a tab, a folder (a path
-   * ending in `/`) is selected and expanded in the tree. The tab takes it with `takeRevealRequest`; a tab not
-   * mounted yet picks it up when it mounts.
-   */
-  revealFile(absPath: string): void;
-  /** The Files tab took the reveal request. */
-  takeRevealRequest(): void;
-  /** Open the panel on Diffs, showing the working tree. Taken like the reveal request. */
-  showWorkingTree(): void;
-  /** The Diffs tab took the working-tree request. */
-  takeWorkingTreeRequest(): void;
-  /** Reload an extension panel's content. */
-  refresh(id: string): void;
-  /** Run an extension panel's action; its content reloads after. */
-  act(id: string, actionId: string, payload?: unknown): Promise<void>;
-}
-
-/** Catalog, strip and open/active state: changes on user navigation, not on content loads. */
-export interface WorkspaceView<T extends WorkspaceTab = WorkspaceTab> {
-  /** The folder extension panels load against (`content.cwd`), or null. */
-  cwd: string | null;
-  /** The scope these tabs belong to (its key): what a conversation switch changes. */
-  scopeKey: string | null;
-  /** Every tab offered here (the catalog). */
-  tabs: readonly T[];
-  /** Tabs in the strips, in order: what the strips show. */
-  openTabs: readonly T[];
-  /** Catalog entries not in a strip (what the `+` menu offers). */
-  closedTabs: readonly T[];
-  /** The panel is open, and its stored active tab. */
-  state: Pick<PanelState, 'open' | 'activeId'>;
-  /** The focused group's tab, `null` for an empty catalog. */
-  activeTab: T | null;
-  /** The groups as laid out, restricted to tabs on screen; `null` when none is. */
-  tree: PanelViewNode<T> | null;
-  /** The focused group: where new tabs go, what cycling walks; it shows `activeTab`. */
-  focusedGroupId: string | null;
-}
-
-/** One-shot hand-overs to tab bodies (consumed with the matching `take*` action). */
-export interface WorkspaceRequests {
-  /** The tab whose body should take keyboard focus. */
-  focusRequest: string | null;
-  /** The path the Files tab should show (`revealFile`), or `null`. */
-  revealRequest: string | null;
-  /** Bumped by each `showWorkingTree` (a counter: a second ask while Diffs is up still lands); `0` once taken. */
-  workingTreeRequest: number;
-}
-
-/** Extension content and badges: the fast-changing part. */
-export interface WorkspaceContent {
-  /** Attention for the scope on screen's tabs, by tab id. */
-  attention: Readonly<Record<string, TabAttention>>;
-  /** An extension panel's content for the scope on screen. */
-  contentFor(id: string): PanelContentEntry;
-}
-
-/** Everything {@link useWorkspace} returns. */
-export type WorkspaceApi = WorkspaceActions & WorkspaceView & WorkspaceRequests & WorkspaceContent;
-
-const HostContext = createContext<WorkspaceHost | null>(null);
-const ActionsContext = createContext<WorkspaceActions | null>(null);
-const ViewContext = createContext<WorkspaceView | null>(null);
-const RequestsContext = createContext<WorkspaceRequests | null>(null);
-const ContentContext = createContext<WorkspaceContent | null>(null);
-
-/** Props for {@link WorkspaceHostProvider}. */
-export interface WorkspaceHostProviderProps {
-  /** The host the `WorkspaceProvider`s below read when they are given none. */
-  host: WorkspaceHost;
-  /** The app. */
-  children: ReactNode;
-}
-
-/**
- * Puts a {@link WorkspaceHost} in context for the `WorkspaceProvider`s below (what `AppHostProvider` does with
- * `host.workspace`).
- *
- * @param props - The `host` and the `children`.
- */
-export function WorkspaceHostProvider({ host, children }: WorkspaceHostProviderProps) {
-  return <HostContext.Provider value={host}>{children}</HostContext.Provider>;
-}
-
-/** The {@link WorkspaceHost} from the nearest {@link WorkspaceHostProvider}, or `null`. */
-export function useWorkspaceHost(): WorkspaceHost | null {
-  return useContext(HostContext);
-}
-
-/** Where extension panels load: the folder, and the session they show beside. */
-export interface WorkspaceContentTarget {
-  /** The folder. */
-  cwd: string;
-  /** The session, or none (a folder alone). */
-  sessionId?: string | null;
-}
-
-/** Props for {@link WorkspaceProvider}. */
-export interface WorkspaceProviderProps<S extends WorkspaceScope = WorkspaceScope> {
-  /** Where layouts live and extension panels come from. Default: the `WorkspaceHostProvider`'s, else in memory. */
-  host?: WorkspaceHost<S>;
-  /** The scope on screen (a session, a folder), or null: no panel. */
-  scope: S | null;
-  /** The tabs offered here, in catalog order: the app's own kinds and the extension panels. */
-  tabs: readonly WorkspaceTab[];
-  /** When no stored tab is offered here, show the first offered one instead (not stored until picked). */
-  fillEmpty?: boolean;
-  /** Where extension panels load. Absent: they don't load. */
-  content?: WorkspaceContentTarget | null;
-  /** Extra context for one extension panel's load and actions (what it was opened on). */
-  loadContext?: (panelId: string) => PanelLoadContextInput | undefined;
-  /** Overrides for the built-in strings. Keys you leave out keep the default English label. */
-  labels?: Partial<WorkspaceLabels>;
-  /** The components that read the panel. */
-  children: ReactNode;
-}
-
-const NO_ENTRIES: Readonly<Record<string, PanelContentEntry>> = {};
-const NO_ATTENTION: Readonly<Record<string, TabAttention>> = {};
-/** Conversations whose panel content stays cached for an instant switch back. */
-const BINDINGS_KEPT = 8;
-
-/**
- * Provides the side panel's state for `scope` to the components below.
- *
- * @param props - The host, the scope on screen, the tabs offered and where extension panels load.
- */
-export function WorkspaceProvider<S extends WorkspaceScope = WorkspaceScope>({
-  labels,
-  children,
-  ...props
-}: WorkspaceProviderProps<S>) {
-  return (
-    <LabelsProvider<WorkspaceLabels> labels={labels}>
-      <WorkspaceState {...props}>{children}</WorkspaceState>
-    </LabelsProvider>
-  );
-}
-
-function WorkspaceState<S extends WorkspaceScope>({
-  host: given,
-  scope,
-  tabs,
-  fillEmpty = false,
-  content: target,
-  loadContext,
-  children,
-}: Omit<WorkspaceProviderProps<S>, 'labels'>) {
-  const labels = useWorkspaceLabels();
-  const fromContext = useContext(HostContext) as WorkspaceHost<S> | null;
-  const host = given ?? fromContext;
-  const [memory] = useState(() => createMemoryLayouts());
-  const layouts = (host?.layouts ?? memory) as WorkspaceLayouts<S>;
-  const panels = host?.panels;
-  const key = scope?.key ?? null;
-  // The actions (created once) and the effects read the latest render through refs, written during render
-  // so a child acting in its own effects already sees this render's scope and strips.
-  const scopeRef = useRef(scope);
-  // eslint-disable-next-line react-hooks/refs
-  scopeRef.current = scope;
-
-  const read = () => (scope ? layouts.get(scope) : EMPTY_WORKSPACE_LAYOUT);
-  const layout: WorkspaceLayout = useSyncExternalStore(layouts.subscribe, read, read);
-  const tree = layout.tree;
-  const storedActiveId = activeTabOf(tree);
-  const state = useMemo(() => ({ open: layout.open, activeId: storedActiveId }), [layout.open, storedActiveId]);
-
-  const view = useMemo(() => viewOf(tree.root, tabs, fillEmpty), [tree.root, tabs, fillEmpty]);
-  const openTabs = useMemo(() => (view ? groupViews(view).flatMap((g) => g.tabs) : []), [view]);
-  const closedTabs = useMemo(() => tabs.filter((t) => !openTabs.includes(t)), [tabs, openTabs]);
-  const focusedGroup = useMemo(() => {
-    const groups = view ? groupViews(view) : [];
-    return groups.find((g) => g.id === tree.focused) ?? groups[0] ?? null;
-  }, [view, tree.focused]);
-  const activeTab = focusedGroup?.activeTab ?? null;
-  const focusedGroupId = focusedGroup?.id ?? null;
-
-  // ---- content --------------------------------------------------------
-  const cwd = target?.cwd || null;
-  const sessionId = target?.sessionId ?? null;
-  const binding = cwd ? bindingKey(cwd, sessionId) : null;
-  const bindingRef = useRef(binding);
-  // eslint-disable-next-line react-hooks/refs
-  bindingRef.current = binding;
-  const [contentsStore] = useState(createPanelContents);
-  const cache = useSyncExternalStore(contentsStore.subscribe, contentsStore.get, contentsStore.get);
-  const contents = (binding && cache[binding]) || NO_ENTRIES;
-  const loadContextRef = useRef(loadContext);
-  // eslint-disable-next-line react-hooks/refs
-  loadContextRef.current = loadContext;
-  /** The context for one panel: the session, plus what the app adds (what it was opened on). */
-  const ctxFor = useCallback(
-    (id: string): PanelLoadContextInput => {
-      const base = sessionId ? { sessionId } : {};
-      const extra = loadContextRef.current?.(id);
-      return extra ? { ...base, ...extra } : base;
-    },
-    [sessionId],
-  );
-  const errorText = useCallback(
-    (error: WorkspaceHostError) => (error.code === 'failed' ? error.message : labels.panelUnavailable),
-    [labels],
-  );
-
-  const refresh = useCallback(
-    (id: string) => {
-      if (!cwd || !binding || !panels) return;
-      const token = contentsStore.begin(binding, id);
-      panels
-        .load(cwd, id, ctxFor(id))
-        .then((content) => contentsStore.settle(binding, id, token, { content }))
-        .catch((err: unknown) =>
-          contentsStore.settle(binding, id, token, { error: err instanceof Error ? err.message : String(err) }),
-        );
-    },
-    [cwd, binding, panels, ctxFor, contentsStore],
-  );
-
-  // Visible extension tab: load on show, watch while shown.
-  const visibleExtId = state.open && activeTab && !activeTab.builtin ? activeTab.id : null;
-  useEffect(() => {
-    if (!cwd || !visibleExtId) return undefined;
-    refresh(visibleExtId);
-    return panels?.watch?.(cwd, visibleExtId);
-  }, [cwd, visibleExtId, refresh, panels]);
-
-  /*
-   * Live updates: the visible panel reloads; anywhere else (a hidden tab,
-   * another conversation's cached copy in this folder) the content is only
-   * flagged pending, and reloads when shown or when its conversation is
-   * switched back to.
-   */
-  useEffect(() => {
-    if (!panels?.subscribe) return undefined;
-    return panels.subscribe((change) => {
-      const here = change.cwd === cwd;
-      const reloads = here && change.panelId === visibleExtId;
-      if (reloads) refresh(change.panelId);
-      contentsStore.markChanged(change.cwd, change.panelId, reloads ? binding : null);
-    });
-  }, [panels, cwd, binding, visibleExtId, refresh, contentsStore]);
-
-  /*
-   * A conversation's strip shows every extension tab's badge, not only the
-   * visible one's: on entering a binding (and when the strip gains a tab),
-   * load the strip's extension tabs that have no content for it yet or that
-   * changed while it was away. Hidden tabs are not watched; later changes
-   * only flag them (above).
-   */
-  const contentsRef = useRef(contents);
-  // eslint-disable-next-line react-hooks/refs
-  contentsRef.current = contents;
-  const stripExtIds = useMemo(
-    () =>
-      openTabs
-        .filter((t) => !t.builtin)
-        .map((t) => t.id)
-        .join('\u0000'),
-    [openTabs],
-  );
-  useEffect(() => {
-    if (!binding || !stripExtIds) return;
-    for (const id of stripExtIds.split('\u0000')) {
-      if (id === visibleExtId) continue; // the visible tab loads (and watches) itself
-      const entry = contentsRef.current[id];
-      if (!entry || (entry.pending && !entry.loading)) refresh(id);
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- on entering a binding or a strip change, not on content updates
-  }, [binding, stripExtIds]);
-
-  // Keep the most recently shown bindings; older ones reload when revisited.
-  const recentBindings = useRef<string[]>([]);
-  useEffect(() => {
-    if (!binding) return;
-    const recent = [binding, ...recentBindings.current.filter((b) => b !== binding)].slice(0, BINDINGS_KEPT);
-    recentBindings.current = recent;
-    contentsStore.keep(recent);
-  }, [binding, contentsStore]);
-
-  const act = useCallback(
-    async (id: string, actionId: string, payload?: unknown) => {
-      if (!cwd || !panels) return;
-      const at = binding;
-      let error: string | null;
-      try {
-        const result = await panels.action(cwd, id, actionId, payload, ctxFor(id));
-        error = result.ok ? null : errorText(result.error);
-      } catch (err) {
-        error = err instanceof Error ? err.message : String(err);
-      }
-      if (!at) return;
-      if (error !== null) {
-        contentsStore.setError(at, id, error);
-        return;
-      }
-      // Still on the conversation that acted: show the result; else it reloads when switched back to.
-      if (bindingRef.current === at) refresh(id);
-      else contentsStore.markPending(at, id);
-    },
-    [cwd, binding, panels, ctxFor, refresh, contentsStore, errorText],
-  );
-
-  // ---- badges and requests ----------------------------------------------
-  const [attentionByScope, setAttentionByScope] = useState<Record<string, Record<string, TabAttention>>>({});
-  const setAttention = useCallback((forScope: string, id: string, value: TabAttention | null) => {
-    setAttentionByScope((prev) => {
-      const current = prev[forScope] ?? {};
-      const existing = current[id];
-      if (value === null ? !existing : existing !== undefined && sameAttention(existing, value)) return prev;
-      const next = { ...current };
-      if (value === null) delete next[id];
-      else next[id] = value;
-      return { ...prev, [forScope]: next };
-    });
-  }, []);
-  const attention = useMemo(
-    () => (key ? (attentionByScope[key] ?? NO_ATTENTION) : NO_ATTENTION),
-    [attentionByScope, key],
-  );
-  const [focusRequest, setFocusRequest] = useState<string | null>(null);
-  const [revealRequest, setRevealRequest] = useState<string | null>(null);
-  const [workingTreeRequest, setWorkingTreeRequest] = useState(0);
-
-  // Actions read the latest render through a ref, so the object is created
-  // once and never invalidates consumers that only hold callbacks.
-  const latest = useRef({ openTabs, tabs, view, layouts, refresh, act });
-  // eslint-disable-next-line react-hooks/refs
-  latest.current = { openTabs, tabs, view, layouts, refresh, act };
-  const actions = useMemo<WorkspaceActions>(() => {
-    // The accessors read the refs when an action runs, never during render.
-    // eslint-disable-next-line react-hooks/refs
-    const ops = createWorkspaceOps<S>({
-      layouts: () => latest.current.layouts,
-      scope: () => scopeRef.current,
-      view: () => latest.current,
-    });
-    return {
-      ...ops,
-      setAttention,
-      requestAttention: (id, opts) => {
-        const show = opts?.open !== false;
-        ops.requestAttention(id, show);
-        if (show && opts?.focus) setFocusRequest(id);
-      },
-      focusTab: (id) => {
-        ops.pick(id);
-        setFocusRequest(id);
-      },
-      takeFocusRequest: () => setFocusRequest(null),
-      revealFile: (absPath) => {
-        setRevealRequest(absPath);
-        ops.pick(FILES_PANEL_ID);
-      },
-      takeRevealRequest: () => setRevealRequest(null),
-      showWorkingTree: () => {
-        setWorkingTreeRequest((n) => n + 1);
-        ops.pick(DIFFS_PANEL_ID);
-      },
-      takeWorkingTreeRequest: () => setWorkingTreeRequest(0),
-      refresh: (id) => latest.current.refresh(id),
-      act: (id, actionId, payload) => latest.current.act(id, actionId, payload),
-    };
-  }, [setAttention]);
-
-  const viewValue = useMemo<WorkspaceView>(
-    () => ({ cwd, scopeKey: key, tabs, openTabs, closedTabs, state, activeTab, tree: view, focusedGroupId }),
-    [cwd, key, tabs, openTabs, closedTabs, state, activeTab, view, focusedGroupId],
-  );
-  const requests = useMemo<WorkspaceRequests>(
-    () => ({ focusRequest, revealRequest, workingTreeRequest }),
-    [focusRequest, revealRequest, workingTreeRequest],
-  );
-  const contentValue = useMemo<WorkspaceContent>(
-    () => ({ attention, contentFor: (id) => contents[id] ?? EMPTY_CONTENT_ENTRY }),
-    [attention, contents],
-  );
-
-  return (
-    <ActionsContext.Provider value={actions}>
-      <ViewContext.Provider value={viewValue}>
-        <RequestsContext.Provider value={requests}>
-          <ContentContext.Provider value={contentValue}>{children}</ContentContext.Provider>
-        </RequestsContext.Provider>
-      </ViewContext.Provider>
-    </ActionsContext.Provider>
-  );
-}
-
-function required<T>(value: T | null, hook: string): T {
-  if (!value) throw new Error(`zidane-ui/workspace: ${hook} must be used within <WorkspaceProvider>`);
-  return value;
-}
-
-/** Stable actions only: never re-renders on panel state changes. Throws outside a `WorkspaceProvider`. */
-export function useWorkspaceActions(): WorkspaceActions {
-  return required(useContext(ActionsContext), 'useWorkspaceActions');
-}
-
-/** {@link useWorkspaceActions}, or `null` outside a `WorkspaceProvider`. */
-export function useOptionalWorkspaceActions(): WorkspaceActions | null {
-  return useContext(ActionsContext);
-}
-
-/** The catalog, strips and open state. Re-renders on navigation, not on content loads. */
-export function useWorkspaceView(): WorkspaceView {
-  return required(useContext(ViewContext), 'useWorkspaceView');
-}
-
-/** The one-shot requests to tab bodies. */
-export function useWorkspaceRequests(): WorkspaceRequests {
-  return required(useContext(RequestsContext), 'useWorkspaceRequests');
-}
-
-/** Extension content and badges. Re-renders on every content load and badge change. */
-export function useWorkspaceContent(): WorkspaceContent {
-  return required(useContext(ContentContext), 'useWorkspaceContent');
-}
-
-/** Everything at once (re-renders on any panel change); prefer the narrower hooks above. */
-export function useWorkspace(): WorkspaceApi {
-  const actions = useContext(ActionsContext);
-  const view = useContext(ViewContext);
-  const requests = useContext(RequestsContext);
-  const content = useContext(ContentContext);
-  if (!actions || !view || !requests || !content) {
-    throw new Error('zidane-ui/workspace: useWorkspace must be used within <WorkspaceProvider>');
-  }
-  return useMemo(() => ({ ...actions, ...view, ...requests, ...content }), [actions, view, requests, content]);
-}
-
-const NO_PANELS: readonly WorkspacePanelSummary[] = [];
-
-/**
- * The extension panels offered in `cwd`, kept per folder: switching back to a
- * folder shows its tabs at once, and a slow list for a folder left behind
- * never lands on the one shown. A folder not listed yet keeps the last list
- * until its own arrives, so the strip does not drop its tabs for a frame.
- * Re-lists when the host says the catalog changed.
- *
- * @param panels - The host's extension panels (`host.panels`), or nothing.
- * @param cwd - The folder, or null (no extension panels).
- */
-export function useExtensionPanels(
-  panels: WorkspacePanels | undefined,
-  cwd: string | null,
-): readonly WorkspacePanelSummary[] {
-  const [catalogs, setCatalogs] = useState<Readonly<Record<string, readonly WorkspacePanelSummary[]>>>({});
-  const [lastCatalog, setLastCatalog] = useState<readonly WorkspacePanelSummary[]>(NO_PANELS);
-  const known = cwd ? catalogs[cwd] : NO_PANELS;
-  if (known && known !== lastCatalog) setLastCatalog(known);
-
-  const load = useCallback(
-    async (folder: string) => {
-      let list: readonly WorkspacePanelSummary[];
-      try {
-        list = panels ? await panels.list(folder) : NO_PANELS;
-      } catch {
-        list = NO_PANELS;
-      }
-      setCatalogs((prev) => (prev[folder] === list ? prev : { ...prev, [folder]: list }));
-    },
-    [panels],
-  );
-  useEffect(() => {
-    if (!cwd || !panels) return undefined;
-    // eslint-disable-next-line react-hooks/set-state-in-effect -- the list lands when the host answers
-    void load(cwd);
-    return panels.subscribeCatalog?.(() => {
-      // Every folder's list may have changed: keep only this one's, refreshed.
-      setCatalogs((prev) => (cwd in prev ? { [cwd]: prev[cwd]! } : {}));
-      void load(cwd);
-    });
-  }, [cwd, panels, load]);
-  return known ?? lastCatalog;
-}