@mks2508/mks-ui 0.3.2 → 0.5.0

package/src/react-ui/blocks/Terminal/TerminalXterm.tsx

@@ -0,0 +1,230 @@
+/**
+ * xterm.js wrapper component.
+ *
+ * Encapsulates xterm.js initialization, addon loading,
+ * and cleanup following React best practices with proper
+ * ref management and effect hooks.
+ *
+ * @module components/devenv/terminal/xterm
+ */
+
+'use client';
+
+import { useEffect, useRef, useCallback } from 'react';
+import { Terminal } from '@xterm/xterm';
+import { FitAddon } from '@xterm/addon-fit';
+import { WebLinksAddon } from '@xterm/addon-web-links';
+import { SearchAddon } from '@xterm/addon-search';
+import { Unicode11Addon } from '@xterm/addon-unicode11';
+import type { ITerminalOptions, ITerminalTheme } from './Terminal.types';
+import '@xterm/xterm/css/xterm.css';
+
+/**
+ * Props for the XTermWrapper component.
+ */
+export interface IXTermWrapperProps {
+  /** Terminal initialization options */
+  options: ITerminalOptions;
+
+  /** Terminal theme (defaults to Synthwave if not provided) */
+  theme?: ITerminalTheme;
+
+  /** Callback when user types data in interactive mode */
+  onData?: (data: string) => void;
+
+  /** Callback when terminal is ready for interaction */
+  onReady?: (terminal: Terminal) => void;
+
+  /** Callback when terminal resizes */
+  onResize?: (cols: number, rows: number) => void;
+
+  /** Custom class name for the container */
+  className?: string;
+}
+
+/**
+ * xterm.js wrapper component.
+ *
+ * Manages xterm.js lifecycle including initialization, addon loading,
+ * WebSocket/SSE connections, and cleanup. Provides auto-resize via
+ * FitAddon and clickable URLs via WebLinksAddon.
+ *
+ * @example
+ * ```tsx
+ * <XTermWrapper
+ *   options={{ mode: 'interactive', wsUrl: 'ws://localhost:3100/terminal' }}
+ *   onData={(data) => console.log('User input:', data)}
+ *   onReady={(terminal) => console.log('Terminal ready')}
+ * />
+ * ```
+ */
+export function XTermWrapper({
+  options,
+  theme,
+  onData,
+  onReady,
+  onResize,
+  className,
+}: IXTermWrapperProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const terminalRef = useRef<Terminal | null>(null);
+  const fitAddonRef = useRef<FitAddon | null>(null);
+  const searchAddonRef = useRef<SearchAddon | null>(null);
+
+  /**
+   * Handle terminal data input from user.
+   */
+  const handleData = useCallback(
+    (data: string) => {
+      if (options.mode === 'interactive' && onData) {
+        onData(data);
+      }
+    },
+    [options.mode, onData]
+  );
+
+  /**
+   * Initialize xterm.js instance and load addons.
+   *
+   * Note: LigaturesAddon uses `fs` (Node.js module) internally,
+   * so it must be loaded via dynamic import to avoid SSR/bundler
+   * errors. All other addons are browser-safe static imports.
+   */
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    let disposed = false;
+
+    // Create terminal instance with options
+    const terminal = new Terminal({
+      cursorBlink: options.cursorBlink ?? true,
+      scrollback: options.scrollback ?? 1000,
+      fontSize: options.fontSize ?? 14,
+      fontFamily:
+        options.fontFamily ??
+        "'JetBrains Mono', 'Fira Code', 'SF Mono', 'Monaco', 'Inconsolata', monospace",
+      theme: theme ?? {},
+      convertEol: true,
+      allowProposedApi: true,
+    });
+
+    // Load browser-safe addons (static imports)
+    const fitAddon = new FitAddon();
+    const webLinksAddon = new WebLinksAddon();
+    const searchAddon = new SearchAddon();
+    const unicode11Addon = new Unicode11Addon();
+
+    terminal.loadAddon(fitAddon);
+    terminal.loadAddon(webLinksAddon);
+    terminal.loadAddon(searchAddon);
+    terminal.loadAddon(unicode11Addon);
+
+    // Enable Unicode 11 support
+    terminal.unicode.activeVersion = '11';
+
+    // Open terminal in container
+    terminal.open(containerRef.current);
+    fitAddon.fit();
+
+    // Store references
+    terminalRef.current = terminal;
+    fitAddonRef.current = fitAddon;
+    searchAddonRef.current = searchAddon;
+
+    // Load LigaturesAddon dynamically (requires `fs` — Node.js only at import time)
+    import('@xterm/addon-ligatures').then(({ LigaturesAddon }) => {
+      if (disposed) return;
+      terminal.loadAddon(new LigaturesAddon());
+    }).catch(() => {
+      // Ligatures addon is optional — gracefully degrade if unavailable
+    });
+
+    // Handle data callback
+    if (options.mode === 'interactive') {
+      terminal.onData(handleData);
+    }
+
+    // Notify ready
+    onReady?.(terminal);
+
+    // Cleanup on unmount
+    return () => {
+      disposed = true;
+      terminal.dispose();
+    };
+    // Only run on mount/unmount
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  /**
+   * Handle window resize with auto-fit.
+   */
+  useEffect(() => {
+    const handleResize = () => {
+      if (!fitAddonRef.current || !terminalRef.current) return;
+
+      const previousDims = { cols: terminalRef.current.cols, rows: terminalRef.current.rows };
+      fitAddonRef.current.fit();
+
+      // Notify parent of resize if dimensions changed
+      if (
+        onResize &&
+        (terminalRef.current.cols !== previousDims.cols ||
+          terminalRef.current.rows !== previousDims.rows)
+      ) {
+        onResize(terminalRef.current.cols, terminalRef.current.rows);
+      }
+    };
+
+    window.addEventListener('resize', handleResize);
+    return () => window.removeEventListener('resize', handleResize);
+  }, [onResize]);
+
+  /**
+   * Handle theme updates.
+   */
+  useEffect(() => {
+    if (!terminalRef.current || !theme) return;
+
+    terminalRef.current.options.theme = theme;
+  }, [theme]);
+
+  /**
+   * Handle data callback updates.
+   */
+  useEffect(() => {
+    if (!terminalRef.current) return;
+
+    // Remove previous listener
+    terminalRef.current.onData(undefined!);
+
+    // Add new listener if interactive mode
+    if (options.mode === 'interactive' && onData) {
+      terminalRef.current.onData(onData);
+    }
+  }, [options.mode, onData]);
+
+  return (
+    <div
+      ref={containerRef}
+      className={className ?? 'xterm-container w-full h-full'}
+      style={{ minHeight: '400px' }}
+      data-terminal-mode={options.mode ?? 'interactive'}
+    />
+  );
+}
+
+/**
+ * Export search addon reference for external access.
+ *
+ * Allows parent components to trigger search in the terminal buffer.
+ */
+export function useTerminalSearch(terminalRef: React.RefObject<Terminal | null>) {
+  const search = useCallback((_term: string, _options?: { caseSensitive?: boolean; regex?: boolean }) => {
+    // The search addon needs to be accessed differently
+    // This is a placeholder for future search functionality
+    return false;
+  }, [terminalRef]);
+
+  return { search };
+}

