@pokit/tabs-core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Daniel Grant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @pokit/tabs-core
+
+Shared logic for pok tabbed terminal UI adapters.
+
+## Purpose
+
+This package provides framework-agnostic types, state management, and process handling used by tabs adapter implementations like `@pokit/tabs-ink`.
+
+## Installation
+
+```bash
+bun add @pokit/tabs-core
+```
+
+Note: This is typically a dependency of adapter packages, not installed directly.
+
+## Exports
+
+### State Management
+
+```typescript
+import { createInitialState, reducer } from '@pokit/tabs-core';
+```
+
+### Process Manager
+
+```typescript
+import { ProcessManager } from '@pokit/tabs-core';
+```
+
+### Types
+
+```typescript
+import type { TabStatus, TabProcess, EventDrivenState } from '@pokit/tabs-core';
+```
+
+### Status Indicators
+
+```typescript
+import { STATUS_INDICATORS, getStatusIndicator } from '@pokit/tabs-core';
+```
+
+## Documentation
+
+See the [full documentation](https://github.com/openpok/pok/blob/main/docs/packages/tabs-core.md).

package/dist/constants/help-content.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared Help Content for CLI Tabs
+ *
+ * Keyboard shortcut definitions and help overlay content used by all adapters.
+ */
+export type Shortcut = {
+    key: string;
+    description: string;
+};
+export type ShortcutGroup = {
+    title: string;
+    shortcuts: Shortcut[];
+};
+/**
+ * Standard keyboard shortcut help content.
+ * Used by both Ink and OpenTUI help overlays.
+ */
+export declare const HELP_CONTENT: ShortcutGroup[];
+//# sourceMappingURL=help-content.d.ts.map

package/dist/constants/help-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-content.d.ts","sourceRoot":"","sources":["../../src/constants/help-content.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,QAAQ,EAAE,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,aAAa,EA4BvC,CAAC"}

package/dist/constants/help-content.js

@@ -0,0 +1,38 @@
+/**
+ * Shared Help Content for CLI Tabs
+ *
+ * Keyboard shortcut definitions and help overlay content used by all adapters.
+ */
+/**
+ * Standard keyboard shortcut help content.
+ * Used by both Ink and OpenTUI help overlays.
+ */
+export const HELP_CONTENT = [
+    {
+        title: 'Navigation',
+        shortcuts: [
+            { key: '\u2191/\u2193', description: 'Scroll output up/down' },
+            { key: 'Page Up/Dn', description: 'Scroll by page' },
+            { key: 'Tab', description: 'Next tab' },
+            { key: 'Shift+Tab', description: 'Previous tab' },
+            { key: '1-9', description: 'Jump to tab by number' },
+            { key: 'Meta+\u2190/\u2192', description: 'Previous/next tab' },
+        ],
+    },
+    {
+        title: 'Process Control',
+        shortcuts: [
+            { key: 'r', description: 'Restart current process' },
+            { key: 'k', description: 'Kill current process' },
+            { key: 'q', description: 'Quit (with confirmation)' },
+            { key: 'Ctrl+C', description: 'Force quit immediately' },
+        ],
+    },
+    {
+        title: 'Input Mode',
+        shortcuts: [
+            { key: 'i', description: 'Enter input mode' },
+            { key: 'Escape', description: 'Exit input mode' },
+        ],
+    },
+];

package/dist/constants/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Constants Index
+ *
+ * Re-exports all shared constants for CLI tabs.
+ */
+export type { Shortcut, ShortcutGroup } from './help-content.js';
+export { HELP_CONTENT } from './help-content.js';
+export { KEY_SEQUENCES, ctrlKeyToSequence, HELP_HINT_DURATION_MS } from './keyboard.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/constants/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/constants/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/dist/constants/index.js

@@ -0,0 +1,7 @@
+/**
+ * Constants Index
+ *
+ * Re-exports all shared constants for CLI tabs.
+ */
+export { HELP_CONTENT } from './help-content.js';
+export { KEY_SEQUENCES, ctrlKeyToSequence, HELP_HINT_DURATION_MS } from './keyboard.js';

package/dist/constants/keyboard.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Keyboard Constants for CLI Tabs
+ *
+ * Escape sequences and key mappings for terminal input handling.
+ */
+/**
+ * Common terminal escape sequences for special keys.
+ * Used when forwarding input to child processes in focus mode.
+ */
+export declare const KEY_SEQUENCES: {
+    readonly RETURN: "\n";
+    readonly TAB: "\t";
+    readonly BACKSPACE: "";
+    readonly DELETE: "\u001B[3~";
+    readonly ARROW_UP: "\u001B[A";
+    readonly ARROW_DOWN: "\u001B[B";
+    readonly ARROW_RIGHT: "\u001B[C";
+    readonly ARROW_LEFT: "\u001B[D";
+};
+/**
+ * Convert a Ctrl+key combination to its terminal escape sequence.
+ * Ctrl+A = 1, Ctrl+B = 2, ..., Ctrl+Z = 26
+ */
+export declare function ctrlKeyToSequence(key: string): string | null;
+/**
+ * Duration to show help hint on startup (in milliseconds).
+ */
+export declare const HELP_HINT_DURATION_MS = 5000;
+//# sourceMappingURL=keyboard.d.ts.map

package/dist/constants/keyboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard.d.ts","sourceRoot":"","sources":["../../src/constants/keyboard.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;;;;;CAShB,CAAC;AAEX;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM5D;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC"}

package/dist/constants/keyboard.js

@@ -0,0 +1,34 @@
+/**
+ * Keyboard Constants for CLI Tabs
+ *
+ * Escape sequences and key mappings for terminal input handling.
+ */
+/**
+ * Common terminal escape sequences for special keys.
+ * Used when forwarding input to child processes in focus mode.
+ */
+export const KEY_SEQUENCES = {
+    RETURN: '\n',
+    TAB: '\t',
+    BACKSPACE: '\x7f',
+    DELETE: '\x1b[3~',
+    ARROW_UP: '\x1b[A',
+    ARROW_DOWN: '\x1b[B',
+    ARROW_RIGHT: '\x1b[C',
+    ARROW_LEFT: '\x1b[D',
+};
+/**
+ * Convert a Ctrl+key combination to its terminal escape sequence.
+ * Ctrl+A = 1, Ctrl+B = 2, ..., Ctrl+Z = 26
+ */
+export function ctrlKeyToSequence(key) {
+    const code = key.toUpperCase().charCodeAt(0) - 64;
+    if (code >= 1 && code <= 26) {
+        return String.fromCharCode(code);
+    }
+    return null;
+}
+/**
+ * Duration to show help hint on startup (in milliseconds).
+ */
+export const HELP_HINT_DURATION_MS = 5000;

package/dist/hooks/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Hooks Index
+ *
+ * Re-exports all shared hooks for CLI tabs.
+ */
+export type { UseTabsStateOptions, TabsState, TabsActions } from './use-tabs-state.js';
+export { useTabsState } from './use-tabs-state.js';
+export type { KeyboardCallbacks, KeyboardState, NormalizedKeyEvent, KeyboardAction, } from './use-keyboard-handler.js';
+export { processKeyEvent, useKeyboardCallbackRefs, executeKeyboardAction, } from './use-keyboard-handler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,cAAc,GACf,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,2BAA2B,CAAC"}

package/dist/hooks/index.js

@@ -0,0 +1,7 @@
+/**
+ * Hooks Index
+ *
+ * Re-exports all shared hooks for CLI tabs.
+ */
+export { useTabsState } from './use-tabs-state.js';
+export { processKeyEvent, useKeyboardCallbackRefs, executeKeyboardAction, } from './use-keyboard-handler.js';

package/dist/hooks/use-keyboard-handler.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Shared Keyboard Handler Logic
+ *
+ * Framework-agnostic keyboard action handling for tabbed terminal interfaces.
+ * Provides normalized keyboard actions that can be called by framework-specific handlers.
+ */
+/**
+ * Callbacks for keyboard actions in the tabbed view.
+ */
+export type KeyboardCallbacks = {
+    onQuit: () => void;
+    onQuitRequest: () => void;
+    onRestart: (index: number) => void;
+    onKill: (index: number) => void;
+    onEnterFocusMode: () => void;
+    onExitFocusMode: () => void;
+    onSendInput: (data: string) => void;
+    onToggleHelp: () => void;
+    onCloseHelp: () => void;
+};
+/**
+ * Current state needed for keyboard handling decisions.
+ */
+export type KeyboardState = {
+    helpVisible: boolean;
+    focusMode: boolean;
+    quitConfirmPending: boolean;
+    activeIndex: number;
+    tabCount: number;
+};
+/**
+ * Normalized key event structure.
+ * Provides a unified interface for different terminal keyboard APIs.
+ */
+export type NormalizedKeyEvent = {
+    /** The character(s) typed, if any */
+    char?: string;
+    /** Named key (e.g., 'escape', 'tab', 'up', 'down') */
+    name?: string;
+    /** Whether Ctrl was held */
+    ctrl?: boolean;
+    /** Whether Shift was held */
+    shift?: boolean;
+    /** Whether Meta/Alt was held */
+    meta?: boolean;
+};
+/**
+ * Action results from keyboard handling.
+ */
+export type KeyboardAction = {
+    type: 'toggle-help';
+} | {
+    type: 'close-help';
+} | {
+    type: 'exit-focus-mode';
+} | {
+    type: 'send-input';
+    data: string;
+} | {
+    type: 'quit';
+} | {
+    type: 'quit-request';
+} | {
+    type: 'cancel-quit';
+} | {
+    type: 'enter-focus-mode';
+} | {
+    type: 'restart';
+    index: number;
+} | {
+    type: 'kill';
+    index: number;
+} | {
+    type: 'switch-tab';
+    index: number;
+} | {
+    type: 'next-tab';
+} | {
+    type: 'prev-tab';
+} | {
+    type: 'scroll';
+    delta: number;
+} | {
+    type: 'none';
+};
+/**
+ * Process a normalized key event and return the appropriate action.
+ *
+ * This is the core keyboard handling logic, extracted to be framework-agnostic.
+ * Each adapter (Ink, OpenTUI) normalizes their keyboard events and calls this function.
+ */
+export declare function processKeyEvent(event: NormalizedKeyEvent, state: KeyboardState, viewHeight: number): KeyboardAction;
+/**
+ * Hook to create stable references for keyboard callbacks.
+ *
+ * This solves the common React issue where callbacks in keyboard handlers
+ * may have stale closures. The refs always point to the current callback.
+ */
+export declare function useKeyboardCallbackRefs(callbacks: KeyboardCallbacks): {
+    onQuitRef: import("react").RefObject<() => void>;
+    onQuitRequestRef: import("react").RefObject<() => void>;
+    onRestartRef: import("react").RefObject<(index: number) => void>;
+    onKillRef: import("react").RefObject<(index: number) => void>;
+    onEnterFocusModeRef: import("react").RefObject<() => void>;
+    onExitFocusModeRef: import("react").RefObject<() => void>;
+    onSendInputRef: import("react").RefObject<(data: string) => void>;
+    onToggleHelpRef: import("react").RefObject<() => void>;
+    onCloseHelpRef: import("react").RefObject<() => void>;
+};
+/**
+ * Execute a keyboard action using the provided callback refs.
+ */
+export declare function executeKeyboardAction(action: KeyboardAction, refs: ReturnType<typeof useKeyboardCallbackRefs>, scrollBy: (delta: number) => void, switchTab: (index: number) => void, nextTab: () => void, prevTab: () => void): void;
+//# sourceMappingURL=use-keyboard-handler.d.ts.map

package/dist/hooks/use-keyboard-handler.d.ts.map

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

package/dist/hooks/use-keyboard-handler.js

@@ -0,0 +1,224 @@
+/**
+ * Shared Keyboard Handler Logic
+ *
+ * Framework-agnostic keyboard action handling for tabbed terminal interfaces.
+ * Provides normalized keyboard actions that can be called by framework-specific handlers.
+ */
+import { useRef, useEffect } from 'react';
+import { KEY_SEQUENCES, ctrlKeyToSequence } from '../constants/keyboard.js';
+/**
+ * Process a normalized key event and return the appropriate action.
+ *
+ * This is the core keyboard handling logic, extracted to be framework-agnostic.
+ * Each adapter (Ink, OpenTUI) normalizes their keyboard events and calls this function.
+ */
+export function processKeyEvent(event, state, viewHeight) {
+    const { char, name, ctrl, shift, meta } = event;
+    const { helpVisible, focusMode, quitConfirmPending, activeIndex, tabCount } = state;
+    // Help toggle takes priority
+    if (char === '?') {
+        return { type: 'toggle-help' };
+    }
+    // Escape closes help if visible
+    if (name === 'escape' && helpVisible) {
+        return { type: 'close-help' };
+    }
+    // Don't process other keys when help is visible
+    if (helpVisible) {
+        return { type: 'none' };
+    }
+    // Focus mode: forward most input to child process
+    if (focusMode) {
+        if (name === 'escape') {
+            return { type: 'exit-focus-mode' };
+        }
+        const rawInput = getFocusModeInput(event);
+        if (rawInput) {
+            return { type: 'send-input', data: rawInput };
+        }
+        return { type: 'none' };
+    }
+    // Normal mode: handle UI navigation
+    // Quit confirmation handling
+    if (quitConfirmPending) {
+        if (char === 'q' || name === 'q') {
+            return { type: 'quit' };
+        }
+        return { type: 'cancel-quit' };
+    }
+    // Quit request
+    if (char === 'q' || name === 'q') {
+        return { type: 'quit-request' };
+    }
+    // Ctrl+C for instant quit
+    if ((char === 'c' || name === 'c') && ctrl) {
+        return { type: 'quit' };
+    }
+    // Enter focus/input mode
+    if (char === 'i' || name === 'i') {
+        return { type: 'enter-focus-mode' };
+    }
+    // Restart current tab
+    if (char === 'r' || name === 'r') {
+        return { type: 'restart', index: activeIndex };
+    }
+    // Kill current tab's process
+    if (char === 'k' || name === 'k') {
+        return { type: 'kill', index: activeIndex };
+    }
+    // Number keys 1-9 for direct tab access
+    const input = char || name || '';
+    const num = parseInt(input, 10);
+    if (num >= 1 && num <= tabCount) {
+        return { type: 'switch-tab', index: num - 1 };
+    }
+    // Tab navigation
+    if (name === 'tab' && shift) {
+        return { type: 'prev-tab' };
+    }
+    if (name === 'tab') {
+        return { type: 'next-tab' };
+    }
+    // Arrow key tab navigation (with meta)
+    if ((name === 'left' || name === 'leftArrow') && meta) {
+        return { type: 'prev-tab' };
+    }
+    if ((name === 'right' || name === 'rightArrow') && meta) {
+        return { type: 'next-tab' };
+    }
+    // Scrolling
+    if (name === 'up' || name === 'upArrow') {
+        return { type: 'scroll', delta: -1 };
+    }
+    if (name === 'down' || name === 'downArrow') {
+        return { type: 'scroll', delta: 1 };
+    }
+    if (name === 'pageup' || name === 'pageUp') {
+        return { type: 'scroll', delta: -viewHeight };
+    }
+    if (name === 'pagedown' || name === 'pageDown') {
+        return { type: 'scroll', delta: viewHeight };
+    }
+    return { type: 'none' };
+}
+/**
+ * Get the raw input to send to child process when in focus mode.
+ */
+function getFocusModeInput(event) {
+    const { char, name, ctrl } = event;
+    // Map special keys to escape sequences
+    if (name === 'return')
+        return KEY_SEQUENCES.RETURN;
+    if (name === 'tab')
+        return KEY_SEQUENCES.TAB;
+    if (name === 'backspace')
+        return KEY_SEQUENCES.BACKSPACE;
+    if (name === 'delete')
+        return KEY_SEQUENCES.DELETE;
+    if (name === 'up' || name === 'upArrow')
+        return KEY_SEQUENCES.ARROW_UP;
+    if (name === 'down' || name === 'downArrow')
+        return KEY_SEQUENCES.ARROW_DOWN;
+    if (name === 'right' || name === 'rightArrow')
+        return KEY_SEQUENCES.ARROW_RIGHT;
+    if (name === 'left' || name === 'leftArrow')
+        return KEY_SEQUENCES.ARROW_LEFT;
+    // Ctrl+key combinations
+    if (ctrl && name && name.length === 1) {
+        return ctrlKeyToSequence(name);
+    }
+    // Regular character input
+    if (char) {
+        return char;
+    }
+    return null;
+}
+/**
+ * Hook to create stable references for keyboard callbacks.
+ *
+ * This solves the common React issue where callbacks in keyboard handlers
+ * may have stale closures. The refs always point to the current callback.
+ */
+export function useKeyboardCallbackRefs(callbacks) {
+    const onQuitRef = useRef(callbacks.onQuit);
+    const onQuitRequestRef = useRef(callbacks.onQuitRequest);
+    const onRestartRef = useRef(callbacks.onRestart);
+    const onKillRef = useRef(callbacks.onKill);
+    const onEnterFocusModeRef = useRef(callbacks.onEnterFocusMode);
+    const onExitFocusModeRef = useRef(callbacks.onExitFocusMode);
+    const onSendInputRef = useRef(callbacks.onSendInput);
+    const onToggleHelpRef = useRef(callbacks.onToggleHelp);
+    const onCloseHelpRef = useRef(callbacks.onCloseHelp);
+    useEffect(() => {
+        onQuitRef.current = callbacks.onQuit;
+        onQuitRequestRef.current = callbacks.onQuitRequest;
+        onRestartRef.current = callbacks.onRestart;
+        onKillRef.current = callbacks.onKill;
+        onEnterFocusModeRef.current = callbacks.onEnterFocusMode;
+        onExitFocusModeRef.current = callbacks.onExitFocusMode;
+        onSendInputRef.current = callbacks.onSendInput;
+        onToggleHelpRef.current = callbacks.onToggleHelp;
+        onCloseHelpRef.current = callbacks.onCloseHelp;
+    }, [callbacks]);
+    return {
+        onQuitRef,
+        onQuitRequestRef,
+        onRestartRef,
+        onKillRef,
+        onEnterFocusModeRef,
+        onExitFocusModeRef,
+        onSendInputRef,
+        onToggleHelpRef,
+        onCloseHelpRef,
+    };
+}
+/**
+ * Execute a keyboard action using the provided callback refs.
+ */
+export function executeKeyboardAction(action, refs, scrollBy, switchTab, nextTab, prevTab) {
+    switch (action.type) {
+        case 'toggle-help':
+            refs.onToggleHelpRef.current();
+            break;
+        case 'close-help':
+            refs.onCloseHelpRef.current();
+            break;
+        case 'exit-focus-mode':
+            refs.onExitFocusModeRef.current();
+            break;
+        case 'send-input':
+            refs.onSendInputRef.current(action.data);
+            break;
+        case 'quit':
+            refs.onQuitRef.current();
+            break;
+        case 'quit-request':
+        case 'cancel-quit':
+            refs.onQuitRequestRef.current();
+            break;
+        case 'enter-focus-mode':
+            refs.onEnterFocusModeRef.current();
+            break;
+        case 'restart':
+            refs.onRestartRef.current(action.index);
+            break;
+        case 'kill':
+            refs.onKillRef.current(action.index);
+            break;
+        case 'switch-tab':
+            switchTab(action.index);
+            break;
+        case 'next-tab':
+            nextTab();
+            break;
+        case 'prev-tab':
+            prevTab();
+            break;
+        case 'scroll':
+            scrollBy(action.delta);
+            break;
+        case 'none':
+            // Do nothing
+            break;
+    }
+}

package/dist/hooks/use-tabs-state.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared Tab State Management Hook
+ *
+ * Framework-agnostic state management for tabbed terminal interfaces.
+ * Handles tab selection, scroll offsets, auto-scroll behavior, and help hint visibility.
+ */
+import type { TabProcess } from '../types.js';
+export type UseTabsStateOptions = {
+    /** List of tab processes */
+    tabs: TabProcess[];
+    /** Current active tab index */
+    activeIndex: number;
+    /** Callback when active index changes */
+    onActiveIndexChange: (index: number) => void;
+    /** Height of the output view in lines */
+    viewHeight: number;
+};
+export type TabsState = {
+    /** Whether to show the help hint */
+    showHelpHint: boolean;
+    /** Current scroll offset for the active tab */
+    activeScrollOffset: number;
+    /** Whether the user can scroll up */
+    canScrollUp: boolean;
+    /** Whether the user can scroll down */
+    canScrollDown: boolean;
+};
+export type TabsActions = {
+    /** Scroll by a given delta (positive = down, negative = up) */
+    scrollBy: (delta: number) => void;
+    /** Switch to a specific tab by index */
+    switchTab: (index: number) => void;
+    /** Switch to the next tab (wraps around) */
+    nextTab: () => void;
+    /** Switch to the previous tab (wraps around) */
+    prevTab: () => void;
+};
+/**
+ * Hook for managing tabbed interface state.
+ *
+ * Provides:
+ * - Per-tab scroll offsets with auto-scroll behavior
+ * - Tab navigation helpers
+ * - Help hint auto-dismiss timer
+ */
+export declare function useTabsState({ tabs, activeIndex, onActiveIndexChange, viewHeight, }: UseTabsStateOptions): TabsState & TabsActions;
+//# sourceMappingURL=use-tabs-state.d.ts.map

package/dist/hooks/use-tabs-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tabs-state.d.ts","sourceRoot":"","sources":["../../src/hooks/use-tabs-state.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,MAAM,MAAM,mBAAmB,GAAG;IAChC,4BAA4B;IAC5B,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,oCAAoC;IACpC,YAAY,EAAE,OAAO,CAAC;IACtB,+CAA+C;IAC/C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qCAAqC;IACrC,WAAW,EAAE,OAAO,CAAC;IACrB,uCAAuC;IACvC,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,+DAA+D;IAC/D,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,wCAAwC;IACxC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,4CAA4C;IAC5C,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,gDAAgD;IAChD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,EAC3B,IAAI,EACJ,WAAW,EACX,mBAAmB,EACnB,UAAU,GACX,EAAE,mBAAmB,GAAG,SAAS,GAAG,WAAW,CA4F/C"}