feat(terminal): introduce terminal package with session management and UI components

aesopov · aesopov · commit be9a442e422c · 2026-05-05T16:39:17.000+03:00
- Added TerminalSession class for managing terminal sessions and handling input/output.
- Implemented TerminalView component for rendering terminal UI using xterm.js.
- Created utility functions for path normalization and hidden command formatting.
- Established state management with Jotai atoms for terminal sessions.
- Defined types for terminal session management and capabilities.
- Included CSS modules for terminal styling.
- Configured TypeScript and build settings for the new terminal package.
diff --git a/packages/terminal/package.json b/packages/terminal/package.json
@@ -0,0 +1,71 @@
+{
+  "name": "@dotdirfm/terminal",
+  "version": "0.1.0",
+  "description": "Terminal session and xterm.js terminal React component for DotDir.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.mts"
+    },
+    "./terminal.css": {
+      "import": "./dist/terminal.css"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "dotdir",
+    "terminal",
+    "xterm",
+    "pty",
+    "react"
+  ],
+  "author": "Mikhail Isupov",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotdirfm/dotdir.git"
+  },
+  "homepage": "https://github.com/dotdirfm/dotdir#readme",
+  "bugs": {
+    "url": "https://github.com/dotdirfm/dotdir/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "dependencies": {
+    "@dotdirfm/commands": "workspace:*",
+    "@dotdirfm/ui-bridge": "workspace:*",
+    "@dotdirfm/ui-focus": "workspace:*",
+    "@dotdirfm/ui-utils": "workspace:*",
+    "@xterm/addon-fit": "catalog:",
+    "@xterm/xterm": "catalog:",
+    "jotai": "catalog:"
+  },
+  "devDependencies": {
+    "@tsdown/css": "catalog:",
+    "@types/react": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "^4.1.5"
+  },
+  "packageManager": "pnpm@10.30.3"
+}
diff --git a/packages/terminal/src/TerminalSession.ts b/packages/terminal/src/TerminalSession.ts
diff --git a/packages/terminal/src/TerminalView.tsx b/packages/terminal/src/TerminalView.tsx
@@ -1,7 +1,7 @@
 import { useCommandRegistry } from "@dotdirfm/commands";
 import { DOTDIR_EXIT, SHOW_COMMAND_PALETTE, SHOW_EXTENSIONS, TOGGLE_HIDDEN_FILES, TOGGLE_PANELS } from "@dotdirfm/commands";
 import { useFocusContext } from "@dotdirfm/ui-focus";
-import styles from "@/styles/terminal.module.css";
+import styles from "./terminal.module.css";
 import { FitAddon } from "@xterm/addon-fit";
 import { Terminal, type IDisposable } from "@xterm/xterm";
 import "@xterm/xterm/css/xterm.css";
@@ -102,7 +102,7 @@ export function TerminalView({ session, expanded = false, focusRequestKey = 0 }:
         const w = body.clientWidth;
         const h = body.clientHeight;
         const last = lastFitSizeRef.current;
-        if (last.w === w && last.h === h) return;
+        if (last.w === last.h && last.h === h) return;
         lastFitSizeRef.current = { w, h };
         fit.fit();
         void session.resize(Math.max(2, term.cols), Math.max(1, term.rows));
diff --git a/packages/terminal/src/css-modules.d.ts b/packages/terminal/src/css-modules.d.ts
@@ -0,0 +1,9 @@
+declare module "*.module.css" {
+  const classes: Record<string, string>;
+  export default classes;
+}
+
+declare module "*.css" {
+  const content: string;
+  export default content;
+}
diff --git a/packages/terminal/src/index.ts b/packages/terminal/src/index.ts
@@ -0,0 +1,11 @@
+export { TerminalSession } from "./TerminalSession";
+export { TerminalView } from "./TerminalView";
+export { normalizeTerminalPath, formatHiddenCd } from "./path";
+export { terminalSessionsAtom, terminalActiveSessionIdAtom } from "./terminalAtoms";
+export type {
+  ManagedTerminalSession,
+  PtyLaunchInfo,
+  TerminalCapabilities,
+  TerminalSessionEvent,
+  TerminalSessionStatus,
+} from "./types";
diff --git a/packages/terminal/src/path.ts b/packages/terminal/src/path.ts
diff --git a/packages/terminal/src/terminal.module.css b/packages/terminal/src/terminal.module.css
@@ -0,0 +1,26 @@
+.terminal-container {
+  flex: 1 1 auto;
+  min-height: 0;
+  width: 100%;
+  overflow: hidden;
+}
+
+.terminal-container :global(.xterm) {
+  height: 100%;
+  padding: 0 0 0 4px;
+  display: grid;
+  padding-bottom: 1px;
+}
+
+.terminal-container :global(.xterm-viewport) {
+  height: 100% !important;
+  overflow-y: auto !important;
+}
+
+.terminal-container :global(.xterm .xterm-viewport) {
+  position: absolute !important;
+  top: 0 !important;
+  bottom: 0 !important;
+  left: 0 !important;
+  right: 0 !important;
+}
diff --git a/packages/terminal/src/terminalAtoms.ts b/packages/terminal/src/terminalAtoms.ts
diff --git a/packages/terminal/src/types.ts b/packages/terminal/src/types.ts
diff --git a/packages/terminal/tsconfig.json b/packages/terminal/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}
diff --git a/packages/terminal/tsdown.config.ts b/packages/terminal/tsdown.config.ts
@@ -0,0 +1,20 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: {
+    index: "src/index.ts",
+  },
+  format: ["esm", "cjs"],
+  dts: true,
+  clean: true,
+  deps: {
+    neverBundle: ["react", "react/jsx-runtime"],
+  },
+  css: {
+    fileName: "terminal.css",
+    inject: true,
+    modules: {
+      localsConvention: "camelCase",
+    },
+  },
+});
diff --git a/packages/ui/lib/dialogs/dialogContext.tsx b/packages/ui/lib/dialogs/dialogContext.tsx
@@ -317,9 +317,7 @@ export function DialogProvider({ children }: { children: ReactNode }) {
         dialogs: prev.dialogs.slice(0, -1),
       };
     });
