@nindroidsystems/pluginator 2.3.0

package/dist/ui/hooks/useDashboard.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Dashboard State Management Hook
+ *
+ * Manages dashboard state including active layout, widget states,
+ * and widget registry initialization.
+ *
+ * @since v1.64.0
+ */
+import type { Tier } from '../../core/types/auth.js';
+import { type DashboardConfig, type DashboardLayout, type RegisteredWidget, type WidgetState } from '../widgets/index.js';
+export interface UseDashboardOptions {
+    /** User's tier */
+    tier?: Tier;
+    /** Initial layout ID */
+    initialLayoutId?: string;
+}
+export interface UseDashboardResult {
+    /** Dashboard configuration */
+    config: DashboardConfig;
+    /** Active layout */
+    activeLayout: DashboardLayout | null;
+    /** All available layouts for user's tier */
+    availableLayouts: DashboardLayout[];
+    /** Widget states */
+    widgetStates: Record<string, Partial<WidgetState>>;
+    /** All registered widgets */
+    widgets: RegisteredWidget[];
+    /** Widgets available for user's tier */
+    availableWidgets: RegisteredWidget[];
+    /** Loading state */
+    loading: boolean;
+    /** Error message */
+    error: string | null;
+    /** Whether registry is initialized */
+    initialized: boolean;
+    /** Change active layout */
+    setActiveLayout: (layoutId: string) => void;
+    /** Update widget state */
+    updateWidgetState: (widgetId: string, state: Partial<WidgetState>) => void;
+    /** Refresh a widget */
+    refreshWidget: (widgetId: string) => Promise<void>;
+    /** Refresh all widgets */
+    refreshAll: () => Promise<void>;
+    /** Reset to default config */
+    resetConfig: () => void;
+}
+/**
+ * Hook for managing dashboard state
+ */
+export declare function useDashboard(options?: UseDashboardOptions): UseDashboardResult;
+export default useDashboard;
+//# sourceMappingURL=useDashboard.d.ts.map

package/dist/ui/hooks/useDashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDashboard.d.ts","sourceRoot":"","sources":["../../../src/ui/hooks/useDashboard.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAA4B,KAAK,eAAe,EAAE,KAAK,eAAe,EAAkB,KAAK,gBAAgB,EAAE,KAAK,WAAW,EAAiC,MAAM,qBAAqB,CAAC;AAEnM,MAAM,WAAW,mBAAmB;IAClC,kBAAkB;IAClB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,wBAAwB;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,oBAAoB;IACpB,YAAY,EAAE,eAAe,GAAG,IAAI,CAAC;IACrC,4CAA4C;IAC5C,gBAAgB,EAAE,eAAe,EAAE,CAAC;IACpC,oBAAoB;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACnD,6BAA6B;IAC7B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,wCAAwC;IACxC,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;IACrC,oBAAoB;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,oBAAoB;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,sCAAsC;IACtC,WAAW,EAAE,OAAO,CAAC;IACrB,2BAA2B;IAC3B,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,0BAA0B;IAC1B,iBAAiB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAC3E,uBAAuB;IACvB,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,0BAA0B;IAC1B,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,8BAA8B;IAC9B,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,kBAAkB,CA+IlF;AAED,eAAe,YAAY,CAAC"}

package/dist/ui/hooks/useDebounce.d.ts

