@hrnec06/react_utils 1.4.1 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hrnec06/react_utils",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "A debugger component for react.",
   "exports": {
     ".": "./src/index.ts"
@@ -26,12 +26,13 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
-    "@hrnec06/util": "^1.4.21",
+    "@hrnec06/util": "^1.6.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.525.0",
     "react": "^19.1.0",
     "react-dom": "^19.2.3",
-    "uuid": "^13.0.0"
+    "uuid": "^13.0.0",
+    "zod": "^4.2.1"
   },
   "scripts": {
     "dev": "tsup src/index.tsx --format cjs,esm --dts --watch"

package/src/components/Debugger/Debugger.tsx

@@ -19,7 +19,7 @@ interface DebugProps {
 	autoHeight?: boolean,
 	openRoot?: boolean
 }
-export default function Debug({
+function Debug({
 	value,
 	openPaths,
 	excludePaths,
@@ -312,4 +312,7 @@ export default function Debug({
 		),
 		document.body
 	);
-}
+}
+
+export * as terminal from "./DebuggerTerminal";
+export { Debug };

package/src/components/Debugger/DebuggerSymbols.tsx

@@ -1,5 +1,5 @@
 import clsx from "clsx";
-import { ChevronDown } from "lucide-react";
+import { ChevronDown, Terminal } from "lucide-react";
 
 export function Char_Colon() {
 	return (
@@ -60,4 +60,9 @@ export function Chevron_Toggle({
 			}
 		</button>
 	);
+}
+
+export function Terminal_Icon()
+{
+	return ( <Terminal /> );
 }

package/src/components/Debugger/DebuggerTerminal.tsx

@@ -0,0 +1,336 @@
+import React, { createContext, useContext, useEffect, useMemo, useState } from "react";
+import { assert, Optional, ReactUtils } from "@hrnec06/util";
+import useUpdateEffect from "../../hooks/useUpdateEffect";
+import useNamespacedId from "../../hooks/useNamespacedId";
+import z from "zod";
+
+const TERMINAL_NAMESPACE = "terminal";
+
+enum LogRole {
+	Input,
+	History
+}
+
+enum LogType {
+	Info,
+	Warning,
+	Error,
+}
+
+interface LogItem {
+	value: unknown,
+	role: LogRole,
+	type: LogType
+}
+
+interface TerminalContext {
+	terminal: Terminal,
+	parent?: TerminalContext
+}
+const TerminalContext = createContext<Optional<TerminalContext>>(undefined);
+
+type OnInputCallback = (command: string, args: string[], terminal: Terminal) => boolean;
+
+class Terminal
+{
+	public readonly id: string;
+	public readonly name: string;
+	private readonly onInput?: OnInputCallback;
+	
+	private history: ReactUtils.State<LogItem[]>;
+	private inputHistory: ReactUtils.State<string[]>;
+
+	public parentTerminal?: Terminal;
+
+	constructor(
+		id: string,
+		name: string,
+		history: ReactUtils.State<LogItem[]>,
+		inputHistory: ReactUtils.State<string[]>,
+		onInput?: OnInputCallback,
+	)
+	{
+		this.id = id;
+		this.name = name;
+		this.history = history;
+		this.inputHistory = inputHistory;
+		this.onInput = onInput;
+	}
+
+	protected addLog(value: unknown, type: LogType, role: LogRole)
+	{
+		const newEntry = {
+			value: value,
+			role: role,
+			type: type
+		};
+
+		this.history[1](prev => [...prev, newEntry]);
+	}
+
+	public _mount(history: ReactUtils.State<LogItem[]>)
+	{
+		this.history = history;
+	}
+
+	public getLsKey(): string
+	{
+		return "terminal." + this.id;
+	}
+
+	public clear(): Terminal
+	{
+		this.history[1]([]);
+
+		return this;
+	}
+
+	public log(value: unknown, type: LogType = LogType.Info): Terminal
+	{
+		this.addLog(value, type, LogRole.History);
+
+		return this;
+	}
+
+	public getLog(): LogItem[]
+	{
+		return this.history[0];
+	}
+
+	public getInputHistory(): string[]
+	{
+		return this.inputHistory[0];
+	}
+
+	public hasInput(): boolean
+	{
+		return this.onInput !== undefined;
+	}
+
+	public input(value: string): boolean
+	{
+		if (!this.onInput)
+			return false;
+
+		this.inputHistory[1](prev => [
+			...prev.filter((item) => item !== value),
+			value
+		]);
+
+		this.addLog(value, LogType.Info, LogRole.Input);
+
+		try
+		{
+			const args = value.split(" ");
+			const command = args.shift();
+			assert(typeof command === "string");
+	
+			this.handleCommand(command, args);
+
+			return true;
+		}
+		catch (error)
+		{
+			if (typeof error === "string")
+			{
+				this.log(error, LogType.Error);
+			}
+			else if (error instanceof Error)
+			{
+				this.log(error.message, LogType.Error);
+			}
+			else
+			{
+				this.log("Unknown error.", LogType.Error);
+			}
+
+			return false;
+		}
+	}
+
+	private handleCommand(command: string, args: string[])
+	{
+		switch (command)
+		{
+			case 'clear':
+			{
+				this.clear();
+				this.log("Console was cleared!");
+
+				return true;
+			}
+
+			case 'json':
+			{
+				const rest = args.join('');
+
+				try
+				{
+					const parsed = JSON.parse(rest);
+
+					this.log(parsed);
+				}
+				catch (error)
+				{
+					assert(error instanceof SyntaxError);
+
+					throw `Invalid JSON: ${error.message}`;
+				}
+
+				return true;
+			}
+
+			default:
+			{
+				if (this.onInput && this.onInput(command, args, this))
+				{
+					return true;
+				}
+
+				throw `Invalid command: ${command}`;
+			}
+		}
+	}
+}
+
+interface TerminalContextProviderProps extends React.PropsWithChildren {
+	terminal: Terminal
+}
+function TerminalContextProvider({
+	terminal,
+	children
+}: TerminalContextProviderProps)
+{
+	const parent = findTerminalContext();
+
+	return (
+		<TerminalContext.Provider
+			value={{
+				terminal: terminal,
+				parent: parent
+			}}
+		>
+			{children}
+		</TerminalContext.Provider>
+	)
+}
+
+/**
+ * Returns the default history for a terminal
+ */
+function getDefaultHistory(terminal: Terminal)
+{
+	try
+	{
+		const savedValue = localStorage.getItem(terminal.getLsKey());
+
+		const savedValueJSON = JSON.parse(savedValue ?? "[]");
+
+		const schema = z.array(z.object({
+			value: z.any(),
+			role: z.enum(LogRole),
+			type: z.enum(LogType)
+		}));
+
+		const parsed = schema.parse(savedValueJSON);
+
+		return parsed;
+	}
+	catch (error)
+	{
+		localStorage.removeItem(terminal.getLsKey());
+		console.error("Terminal data parse failed: ", error);
+
+		return [];
+	}
+}
+
+/**
+ * Recursively browses the contexts to find a matching terminal
+ */
+function matchTerminal(name: string, ctx: TerminalContext): Optional<TerminalContext>
+{
+	if (name === ctx.terminal.name)
+		return ctx;
+
+	if (ctx.parent)
+		return matchTerminal(name, ctx.parent);
+		
+	return undefined;
+}
+
+/**
+ * Attempts to find a TerminalContext matching the query
+ */
+function findTerminalContext(name?: string): Optional<TerminalContext>
+{
+	const ctx = useContext(TerminalContext);
+
+	if (ctx && name)
+	{
+		return matchTerminal(name, ctx);
+	}
+
+	return ctx;
+}
+
+/**
+ * Get terminal context
+ */
+function useTerminalContext(name: string, shouldThrow: true): Terminal;
+function useTerminalContext(name?: string, shouldThrow?: false): Optional<Terminal>
+function useTerminalContext(name?: string, shouldThrow: boolean = false): Optional<Terminal>
+{
+	const ctx = findTerminalContext(name);
+
+	if (shouldThrow === true && ctx === undefined)
+	{
+		if (name)
+			throw new Error(`Terminal with the name "${name}" was not found.`);
+		else
+			throw new Error(`useTerminalContext may be used only within TerminalContext.Provider!`);
+	}
+
+	return ctx?.terminal;
+}
+
+/**
+ * Initializes a terminal
+ */
+function useTerminal(
+	name: string,
+	onInput?: OnInputCallback,
+): Terminal
+{
+	const id = useNamespacedId(TERMINAL_NAMESPACE);
+
+	const history = useState<LogItem[]>([]);
+	const inputHistory = useState<string[]>([]);
+
+	const terminal = useMemo(() => {
+		return new Terminal(id, name, history, inputHistory, onInput);
+	}, [name, history, onInput]);
+
+	useEffect(() => {
+		const def = getDefaultHistory(terminal);
+
+		history[1](def);
+	}, []);
+
+	useUpdateEffect(() => {
+		localStorage.setItem(terminal.getLsKey(), JSON.stringify(history[0]));
+	}, [history]);
+
+	return terminal;
+}
+
+export {
+	LogRole,
+	LogType,
+	Terminal,
+	TerminalContextProvider,
+	useTerminal,
+	useTerminalContext,
+	
+	type LogItem,
+};

package/src/components/Debugger/parser/DebugParser.tsx

@@ -1,5 +1,7 @@
 import useDebugger from "../DebuggerContext";
 import { matchPath } from "../DebuggerLogic";
+import { Terminal } from "../DebuggerTerminal";
+import DebugTerminal from "./DebugTerminal";
 import ValueArray from "./ValueArray";
 import ValueBoolean from "./ValueBoolean";
 import ValueFunction from "./ValueFunction";
@@ -35,6 +37,9 @@ export default function ParseValue({
 
 			const shouldBeExpanded = (isRootObject && debug.options.openRoot) || (matchPath(path, debug.paths.open) && !matchPath(path, debug.paths.exclude));
 
+			if (value instanceof Terminal)
+				return <DebugTerminal terminal={value} path={path} defaultExpanded={shouldBeExpanded} />
+
 			if (Array.isArray(value)) {
 				return <ValueArray value={value} path={path} defaultExpanded={shouldBeExpanded} />
 			}

package/src/components/Debugger/parser/DebugParserSimple.tsx

@@ -1,3 +1,5 @@
+import { TerminalIcon } from "lucide-react";
+import { Terminal } from "../DebuggerTerminal";
 import ValueBoolean from "./ValueBoolean";
 import ValueFunction from "./ValueFunction";
 import ValueKeyword from "./ValueKeyword";
@@ -42,6 +44,16 @@ export default function ParseValueSimple({
 			if (value === null)
 				return <ValueKeyword value="null" />
 
+			if (value instanceof Terminal)
+				return (
+					<div className="inline-flex gap-1 align-bottom text-white">
+						<div className="size-5">
+							<TerminalIcon />
+						</div>
+						<span>{value.name}</span>
+					</div>)
+				;
+
 			const className = Object.getPrototypeOf(value) !== Object.prototype ? value.constructor.name : null;
 
 			if (className === null || className.length > MAX_LENGTH)