-  }, []);
-
-  const updateDialog = useCallback((update: DialogUpdate) => {
+  }, []);  const updateDialog = useCallback((update: DialogUpdate) => {
     setState((prev) => {
       const current = prev.dialogs.length > 0 ? prev.dialogs[prev.dialogs.length - 1]! : null;
       if (current?.type === "deleteProgress" || current?.type === "copyProgress" || current?.type === "moveProgress") {
diff --git a/packages/ui/lib/features/command-line/commandLineCd.ts b/packages/ui/lib/features/command-line/commandLineCd.ts
@@ -7,7 +7,7 @@
  */
 
 import type { Bridge } from "@dotdirfm/ui-bridge";
-import { normalizeTerminalPath } from "@/features/terminal/path";
+import { normalizeTerminalPath } from "@dotdirfm/terminal";
 import { join, normalizePath, resolveDotSegments } from "@dotdirfm/ui-utils";
 
 export type ParsedCdCommand =
diff --git a/packages/ui/lib/features/command-line/useCommandLine.tsx b/packages/ui/lib/features/command-line/useCommandLine.tsx
@@ -6,7 +6,7 @@ import { parseCdCommand, resolveCdPath } from "@/features/command-line/commandLi
 import { isExistingDirectory } from "@/features/file-system/utils";
 import { useActivePanelNavigation } from "@/features/panels/panelControllers";
 import { useUserSettings } from "@/features/settings/useUserSettings";
-import { normalizeTerminalPath } from "@/features/terminal/path";
+import { normalizeTerminalPath } from "@dotdirfm/terminal";
 import type { TerminalContextValue } from "@/features/terminal/useTerminal";
 import { normalizePath, resolveDotSegments } from "@dotdirfm/ui-utils";
 import { useAtomValue } from "jotai";
diff --git a/packages/ui/lib/features/terminal/Terminal.tsx b/packages/ui/lib/features/terminal/Terminal.tsx
@@ -1,6 +1,6 @@
 import { panelsVisibleAtom, terminalFocusRequestKeyAtom } from "@/atoms";
 import { Tabs, type TabsItem } from "@/components/Tabs/Tabs";
-import { TerminalView } from "@/features/terminal/TerminalView";
+import { TerminalView } from "@dotdirfm/terminal";
 import { useTerminal } from "@/features/terminal/useTerminal";
 import styles from "@/styles/terminal.module.css";
 import { cx } from "@dotdirfm/ui-utils";
diff --git a/packages/ui/lib/features/terminal/useTerminal.tsx b/packages/ui/lib/features/terminal/useTerminal.tsx
@@ -8,7 +8,7 @@ import type { TerminalProfile } from "@dotdirfm/ui-bridge";
 import { useBridge } from "@dotdirfm/ui-bridge";
 import { useCommandRegistry } from "@dotdirfm/commands";
 import { useActivePanelNavigation } from "@/features/panels/panelControllers";
-import { normalizeTerminalPath } from "@/features/terminal/path";
+import { normalizeTerminalPath } from "@dotdirfm/terminal";
 import { useTerminalState, type TerminalState } from "@/features/terminal/useTerminalState";
 import { useFocusContext } from "@dotdirfm/ui-focus";
 import { normalizePath } from "@dotdirfm/ui-utils";
diff --git a/packages/ui/lib/features/terminal/useTerminalState.ts b/packages/ui/lib/features/terminal/useTerminalState.ts
@@ -1,9 +1,9 @@
 import type { TerminalProfile } from "@dotdirfm/ui-bridge";
 import { useBridge } from "@dotdirfm/ui-bridge";
-import { formatHiddenCd, normalizeTerminalPath } from "@/features/terminal/path";
-import { terminalActiveSessionIdAtom, terminalSessionsAtom } from "@/features/terminal/terminalAtoms";
-import { TerminalSession } from "@/features/terminal/TerminalSession";
-import type { ManagedTerminalSession } from "@/features/terminal/types";
+import { formatHiddenCd, normalizeTerminalPath } from "@dotdirfm/terminal";
+import { terminalActiveSessionIdAtom, terminalSessionsAtom } from "@dotdirfm/terminal";
+import { TerminalSession } from "@dotdirfm/terminal";
+import type { ManagedTerminalSession } from "@dotdirfm/terminal";
 import { useFocusContext } from "@dotdirfm/ui-focus";
 import { useAtomValue, useSetAtom } from "jotai";
 import { useLatestRef } from "@/hooks/useLatestRef";
diff --git a/packages/ui/lib/hooks/useViewerEditorState.tsx b/packages/ui/lib/hooks/useViewerEditorState.tsx
@@ -10,7 +10,7 @@ import { basename } from "@dotdirfm/ui-utils";
 import { useEditorRegistry, useFsProviderRegistry, useViewerRegistry } from "@/viewerEditorRegistry";
 import { useLatestRef } from "@/hooks/useLatestRef";
 import { useAtomValue, useSetAtom } from "jotai";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 
 function sameViewerDialog(
   dialog: ReturnType<typeof useDialog>["dialog"],
@@ -81,7 +81,6 @@ export function useViewerEditorState(): UseViewerEditorStateResult {
   const leftActiveTab = useAtomValue(leftActiveTabAtom);
   const rightActiveTab = useAtomValue(rightActiveTabAtom);
   const [editorDirty, setEditorDirty] = useState(false);
-  const editorCloseConfirmOpenRef = useRef(false);
   const { showHidden } = useShowHidden();
   const { dialog, showDialog, replaceDialog, closeDialog } = useDialog();
 
@@ -134,14 +133,12 @@ export function useViewerEditorState(): UseViewerEditorStateResult {
   }, []);
 
   const requestCloseEditor = useCallback(() => {
-    if (editorCloseConfirmOpenRef.current) return;
     if (!editorDirty || !editorFile) {
       focusContext.restore();
       setEditorDirty(false);
       setEditorFile(null);
       return;
     }
-    editorCloseConfirmOpenRef.current = true;
     showDialog({
       type: "message",
       title: "Unsaved Changes",
@@ -151,7 +148,6 @@ export function useViewerEditorState(): UseViewerEditorStateResult {
           label: "Cancel",
           default: true,
           onClick: () => {
-            editorCloseConfirmOpenRef.current = false;
             requestAnimationFrame(() => {
               focusContext.request("editor");
             });
@@ -160,7 +156,6 @@ export function useViewerEditorState(): UseViewerEditorStateResult {
         {
           label: "Discard",
           onClick: () => {
-            editorCloseConfirmOpenRef.current = false;
             focusContext.restore();
             setEditorDirty(false);
             setEditorFile(null);
diff --git a/packages/ui/package.json b/packages/ui/package.json
@@ -59,12 +59,11 @@
     "@dotdirfm/extension-api": "workspace:*",
     "@dotdirfm/file-list": "workspace:*",
     "@dotdirfm/fss": "workspace:*",
+    "@dotdirfm/terminal": "workspace:*",
     "@dotdirfm/ui-bridge": "workspace:*",
     "@dotdirfm/ui-focus": "workspace:*",
     "@dotdirfm/ui-utils": "workspace:*",
     "@tanstack/react-virtual": "catalog:",
-    "@xterm/addon-fit": "catalog:",
-    "@xterm/xterm": "catalog:",
     "jotai": "catalog:",
     "jsonc-parser": "catalog:",
     "marked": "catalog:",
diff --git a/packages/ui/vite.config.ts b/packages/ui/vite.config.ts
@@ -26,6 +26,7 @@ export default defineConfig({
         "jotai",
         "@xterm/addon-fit",
         "@xterm/xterm",
+        "@xterm/xterm/css/xterm.css",
         "cmdk",
         "jsonc-parser",
         "marked",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