@@ -0,0 +1,78 @@
+/**
+ * useDebounce Hook
+ *
+ * Debounces a callback function, delaying execution until after
+ * a specified time has passed since the last call. Each new call
+ * resets the timer.
+ */
+/**
+ * Options for the useDebounce hook
+ */
+export interface UseDebounceOptions {
+    /** Maximum time to wait before forcing execution (default: none) */
+    maxWait?: number;
+    /** Whether to call on leading edge instead of trailing (default: false) */
+    leading?: boolean;
+}
+/**
+ * Return type for useDebounce hook
+ */
+export interface UseDebounceResult<T extends (...args: unknown[]) => unknown> {
+    /** The debounced function */
+    debouncedFn: (...args: Parameters<T>) => void;
+    /** Whether there's a pending debounced call */
+    isPending: boolean;
+    /** Cancel any pending call */
+    cancel: () => void;
+    /** Immediately execute any pending call */
+    flush: () => void;
+}
+/**
+ * Debounces a callback function to delay execution
+ *
+ * @param callback - The function to debounce
+ * @param delay - Time to wait after last call before executing (ms)
+ * @param options - Debounce options
+ * @returns Object with debounced function and control methods
+ *
+ * @example
+ * const { debouncedFn, isPending } = useDebounce(search, 300);
+ *
+ * // Each call resets the timer
+ * debouncedFn('a');   // Starts 300ms timer
+ * debouncedFn('ab');  // Resets timer
+ * debouncedFn('abc'); // Resets timer
+ * // After 300ms of no calls, search('abc') is called
+ */
+export declare function useDebounce<T extends (...args: unknown[]) => unknown>(callback: T, delay: number, options?: UseDebounceOptions): UseDebounceResult<T>;
+/**
+ * Simple debounce hook that just returns the debounced function
+ *
+ * @param callback - The function to debounce
+ * @param delay - Time to wait after last call before executing (ms)
+ * @returns The debounced function
+ *
+ * @example
+ * const debouncedSearch = useDebounceFn(search, 300);
+ * debouncedSearch(query);
+ */
+export declare function useDebounceFn<T extends (...args: unknown[]) => unknown>(callback: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Debounce a value (re-renders when debounced value changes)
+ *
+ * @param value - The value to debounce
+ * @param delay - Debounce delay in milliseconds
+ * @returns The debounced value
+ *
+ * @example
+ * const [searchTerm, setSearchTerm] = useState('');
+ * const debouncedSearch = useDebouncedValue(searchTerm, 300);
+ *
+ * useEffect(() => {
+ *   // Only runs 300ms after user stops typing
+ *   performSearch(debouncedSearch);
+ * }, [debouncedSearch]);
+ */
+export declare function useDebouncedValue<T>(value: T, delay: number): T;
+export default useDebounce;
+//# sourceMappingURL=useDebounce.d.ts.map

package/dist/ui/hooks/useDebounce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebounce.d.ts","sourceRoot":"","sources":["../../../src/ui/hooks/useDebounce.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO;IAC1E,6BAA6B;IAC7B,WAAW,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC9C,+CAA+C;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAgIzJ;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAGrI;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,CAc/D;AAED,eAAe,WAAW,CAAC"}

package/dist/ui/hooks/useGroups.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Groups Hook
+ *
+ * React hook for plugin groups state management.
+ *
+ * @since v1.28.0
+ */
+import { type GroupStatus, type PluginGroup, type PluginStatusItem, type TagColor } from '../../core/tags/index.js';
+/**
+ * Hook return type
+ */
+interface UseGroupsResult {
+    /** All defined groups */
+    groups: PluginGroup[];
+    /** Number of groups */
+    groupCount: number;
+    /** Get a group by ID */
+    getGroup: (id: string) => PluginGroup | null;
+    /** Check if group exists */
+    hasGroup: (id: string) => boolean;
+    /** Create a new group */
+    createGroup: (name: string, color?: TagColor, description?: string, icon?: string) => PluginGroup;
+    /** Update a group */
+    updateGroup: (id: string, updates: Partial<Omit<PluginGroup, 'id' | 'createdAt' | 'plugins'>>) => void;
+    /** Delete a group */
+    deleteGroup: (id: string) => void;
+    /** Add plugin to group */
+    addToGroup: (groupId: string, pluginName: string) => void;
+    /** Remove plugin from group */
+    removeFromGroup: (groupId: string, pluginName: string) => void;
+    /** Move plugin between groups */
+    moveToGroup: (pluginName: string, fromGroupId: string, toGroupId: string) => void;
+    /** Check if plugin is in group */
+    isInGroup: (groupId: string, pluginName: string) => boolean;
+    /** Get groups for a plugin */
+    getPluginGroups: (pluginName: string) => PluginGroup[];
+    /** Get group IDs for a plugin */
+    getPluginGroupIds: (pluginName: string) => string[];
+    /** Get plugins in a group */
+    getGroupPlugins: (groupId: string) => string[];
+    /** Get ungrouped plugins */
+    getUngroupedPlugins: (allPlugins: string[]) => string[];
+    /** Toggle group expanded state */
+    toggleExpanded: (groupId: string) => boolean;
+    /** Set group expanded state */
+    setExpanded: (groupId: string, expanded: boolean) => void;
+    /** Expand all groups */
+    expandAll: () => void;
+    /** Collapse all groups */
+    collapseAll: () => void;
+    /** Get group status */
+    getGroupStatus: (groupId: string, plugins: PluginStatusItem[]) => GroupStatus;
+    /** Reorder group in list */
+    reorderGroup: (groupId: string, newIndex: number) => void;
+    /** Set plugins in group */
+    setGroupPlugins: (groupId: string, pluginNames: string[]) => void;
+    /** Clear group plugins */
+    clearGroup: (groupId: string) => void;
+    /** Serialize for persistence */
+    serialize: () => string;
+}
+/**
+ * Hook options
+ */
+interface UseGroupsOptions {
+    /** Initial serialized data to load */
+    initialData?: string;
+}
+/**
+ * React hook for managing plugin groups
+ */
+export declare function useGroups(options?: UseGroupsOptions): UseGroupsResult;
+export {};
+//# sourceMappingURL=useGroups.d.ts.map

package/dist/ui/hooks/useGroups.d.ts.map

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

package/dist/ui/hooks/useHealth.d.ts

@@ -0,0 +1,62 @@
+/**
+ * useHealth Hook
+ *
+ * Hook for managing plugin health state and calculations.
+ *
+ * @since v1.72.0
+ */
+import { type HealthCheckConfig, type PluginHealthScore, type ServerHealthSummary } from '../../core/health/index.js';
+import type { Plugin } from '../../core/types/index.js';
+/**
+ * Health state
+ */
+export interface HealthState {
+    /** Server-wide health summary */
+    summary: ServerHealthSummary | null;
+    /** Individual plugin scores */
+    pluginScores: PluginHealthScore[];
+    /** Whether health is loading */
+    loading: boolean;
+    /** Error message */
+    error: string | null;
+    /** Last check timestamp */
+    lastCheck: number | null;
+}
+/**
+ * Health hook return type
+ */
+export interface UseHealthReturn extends HealthState {
+    /** Refresh health scores */
+    refresh: () => Promise<void>;
+    /** Get score for a specific plugin */
+    getPluginScore: (pluginName: string) => PluginHealthScore | undefined;
+    /** Get plugins with issues */
+    getPluginsWithIssues: () => PluginHealthScore[];
+    /** Get critical plugins */
+    getCriticalPlugins: () => PluginHealthScore[];
+}
+/**
+ * Health hook options
+ */
+export interface UseHealthOptions {
+    /** Plugins to check health for */
+    plugins: Plugin[];
+    /** Server's Minecraft version */
+    minecraftVersion?: string;
+    /** Health check configuration */
+    config?: Partial<HealthCheckConfig>;
+    /** Auto-refresh on plugin changes */
+    autoRefresh?: boolean;
+    /** Update check results — provides latestVersion for accurate scoring */
+    updateResults?: Array<{
+        pluginName: string;
+        latestVersion?: string;
+        hasUpdate?: boolean;
+    }>;
+}
+/**
+ * useHealth hook
+ */
+export declare function useHealth(options: UseHealthOptions): UseHealthReturn;
+export default useHealth;
+//# sourceMappingURL=useHealth.d.ts.map

package/dist/ui/hooks/useHealth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHealth.d.ts","sourceRoot":"","sources":["../../../src/ui/hooks/useHealth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAGL,KAAK,iBAAiB,EAKtB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EAEzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,+BAA+B;IAC/B,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,oBAAoB;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,4BAA4B;IAC5B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,sCAAsC;IACtC,cAAc,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,iBAAiB,GAAG,SAAS,CAAC;IACtE,8BAA8B;IAC9B,oBAAoB,EAAE,MAAM,iBAAiB,EAAE,CAAC;IAChD,2BAA2B;IAC3B,kBAAkB,EAAE,MAAM,iBAAiB,EAAE,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iCAAiC;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iCAAiC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACpC,qCAAqC;IACrC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,yEAAyE;IACzE,aAAa,CAAC,EAAE,KAAK,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC,CAAC;CACJ;AA4JD;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CA6GpE;AAED,eAAe,SAAS,CAAC"}

package/dist/ui/hooks/useInputGuard.d.ts

@@ -0,0 +1,89 @@
+/**
+ * useInputGuard Hook
+ *
+ * Validates keyboard input against the current UI state.
+ * Provides centralized input validation with debug logging support.
+ */
+import { type Key, type StateContext, type UIState } from '../state/index.js';
+/**
+ * Options for the useInputGuard hook
+ */
+export interface UseInputGuardOptions {
+    /** Current UI state context */
+    context: StateContext;
+    /** Callback when input is rejected */
+    onInvalidInput?: (keyId: string, state: UIState, reason: string) => void;
+    /** Callback when input is throttled */
+    onThrottled?: (keyId: string, action: string) => void;
+}
+/**
+ * Return type for useInputGuard hook
+ */
+export interface UseInputGuardResult {
+    /**
+     * Validate an input against the current state.
+     * Returns true if the input should be processed.
+     */
+    validateInput: (input: string, key: Key) => boolean;
+    /**
+     * Check if a specific key ID is valid for the current state.
+     * Useful for checking before dispatching an action.
+     */
+    isKeyValid: (keyId: string) => boolean;
+    /**
+     * Get the normalized key identifier for an input.
+     */
+    getKeyId: (input: string, key: Key) => string;
+    /**
+     * Current UI state (convenience accessor)
+     */
+    currentState: UIState;
+}
+/**
+ * Hook that provides input validation against the current UI state
+ *
+ * @param options - Configuration options
+ * @returns Validation functions and state info
+ *
+ * @example
+ * const { validateInput, currentState } = useInputGuard({ context });
+ *
+ * useInput((input, key) => {
+ *   // Skip invalid inputs
+ *   if (!validateInput(input, key)) return;
+ *
+ *   // Process valid input
+ *   if (input === 'r') {
+ *     refresh();
+ *   }
+ * });
+ */
+export declare function useInputGuard(options: UseInputGuardOptions): UseInputGuardResult;
+/**
+ * Simple validation function (non-hook) for use outside React components
+ *
+ * @param input - Input character
+ * @param key - Key object from useInput
+ * @param state - Current UI state
+ * @returns Whether the input is valid
+ */
+export declare function validateInputForState(input: string, key: Key, state: UIState): boolean;
+/**
+ * Check if input should trigger special handling in a state
+ *
+ * Some states have special behavior:
+ * - 'help' and 'config': any key closes them
+ * - 'command-palette': any printable char is valid for typing
+ * - 'login-dialog': text input for form fields
+ */
+export declare function hasSpecialInputHandling(state: UIState): boolean;
+/**
+ * Get the appropriate action for an escape key press
+ *
+ * @param state - Current UI state
+ * @param canCancel - Whether the current operation can be cancelled
+ * @returns The action to take, or null if escape should be ignored
+ */
+export declare function getEscapeAction(state: UIState, canCancel?: boolean): 'close' | 'cancel' | 'ignore' | null;
+export default useInputGuard;
+//# sourceMappingURL=useInputGuard.d.ts.map

package/dist/ui/hooks/useInputGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useInputGuard.d.ts","sourceRoot":"","sources":["../../../src/ui/hooks/useInputGuard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,YAAY,EAAE,KAAK,OAAO,EAA0E,MAAM,mBAAmB,CAAC;AAEtJ;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,OAAO,EAAE,YAAY,CAAC;IACtB,sCAAsC;IACtC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzE,uCAAuC;IACvC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACvD;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;IAEpD;;;OAGG;IACH,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IAEvC;;OAEG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC;IAE9C;;OAEG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,mBAAmB,CAgEhF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAGtF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAwBzG;AAED,eAAe,aAAa,CAAC"}

package/dist/ui/hooks/useKeyboardFeatures.d.ts

@@ -0,0 +1,83 @@
+/**
+ * useKeyboardFeatures Hook
+ *
+ * Unified hook that integrates premium keyboard features:
+ * - Macro recording and playback
+ * - Jump list navigation (Ctrl+O/Ctrl+I)
+ * - Accessibility features (sticky keys, slow keys)
+ *
+ * @since v1.58.6
+ */
+import type { Tier } from '../../core/types/auth.js';
+import { type AccessibilityConfig, type ProcessedKeyResult } from '../keyboard/index.js';
+export interface KeyboardFeaturesConfig {
+    /** User's subscription tier */
+    tier: Tier;
+    /** Enable accessibility features */
+    accessibilityEnabled?: boolean;
+    /** Accessibility configuration */
+    accessibilityConfig?: Partial<AccessibilityConfig>;
+    /** Enable macro recording */
+    macrosEnabled?: boolean;
+    /** Enable jump list navigation */
+    jumpListEnabled?: boolean;
+}
+export interface KeyboardFeaturesState {
+    /** Currently recording macro register (null if not recording) */
+    recordingRegister: string | null;
+    /** Currently playing macro register (null if not playing) */
+    playingRegister: string | null;
+    /** Whether accessibility is enabled */
+    accessibilityEnabled: boolean;
+    /** Active sticky modifiers */
+    stickyModifiers: string[];
+    /** Jump list can go back */
+    canJumpBack: boolean;
+    /** Jump list can go forward */
+    canJumpForward: boolean;
+}
+export interface UseKeyboardFeaturesReturn {
+    /** Current state */
+    state: KeyboardFeaturesState;
+    /** Start recording a macro to a register (q, w, e, r) */
+    startRecording: (register: string) => boolean;
+    /** Stop recording the current macro */
+    stopRecording: () => void;
+    /** Play a macro from a register */
+    playRegister: (register: string) => Promise<boolean>;
+    /** Record a keypress during macro recording */
+    recordKeypress: (key: string, modifiers?: ('ctrl' | 'alt' | 'shift' | 'meta')[]) => void;
+    /** Record an action during macro recording */
+    recordAction: (action: string, params?: Record<string, unknown>) => void;
+    /** Check if currently recording */
+    isRecording: () => boolean;
+    /** Record a navigation for jump list */
+    recordNavigation: (view: string, index: number, label: string, itemId?: string) => void;
+    /** Jump back in navigation history (Ctrl+O) */
+    jumpBack: () => {
+        view: string;
+        index: number;
+        label: string;
+        itemId?: string;
+    } | null;
+    /** Jump forward in navigation history (Ctrl+I) */
+    jumpForward: () => {
+        view: string;
+        index: number;
+        label: string;
+        itemId?: string;
+    } | null;
+    /** Toggle accessibility on/off */
+    toggleAccessibility: () => void;
+    /** Update accessibility config */
+    updateAccessibilityConfig: (config: Partial<AccessibilityConfig>) => void;
+    /** Get current accessibility config */
+    getAccessibilityConfig: () => AccessibilityConfig;
+    /** Process a key through accessibility filters */
+    processKey: (key: string, type: 'keydown' | 'keyup', modifiers: string[]) => ProcessedKeyResult;
+    /** Announce for screen readers */
+    announce: (message: string) => void;
+}
+export declare function useKeyboardFeatures(config: KeyboardFeaturesConfig): UseKeyboardFeaturesReturn;
+export default useKeyboardFeatures;
+//# sourceMappingURL=useKeyboardFeatures.d.ts.map

package/dist/ui/hooks/useKeyboardFeatures.d.ts.map

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

package/dist/ui/hooks/useKeyboardNav.d.ts

@@ -0,0 +1,45 @@
+/**
+ * useKeyboardNav Hook
+ *
+ * Provides keyboard navigation for lists and tabs
+ */
+export interface UseKeyboardNavOptions {
+    itemCount: number;
+    initialIndex?: number;
+    wrap?: boolean;
+    onSelect?: (index: number) => void;
+    onBack?: () => void;
+    enabled?: boolean;
+}
+export interface KeyboardNavState {
+    selectedIndex: number;
+    setSelectedIndex: (index: number) => void;
+    moveUp: () => void;
+    moveDown: () => void;
+    moveToTop: () => void;
+    moveToBottom: () => void;
+    select: () => void;
+}
+/**
+ * Hook for keyboard navigation in lists
+ */
+export declare function useKeyboardNav({ itemCount, initialIndex, wrap, onSelect, onBack, enabled }: UseKeyboardNavOptions): KeyboardNavState;
+/**
+ * Hook for tab navigation
+ */
+export interface UseTabNavOptions {
+    tabCount: number;
+    initialTab?: number;
+    onTabChange?: (index: number) => void;
+    /** Optional validator — return false to block a tab switch (v2.2.6) */
+    onTabValidate?: (index: number) => boolean;
+    enabled?: boolean;
+}
+export interface TabNavState {
+    activeTab: number;
+    setActiveTab: (index: number) => void;
+    nextTab: () => void;
+    prevTab: () => void;
+}
+export declare function useTabNav({ tabCount, initialTab, onTabChange, onTabValidate, enabled }: UseTabNavOptions): TabNavState;
+//# sourceMappingURL=useKeyboardNav.d.ts.map

package/dist/ui/hooks/useKeyboardNav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useKeyboardNav.d.ts","sourceRoot":"","sources":["../../../src/ui/hooks/useKeyboardNav.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,SAAS,EAAE,YAAgB,EAAE,IAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAc,EAAE,EAAE,qBAAqB,GAAG,gBAAgB,CA0EtJ;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,uEAAuE;IACvE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,UAAc,EAAE,WAAW,EAAE,aAAa,EAAE,OAAc,EAAE,EAAE,gBAAgB,GAAG,WAAW,CAmEjI"}

package/dist/ui/hooks/useNetworkStatus.d.ts

@@ -0,0 +1,20 @@
+/**
+ * useNetworkStatus Hook
+ *
+ * Provides network connectivity status for UI components.
+ * Periodically checks connectivity and updates state.
+ */
+export interface NetworkStatusState {
+    online: boolean | null;
+    checking: boolean;
+}
+export interface UseNetworkStatusReturn extends NetworkStatusState {
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for tracking network connectivity status
+ *
+ * @returns Network status state and refresh function
+ */
+export declare function useNetworkStatus(): UseNetworkStatusReturn;
+//# sourceMappingURL=useNetworkStatus.d.ts.map

package/dist/ui/hooks/useNetworkStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNetworkStatus.d.ts","sourceRoot":"","sources":["../../../src/ui/hooks/useNetworkStatus.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,sBAAsB,CA6BzD"}

package/dist/ui/hooks/useNotifications.d.ts

@@ -0,0 +1,49 @@
+/**
+ * useNotifications Hook
+ *
+ * Manages toast notifications with auto-dismiss
+ */
+import type { NotificationType } from '../components/Notification.js';
+export interface AppNotification {
+    id: string;
+    type: NotificationType;
+    message: string;
+    title?: string;
+    duration?: number;
+    createdAt: number;
+}
+export interface UseNotificationsOptions {
+    defaultDuration?: number;
+    maxNotifications?: number;
+}
+/**
+ * Options for adding notifications
+ */
+export interface NotificationOptions {
+    title?: string;
+    duration?: number;
+    /** Prevent duplicate messages of the same type (v1.50.4) */
+    dedupe?: boolean;
+}
+/**
+ * Shorthand options for convenience methods
+ */
+export interface ShorthandNotificationOptions {
+    title?: string;
+    dedupe?: boolean;
+}
+export interface NotificationsState {
+    notifications: AppNotification[];
+    addNotification: (type: NotificationType, message: string, options?: NotificationOptions) => string;
+    removeNotification: (id: string) => void;
+    clearNotifications: () => void;
+    success: (message: string, options?: ShorthandNotificationOptions) => string;
+    error: (message: string, options?: ShorthandNotificationOptions) => string;
+    warning: (message: string, options?: ShorthandNotificationOptions) => string;
+    info: (message: string, options?: ShorthandNotificationOptions) => string;
+}
+/**
+ * Hook for managing notifications
+ */
+export declare function useNotifications({ defaultDuration, maxNotifications }?: UseNotificationsOptions): NotificationsState;
+//# sourceMappingURL=useNotifications.d.ts.map

package/dist/ui/hooks/useNotifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNotifications.d.ts","sourceRoot":"","sources":["../../../src/ui/hooks/useNotifications.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,eAAe,EAAE,CAAC;IACjC,eAAe,EAAE,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,MAAM,CAAC;IACpG,kBAAkB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,4BAA4B,KAAK,MAAM,CAAC;IAC7E,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,4BAA4B,KAAK,MAAM,CAAC;IAC3E,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,4BAA4B,KAAK,MAAM,CAAC;IAC7E,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,4BAA4B,KAAK,MAAM,CAAC;CAC3E;AAID;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,eAAsB,EAAE,gBAAoB,EAAE,GAAE,uBAA4B,GAAG,kBAAkB,CAuGnI"}