@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.
Files changed (69) hide show
  1. package/dist/lib/chunk-cli.mjs +500 -0
  2. package/dist/lib/chunk-cli.mjs.map +1 -0
  3. package/dist/lib/cli.mjs +2 -0
  4. package/dist/lib/index.mjs +157 -0
  5. package/dist/lib/index.mjs.map +1 -0
  6. package/dist/lib/testing.mjs +41 -0
  7. package/dist/lib/testing.mjs.map +1 -0
  8. package/dist/types/src/cli/bridge.d.ts +42 -0
  9. package/dist/types/src/cli/bridge.d.ts.map +1 -0
  10. package/dist/types/src/cli/console.d.ts +16 -0
  11. package/dist/types/src/cli/console.d.ts.map +1 -0
  12. package/dist/types/src/cli/console.test.d.ts +2 -0
  13. package/dist/types/src/cli/console.test.d.ts.map +1 -0
  14. package/dist/types/src/cli/context.d.ts +17 -0
  15. package/dist/types/src/cli/context.d.ts.map +1 -0
  16. package/dist/types/src/cli/index.d.ts +9 -0
  17. package/dist/types/src/cli/index.d.ts.map +1 -0
  18. package/dist/types/src/cli/input.d.ts +14 -0
  19. package/dist/types/src/cli/input.d.ts.map +1 -0
  20. package/dist/types/src/cli/input.test.d.ts +2 -0
  21. package/dist/types/src/cli/input.test.d.ts.map +1 -0
  22. package/dist/types/src/cli/line-editor.d.ts +35 -0
  23. package/dist/types/src/cli/line-editor.d.ts.map +1 -0
  24. package/dist/types/src/cli/line-editor.test.d.ts +2 -0
  25. package/dist/types/src/cli/line-editor.test.d.ts.map +1 -0
  26. package/dist/types/src/cli/shell.d.ts +30 -0
  27. package/dist/types/src/cli/shell.d.ts.map +1 -0
  28. package/dist/types/src/cli/terminal.d.ts +12 -0
  29. package/dist/types/src/cli/terminal.d.ts.map +1 -0
  30. package/dist/types/src/cli/testing.d.ts +20 -0
  31. package/dist/types/src/cli/testing.d.ts.map +1 -0
  32. package/dist/types/src/cli/tokenize.d.ts +12 -0
  33. package/dist/types/src/cli/tokenize.d.ts.map +1 -0
  34. package/dist/types/src/components/Terminal/Terminal.d.ts +30 -0
  35. package/dist/types/src/components/Terminal/Terminal.d.ts.map +1 -0
  36. package/dist/types/src/components/Terminal/Terminal.stories.d.ts +18 -0
  37. package/dist/types/src/components/Terminal/Terminal.stories.d.ts.map +1 -0
  38. package/dist/types/src/components/Terminal/index.d.ts +2 -0
  39. package/dist/types/src/components/Terminal/index.d.ts.map +1 -0
  40. package/dist/types/src/components/Terminal/theme.d.ts +7 -0
  41. package/dist/types/src/components/Terminal/theme.d.ts.map +1 -0
  42. package/dist/types/src/components/index.d.ts +2 -0
  43. package/dist/types/src/components/index.d.ts.map +1 -0
  44. package/dist/types/src/index.d.ts +2 -0
  45. package/dist/types/src/index.d.ts.map +1 -0
  46. package/dist/types/src/testing.d.ts +23 -0
  47. package/dist/types/src/testing.d.ts.map +1 -0
  48. package/dist/types/tsconfig.tsbuildinfo +1 -0
  49. package/package.json +65 -0
  50. package/src/cli/bridge.ts +102 -0
  51. package/src/cli/console.test.ts +73 -0
  52. package/src/cli/console.ts +91 -0
  53. package/src/cli/context.ts +26 -0
  54. package/src/cli/index.ts +13 -0
  55. package/src/cli/input.test.ts +109 -0
  56. package/src/cli/input.ts +132 -0
  57. package/src/cli/line-editor.test.ts +141 -0
  58. package/src/cli/line-editor.ts +199 -0
  59. package/src/cli/shell.ts +103 -0
  60. package/src/cli/terminal.ts +43 -0
  61. package/src/cli/testing.ts +51 -0
  62. package/src/cli/tokenize.ts +35 -0
  63. package/src/components/Terminal/Terminal.stories.tsx +114 -0
  64. package/src/components/Terminal/Terminal.tsx +118 -0
  65. package/src/components/Terminal/index.ts +5 -0
  66. package/src/components/Terminal/theme.ts +87 -0
  67. package/src/components/index.ts +5 -0
  68. package/src/index.ts +5 -0
  69. 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,5 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ export * from './Terminal';
@@ -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
+ };
@@ -0,0 +1,5 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ export * from './Terminal';
package/src/index.ts ADDED
@@ -0,0 +1,5 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ export * from './components';
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
+ };