zidane-ui 9.1.1 → 9.1.4

package/src/terminal/TerminalProvider.tsx

@@ -1,201 +0,0 @@
-/**
- * Puts the terminal store (over a `TerminalHost`) in context for the
- * drawer, the panel tab and their views, with what only the app can do for
- * them (`TerminalAppActions`: open a link, add a selection to the chat, open
- * its settings) and optional label overrides.
- *
- *   <TerminalProvider host={host} actions={{ openUrl, addToChat }}>
- *     <TerminalDrawer scope={scope} />
- *   </TerminalProvider>
- *
- * An app that drives terminals outside React too (a keybinding opening the
- * drawer) creates the store itself (`createTerminalStore`) and passes
- * `store` instead of `host`.
- *
- * `enabled` and `waiting` sit in a context of their own: changing them
- * re-renders the drawer, the toggle and the unavailable state, never a
- * terminal's view.
- */
-import { createContext, useContext, useEffect, useMemo, useState, useSyncExternalStore, type ReactNode } from 'react';
-
-import { LabelsProvider } from '../labels';
-import type { TerminalHost } from './headless/host';
-import type { TerminalLabels } from './headless/labels';
-import type { TerminalLayout } from './headless/layout';
-import { terminalScopeKey, type TerminalScope } from './headless/scope';
-import { createTerminalStore, type ScopeTerminals, type TerminalStore } from './headless/store';
-
-/** A selection of a terminal's output, to add to the chat. */
-export interface TerminalExcerpt {
-  /** The terminal's label (`Terminal 1`). */
-  label: string;
-  /** First buffer line of the selection (1-based). */
-  startLine: number;
-  /** Last buffer line of the selection (1-based). */
-  endLine: number;
-  /** The selected text. */
-  text: string;
-}
-
-/** Keyboard handlers a terminal area registers on its root (`TerminalAppActions.registerTabScope`). */
-export interface TerminalTabHandlers {
-  /** Activates the next (`1`) or previous (`-1`) terminal. False when there was nothing to move to. */
-  step(direction: 1 | -1): boolean;
-  /** Closes the active terminal. False when there was none (whatever holds the area closes instead). */
-  close(): boolean;
-}
-
-/** What only the app can do for the terminal components. Each one left out hides what needs it. */
-export interface TerminalAppActions {
-  /**
-   * Opens a web link a terminal printed; `external`: ⌘/Ctrl-click asked for the system browser.
-   * `cwd`: where the terminal's paths resolve (`''` when they are not this machine's). Absent: a new window.
-   */
-  openUrl?(scope: TerminalScope, url: string, external: boolean, cwd: string): void;
-  /** Opens a file a terminal printed (absolute path, optional 1-based position). Absent: paths don't link. */
-  openFile?(scope: TerminalScope, path: string, event: MouseEvent, at?: { line: number; column?: number }): void;
-  /** Adds a selection to the scope's chat. Absent: no Add to chat. */
-  addToChat?(scope: TerminalScope, excerpt: TerminalExcerpt): void;
-  /** Whether the scope has a chat to add to now (read when a menu opens). Absent: always, given `addToChat`. */
-  canAddToChat?(scope: TerminalScope): boolean;
-  /** Opens the app's settings where terminals are turned on (the unavailable state's button). Absent: no button. */
-  openSettings?(): void;
-  /** The machine the scope's terminals run on when it is not this one: their files don't link, their loopback links don't open. */
-  remoteName?(scope: TerminalScope): string | null;
-  /** Registers keyboard handlers on a terminal area's root element. Returns the unregister. */
-  registerTabScope?(element: HTMLElement, handlers: TerminalTabHandlers): () => void;
-  /** Extra attributes for the drawer's root (a focus region's marker). */
-  drawerProps?: Readonly<Record<string, string | number | boolean>>;
-}
-
-/** Why there are no terminals for a while: the link to what runs them is coming up, or down. */
-export type TerminalWaiting = 'connecting' | 'unreachable';
-
-interface TerminalContextValue {
-  store: TerminalStore;
-  actions: TerminalAppActions;
-  symbolsFontUrl: string | undefined;
-}
-
-interface TerminalStatus {
-  enabled: boolean;
-  waiting: TerminalWaiting | null;
-}
-
-const TerminalContext = createContext<TerminalContextValue | null>(null);
-const StatusContext = createContext<TerminalStatus>({ enabled: true, waiting: null });
-
-const NO_ACTIONS: TerminalAppActions = {};
-
-/** Props for {@link TerminalProvider}: a `host` (the provider creates the store) or a `store` the app created. */
-export type TerminalProviderProps = (
-  | {
-      /** The terminal host. */
-      host: TerminalHost;
-      store?: never;
-    }
-  | {
-      /** A store the app created over its host (`createTerminalStore`). */
-      store: TerminalStore;
-      host?: never;
-    }
-) & {
-  /** What only the app can do (open links, add to chat, settings). Keep it stable: a new object re-renders every view. */
-  actions?: TerminalAppActions;
-  /** `false` removes the drawer and its toggle (terminals turned off). Default: true. */
-  enabled?: boolean;
-  /** Set while the link to what runs terminals is coming up or down: the unavailable state says so. */
-  waiting?: TerminalWaiting | null;
-  /** Where the app serves the Nerd Font symbols face (`SYMBOLS_FONT`), loaded before a terminal measures its cells. */
-  symbolsFontUrl?: string;
-  /** Overrides for the built-in strings. Keys you leave out keep the default English label. */
-  labels?: Partial<TerminalLabels>;
-  /** The app. */
-  children: ReactNode;
-};
-
-/**
- * Provides the terminal store and the app's actions to the terminal components below it.
- *
- * @param props - Provider props: the `host` or `store`, the app's `actions`, `enabled`, `waiting`, `symbolsFontUrl`, `labels` and the `children`.
- */
-export function TerminalProvider(props: TerminalProviderProps) {
-  const { actions = NO_ACTIONS, enabled = true, waiting = null, symbolsFontUrl, labels, children } = props;
-  const [own] = useState(() => (props.store ? null : createTerminalStore(props.host!)));
-  const store = props.store ?? own!;
-  const value = useMemo(() => ({ store, actions, symbolsFontUrl }), [store, actions, symbolsFontUrl]);
-  const status = useMemo(() => ({ enabled, waiting }), [enabled, waiting]);
-  return (
-    <TerminalContext.Provider value={value}>
-      <StatusContext.Provider value={status}>
-        <LabelsProvider<TerminalLabels> labels={labels}>{children}</LabelsProvider>
-      </StatusContext.Provider>
-    </TerminalContext.Provider>
-  );
-}
-
-function useTerminalContext(): TerminalContextValue {
-  const value = useContext(TerminalContext);
-  if (!value) throw new Error('zidane-ui/terminal: wrap the terminals in <TerminalProvider host={…}>');
-  return value;
-}
-
-/** The {@link TerminalStore} from the nearest {@link TerminalProvider}. Throws outside one. */
-export function useTerminalStore(): TerminalStore {
-  return useTerminalContext().store;
-}
-
-/** The app's actions from the nearest {@link TerminalProvider}. */
-export function useTerminalActions(): TerminalAppActions {
-  return useTerminalContext().actions;
-}
-
-/** @internal The symbols face's URL for the views. */
-export function useSymbolsFontUrl(): string | undefined {
-  return useTerminalContext().symbolsFontUrl;
-}
-
-/** Whether terminals are on (`TerminalProvider`'s `enabled`). */
-export function useTerminalsEnabled(): boolean {
-  return useContext(StatusContext).enabled;
-}
-
-/** @internal Why there are no terminals for a while (`TerminalProvider`'s `waiting`). */
-export function useTerminalWaiting(): TerminalWaiting | null {
-  return useContext(StatusContext).waiting;
-}
-
-/**
- * A scope's terminals (state, active terminal, error, agent badge), re-rendering when they change.
- *
- * @param scope - The scope, or `null` for none.
- */
-export function useScopeTerminals(scope: TerminalScope | null): ScopeTerminals {
-  const store = useTerminalStore();
-  const key = scope ? terminalScopeKey(scope) : null;
-  return useSyncExternalStore(
-    store.subscribe,
-    () => store.get(key),
-    () => store.get(key),
-  );
-}
-
-/**
- * A scope's terminal layout (drawer, order, agent filter), re-rendering when it changes. Tells the
- * layouts the scope is shown (`TerminalLayouts.show`) once per scope.
- *
- * @param scope - The scope.
- */
-export function useTerminalLayout(scope: TerminalScope): TerminalLayout {
-  const { layouts } = useTerminalStore();
-  const ref = `${terminalScopeKey(scope)}\u0000${scope.root}\u0000${scope.cwd}`;
-  useEffect(() => {
-    layouts.show?.(scope);
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- per scope identity, not its object
-  }, [layouts, ref]);
-  return useSyncExternalStore(
-    layouts.subscribe,
-    () => layouts.get(scope),
-    () => layouts.get(scope),
-  );
-}

