@industry-theme/xterm-terminal-panel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Principal ADE Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,298 @@
+# @principal-ade/industry-themed-terminal
+
+Industry-themed terminal wrapper with integrated theming support for `xterm.js`.
+
+## Features
+
+- Seamless integration with `@a24z/industry-theme`
+- Automatic theme synchronization with xterm.js
+- Built on pure UI component architecture (no backend dependencies)
+- TypeScript support with full type definitions
+- Custom CSS theming via CSS custom properties
+- Customizable header, badges, and overlays
+- Support for all xterm.js addons (FitAddon, SearchAddon, WebLinksAddon, etc.)
+- Programmatic control via imperative ref API
+- Scroll preservation and user intent tracking
+- Optional WebGL rendering support
+
+## Installation
+
+```bash
+npm install @principal-ade/industry-themed-terminal @xterm/xterm @a24z/industry-theme
+```
+
+or with bun:
+
+```bash
+bun add @principal-ade/industry-themed-terminal @xterm/xterm @a24z/industry-theme
+```
+
+### Optional addons:
+
+```bash
+npm install @xterm/addon-fit @xterm/addon-search @xterm/addon-web-links
+```
+
+## Usage
+
+### Basic Usage with Theme Provider
+
+```tsx
+import { ThemedTerminalWithProvider } from '@principal-ade/industry-themed-terminal';
+import '@xterm/xterm/css/xterm.css';
+import '@principal-ade/industry-themed-terminal/styles.css';
+
+function App() {
+  const handleData = (data: string) => {
+    // Send data to your backend (WebSocket, HTTP, etc.)
+    console.log('User input:', data);
+  };
+
+  return (
+    <ThemedTerminalWithProvider
+      onData={handleData}
+      headerTitle="Terminal"
+      headerSubtitle="/home/user/project"
+    />
+  );
+}
+```
+
+### Usage with Explicit Theme
+
+```tsx
+import { ThemedTerminal } from '@principal-ade/industry-themed-terminal';
+import { useTheme } from '@a24z/industry-theme';
+import '@xterm/xterm/css/xterm.css';
+import '@principal-ade/industry-themed-terminal/styles.css';
+
+function Terminal() {
+  const { theme } = useTheme();
+
+  const handleData = (data: string) => {
+    // Send to backend
+    websocket.send(data);
+  };
+
+  return (
+    <ThemedTerminal
+      theme={theme}
+      onData={handleData}
+      headerTitle="Terminal"
+    />
+  );
+}
+```
+
+### With Programmatic Control
+
+```tsx
+import { ThemedTerminal, ThemedTerminalRef } from '@principal-ade/industry-themed-terminal';
+import { useRef, useEffect } from 'react';
+
+function Terminal() {
+  const terminalRef = useRef<ThemedTerminalRef>(null);
+
+  useEffect(() => {
+    // Connect to backend
+    const ws = new WebSocket('wss://terminal-server.example.com');
+
+    ws.onmessage = (event) => {
+      // Write data from backend to terminal
+      terminalRef.current?.write(event.data);
+    };
+
+    return () => ws.close();
+  }, []);
+
+  const handleData = (data: string) => {
+    ws.send(data);
+  };
+
+  const handleClear = () => {
+    terminalRef.current?.clear();
+  };
+
+  return (
+    <>
+      <button onClick={handleClear}>Clear Terminal</button>
+      <ThemedTerminal
+        ref={terminalRef}
+        onData={handleData}
+        headerTitle="Terminal"
+      />
+    </>
+  );
+}
+```
+
+### With Custom Header and Actions
+
+```tsx
+import { ThemedTerminal } from '@principal-ade/industry-themed-terminal';
+
+function Terminal() {
+  return (
+    <ThemedTerminal
+      onData={handleData}
+      headerTitle="Terminal"
+      headerSubtitle="/home/user/project"
+      headerBadge={{ label: 'Running', color: '#50fa7b' }}
+      onClose={() => console.log('Hide terminal')}
+      onPopOut={() => console.log('Pop out terminal')}
+      onDestroy={() => console.log('Destroy terminal')}
+    />
+  );
+}
+```
+
+### With Overlay State
+
+```tsx
+import { ThemedTerminal } from '@principal-ade/industry-themed-terminal';
+import { Monitor } from 'lucide-react';
+
+function Terminal() {
+  const overlayState = {
+    message: 'Terminal is owned by another window',
+    subtitle: 'This terminal is currently active in a different window.',
+    opacity: 1.0, // Full opacity (default) - completely hides terminal content
+    actions: [
+      {
+        label: 'Claim Ownership',
+        primary: true,
+        onClick: () => console.log('Claim ownership'),
+      },
+    ],
+  };
+
+  return (
+    <ThemedTerminal
+      onData={handleData}
+      overlayState={overlayState}
+    />
+  );
+}
+```
+
+The `opacity` property controls the overlay background opacity (0-1):
+- `1.0` (default): Full opacity - completely hides terminal content
+- `0.85`: Semi-transparent - terminal content slightly visible
+- `0.5`: Very transparent - terminal content clearly visible
+- Omitted: Defaults to `1.0` for full opacity
+
+## API
+
+### ThemedTerminal Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `theme` | `Theme` | Required | Industry theme object |
+| `onData` | `(data: string) => void` | - | Callback when user types |
+| `onBinary` | `(data: string) => void` | - | Callback for binary data |
+| `onResize` | `(cols: number, rows: number) => void` | - | Callback when terminal resizes |
+| `onLinkClick` | `(url: string, isLocalhost: boolean) => void` | - | Callback when link is clicked |
+| `headerTitle` | `string` | `'Terminal'` | Header title text |
+| `headerSubtitle` | `string` | - | Header subtitle text |
+| `headerBadge` | `{ label: string; color?: string }` | - | Header badge |
+| `hideHeader` | `boolean` | `false` | Hide the header |
+| `autoFocus` | `boolean` | `true` | Auto-focus on mount |
+| `isVisible` | `boolean` | `true` | Visibility state |
+| `scrollbarStyle` | `'overlay' \| 'hidden' \| 'thin' \| 'auto-hide'` | `'overlay'` | Scrollbar style |
+| `onClose` | `() => void` | - | Hide button callback |
+| `onDestroy` | `() => void` | - | Destroy button callback |
+| `onPopOut` | `() => void` | - | Pop-out button callback |
+| `overlayState` | `OverlayState` | - | Overlay message state |
+| `className` | `string` | - | Additional CSS classes |
+
+### ThemedTerminalWithProvider Props
+
+Same as `ThemedTerminal` but without the `theme` prop (uses theme from context).
+
+### ThemedTerminalRef Methods
+
+```typescript
+interface ThemedTerminalRef {
+  write: (data: string | Uint8Array) => void;
+  writeln: (data: string) => void;
+  clear: () => void;
+  scrollToBottom: () => void;
+  focus: () => void;
+  getTerminal: () => Terminal | null;
+  findNext: (term: string, options?: ISearchOptions) => boolean;
+  findPrevious: (term: string, options?: ISearchOptions) => boolean;
+  clearSearch: () => void;
+  fit: () => void;
+}
+```
+
+### useThemedTerminal Hook
+
+```typescript
+const { theme, getTerminalOptions } = useThemedTerminal();
+```
+
+Returns:
+- `theme` - Processed theme object with terminal-specific values
+- `getTerminalOptions()` - Function that returns xterm.js terminal options
+
+## Backend Integration
+
+This package provides only the UI component. You need to provide your own backend for terminal functionality:
+
+### WebSocket Example
+
+```typescript
+import { ThemedTerminal, ThemedTerminalRef } from '@principal-ade/industry-themed-terminal';
+import { useRef, useEffect } from 'react';
+
+function Terminal() {
+  const terminalRef = useRef<ThemedTerminalRef>(null);
+  const ws = useRef<WebSocket>();
+
+  useEffect(() => {
+    ws.current = new WebSocket('wss://your-terminal-backend.com');
+
+    ws.current.onmessage = (event) => {
+      terminalRef.current?.write(event.data);
+    };
+
+    ws.current.onclose = () => {
+      terminalRef.current?.write('\r\nConnection closed\r\n');
+    };
+
+    return () => ws.current?.close();
+  }, []);
+
+  const handleData = (data: string) => {
+    ws.current?.send(data);
+  };
+
+  const handleResize = (cols: number, rows: number) => {
+    ws.current?.send(JSON.stringify({ type: 'resize', cols, rows }));
+  };
+
+  return (
+    <ThemedTerminal
+      ref={terminalRef}
+      onData={handleData}
+      onResize={handleResize}
+    />
+  );
+}
+```
+
+## CSS Custom Properties
+
+The package uses CSS custom properties for theming:
+
+- `--terminal-bg` - Background color
+- `--terminal-fg` - Foreground (text) color
+- `--terminal-border` - Border color
+- `--terminal-header-bg` - Header background
+- `--terminal-font-family` - Font family
+- `--terminal-font-size` - Font size
+
+## License
+
+MIT © Principal ADE Team

