@mks2508/mks-ui 0.6.8 → 0.8.0

package/dist/react-ui/blocks/Terminal/hooks/useTerminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTerminal.d.ts","sourceRoot":"","sources":["../../../../../src/react-ui/blocks/Terminal/hooks/useTerminal.ts"],"names":[],"mappings":"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"}

package/dist/react-ui/blocks/Terminal/hooks/useTerminal.js

@@ -0,0 +1,198 @@
+'use client';
+
+import { useTerminalSettings } from "./useTerminalSettings.js";
+import { useTerminalConnection } from "./useTerminalConnection.js";
+import { useTerminalFontSize } from "./useTerminalFontSize.js";
+import { useTerminalPaneManager } from "./useTerminalPaneManager.js";
+import { useTerminalDimensions } from "./useTerminalDimensions.js";
+import { useTerminalKeyboardShortcuts } from "./useTerminalKeyboardShortcuts.js";
+import { useCallback, useMemo, useRef } from "react";
+
+//#region src/react-ui/blocks/Terminal/hooks/useTerminal.ts
+/**
+* Main composable terminal hook.
+*
+* Orchestrates all terminal sub-hooks into a single unified API:
+* connection state, font size, pane management, dimensions, keyboard
+* shortcuts, and a `resttyProps` spread object for zero-config wiring.
+*
+* This is the recommended entry point for building custom terminal UIs.
+*
+* @module @mks2508/mks-ui/react/blocks/Terminal/hooks/useTerminal
+*
+* @example
+* ```tsx
+* // Tier 2: Composable with chrome
+* const terminal = useTerminal({ wsUrl: 'ws://localhost:3100/pty' });
+*
+* <TerminalPanelChrome
+*   containerName="my-app"
+*   isConnected={terminal.isConnected}
+*   actionBar={<TerminalActionBar terminal={terminal} />}
+*   footer={<TerminalStatusBar terminal={terminal} />}
+* >
+*   <ResttyTerminal ref={terminal.ref} {...terminal.resttyProps} />
+* </TerminalPanelChrome>
+*
+* // Tier 3: Fully custom layout
+* const terminal = useTerminal({ wsUrl: 'ws://...', keyboardShortcuts: true });
+*
+* <div className="my-terminal">
+*   <ResttyTerminal ref={terminal.ref} {...terminal.resttyProps} className="flex-1" />
+*   <span>{terminal.paneCount} panes, {terminal.dimensions.cols}×{terminal.dimensions.rows}</span>
+* </div>
+* ```
+*/
+/**
+* Main composable terminal hook.
+*
+* Composes `useTerminalConnection`, `useTerminalFontSize`,
+* `useTerminalPaneManager`, `useTerminalDimensions`, and
+* `useTerminalKeyboardShortcuts` into a single unified API.
+*
+* Returns everything needed to build a fully interactive terminal UI:
+* - **Connection** state + reconnect/disconnect
+* - **Font size** with increase/decrease/set
+* - **Pane management** with split/close/setActive
+* - **Dimensions** tracking (cols × rows)
+* - **Actions**: clear, focus, sendInput
+* - **`resttyProps`**: spread onto `<ResttyTerminal>` for zero-config wiring
+*
+* @param options - Terminal configuration
+* @returns Unified terminal state and controls
+*
+* @example
+* ```tsx
+* function MyTerminal() {
+*   const terminal = useTerminal({
+*     wsUrl: 'ws://localhost:3100/pty',
+*     keyboardShortcuts: true,
+*   });
+*
+*   return (
+*     <div className="flex flex-col h-full">
+*       <div className="flex items-center gap-2 p-2">
+*         <span>{terminal.isConnected ? 'Connected' : 'Disconnected'}</span>
+*         <button onClick={terminal.clear}>Clear</button>
+*         <button onClick={() => terminal.splitActive('vertical')}>Split</button>
+*         <button onClick={terminal.fontIncrease}>A+</button>
+*         <button onClick={terminal.fontDecrease}>A-</button>
+*       </div>
+*       <ResttyTerminal ref={terminal.ref} {...terminal.resttyProps} className="flex-1" />
+*       <span>{terminal.dimensions.cols}×{terminal.dimensions.rows} | {terminal.paneCount} panes</span>
+*     </div>
+*   );
+* }
+* ```
+*/
+function useTerminal(options = {}) {
+	const { wsUrl, keyboardShortcuts = false, persistFontSize = true, onConnect, onDisconnect, onError, onResize, onPaneSplit, onPaneClose, onPaneCreated, onActivePaneChange } = options;
+	const ref = useRef(null);
+	const { settings } = useTerminalSettings();
+	const connection = useTerminalConnection({
+		onConnect,
+		onDisconnect,
+		onError
+	});
+	const font = useTerminalFontSize({
+		ref,
+		initial: options.fontSize,
+		persist: persistFontSize
+	});
+	const panes = useTerminalPaneManager({
+		ref,
+		onPaneCreated,
+		onPaneClosed: onPaneClose,
+		onPaneSplit,
+		onActivePaneChange
+	});
+	const dims = useTerminalDimensions();
+	const handleResize = useCallback((cols, rows) => {
+		dims.handleResize(cols, rows);
+		onResize?.(cols, rows);
+	}, [dims.handleResize, onResize]);
+	const clear = useCallback(() => {
+		ref.current?.clear();
+	}, []);
+	const focus = useCallback(() => {
+		ref.current?.focus();
+	}, []);
+	const sendInput = useCallback((data) => {
+		ref.current?.sendInput(data);
+	}, []);
+	const copySelection = useCallback(async () => {
+		return await ref.current?.copySelection() ?? false;
+	}, []);
+	const pasteClipboard = useCallback(async () => {
+		return await ref.current?.pasteClipboard() ?? false;
+	}, []);
+	const reconnect = useCallback(() => {
+		connection.reconnect(ref, wsUrl);
+	}, [connection.reconnect, wsUrl]);
+	const disconnect = useCallback(() => {
+		connection.disconnect(ref);
+	}, [connection.disconnect]);
+	useTerminalKeyboardShortcuts({
+		enabled: keyboardShortcuts,
+		onClear: clear,
+		onFontIncrease: font.increase,
+		onFontDecrease: font.decrease,
+		onFontReset: () => font.set(14),
+		onSplitVertical: () => panes.splitActive("vertical"),
+		onSplitHorizontal: () => panes.splitActive("horizontal"),
+		onClosePane: () => {
+			if (panes.activePaneId !== null) panes.closePane(panes.activePaneId);
+		},
+		onReconnect: reconnect
+	});
+	const resttyProps = useMemo(() => ({
+		wsUrl,
+		fontSize: font.fontSize,
+		onResize: handleResize,
+		onConnect: connection.handlers.onConnect,
+		onDisconnect: connection.handlers.onDisconnect,
+		onError: connection.handlers.onError,
+		onPtyStatus: connection.handlers.onPtyStatus,
+		onPaneCreated: panes.handlers.onPaneCreated,
+		onPaneClosed: panes.handlers.onPaneClosed,
+		onPaneSplit: panes.handlers.onPaneSplit,
+		onActivePaneChange: panes.handlers.onActivePaneChange
+	}), [
+		wsUrl,
+		font.fontSize,
+		handleResize,
+		connection.handlers,
+		panes.handlers
+	]);
+	return {
+		ref,
+		status: connection.status,
+		isConnected: connection.isConnected,
+		reconnect,
+		disconnect,
+		uptimeSeconds: connection.uptimeSeconds,
+		fontSize: font.fontSize,
+		fontIncrease: font.increase,
+		fontDecrease: font.decrease,
+		setFontSize: font.set,
+		isFontMin: font.isMin,
+		isFontMax: font.isMax,
+		paneCount: panes.paneCount,
+		activePaneId: panes.activePaneId,
+		splitActive: panes.splitActive,
+		splitPane: panes.splitPane,
+		closePane: panes.closePane,
+		setActivePane: panes.setActivePane,
+		dimensions: dims.dimensions,
+		clear,
+		focus,
+		sendInput,
+		copySelection,
+		pasteClipboard,
+		settings,
+		resttyProps
+	};
+}
+
+//#endregion
+export { useTerminal };

