@dxos/react-ui-terminal 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/lib/chunk-cli.mjs +500 -0
- package/dist/lib/chunk-cli.mjs.map +1 -0
- package/dist/lib/cli.mjs +2 -0
- package/dist/lib/index.mjs +157 -0
- package/dist/lib/index.mjs.map +1 -0
- package/dist/lib/testing.mjs +41 -0
- package/dist/lib/testing.mjs.map +1 -0
- package/dist/types/src/cli/bridge.d.ts +42 -0
- package/dist/types/src/cli/bridge.d.ts.map +1 -0
- package/dist/types/src/cli/console.d.ts +16 -0
- package/dist/types/src/cli/console.d.ts.map +1 -0
- package/dist/types/src/cli/console.test.d.ts +2 -0
- package/dist/types/src/cli/console.test.d.ts.map +1 -0
- package/dist/types/src/cli/context.d.ts +17 -0
- package/dist/types/src/cli/context.d.ts.map +1 -0
- package/dist/types/src/cli/index.d.ts +9 -0
- package/dist/types/src/cli/index.d.ts.map +1 -0
- package/dist/types/src/cli/input.d.ts +14 -0
- package/dist/types/src/cli/input.d.ts.map +1 -0
- package/dist/types/src/cli/input.test.d.ts +2 -0
- package/dist/types/src/cli/input.test.d.ts.map +1 -0
- package/dist/types/src/cli/line-editor.d.ts +35 -0
- package/dist/types/src/cli/line-editor.d.ts.map +1 -0
- package/dist/types/src/cli/line-editor.test.d.ts +2 -0
- package/dist/types/src/cli/line-editor.test.d.ts.map +1 -0
- package/dist/types/src/cli/shell.d.ts +30 -0
- package/dist/types/src/cli/shell.d.ts.map +1 -0
- package/dist/types/src/cli/terminal.d.ts +12 -0
- package/dist/types/src/cli/terminal.d.ts.map +1 -0
- package/dist/types/src/cli/testing.d.ts +20 -0
- package/dist/types/src/cli/testing.d.ts.map +1 -0
- package/dist/types/src/cli/tokenize.d.ts +12 -0
- package/dist/types/src/cli/tokenize.d.ts.map +1 -0
- package/dist/types/src/components/Terminal/Terminal.d.ts +30 -0
- package/dist/types/src/components/Terminal/Terminal.d.ts.map +1 -0
- package/dist/types/src/components/Terminal/Terminal.stories.d.ts +18 -0
- package/dist/types/src/components/Terminal/Terminal.stories.d.ts.map +1 -0
- package/dist/types/src/components/Terminal/index.d.ts +2 -0
- package/dist/types/src/components/Terminal/index.d.ts.map +1 -0
- package/dist/types/src/components/Terminal/theme.d.ts +7 -0
- package/dist/types/src/components/Terminal/theme.d.ts.map +1 -0
- package/dist/types/src/components/index.d.ts +2 -0
- package/dist/types/src/components/index.d.ts.map +1 -0
- package/dist/types/src/index.d.ts +2 -0
- package/dist/types/src/index.d.ts.map +1 -0
- package/dist/types/src/testing.d.ts +23 -0
- package/dist/types/src/testing.d.ts.map +1 -0
- package/dist/types/tsconfig.tsbuildinfo +1 -0
- package/package.json +65 -0
- package/src/cli/bridge.ts +102 -0
- package/src/cli/console.test.ts +73 -0
- package/src/cli/console.ts +91 -0
- package/src/cli/context.ts +26 -0
- package/src/cli/index.ts +13 -0
- package/src/cli/input.test.ts +109 -0
- package/src/cli/input.ts +132 -0
- package/src/cli/line-editor.test.ts +141 -0
- package/src/cli/line-editor.ts +199 -0
- package/src/cli/shell.ts +103 -0
- package/src/cli/terminal.ts +43 -0
- package/src/cli/testing.ts +51 -0
- package/src/cli/tokenize.ts +35 -0
- package/src/components/Terminal/Terminal.stories.tsx +114 -0
- package/src/components/Terminal/Terminal.tsx +118 -0
- package/src/components/Terminal/index.ts +5 -0
- package/src/components/Terminal/theme.ts +87 -0
- package/src/components/index.ts +5 -0
- package/src/index.ts +5 -0
- package/src/testing.ts +56 -0
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
import '@xterm/xterm/css/xterm.css';
|
|
6
|
+
|
|
7
|
+
import type * as Command from '@effect/cli/Command';
|
|
8
|
+
import { FitAddon } from '@xterm/addon-fit';
|
|
9
|
+
import { Terminal as Xterm } from '@xterm/xterm';
|
|
10
|
+
import * as Effect from 'effect/Effect';
|
|
11
|
+
import * as Fiber from 'effect/Fiber';
|
|
12
|
+
import type * as Layer from 'effect/Layer';
|
|
13
|
+
import React, { useEffect, useRef } from 'react';
|
|
14
|
+
|
|
15
|
+
import { type ThemedClassName } from '@dxos/react-ui';
|
|
16
|
+
import { mx } from '@dxos/ui-theme';
|
|
17
|
+
|
|
18
|
+
import { XtermBridge, XtermContext, runShell } from '../../cli';
|
|
19
|
+
import { createXtermTheme } from './theme';
|
|
20
|
+
|
|
21
|
+
export type TerminalProps<Name extends string, R, E, A> = ThemedClassName<{
|
|
22
|
+
/**
|
|
23
|
+
* Root of an `@effect/cli` command tree; typically built with `Command.withSubcommands`.
|
|
24
|
+
*/
|
|
25
|
+
command: Command.Command<Name, R, E, A>;
|
|
26
|
+
/**
|
|
27
|
+
* Services the command handlers need beyond the platform services provided internally, which is
|
|
28
|
+
* why the terminal's own environment is excluded from what this must supply.
|
|
29
|
+
*/
|
|
30
|
+
layer: Layer.Layer<Exclude<R, XtermContext.Provided>, any, never>;
|
|
31
|
+
name?: string;
|
|
32
|
+
version?: string;
|
|
33
|
+
prompt?: string;
|
|
34
|
+
banner?: string;
|
|
35
|
+
fontSize?: number;
|
|
36
|
+
}>;
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Terminal emulator hosting an `@effect/cli` command tree entirely in the browser.
|
|
40
|
+
*
|
|
41
|
+
* The command tree and its layer are built once per mount, so state held by the services (a DXOS
|
|
42
|
+
* client, for instance) persists across commands the way it does in a long-lived shell.
|
|
43
|
+
*/
|
|
44
|
+
export const Terminal = <Name extends string, R, E, A>({
|
|
45
|
+
classNames,
|
|
46
|
+
command,
|
|
47
|
+
layer,
|
|
48
|
+
name,
|
|
49
|
+
version,
|
|
50
|
+
prompt,
|
|
51
|
+
banner,
|
|
52
|
+
fontSize = 13,
|
|
53
|
+
}: TerminalProps<Name, R, E, A>) => {
|
|
54
|
+
const containerRef = useRef<HTMLDivElement>(null);
|
|
55
|
+
|
|
56
|
+
useEffect(() => {
|
|
57
|
+
const container = containerRef.current;
|
|
58
|
+
if (!container) {
|
|
59
|
+
return;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
// The face must come from the mono token rather than the container, whose inherited UI face is
|
|
63
|
+
// proportional and would leave xterm's fixed cells ragged.
|
|
64
|
+
const styles = getComputedStyle(container);
|
|
65
|
+
const xterm = new Xterm({
|
|
66
|
+
fontSize,
|
|
67
|
+
fontFamily: styles.getPropertyValue('--font-mono').trim() || 'monospace',
|
|
68
|
+
cursorBlink: true,
|
|
69
|
+
});
|
|
70
|
+
|
|
71
|
+
const fitAddon = new FitAddon();
|
|
72
|
+
xterm.loadAddon(fitAddon);
|
|
73
|
+
xterm.open(container);
|
|
74
|
+
|
|
75
|
+
// Fitting a zero-sized container pins the terminal to its one-column minimum, and fitting
|
|
76
|
+
// before xterm's render service exists throws, so the observer's initial callback — which
|
|
77
|
+
// lands once the element is measurable and the renderer is up — drives the first fit too.
|
|
78
|
+
const fit = () => {
|
|
79
|
+
if (container.clientWidth > 0 && container.clientHeight > 0) {
|
|
80
|
+
fitAddon.fit();
|
|
81
|
+
}
|
|
82
|
+
};
|
|
83
|
+
|
|
84
|
+
// Drive the palette from the design system tokens so the terminal tracks light/dark without a
|
|
85
|
+
// scheme of its own. The theme class lands on the document from a provider whose effect runs
|
|
86
|
+
// after this one, so the palette is applied on the next frame and refreshed on every change.
|
|
87
|
+
const applyTheme = () => {
|
|
88
|
+
xterm.options.theme = createXtermTheme(container);
|
|
89
|
+
};
|
|
90
|
+
|
|
91
|
+
const frame = requestAnimationFrame(applyTheme);
|
|
92
|
+
const themeObserver = new MutationObserver(applyTheme);
|
|
93
|
+
themeObserver.observe(document.documentElement, { attributes: true, attributeFilter: ['class', 'style'] });
|
|
94
|
+
|
|
95
|
+
xterm.focus();
|
|
96
|
+
|
|
97
|
+
const bridge = new XtermBridge(xterm);
|
|
98
|
+
const shell = runShell(bridge, { command, name, version, prompt, banner }).pipe(
|
|
99
|
+
Effect.provide(XtermContext.layer(bridge)),
|
|
100
|
+
Effect.provide(layer),
|
|
101
|
+
);
|
|
102
|
+
const fiber = Effect.runFork(Effect.scoped(shell));
|
|
103
|
+
|
|
104
|
+
const observer = new ResizeObserver(fit);
|
|
105
|
+
observer.observe(container);
|
|
106
|
+
|
|
107
|
+
return () => {
|
|
108
|
+
cancelAnimationFrame(frame);
|
|
109
|
+
themeObserver.disconnect();
|
|
110
|
+
observer.disconnect();
|
|
111
|
+
Effect.runFork(Fiber.interrupt(fiber));
|
|
112
|
+
bridge.dispose();
|
|
113
|
+
xterm.dispose();
|
|
114
|
+
};
|
|
115
|
+
}, [command, layer, name, version, prompt, banner, fontSize]);
|
|
116
|
+
|
|
117
|
+
return <div ref={containerRef} className={mx('grow w-full h-full overflow-hidden bg-base-surface', classNames)} />;
|
|
118
|
+
};
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
import type { ITheme } from '@xterm/xterm';
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* ANSI slots mapped onto the design system's semantic hues. The theme carries one text weight per
|
|
9
|
+
* hue, so a bright slot reuses its base token rather than inventing a second shade; the neutral
|
|
10
|
+
* slots step through the greys so dim output stays legible against the surface.
|
|
11
|
+
*/
|
|
12
|
+
const ANSI_TOKENS = {
|
|
13
|
+
black: '--color-subdued',
|
|
14
|
+
red: '--color-red-text',
|
|
15
|
+
green: '--color-green-text',
|
|
16
|
+
yellow: '--color-yellow-text',
|
|
17
|
+
blue: '--color-blue-text',
|
|
18
|
+
magenta: '--color-fuchsia-text',
|
|
19
|
+
cyan: '--color-cyan-text',
|
|
20
|
+
white: '--color-description',
|
|
21
|
+
brightBlack: '--color-description',
|
|
22
|
+
brightRed: '--color-red-text',
|
|
23
|
+
brightGreen: '--color-green-text',
|
|
24
|
+
brightYellow: '--color-yellow-text',
|
|
25
|
+
brightBlue: '--color-blue-text',
|
|
26
|
+
brightMagenta: '--color-fuchsia-text',
|
|
27
|
+
brightCyan: '--color-cyan-text',
|
|
28
|
+
brightWhite: '--color-base-fg',
|
|
29
|
+
} as const;
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Resolves design system color tokens to the hex form xterm's parser accepts.
|
|
33
|
+
*
|
|
34
|
+
* Two steps, because neither alone suffices: a probe element inside the token scope turns
|
|
35
|
+
* `light-dark(var(…))` into an absolute computed color, then a canvas rasterizes that color — which
|
|
36
|
+
* the theme states in `oklch()` — down to sRGB channels.
|
|
37
|
+
*/
|
|
38
|
+
const makeResolver = (scope: Element) => {
|
|
39
|
+
const probe = document.createElement('span');
|
|
40
|
+
probe.style.display = 'none';
|
|
41
|
+
scope.appendChild(probe);
|
|
42
|
+
|
|
43
|
+
const context = document.createElement('canvas').getContext('2d', { willReadFrequently: true });
|
|
44
|
+
|
|
45
|
+
const resolve = (token: string): string | undefined => {
|
|
46
|
+
probe.style.color = `var(${token})`;
|
|
47
|
+
const computed = getComputedStyle(probe).color;
|
|
48
|
+
if (!context || computed.length === 0) {
|
|
49
|
+
return undefined;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
context.clearRect(0, 0, 1, 1);
|
|
53
|
+
context.fillStyle = computed;
|
|
54
|
+
context.fillRect(0, 0, 1, 1);
|
|
55
|
+
const [red, green, blue] = context.getImageData(0, 0, 1, 1).data;
|
|
56
|
+
return `#${[red, green, blue].map((channel) => channel.toString(16).padStart(2, '0')).join('')}`;
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
return { resolve, dispose: () => probe.remove() };
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Builds an xterm theme from the design system tokens in scope at `element`, so the terminal
|
|
64
|
+
* follows light/dark and any theme override rather than carrying its own palette.
|
|
65
|
+
*/
|
|
66
|
+
export const createXtermTheme = (element: Element): ITheme => {
|
|
67
|
+
const { resolve, dispose } = makeResolver(element);
|
|
68
|
+
try {
|
|
69
|
+
const surface = resolve('--color-base-surface');
|
|
70
|
+
const foreground = resolve('--color-base-fg');
|
|
71
|
+
const ansi = Object.fromEntries(Object.entries(ANSI_TOKENS).map(([slot, token]) => [slot, resolve(token)])) as Pick<
|
|
72
|
+
ITheme,
|
|
73
|
+
keyof typeof ANSI_TOKENS
|
|
74
|
+
>;
|
|
75
|
+
|
|
76
|
+
return {
|
|
77
|
+
background: surface,
|
|
78
|
+
foreground,
|
|
79
|
+
cursor: foreground,
|
|
80
|
+
cursorAccent: surface,
|
|
81
|
+
selectionBackground: resolve('--color-accent-surface'),
|
|
82
|
+
...ansi,
|
|
83
|
+
};
|
|
84
|
+
} finally {
|
|
85
|
+
dispose();
|
|
86
|
+
}
|
|
87
|
+
};
|
package/src/index.ts
ADDED
package/src/testing.ts
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
const POLL_INTERVAL = 50;
|
|
6
|
+
const DEFAULT_TIMEOUT = 15_000;
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Reads the terminal's visible contents as plain text.
|
|
10
|
+
*
|
|
11
|
+
* xterm splits a row into a span per style run and pads with non-breaking spaces, so a story cannot
|
|
12
|
+
* assert against it with a plain text query — this flattens a row back to what the user sees.
|
|
13
|
+
*/
|
|
14
|
+
export const readTerminal = (element: HTMLElement): string =>
|
|
15
|
+
Array.from(element.querySelectorAll('.xterm-rows > div'))
|
|
16
|
+
.map((row) => (row.textContent ?? '').replace(/ /g, ' ').trimEnd())
|
|
17
|
+
.join('\n');
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* The hidden textarea xterm reads keystrokes from.
|
|
21
|
+
*/
|
|
22
|
+
export const getTerminalInput = (element: HTMLElement): HTMLTextAreaElement | null =>
|
|
23
|
+
element.querySelector('.xterm-helper-textarea');
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Resolves once the terminal shows `text`, or throws with the current contents.
|
|
27
|
+
*/
|
|
28
|
+
export const waitForTerminal = async (element: HTMLElement, text: string, timeout = DEFAULT_TIMEOUT): Promise<void> => {
|
|
29
|
+
const deadline = Date.now() + timeout;
|
|
30
|
+
do {
|
|
31
|
+
if (readTerminal(element).includes(text)) {
|
|
32
|
+
return;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
|
|
36
|
+
} while (Date.now() < deadline);
|
|
37
|
+
|
|
38
|
+
throw new Error(`Timed out waiting for "${text}". Terminal contents:\n${readTerminal(element)}`);
|
|
39
|
+
};
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Types a command and submits it.
|
|
43
|
+
*
|
|
44
|
+
* Waits for the input to echo before sending the return, because the shell drops keystrokes that
|
|
45
|
+
* arrive before its line editor has subscribed — without this the command silently never runs.
|
|
46
|
+
*/
|
|
47
|
+
export const runCommand = async (
|
|
48
|
+
element: HTMLElement,
|
|
49
|
+
command: string,
|
|
50
|
+
keyboard: (text: string) => Promise<unknown>,
|
|
51
|
+
): Promise<void> => {
|
|
52
|
+
getTerminalInput(element)?.focus();
|
|
53
|
+
await keyboard(command);
|
|
54
|
+
await waitForTerminal(element, command);
|
|
55
|
+
await keyboard('{Enter}');
|
|
56
|
+
};
|