package/src/react-ui/blocks/Terminal/XTermAdapter.ts

@@ -0,0 +1,163 @@
+/**
+ * XTerm Adapter - ITerminalAdapter implementation for xterm.js.
+ *
+ * Wrapper class that adapts xterm.js Terminal to the ITerminalAdapter
+ * interface, enabling consistent API across different backends.
+ *
+ * @module components/devenv/terminal/XTermAdapter
+ */
+
+import { Terminal } from '@xterm/xterm';
+import { FitAddon } from '@xterm/addon-fit';
+import type {
+  ITerminalAdapter,
+  ITerminalAdapterCapabilities,
+  ITerminalOptions,
+  ITerminalMode,
+} from './Terminal.types';
+
+/**
+ * XTermAdapter implements ITerminalAdapter for xterm.js.
+ *
+ * Provides xterm.js functionality through the standardized adapter interface.
+ * Manages terminal lifecycle including initialization, data writing,
+ * resizing, and cleanup.
+ */
+export class XTermAdapter implements ITerminalAdapter {
+  /** Backend type identifier */
+  public readonly type = 'xterm' as const;
+
+  /** Adapter capabilities for runtime feature detection */
+  public readonly capabilities: ITerminalAdapterCapabilities = {
+    managesOwnConnection: false,
+    gpuRendering: false,
+    multiPane: false,
+    builtinThemes: false,
+  };
+
+  /** xterm.js Terminal instance */
+  private terminal: Terminal | null = null;
+
+  /** FitAddon for auto-resize */
+  private fitAddon: FitAddon | null = null;
+
+  /** Current options */
+  private options: ITerminalOptions;
+
+  /**
+   * Create XTermAdapter instance.
+   *
+   * @param options - Terminal initialization options
+   */
+  constructor(options: ITerminalOptions) {
+    this.options = options;
+  }
+
+  /**
+   * Initialize the terminal in the given container element.
+   *
+   * Creates xterm.js Terminal instance, loads addons, and opens
+   * in the provided container.
+   *
+   * @param container - DOM element to render terminal into
+   * @param options - Terminal initialization options
+   * @returns Promise that resolves when terminal is ready
+   */
+  async initialize(container: HTMLElement, options: ITerminalOptions): Promise<void> {
+    this.options = options;
+
+    // Create terminal instance
+    this.terminal = new Terminal({
+      cursorBlink: options.cursorBlink ?? true,
+      scrollback: options.scrollback ?? 1000,
+      fontSize: options.fontSize ?? 14,
+      fontFamily:
+        options.fontFamily ??
+        "'JetBrains Mono', 'Fira Code', 'SF Mono', 'Monaco', 'Inconsolata', monospace",
+      theme: options.theme ?? {},
+      convertEol: true,
+    });
+
+    // Load fit addon
+    this.fitAddon = new FitAddon();
+    this.terminal.loadAddon(this.fitAddon);
+
+    // Open terminal
+    this.terminal.open(container);
+    this.fitAddon.fit();
+
+    // Setup data handler for interactive mode
+    if (options.mode === 'interactive' && options.onData) {
+      this.terminal.onData(options.onData);
+    }
+  }
+
+  /**
+   * Write data to the terminal without newline.
+   *
+   * @param data - String data to write
+   */
+  write(data: string): void {
+    this.terminal?.write(data);
+  }
+
+  /**
+   * Write data to the terminal with newline.
+   *
+   * @param data - String data to write
+   */
+  writeln(data: string): void {
+    this.terminal?.writeln(data);
+  }
+
+  /**
+   * Clear the terminal buffer.
+   */
+  clear(): void {
+    this.terminal?.clear();
+  }
+
+  /**
+   * Resize the terminal to the given dimensions.
+   *
+   * @param cols - Number of columns
+   * @param rows - Number of rows
+   */
+  resize(cols: number, rows: number): void {
+    this.terminal?.resize(cols, rows);
+  }
+
+  /**
+   * Dispose of the terminal and release resources.
+   */
+  dispose(): void {
+    this.terminal?.dispose();
+    this.terminal = null;
+    this.fitAddon = null;
+  }
+
+  /**
+   * Switch between interactive and readonly modes.
+   *
+   * @param mode - Target mode
+   */
+  setMode(mode: ITerminalMode): void {
+    // xterm.js doesn't have a built-in readonly mode
+    // We handle this at the component level by not attaching onData handler
+    this.options = { ...this.options, mode };
+  }
+
+  /**
+   * Focus the terminal for input.
+   */
+  focus(): void {
+    this.terminal?.focus();
+  }
+
+  /**
+   * Remove focus from the terminal.
+   */
+  blur(): void {
+    this.terminal?.blur();
+  }
+}

package/src/react-ui/blocks/Terminal/chrome.ts

@@ -0,0 +1,25 @@
+/**
+ * Terminal Chrome — lightweight barrel export.
+ *
+ * Exports only the glassmorphism shell components (no restty, no xterm).
+ * Use `@mks2508/mks-ui/react/blocks/Terminal/chrome` for zero terminal deps.
+ *
+ * @module @mks2508/mks-ui/react/blocks/Terminal/chrome
+ */
+
+// Chrome shell
+export { TerminalPanelChrome, NOISE_TEXTURE_SVG, terminalScrollStyles } from './panel/TerminalPanelChrome';
+export { TerminalPanelHeader } from './panel/TerminalPanelHeader';
+export { TerminalPanelFooter } from './panel/TerminalPanelFooter';
+
+// Chrome styles + variants
+export {
+  terminalChromeStyles,
+  terminalChromeVariants,
+  ACCENT_GRADIENTS,
+  type TerminalChromeSlot,
+  type TerminalChromeVariantProps,
+} from './panel/TerminalPanelChrome.styles';
+
+// Chrome types
+export type { ITerminalPanelChromeProps } from './panel/TerminalPanelChrome.types';