package/dist/react-ui/blocks/Terminal/hooks/useTerminalConnection.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Terminal connection state tracker hook.
+ *
+ * Tracks connection status derived from ResttyTerminal lifecycle callbacks
+ * (`onConnect`, `onDisconnect`, `onError`, `onPtyStatus`). Returns a
+ * `handlers` object to spread onto `<ResttyTerminal>` for automatic wiring.
+ *
+ * This is NOT a WebSocket manager (that's `useTerminalWebSocket` for xterm).
+ * It's a reactive state tracker that works with any terminal renderer.
+ *
+ * @module @mks2508/mks-ui/react/blocks/Terminal/hooks/useTerminalConnection
+ *
+ * @example
+ * ```tsx
+ * const connection = useTerminalConnection({ onConnect: () => console.log('up') });
+ *
+ * <ResttyTerminal ref={resttyRef} {...connection.handlers} />
+ * <span>{connection.status}</span>
+ * ```
+ */
+import type { TTerminalConnectionStatusToken } from '../Terminal.tokens';
+import type { IResttyTerminalRef } from '../restty/ResttyTerminal.types';
+/**
+ * Options for useTerminalConnection.
+ */
+export interface IUseTerminalConnectionOptions {
+    /** Initial connection status (default: 'disconnected'). */
+    initialStatus?: TTerminalConnectionStatusToken;
+    /** Called when PTY connection opens. */
+    onConnect?: () => void;
+    /** Called when PTY connection closes. */
+    onDisconnect?: () => void;
+    /** Called on connection error. */
+    onError?: (message: string) => void;
+}
+/**
+ * Return type for useTerminalConnection.
+ */
+export interface IUseTerminalConnectionReturn {
+    /** Current connection status. */
+    status: TTerminalConnectionStatusToken;
+    /** Whether the PTY is connected. */
+    isConnected: boolean;
+    /** Reconnect via restty ref. */
+    reconnect: (ref: React.RefObject<IResttyTerminalRef | null>, wsUrl?: string) => void;
+    /** Disconnect via restty ref. */
+    disconnect: (ref: React.RefObject<IResttyTerminalRef | null>) => void;
+    /** Handlers to spread onto ResttyTerminal props. */
+    handlers: {
+        onConnect: () => void;
+        onDisconnect: () => void;
+        onError: (message: string) => void;
+        onPtyStatus: (status: string) => void;
+    };
+    /** Uptime in seconds since connection (null if not connected). */
+    uptimeSeconds: number | null;
+}
+/**
+ * Terminal connection state tracker.
+ *
+ * Derives reactive connection state from ResttyTerminal lifecycle callbacks.
+ * Provides `handlers` to spread onto `<ResttyTerminal>` for zero-config wiring,
+ * plus `reconnect`/`disconnect` imperative controls.
+ *
+ * @param options - Connection tracking options
+ * @returns Connection state, handlers, and imperative controls
+ *
+ * @example
+ * ```tsx
+ * const resttyRef = useRef<IResttyTerminalRef>(null);
+ * const connection = useTerminalConnection({
+ *   onConnect: () => console.log('Terminal connected'),
+ *   onError: (msg) => console.error('Terminal error:', msg),
+ * });
+ *
+ * <ResttyTerminal ref={resttyRef} wsUrl="ws://..." {...connection.handlers} />
+ * {connection.isConnected && <span>Online</span>}
+ * ```
+ */
+export declare function useTerminalConnection(options?: IUseTerminalConnectionOptions): IUseTerminalConnectionReturn;
+//# sourceMappingURL=useTerminalConnection.d.ts.map

package/dist/react-ui/blocks/Terminal/hooks/useTerminalConnection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTerminalConnection.d.ts","sourceRoot":"","sources":["../../../../../src/react-ui/blocks/Terminal/hooks/useTerminalConnection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,2DAA2D;IAC3D,aAAa,CAAC,EAAE,8BAA8B,CAAC;IAE/C,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IAEvB,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAE1B,kCAAkC;IAClC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,iCAAiC;IACjC,MAAM,EAAE,8BAA8B,CAAC;IAEvC,oCAAoC;IACpC,WAAW,EAAE,OAAO,CAAC;IAErB,gCAAgC;IAChC,SAAS,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,kBAAkB,GAAG,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAErF,iCAAiC;IACjC,UAAU,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,kBAAkB,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC;IAEtE,oDAAoD;IACpD,QAAQ,EAAE;QACR,SAAS,EAAE,MAAM,IAAI,CAAC;QACtB,YAAY,EAAE,MAAM,IAAI,CAAC;QACzB,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;QACnC,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;KACvC,CAAC;IAEF,kEAAkE;IAClE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,6BAAkC,GAC1C,4BAA4B,CAoF9B"}

package/dist/react-ui/blocks/Terminal/hooks/useTerminalConnection.js

@@ -0,0 +1,115 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+//#region src/react-ui/blocks/Terminal/hooks/useTerminalConnection.ts
+/**
+* Terminal connection state tracker hook.
+*
+* Tracks connection status derived from ResttyTerminal lifecycle callbacks
+* (`onConnect`, `onDisconnect`, `onError`, `onPtyStatus`). Returns a
+* `handlers` object to spread onto `<ResttyTerminal>` for automatic wiring.
+*
+* This is NOT a WebSocket manager (that's `useTerminalWebSocket` for xterm).
+* It's a reactive state tracker that works with any terminal renderer.
+*
+* @module @mks2508/mks-ui/react/blocks/Terminal/hooks/useTerminalConnection
+*
+* @example
+* ```tsx
+* const connection = useTerminalConnection({ onConnect: () => console.log('up') });
+*
+* <ResttyTerminal ref={resttyRef} {...connection.handlers} />
+* <span>{connection.status}</span>
+* ```
+*/
+/**
+* Terminal connection state tracker.
+*
+* Derives reactive connection state from ResttyTerminal lifecycle callbacks.
+* Provides `handlers` to spread onto `<ResttyTerminal>` for zero-config wiring,
+* plus `reconnect`/`disconnect` imperative controls.
+*
+* @param options - Connection tracking options
+* @returns Connection state, handlers, and imperative controls
+*
+* @example
+* ```tsx
+* const resttyRef = useRef<IResttyTerminalRef>(null);
+* const connection = useTerminalConnection({
+*   onConnect: () => console.log('Terminal connected'),
+*   onError: (msg) => console.error('Terminal error:', msg),
+* });
+*
+* <ResttyTerminal ref={resttyRef} wsUrl="ws://..." {...connection.handlers} />
+* {connection.isConnected && <span>Online</span>}
+* ```
+*/
+function useTerminalConnection(options = {}) {
+	const { initialStatus = "disconnected", onConnect, onDisconnect, onError } = options;
+	const [status, setStatus] = useState(initialStatus);
+	const uptimeStartRef = useRef(null);
+	const [uptimeSeconds, setUptimeSeconds] = useState(null);
+	useEffect(() => {
+		if (status !== "connected" || uptimeStartRef.current === null) return;
+		const interval = setInterval(() => {
+			if (uptimeStartRef.current !== null) setUptimeSeconds(Math.floor((Date.now() - uptimeStartRef.current) / 1e3));
+		}, 1e3);
+		return () => clearInterval(interval);
+	}, [status]);
+	const handleConnect = useCallback(() => {
+		setStatus("connected");
+		uptimeStartRef.current = Date.now();
+		setUptimeSeconds(0);
+		onConnect?.();
+	}, [onConnect]);
+	const handleDisconnect = useCallback(() => {
+		setStatus("disconnected");
+		uptimeStartRef.current = null;
+		setUptimeSeconds(null);
+		onDisconnect?.();
+	}, [onDisconnect]);
+	const handleError = useCallback((message) => {
+		setStatus("error");
+		onError?.(message);
+	}, [onError]);
+	const handlePtyStatus = useCallback((ptyStatus) => {
+		if (ptyStatus === "connected" || ptyStatus === "attached" || ptyStatus === "welcome" || ptyStatus === "created") setStatus("connected");
+		else if (ptyStatus === "connecting") setStatus("connecting");
+		else if (ptyStatus === "error") setStatus("error");
+	}, []);
+	const reconnect = useCallback((ref, wsUrl) => {
+		ref.current?.disconnectPty();
+		if (wsUrl) ref.current?.connectPty(wsUrl);
+		else ref.current?.connectPty();
+		setStatus("connecting");
+	}, []);
+	const disconnect = useCallback((ref) => {
+		ref.current?.disconnectPty();
+		setStatus("disconnected");
+		uptimeStartRef.current = null;
+		setUptimeSeconds(null);
+	}, []);
+	const handlers = useMemo(() => ({
+		onConnect: handleConnect,
+		onDisconnect: handleDisconnect,
+		onError: handleError,
+		onPtyStatus: handlePtyStatus
+	}), [
+		handleConnect,
+		handleDisconnect,
+		handleError,
+		handlePtyStatus
+	]);
+	return {
+		status,
+		isConnected: status === "connected",
+		reconnect,
+		disconnect,
+		handlers,
+		uptimeSeconds
+	};
+}
+
+//#endregion
+export { useTerminalConnection };

package/dist/react-ui/blocks/Terminal/hooks/useTerminalDimensions.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Terminal dimensions tracking hook.
+ *
+ * Tracks terminal grid dimensions (cols × rows) from ResttyTerminal's
+ * `onResize` callback. Provides a `handleResize` function to spread
+ * onto the terminal component.
+ *
+ * @module @mks2508/mks-ui/react/blocks/Terminal/hooks/useTerminalDimensions
+ *
+ * @example
+ * ```tsx
+ * const dims = useTerminalDimensions();
+ *
+ * <ResttyTerminal onResize={dims.handleResize} />
+ * <span>{dims.dimensions.cols}×{dims.dimensions.rows}</span>
+ * ```
+ */
+/**
+ * Terminal grid dimensions.
+ */
+export interface ITerminalDimensions {
+    /** Number of columns. */
+    cols: number;
+    /** Number of rows. */
+    rows: number;
+}
+/**
+ * Return type for useTerminalDimensions.
+ */
+export interface IUseTerminalDimensionsReturn {
+    /** Current terminal grid dimensions. */
+    dimensions: ITerminalDimensions;
+    /** Handler to spread onto ResttyTerminal's `onResize` prop. */
+    handleResize: (cols: number, rows: number) => void;
+}
+/**
+ * Terminal dimensions tracker.
+ *
+ * Maintains reactive state of the terminal's grid dimensions.
+ * Pass `handleResize` to ResttyTerminal's `onResize` prop.
+ *
+ * @param initialDimensions - Initial dimensions (default: 80×24)
+ * @returns Dimensions state and resize handler
+ *
+ * @example
+ * ```tsx
+ * const { dimensions, handleResize } = useTerminalDimensions();
+ *
+ * <ResttyTerminal onResize={handleResize} />
+ * <TerminalDimensionsBadge dimensions={dimensions} />
+ * ```
+ */
+export declare function useTerminalDimensions(initialDimensions?: ITerminalDimensions): IUseTerminalDimensionsReturn;
+//# sourceMappingURL=useTerminalDimensions.d.ts.map

package/dist/react-ui/blocks/Terminal/hooks/useTerminalDimensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTerminalDimensions.d.ts","sourceRoot":"","sources":["../../../../../src/react-ui/blocks/Terminal/hooks/useTerminalDimensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,wCAAwC;IACxC,UAAU,EAAE,mBAAmB,CAAC;IAEhC,+DAA+D;IAC/D,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,iBAAiB,GAAE,mBAA4C,GAC9D,4BAA4B,CAQ9B"}

package/dist/react-ui/blocks/Terminal/hooks/useTerminalDimensions.js

@@ -0,0 +1,57 @@
+'use client';
+
+import { useCallback, useState } from "react";
+
+//#region src/react-ui/blocks/Terminal/hooks/useTerminalDimensions.ts
+/**
+* Terminal dimensions tracking hook.
+*
+* Tracks terminal grid dimensions (cols × rows) from ResttyTerminal's
+* `onResize` callback. Provides a `handleResize` function to spread
+* onto the terminal component.
+*
+* @module @mks2508/mks-ui/react/blocks/Terminal/hooks/useTerminalDimensions
+*
+* @example
+* ```tsx
+* const dims = useTerminalDimensions();
+*
+* <ResttyTerminal onResize={dims.handleResize} />
+* <span>{dims.dimensions.cols}×{dims.dimensions.rows}</span>
+* ```
+*/
+/**
+* Terminal dimensions tracker.
+*
+* Maintains reactive state of the terminal's grid dimensions.
+* Pass `handleResize` to ResttyTerminal's `onResize` prop.
+*
+* @param initialDimensions - Initial dimensions (default: 80×24)
+* @returns Dimensions state and resize handler
+*
+* @example
+* ```tsx
+* const { dimensions, handleResize } = useTerminalDimensions();
+*
+* <ResttyTerminal onResize={handleResize} />
+* <TerminalDimensionsBadge dimensions={dimensions} />
+* ```
+*/
+function useTerminalDimensions(initialDimensions = {
+	cols: 80,
+	rows: 24
+}) {
+	const [dimensions, setDimensions] = useState(initialDimensions);
+	return {
+		dimensions,
+		handleResize: useCallback((cols, rows) => {
+			setDimensions({
+				cols,
+				rows
+			});
+		}, [])
+	};
+}
+
+//#endregion
+export { useTerminalDimensions };

package/dist/react-ui/blocks/Terminal/hooks/useTerminalFontSize.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Terminal font size management hook.
+ *
+ * Manages font size state with ResttyTerminal ref integration. Calls
+ * `ref.current?.setFontSize()` on every change and optionally persists
+ * to localStorage via `useTerminalSettings`.
+ *
+ * Replaces the duplicated `useState(fontSize)` + `handleFontIncrease`/
+ * `handleFontDecrease` pattern found in both interactive panels.
+ *
+ * @module @mks2508/mks-ui/react/blocks/Terminal/hooks/useTerminalFontSize
+ *
+ * @example
+ * ```tsx
+ * const resttyRef = useRef<IResttyTerminalRef>(null);
+ * const font = useTerminalFontSize({ ref: resttyRef });
+ *
+ * <ResttyTerminal ref={resttyRef} fontSize={font.fontSize} />
+ * <button onClick={font.increase} disabled={font.isMax}>+</button>
+ * <span>{font.fontSize}px</span>
+ * <button onClick={font.decrease} disabled={font.isMin}>-</button>
+ * ```
+ */
+import type { IResttyTerminalRef } from '../restty/ResttyTerminal.types';
+/**
+ * Options for useTerminalFontSize.
+ */
+export interface IUseTerminalFontSizeOptions {
+    /** Restty terminal ref for imperative font size updates. */
+    ref: React.RefObject<IResttyTerminalRef | null>;
+    /** Initial font size. Defaults to value from useTerminalSettings (usually 14). */
+    initial?: number;
+    /** Minimum font size (default: 10). */
+    min?: number;
+    /** Maximum font size (default: 24). */
+    max?: number;
+    /** Persist font size to localStorage via useTerminalSettings (default: true). */
+    persist?: boolean;
+}
+/**
+ * Return type for useTerminalFontSize.
+ */
+export interface IUseTerminalFontSizeReturn {
+    /** Current font size in CSS pixels. */
+    fontSize: number;
+    /** Increase font size by 1 (clamped to max). */
+    increase: () => void;
+    /** Decrease font size by 1 (clamped to min). */
+    decrease: () => void;
+    /** Set exact font size (clamped to min/max). */
+    set: (size: number) => void;
+    /** Whether the font size is at minimum bound. */
+    isMin: boolean;
+    /** Whether the font size is at maximum bound. */
+    isMax: boolean;
+}
+/**
+ * Terminal font size management.
+ *
+ * Synchronizes font size state with the ResttyTerminal ref and
+ * optionally persists changes to localStorage. Clamps values to
+ * configurable min/max bounds.
+ *
+ * @param options - Font size configuration
+ * @returns Font size state and mutation functions
+ *
+ * @example
+ * ```tsx
+ * const font = useTerminalFontSize({ ref: resttyRef, persist: true });
+ *
+ * <TerminalFontControls
+ *   fontSize={font.fontSize}
+ *   onIncrease={font.increase}
+ *   onDecrease={font.decrease}
+ *   isMin={font.isMin}
+ *   isMax={font.isMax}
+ * />
+ * ```
+ */
+export declare function useTerminalFontSize(options: IUseTerminalFontSizeOptions): IUseTerminalFontSizeReturn;
+//# sourceMappingURL=useTerminalFontSize.d.ts.map

package/dist/react-ui/blocks/Terminal/hooks/useTerminalFontSize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTerminalFontSize.d.ts","sourceRoot":"","sources":["../../../../../src/react-ui/blocks/Terminal/hooks/useTerminalFontSize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AASzE;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,4DAA4D;IAC5D,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAEhD,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IAEjB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,IAAI,CAAC;IAErB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,IAAI,CAAC;IAErB,gDAAgD;IAChD,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAE5B,iDAAiD;IACjD,KAAK,EAAE,OAAO,CAAC;IAEf,iDAAiD;IACjD,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,2BAA2B,GAAG,0BAA0B,CA0CpG"}