package/dist/index.css

@@ -0,0 +1,114 @@
+/* src/styles/terminal-theme.css */
+.terminal-container-fix {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+.terminal-container-fix .xterm {
+  font-variant-ligatures: none;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  padding: 5px 0 0 5px;
+}
+
+.xterm-helper-textarea {
+  position: absolute !important;
+  opacity: 0 !important;
+  z-index: -5 !important;
+  white-space: nowrap !important;
+  overflow: hidden !important;
+  resize: none !important;
+  width: 0 !important;
+  height: 0 !important;
+  top: 0 !important;
+  left: -9999em !important;
+}
+
+.xterm-viewport {
+  overflow-y: auto !important;
+  overflow-x: hidden !important;
+}
+
+.terminal-container-fix .xterm-viewport {
+  scrollbar-width: thin;
+  overflow-y: overlay !important;
+  overflow-y: auto !important;
+}
+
+.terminal-container-fix .xterm-viewport::-webkit-scrollbar {
+  background: none;
+  width: 10px;
+}
+
+.terminal-container-fix .xterm-viewport::-webkit-scrollbar-track {
+  background: #0000001a;
+  border-radius: 10px;
+}
+
+.terminal-container-fix .xterm-viewport::-webkit-scrollbar-thumb {
+  background: #fff3 padding-box content-box;
+  border: 2px solid #0000;
+  border-radius: 10px;
+}
+
+.terminal-container-fix .xterm-viewport::-webkit-scrollbar-thumb:hover {
+  background: #ffffff4d padding-box content-box;
+}
+
+.terminal-container-fix .xterm-viewport::-webkit-scrollbar-thumb:active {
+  background: #fff6 padding-box content-box;
+}
+
+.terminal-container-fix.hide-scrollbar .xterm-viewport {
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+}
+
+.terminal-container-fix.hide-scrollbar .xterm-viewport::-webkit-scrollbar {
+  display: none;
+}
+
+.terminal-container-fix.thin-scrollbar .xterm-viewport::-webkit-scrollbar {
+  width: 4px;
+}
+
+.terminal-container-fix.thin-scrollbar .xterm-viewport::-webkit-scrollbar-track {
+  background: none;
+}
+
+.terminal-container-fix.thin-scrollbar .xterm-viewport::-webkit-scrollbar-thumb {
+  background: #ffffff26;
+  border-radius: 4px;
+}
+
+.terminal-container-fix.auto-hide-scrollbar .xterm-viewport::-webkit-scrollbar {
+  opacity: 0;
+  width: 10px;
+  transition: opacity .3s;
+}
+
+.terminal-container-fix.auto-hide-scrollbar:hover .xterm-viewport::-webkit-scrollbar {
+  opacity: 1;
+}
+
+.terminal-container-fix.auto-hide-scrollbar .xterm-viewport::-webkit-scrollbar-thumb {
+  background: #fff0;
+  transition: background .3s;
+}
+
+.terminal-container-fix.auto-hide-scrollbar:hover .xterm-viewport::-webkit-scrollbar-thumb {
+  background: #fff3;
+}
+
+:root {
+  --terminal-bg: #1e1e1e;
+  --terminal-fg: #ccc;
+  --terminal-border: #3c3c3c;
+  --terminal-header-bg: #2d2d2d;
+  --terminal-font-family: "Menlo", "Monaco", "Courier New", monospace;
+  --terminal-font-size: 14px;
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { ThemedTerminal } from './src/components/ThemedTerminal';
+export { ThemedTerminalWithProvider } from './src/components/ThemedTerminalWithProvider';
+export type { ThemedTerminalProps, ThemedTerminalRef, TerminalHeaderBadge, TerminalOverlayState, TerminalScrollPosition, } from './src/types/terminal.types';
+export { useThemedTerminal } from './src/hooks/useThemedTerminal';
+export type { UseThemedTerminalReturn } from './src/hooks/useThemedTerminal';
+export { createTerminalTheme, getTerminalCSSVariables, } from './src/utils/terminalTheme';
+export { TerminalPanel } from './src/panels/TerminalPanel';
+export { TabbedTerminalPanel } from './src/panels/TabbedTerminalPanel';
+export type { TerminalTabContentRef } from './src/panels/TabbedTerminalPanel';
+export { panels, onPackageLoad, onPackageUnload } from './src/panel-exports';
+export type { PanelDefinition, PanelMetadata, PanelComponentProps, PanelContextValue, PanelActions, PanelEventEmitter, TerminalSessionInfo, CreateTerminalSessionOptions, TerminalPanelActions, TerminalEventType, TerminalScope, TerminalPanelProps, TerminalTab, TabbedTerminalPanelProps, OwnershipStatus, OwnershipResult, PortReadyData, } from './src/panel-types';
+export { getTerminalSessions, getTerminalSession, isTerminalLoading, getRepositoryPath, getWorkspacePath, getTerminalDirectory, getTerminalSlice, } from './src/panel-types';
+export type { Theme } from '@principal-ade/industry-theme';
+export type { Terminal, ITheme as XTermTheme, ITerminalOptions } from '@xterm/xterm';
+export type { ISearchOptions } from '@xterm/addon-search';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,0BAA0B,EAAE,MAAM,6CAA6C,CAAC;AAGzF,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,YAAY,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAG7E,OAAO,EACL,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,2BAA2B,CAAC;AAOnC,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,YAAY,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAG9E,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG7E,YAAY,EACV,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,4BAA4B,EAC5B,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,wBAAwB,EACxB,eAAe,EACf,eAAe,EACf,aAAa,GACd,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAO3B,YAAY,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAC;AAG3D,YAAY,EAAE,QAAQ,EAAE,MAAM,IAAI,UAAU,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrF,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}