package/src/terminal/TerminalSurface.tsx

@@ -1,262 +0,0 @@
-/**
- * A terminal on a canvas (ghostty-web, loaded on first use) over any
- * process the app can reach: a `TerminalAdapter` carries its output in,
- * the keys out, and the grid size. The app owns the process (a PTY, a
- * WebContainer `jsh`); this view only draws and types.
- *
- *   - The grid fits the view (debounced) and every new size goes to
- *     `adapter.resize`. A view that is not laid out (a hidden tab) proposes
- *     nothing, and its render loop pauses while `visible` is off.
- *   - Keys: the host carries `data-zg-keyscope="editor"`, so bare
- *     ctrl+letter chords belong to the shell. macOS editing keys (⌘⌫, ⌥←)
- *     send what Terminal.app sends; Cmd+C copies a selection; other Cmd
- *     chords reach the app.
- *   - Theme changes re-create the terminal (ghostty-web does not repaint a
- *     new theme after open); font changes apply live.
- */
-import type { Terminal } from '@tahul/ghostty-web';
-import { useEffect, useLayoutEffect, useMemo, useRef, useState, type CSSProperties, type KeyboardEvent } from 'react';
-
-import { useLabels } from '../labels';
-import { loadGhostty, openTerminal } from './ghostty';
-import { macTerminalKey } from './keys';
-import type { TerminalTheme } from './theme';
-
-/** The process a {@link TerminalSurface} shows. */
-export interface TerminalAdapter {
-  /** Typed keys and pasted text, as the bytes the process reads. */
-  write: (data: string) => void;
-  /** The process's output; returns the unsubscribe. */
-  onData: (listener: (data: string) => void) => () => void;
-  /** The grid the view fits, on mount and on every change. */
-  resize: (cols: number, rows: number) => void;
-  /** The process ended; returns the unsubscribe. */
-  onExit?: (listener: (code: number) => void) => () => void;
-}
-
-/** Props of {@link TerminalSurface}. */
-export interface TerminalSurfaceProps {
-  /** The process to show; a new adapter re-creates the terminal. */
-  adapter: TerminalAdapter;
-  /** Colors (`terminalTheme(palette)`). */
-  theme: TerminalTheme;
-  /** CSS font family of the grid; applies live. */
-  fontFamily: string;
-  /** Font size in px; applies live. */
-  fontSize: number;
-  /** Where the app serves the Nerd Font symbols face (see `loadGhostty`). */
-  symbolsFontUrl?: string;
-  /** Shown and laid out; off pauses rendering (a background tab). */
-  visible?: boolean;
-  /** Take keyboard focus on mount and whenever the view becomes visible. */
-  autoFocus?: boolean;
-  /** Accessible name. Default: the `terminal` label. */
-  label?: string;
-  /** Extra classes on the host (it already flexes to fill its parent). */
-  className?: string;
-  /** Inline styles on the root element, merged after the component's own. */
-  style?: CSSProperties;
-}
-
-const SCROLLBACK = 10_000;
-const FIT_DEBOUNCE_MS = 40;
-
-/** ghostty-web keeps a render loop for as long as a terminal is open; these TS-private methods pause it. */
-interface RenderLoop {
-  cancelRenderLoop?: () => void;
-  startRenderLoop?: () => void;
-}
-
-/**
- * Renders the terminal (see the module comment), with a notice when
- * ghostty-web fails to load or the process exits.
- *
- * @param props - Component props.
- */
-export function TerminalSurface({
-  adapter,
-  theme,
-  fontFamily,
-  fontSize,
-  symbolsFontUrl,
-  visible = true,
-  autoFocus = false,
-  label,
-  className = '',
-  style,
-}: TerminalSurfaceProps) {
-  const labels = useLabels();
-  const hostRef = useRef<HTMLDivElement>(null);
-  const termRef = useRef<Terminal | null>(null);
-  const [failed, setFailed] = useState<string | null>(null);
-  const [exitCode, setExitCode] = useState<number | null>(null);
-  const themeKey = useMemo(() => JSON.stringify(theme), [theme]);
-  const live = useRef({ theme, fontFamily, fontSize, visible, autoFocus });
-  useLayoutEffect(() => {
-    live.current = { theme, fontFamily, fontSize, visible, autoFocus };
-  });
-  /** Set by the effect: refits and pauses or resumes rendering after `visible` changes. */
-  const showRef = useRef<(shown: boolean) => void>(() => undefined);
-
-  useEffect(() => {
-    const term = termRef.current;
-    if (!term) return;
-    if (term.options.fontFamily !== fontFamily) term.options.fontFamily = fontFamily;
-    if (term.options.fontSize !== fontSize) term.options.fontSize = fontSize;
-  }, [fontFamily, fontSize]);
-
-  useEffect(() => {
-    showRef.current(visible);
-    if (visible && autoFocus) termRef.current?.focus();
-  }, [visible, autoFocus]);
-
-  useEffect(() => {
-    const host = hostRef.current;
-    const mount = host?.querySelector<HTMLElement>('[data-terminal-mount]');
-    if (!mount) return undefined;
-    let disposed = false;
-    let term: Terminal | null = null;
-    let fitTimer = 0;
-    let observer: ResizeObserver | null = null;
-    const unsubscribe: (() => void)[] = [];
-    setFailed(null);
-    setExitCode(null);
-
-    void loadGhostty(symbolsFontUrl).then(
-      ({ Terminal: GhosttyTerminal, FitAddon }) => {
-        if (disposed) return;
-        const { theme: t, fontFamily: family, fontSize: size } = live.current;
-        term = new GhosttyTerminal({
-          fontFamily: family,
-          fontSize: size,
-          theme: t,
-          scrollback: SCROLLBACK,
-          cursorBlink: false,
-          cursorStyle: 'block',
-        });
-        termRef.current = term;
-        openTerminal(term, mount);
-        // Blink only while focused and shown: each blink repaints, and an unfocused terminal's caret needn't move.
-        let focused = false;
-        let shownNow = false;
-        const syncBlink = () => {
-          if (term) term.options.cursorBlink = focused && shownNow;
-        };
-        const onFocusChange = (event: FocusEvent) => {
-          focused = event.type === 'focusin' || mount.contains(event.relatedTarget as Node | null);
-          syncBlink();
-        };
-        mount.addEventListener('focusin', onFocusChange);
-        mount.addEventListener('focusout', onFocusChange);
-        unsubscribe.push(() => {
-          mount.removeEventListener('focusin', onFocusChange);
-          mount.removeEventListener('focusout', onFocusChange);
-        });
-        const fit = new FitAddon();
-        term.loadAddon(fit);
-        let sent = { cols: 0, rows: 0 };
-        const refit = () => {
-          fitTimer = 0;
-          if (!term || disposed || mount.clientWidth === 0 || mount.clientHeight === 0) return;
-          const proposed = fit.proposeDimensions();
-          if (!proposed || proposed.cols < 2 || proposed.rows < 2) return;
-          if (proposed.cols !== term.cols || proposed.rows !== term.rows) term.resize(proposed.cols, proposed.rows);
-          if (proposed.cols === sent.cols && proposed.rows === sent.rows) return;
-          sent = { cols: proposed.cols, rows: proposed.rows };
-          adapter.resize(sent.cols, sent.rows);
-        };
-        const scheduleFit = () => {
-          window.clearTimeout(fitTimer);
-          fitTimer = window.setTimeout(refit, FIT_DEBOUNCE_MS);
-        };
-        observer = new ResizeObserver(scheduleFit);
-        observer.observe(mount);
-        refit();
-
-        let paused = false;
-        showRef.current = (shown) => {
-          if (!term) return;
-          const loop = term as unknown as RenderLoop;
-          shownNow = shown;
-          syncBlink();
-          if (shown) scheduleFit();
-          if (paused === !shown || !loop.cancelRenderLoop || !loop.startRenderLoop) return;
-          paused = !shown;
-          if (paused) loop.cancelRenderLoop();
-          else loop.startRenderLoop();
-        };
-        showRef.current(live.current.visible);
-
-        term.onData((data) => adapter.write(data));
-        unsubscribe.push(
-          adapter.onData((data) => {
-            // An empty write throws (a zero-length wasm alloc).
-            if (data) term?.write(data);
-          }),
-        );
-        if (adapter.onExit) unsubscribe.push(adapter.onExit((code) => setExitCode(code)));
-        if (live.current.autoFocus && live.current.visible) term.focus();
-      },
-      (error: unknown) => {
-        if (!disposed) setFailed(error instanceof Error ? error.message : String(error));
-      },
-    );
-
-    return () => {
-      disposed = true;
-      showRef.current = () => undefined;
-      window.clearTimeout(fitTimer);
-      observer?.disconnect();
-      for (const off of unsubscribe) off();
-      termRef.current = null;
-      term?.dispose();
-    };
-  }, [adapter, themeKey, symbolsFontUrl]);
-
-  const onKeyDownCapture = (e: KeyboardEvent<HTMLDivElement>) => {
-    const term = termRef.current;
-    if (!term) return;
-    const native = e.nativeEvent;
-    const edit = macTerminalKey(native);
-    if (edit) {
-      e.preventDefault();
-      e.stopPropagation();
-      term.input(edit, true);
-      return;
-    }
-    if (native.metaKey && !native.ctrlKey && !native.altKey) {
-      // Cmd+C copies a selection; Cmd+V is the native paste, which the library brackets.
-      if (native.key.toLowerCase() === 'c' && term.copySelection()) e.preventDefault();
-      // Marked composing: ghostty ignores the chord without preventDefault, so it reaches the app.
-      Object.defineProperty(native, 'isComposing', { value: true });
-    }
-  };
-
-  return (
-    <div
-      ref={hostRef}
-      role="group"
-      aria-label={label ?? labels.terminal}
-      className={`relative flex-1 min-h-0 min-w-0 flex overflow-hidden ${className}`}
-      style={style}
-      data-testid="terminal-surface"
-      data-zg-keyscope="editor"
-      onKeyDownCapture={onKeyDownCapture}
-    >
-      {/* ghostty-web makes the mount contenteditable: hide the browser's caret, the canvas draws the real one. */}
-      <div data-terminal-mount className="absolute inset-0 pl-2 pt-1" style={{ caretColor: 'transparent' }} />
-      {(failed !== null || exitCode !== null) && (
-        <div
-          role="status"
-          className={`absolute inset-x-0 bottom-0 m-2 px-2.5 py-1.5 rounded-zg-sm text-zg-label ${
-            failed !== null
-              ? 'bg-zg-danger/10 text-[var(--zg-danger)]'
-              : 'bg-[var(--zg-tray)] text-[var(--zg-text-muted)]'
-          }`}
-        >
-          {failed !== null ? labels.terminalLoadFailed(failed) : labels.terminalExited(exitCode!)}
-        </div>
-      )}
-    </div>
-  );
-}