@panyam/tsappkit 0.0.3

package/dist/index.d.mts

@@ -0,0 +1,866 @@
+/**
+ * Simple event system for component communication
+ * Provides error isolation and idempotent subscriptions
+ */
+/**
+ * Simple event handler function type
+ */
+type EventHandler = (data?: any) => void;
+/**
+ * Interface for components that want to receive events via the EventBus
+ */
+interface EventSubscriber {
+    /**
+     * Handle incoming events from the EventBus
+     * @param eventType - The type of event being handled
+     * @param data - The event data payload
+     * @param subject - The subject/subject entity (what the event is about)
+     * @param emitter - The entity that emitted the event
+     */
+    handleBusEvent(eventType: string, data: any, subject: any, emitter: any): void;
+}
+/**
+ * Synchronous event bus for component communication
+ * Features:
+ * - Type-safe event names and payloads
+ * - Error isolation (one handler failure doesn't stop others)
+ * - Source exclusion (events not sent back to source)
+ * - Debug logging for troubleshooting
+ */
+declare class EventBus {
+    private subscribers;
+    private functionSubscribers;
+    private onceHandlers;
+    private debugMode;
+    constructor(debugMode?: boolean);
+    /**
+     * Subscribe to an event with a simple handler function
+     */
+    on(eventType: string, handler: EventHandler): void;
+    /**
+     * Unsubscribe a handler function from an event
+     */
+    off(eventType: string, handler: EventHandler): void;
+    /**
+     * Subscribe to an event for one-time execution
+     */
+    once(eventType: string, handler: EventHandler): void;
+    /**
+     * Add a subscription using the EventSubscriber pattern
+     * Provides automatic idempotency - same subscriber object won't be added twice
+     */
+    addSubscription(eventType: string, subject: any, subscriber: EventSubscriber): void;
+    /**
+     * Remove a subscription using the EventSubscriber pattern
+     */
+    removeSubscription(eventType: string, subject: any, subscriber: EventSubscriber): void;
+    /**
+     * Emit an event to all subscribers
+     * @param eventType - The event type to emit
+     * @param data - The event data payload
+     * @param subject - The subject/subject entity that this event relates to (optional for simple API)
+     * @param emitter - The entity that emitted the event (optional for simple API)
+     */
+    emit<T = any>(eventType: string, data?: T, subject?: any, emitter?: any): void;
+    /**
+     * Get all event types that have subscribers
+     */
+    getEventTypes(): string[];
+    /**
+     * Get subscriber count for an event type
+     */
+    getSubscriberCount(eventType: string): number;
+    /**
+     * Clear all subscriptions (useful for cleanup)
+     */
+    clear(): void;
+    /**
+     * Enable or disable debug logging
+     */
+    setDebugMode(enabled: boolean): void;
+}
+declare const ComponentEventTypes: {
+    readonly COMPONENT_INITIALIZED: "component-initialized";
+    readonly COMPONENT_HYDRATED: "component-hydrated";
+    readonly COMPONENT_ERROR: "component-error";
+};
+declare const LifecycleEventTypes: {
+    readonly LOCAL_INIT_STARTED: "lifecycle-local-init-started";
+    readonly LOCAL_INIT_FINISHED: "lifecycle-local-init-finished";
+    readonly DEPENDENCIES_INJECTED: "lifecycle-dependencies-injected";
+    readonly ACTIVATION_STARTED: "lifecycle-activation-started";
+    readonly ACTIVATION_FINISHED: "lifecycle-activation-finished";
+    readonly DEACTIVATION_STARTED: "lifecycle-deactivation-started";
+    readonly DEACTIVATION_FINISHED: "lifecycle-deactivation-finished";
+};
+type LifecycleEventType = typeof LifecycleEventTypes[keyof typeof LifecycleEventTypes];
+type ComponentEventType = typeof ComponentEventTypes[keyof typeof ComponentEventTypes];
+
+/**
+ * LCMComponent Interface - Defines multi-phase component initialization
+ *
+ * This interface implements a breadth-first lifecycle pattern that eliminates
+ * initialization order dependencies and race conditions through synchronization barriers.
+ *
+ * Lifecycle Phases:
+ * 1. Construction - Components are created but not initialized
+ * 2. bindToDOM() - Basic DOM setup, discover child components
+ * 3. injectDependencies() - Receive references to other components
+ * 4. activate() - Final setup when all dependencies are ready
+ *
+ * Key Benefits:
+ * - Order Independence: Components can be created in any sequence
+ * - Async Safety: Each phase waits for all components before proceeding
+ * - Clear Dependencies: Explicit injection points prevent race conditions
+ * - Error Isolation: Component failures don't cascade to others
+ */
+/**
+ * LCM Component - Short for LifeCycle Managed Component
+ * enable components to be declared first and their loading be managed by a
+ * LifecycleController so that we have layered creation, dependency injection and setup
+ * in a breadth first way.
+ *
+ * A key constraint on LCMComponents are that they should not perform any initialization
+ * in the constructor.  This is because a LifecycleController should be used to load/setup
+ * these components and they will follow a layered approach.  Performing these actions in
+ * the constructor could violate the idempotency guarantees.
+ */
+interface LCMComponent {
+    /**
+     * Phase 1: The "local" initialization of the component.
+     *
+     * In this phase the component initializes itself and returns any children it might
+     * want initialized as part of the lifecycled loading.
+     *
+     * This phase should:
+     * - Set up basic DOM elements and event listeners
+     * - Create child components (but don't initialize them) and return them
+     * - Return array of child components for lifecycle controller discovery
+     *
+     * This phase must be synchronous and should not:
+     * - Access other components or external dependencies
+     * - Perform async operations
+     * - Emit events or notifications
+     *
+     * @returns Array of child components to be managed by lifecycle controller
+     */
+    performLocalInit(): Promise<LCMComponent[]> | LCMComponent[];
+    /**
+     * Phase 2: Inject dependencies from parent/siblings
+     *
+     * This phase should:
+     * - Receive and store references to required dependencies
+     * - Validate that required dependencies are provided
+     * - Set up internal state based on dependencies
+     *
+     * This phase can be async and may:
+     * - Load external data or resources
+     * - Perform validation or setup operations
+     * - Initialize internal components that depend on injected references
+     *
+     * @param deps Record of dependency name to dependency instance
+     * @returns Promise<void> or void - can be async
+     */
+    setupDependencies(): Promise<void> | void;
+    /**
+     * Phase 3: Activate component when all dependencies are ready
+     *
+     * This phase should:
+     * - Complete final initialization
+     * - Enable component functionality
+     * - Start listening for external events
+     * - Begin normal operation
+     *
+     * This phase can be async and may:
+     * - Connect to external services
+     * - Load initial data
+     * - Emit ready notifications
+     *
+     * @returns Promise<void> or void - can be async
+     */
+    activate(): Promise<void> | void;
+    /**
+     * Cleanup phase: Deactivate component and clean up resources
+     *
+     * This should:
+     * - Stop all ongoing operations
+     * - Remove event listeners
+     * - Clean up external connections
+     * - Dispose of child components
+     *
+     * @returns Promise<void> or void - can be async
+     */
+    deactivate(): Promise<void> | void;
+}
+/**
+ * Configuration for component lifecycle behavior
+ */
+interface LCMComponentConfig {
+    /**
+     * Maximum time to wait for a lifecycle phase to complete (ms)
+     * Default: 10000 (10 seconds)
+     */
+    phaseTimeoutMs?: number;
+    /**
+     * Whether to continue if individual components fail during a phase
+     * Default: false (fail fast)
+     */
+    continueOnError?: boolean;
+    /**
+     * Whether to validate dependencies against declared requirements
+     * Default: true
+     */
+    validateDependencies?: boolean;
+    /**
+     * Enable debug logging for lifecycle phases
+     * Default: false
+     */
+    enableDebugLogging?: boolean;
+}
+/**
+ * Event emitted during component lifecycle transitions
+ */
+interface LCMComponentEvent {
+    type: 'phase-start' | 'phase-complete' | 'phase-error' | 'component-ready';
+    componentName: string;
+    timestamp: number;
+    error?: Error;
+    metadata?: Record<string, any>;
+}
+
+/**
+ * Base interface for all UI components
+ * Enforces separation of concerns and standard lifecycle
+ */
+interface Component {
+    /**
+     * Unique identifier for this component instance
+     */
+    readonly componentId: string;
+    /**
+     * Root DOM element that this component owns and manages
+     */
+    readonly rootElement: HTMLElement;
+    /**
+     * Handle dynamic content updates (e.g., from HTMX or server responses)
+     * @param newHTML - New HTML content to replace current content
+     */
+    contentUpdated(newHTML: string): void;
+}
+/**
+ * Abstract base class implementing common component functionality
+ * Provides standard lifecycle management and event bus integration
+ *
+ * All components auto-initialize in constructor AND implement LCMComponent
+ * for coordination with other components when needed.
+ */
+declare abstract class BaseComponent implements Component, LCMComponent, EventSubscriber {
+    readonly componentId: string;
+    readonly rootElement: HTMLElement;
+    readonly debugMode: boolean;
+    protected _eventBus: EventBus;
+    constructor(componentId: string, rootElement: HTMLElement, eventBus?: EventBus | null, debugMode?: boolean);
+    get eventBus(): EventBus;
+    contentUpdated(newHTML: string): void;
+    /**
+     * Subscribe to an event using the new EventSubscriber pattern
+     */
+    protected addSubscription(eventType: string, target?: any): void;
+    /**
+     * Unsubscribe from an event using the new EventSubscriber pattern
+     */
+    protected removeSubscription(eventType: string, target?: any): void;
+    /**
+     * Emit an event from this component
+     */
+    protected emit<T = any>(eventType: string, data: T, target: any, emitter?: any): void;
+    /**
+     * Default implementation of EventSubscriber interface
+     * Components can override this to handle events
+     */
+    handleBusEvent(eventType: string, data: any, target: any, emitter: any): void;
+    /**
+     * Find elements within this component's root element only
+     * Enforces separation of concerns - no cross-component DOM access
+     */
+    protected findElement<T extends HTMLElement = HTMLElement>(selector: string): T | null;
+    /**
+     * Find multiple elements within this component's root element only
+     */
+    protected findElements<T extends HTMLElement = HTMLElement>(selector: string): T[];
+    /**
+     * Log messages with component identification
+     */
+    protected log(message: string, data?: any): void;
+    /**
+     * Default lifecycle method: discover and return child components
+     * Override this if your component creates child components that need lifecycle management
+     */
+    performLocalInit(): Promise<LCMComponent[]> | LCMComponent[];
+    /**
+     * Default lifecycle method: inject dependencies
+     * Override this if your component needs dependencies from other components
+     */
+    setupDependencies(): void | Promise<void>;
+    /**
+     * Default lifecycle method: activate component for coordination
+     * Override this if your component needs to coordinate with other components after initialization
+     */
+    activate(): void | Promise<void>;
+    /**
+     * Default lifecycle method: deactivate component
+     * Override this if your component needs cleanup during lifecycle management
+     */
+    deactivate(): void | Promise<void>;
+    set innerHTML(innerHTML: string);
+    shouldUpdateHtml(html: string): [string, boolean];
+    htmlUpdated(html: string): void;
+}
+
+/**
+ * LifecycleController - Orchestrates breadth-first component initialization
+ *
+ * This controller implements a breadth-first traversal of the component tree
+ * followed by phase-wise initialization with synchronization barriers.
+ *
+ * Process:
+ * 1. Discovery Phase: Traverse component tree to find all components
+ * 2. DOM Binding Phase: All components bind to DOM simultaneously
+ * 3. Dependency Injection Phase: All components receive dependencies
+ * 4. Activation Phase: All components complete initialization
+ *
+ * Each phase acts as a synchronization barrier - no component can proceed
+ * to the next phase until ALL components have completed the current phase.
+ */
+declare class LifecycleController {
+    protected eventBus: EventBus;
+    private allComponents;
+    private componentsByLevel;
+    private config;
+    static DefaultConfig: LCMComponentConfig;
+    constructor(eventBus: EventBus, config?: LCMComponentConfig);
+    /**
+     * Initialize component tree starting from root component
+     *
+     * @param rootComponent The root component to start initialization from
+     * @param rootName Optional name for the root component (for debugging)
+     * @returns Promise that resolves when all components are fully initialized
+     */
+    initializeFromRoot(rootComponent: LCMComponent): Promise<void>;
+    /**
+     * Phase 0: Discover all components via breadth-first traversal
+     */
+    private performLocalInit;
+    /**
+     * Phase 1: Dependency injection.
+     * Here all our components are already discovered so we can call directly
+     */
+    protected injectDependencies(): void;
+    /**
+     * Phase 2: Activate all components
+     *
+     * Here all our components are already discovered and their dependencies setup
+     * so we can call directly
+     */
+    protected activate(): Promise<void>;
+    /**
+     * Deactivate all components in reverse order.  This is usually called when a page quits or a component is
+     * deactivated
+     */
+    deactivateAll(): Promise<void>;
+    /**
+     * Emit lifecycle event to registered callbacks
+     */
+    private emitEvent;
+    /**
+     * Log message if debug logging is enabled
+     */
+    private log;
+    /**
+     * Log error message
+     */
+    private logError;
+}
+
+interface ComponentLifecycleEvent {
+    success: boolean;
+    error: Error | null;
+}
+
+/**
+ * Theme management for applications
+ */
+declare class ThemeManager {
+    static LIGHT: string;
+    static DARK: string;
+    static SYSTEM: string;
+    static readonly LIGHT_ICON_SVG = "<svg xmlns=\"http://www.w3.org/2000/svg\" fill=\"none\" viewBox=\"0 0 24 24\" stroke-width=\"1.5\" stroke=\"currentColor\" class=\"w-full h-6\"><path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M12 3v2.25m6.364.386l-1.591 1.591M21 12h-2.25m-.386 6.364l-1.591-1.591M12 18.75V21m-4.773-4.227l-1.591 1.591M5.25 12H3m4.227-4.773L5.636 5.636M15.75 12a3.75 3.75 0 11-7.5 0 3.75 3.75 0 017.5 0z\" /></svg>";
+    static readonly DARK_ICON_SVG = "<svg xmlns=\"http://www.w3.org/2000/svg\" fill=\"none\" viewBox=\"0 0 24 24\" stroke-width=\"1.5\" stroke=\"currentColor\" class=\"w-full h-6\"><path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M21.752 15.002A9.718 9.718 0 0118 15.75c-5.385 0-9.75-4.365-9.75-9.75 0-1.33.266-2.597.748-3.752A9.753 9.753 0 003 11.25C3 16.635 7.365 21 12.75 21a9.753 9.753 0 009.002-5.998z\" /></svg>";
+    static readonly SYSTEM_ICON_SVG = "<svg xmlns=\"http://www.w3.org/2000/svg\" fill=\"none\" viewBox=\"0 0 24 24\" stroke-width=\"1.5\" stroke=\"currentColor\" class=\"w-full h-6\"><path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M9 17.25v1.007a3 3 0 01-.879 2.122L7.5 21h9l-.621-.621A3 3 0 0115 18.257V17.25m6-12V15a2.25 2.25 0 01-2.25 2.25H5.25A2.25 2.25 0 013 15V5.25m18 0A2.25 2.25 0 0018.75 3H5.25A2.25 2.25 0 003 5.25m18 0V12a2.25 2.25 0 01-2.25 2.25H5.25A2.25 2.25 0 013 12V5.25\" /></svg>";
+    /**
+     * Initialize theme based on saved preference or system default
+     */
+    static initialize(): void;
+    /**
+     * Set theme and save preference
+     */
+    static setTheme(theme: string): void;
+    /**
+     * Get current theme setting (light, dark, or system)
+     */
+    static getCurrentThemeSetting(): string;
+    /**
+     * Gets the *next* theme in the cycle: Light -> Dark -> System -> Light ...
+     */
+    static getNextTheme(currentSetting: string): string;
+    /**
+     * Gets the appropriate SVG icon string for a given theme setting.
+     */
+    static getIconSVG(themeSetting: string): string;
+    /**
+     * Gets a user-friendly label for the theme setting.
+     */
+    static getThemeLabel(themeSetting: string): string;
+    /**
+     * Initialize the ThemeManager (no instance needed for static methods)
+     */
+    static init(): void;
+}
+
+/**
+ * Modal manager for the application
+ * Handles showing and hiding modals with different content
+ */
+declare class Modal {
+    private static instance;
+    private modalContainer;
+    private modalBackdrop;
+    private modalPanel;
+    private modalContent;
+    private closeButton;
+    private templateLoader;
+    private currentTemplateId;
+    private currentData;
+    private onSubmitCallback;
+    private onApplyCallback;
+    /**
+     * Private constructor for singleton pattern
+     */
+    private constructor();
+    /**
+     * Get the Modal instance (singleton)
+     */
+    static getInstance(): Modal;
+    /**
+     * Bind event listeners for modal interactions
+     */
+    private bindEvents;
+    /**
+     * Check if the modal is currently visible
+     */
+    isVisible(): boolean;
+    /**
+     * Show a modal with content from the specified template ID.
+     * Uses TemplateLoader to get the content element.
+     * @param templateId ID used in `data-template-id` attribute in TemplateRegistry.html
+     * @param data Optional data to pass to the modal. Can include callbacks like `onSubmit`.
+     * @returns The root HTMLElement of the loaded content, or null if failed.
+     */
+    show(templateId: string, data?: any): HTMLElement | null;
+    /**
+     * Hide the modal
+     */
+    hide(): Promise<void>;
+    /**
+     * Get the current modal content element
+     */
+    getContentElement(): HTMLElement | null;
+    /**
+     * Get the current template ID
+     */
+    getCurrentTemplate(): string | null;
+    /**
+     * Get the current modal data
+     */
+    getCurrentData(): any;
+    /**
+     * Update modal data (excluding callbacks for now)
+     */
+    updateData(newData: any): void;
+    /**
+     * Initialize the modal component
+     */
+    static init(): Modal;
+}
+
+/**
+ * Toast types for styling
+ */
+type ToastType = 'success' | 'error' | 'info' | 'warning';
+/**
+ * Manages toast notifications
+ */
+declare class ToastManager {
+    private static instance;
+    private container;
+    private template;
+    private toasts;
+    private counter;
+    /**
+     * Private constructor for singleton pattern
+     */
+    private constructor();
+    /**
+     * Get the ToastManager instance (singleton)
+     */
+    static getInstance(): ToastManager;
+    /**
+     * Show a toast notification
+     * @param title Toast title
+     * @param message Toast message
+     * @param type Toast type for styling
+     * @param duration Duration in ms (default: 4000)
+     */
+    showToast(title: string, message: string, type?: ToastType, duration?: number): string;
+    /**
+     * Hide a toast notification
+     * @param id Toast ID
+     */
+    hideToast(id: string): void;
+    /**
+     * Hide all toast notifications
+     */
+    hideAllToasts(): void;
+    /**
+     * Initialize the component
+     */
+    static init(): ToastManager;
+}
+
+/**
+ * Base class for all pages that provides common UI components and functionality
+ * Implements proper LCMComponent lifecycle management for pages
+ */
+declare abstract class BasePage extends BaseComponent {
+    readonly componentId: string;
+    readonly debugMode: boolean;
+    protected themeManager: typeof ThemeManager;
+    protected modal: Modal;
+    protected toastManager: ToastManager;
+    protected themeToggleButton: HTMLButtonElement;
+    protected themeToggleIcon: HTMLElement;
+    constructor(componentId: string, eventBus?: EventBus | null, debugMode?: boolean);
+    performLocalInit(): Promise<LCMComponent[]> | LCMComponent[];
+    activate(): void;
+    /**
+     * Initialize common UI components that all pages need
+     */
+    protected initializeBaseComponents(): void;
+    /**
+     * Bind common event handlers that all pages need
+     */
+    protected bindBaseEvents(): void;
+    /**
+     * Handle theme toggle button clicks
+     */
+    protected handleThemeToggleClick(): void;
+    /**
+     * Update the theme toggle button state and appearance
+     */
+    protected updateThemeButtonState(currentTheme?: string): void;
+    /**
+     * Show a toast notification
+     */
+    protected showToast(title: string, message: string, type?: 'success' | 'error' | 'info' | 'warning', duration?: number): void;
+    /**
+     * Show a modal dialog
+     */
+    protected showModal(templateId: string, data?: any): void;
+    /**
+     * Hide the modal dialog
+     */
+    protected hideModal(): void;
+    /**
+     * Get the current theme setting
+     */
+    protected getCurrentTheme(): string;
+    /**
+     * Check if the current theme is dark mode
+     */
+    protected isDarkMode(): boolean;
+    /**
+     * Initialize responsive header actions drawer
+     * On desktop: drawer is always visible, positioned inline with header
+     * On mobile: drawer slides down from top when menu button is clicked
+     */
+    protected initializeHeaderActionsDropdown(): void;
+    /**
+     * Abstract method that subclasses must implement to initialize their specific components
+     * Should return any child components that need lifecycle management
+     */
+    protected initializeSpecificComponents(): LCMComponent[];
+    /**
+     * Abstract method that subclasses must implement to bind their specific events
+     */
+    protected bindSpecificEvents(): void;
+    /**
+     * Component-specific cleanup logic (required by BaseComponent)
+     */
+    protected destroyComponent(): void;
+    /**
+     * Ensure an element exists, create if missing
+     * This is acceptable for page-level orchestration to find component root elements
+     */
+    protected ensureElement(selector: string, fallbackId: string): HTMLElement;
+    protected dismissSplashScreen(): void;
+    static loadAfterPageLoaded<T>(pageName: string, PageClass: any, PageClassName: string): void;
+}
+
+declare class TemplateLoader {
+    registryName: string;
+    constructor(registryName?: string);
+    /**
+     * Finds the specified template wrapper element in the registry.
+     * @param templateId The data-template-id of the wrapper element.
+     * @returns The wrapper HTMLElement or null if not found.
+     */
+    private _findTemplateWrapper;
+    /**
+     * Loads and returns the inner HTML of a template definition.
+     * @param templateId The data-template-id of the wrapper element.
+     * @returns The innerHTML content as string if it exists otherwise null.
+     */
+    loadHtml(templateId: string): string | null;
+    /**
+     * Loads and clones the child elements of a template definition.
+     * @param templateId The data-template-id of the wrapper element.
+     * @returns An array of cloned HTMLElement children, or an empty array if not found or has no children.
+     */
+    load(templateId: string): HTMLElement[];
+    /**
+    * Loads a template's content, clears the target element, and appends the cloned content into it.
+    * @param templateId The data-template-id of the wrapper element to load.
+    * @param targetElement The HTMLElement where the cloned content should be placed.
+    * @returns True if the operation was successful (template found and content appended, even if content was empty), false otherwise.
+    */
+    loadInto(templateId: string, targetElement: HTMLElement | null): boolean;
+}
+
+/**
+ * Utility for managing the splash screen that loads before JavaScript
+ */
+declare class SplashScreen {
+    private static readonly SPLASH_ID;
+    private static dismissed;
+    /**
+     * Dismiss the splash screen with a fade-out animation
+     * Safe to call multiple times - only dismisses once
+     */
+    static dismiss(): void;
+    /**
+     * Update the splash screen message (if it hasn't been dismissed yet)
+     */
+    static updateMessage(title?: string, message?: string): void;
+    /**
+     * Update the splash screen progress bar
+     * @param percent - Progress percentage (0-100)
+     */
+    static updateProgress(percent: number): void;
+    /**
+     * Update both message and progress at once
+     */
+    static update(options: {
+        title?: string;
+        message?: string;
+        progress?: number;
+    }): void;
+    /**
+     * Check if splash screen is still visible
+     */
+    static isVisible(): boolean;
+}
+
+/**
+ * MobileBottomDrawer - Reusable bottom drawer component for mobile layouts
+ *
+ * Features:
+ * - Slides up from bottom covering 60-70% of viewport
+ * - Backdrop overlay that dims the content behind
+ * - Auto-closes when backdrop is tapped
+ * - Swipe down to close gesture
+ * - Smooth slide-up/down animations
+ * - Holds any panel content
+ */
+declare class MobileBottomDrawer extends BaseComponent implements LCMComponent {
+    private backdropElement;
+    private drawerElement;
+    private contentElement;
+    private closeButton;
+    private isOpen;
+    private onCloseCallback?;
+    private touchStartY;
+    private touchCurrentY;
+    private isDragging;
+    /**
+     * Create a MobileBottomDrawer
+     * @param rootElement - The root container element for the drawer
+     * @param eventBus - Event bus for component communication
+     * @param debugMode - Enable debug logging
+     */
+    constructor(rootElement: HTMLElement, eventBus: EventBus, debugMode?: boolean);
+    /**
+     * Phase 1: Initialize DOM and discover child components
+     */
+    performLocalInit(): Promise<LCMComponent[]>;
+    /**
+     * Bind event listeners for drawer interactions
+     */
+    private bindEvents;
+    /**
+     * Handle touch start for swipe gesture
+     */
+    private handleTouchStart;
+    /**
+     * Handle touch move for swipe gesture
+     */
+    private handleTouchMove;
+    /**
+     * Handle touch end for swipe gesture
+     */
+    private handleTouchEnd;
+    /**
+     * Open the drawer with slide-up animation
+     */
+    open(): void;
+    /**
+     * Close the drawer with slide-down animation
+     */
+    close(): void;
+    /**
+     * Toggle drawer open/closed
+     */
+    toggle(): void;
+    /**
+     * Check if drawer is currently open
+     */
+    getIsOpen(): boolean;
+    /**
+     * Set the content element for the drawer
+     * @param element - The element to insert into the drawer content area
+     */
+    setContent(element: HTMLElement): void;
+    /**
+     * Set a callback to be called when drawer closes
+     * @param callback - Function to call on close
+     */
+    setOnClose(callback: () => void): void;
+    /**
+     * Get the content container element
+     */
+    getContentContainer(): HTMLElement;
+}
+
+/**
+ * Common DOM utility functions for consistent behavior across components
+ */
+/**
+ * Checks if the user is currently typing in an input field, textarea, or other editable element.
+ * This is used to prevent keyboard shortcuts from interfering with user input.
+ *
+ * @param element - The target element from a keyboard event
+ * @returns true if the user is in an input context, false otherwise
+ */
+declare function isInInputContext(element: HTMLElement | null): boolean;
+/**
+ * Checks if modifier keys are pressed (Ctrl, Alt, Cmd, Shift).
+ * This is commonly used to filter keyboard shortcuts.
+ *
+ * @param event - The keyboard event
+ * @returns true if any modifier keys are pressed, false otherwise
+ */
+declare function hasModifierKeys(event: KeyboardEvent): boolean;
+/**
+ * Combined check for whether keyboard shortcuts should be ignored.
+ * This checks both modifier keys and input context.
+ *
+ * @param event - The keyboard event
+ * @returns true if shortcuts should be ignored, false if they can be processed
+ */
+declare function shouldIgnoreShortcut(event: KeyboardEvent): boolean;
+
+/**
+ * Generic keyboard shortcut manager for handling multi-key commands
+ * across all application pages
+ *
+ * Current Behavior (default):
+ * - User types 'c3' → visual indicator → Enter/timeout → execute
+ * - Requires explicit confirmation for execution
+ *
+ * Future Immediate Mode (when enabled):
+ * - User types 'c3' → immediate preview → Escape to cancel
+ * - Provides instant feedback with option to cancel
+ */
+interface ShortcutConfig {
+    key: string;
+    handler: (args?: string) => void;
+    description: string;
+    category?: string;
+    requiresArgs?: boolean;
+    argType?: 'number' | 'string';
+    contextFilter?: (event: KeyboardEvent) => boolean;
+    previewHandler?: (args?: string) => void;
+    cancelHandler?: () => void;
+    executeImmediately?: boolean;
+}
+interface ShortcutManagerConfig {
+    shortcuts: ShortcutConfig[];
+    helpContainer?: string;
+    timeout?: number;
+    immediateExecution?: boolean;
+    previewDelay?: number;
+    onStateChange?: (state: KeyboardState, command?: string) => void;
+}
+declare enum KeyboardState {
+    NORMAL = "normal",
+    AWAITING_ARGS = "awaiting_args"
+}
+declare class KeyboardShortcutManager {
+    private shortcuts;
+    private state;
+    private currentCommand;
+    private currentArgs;
+    private helpContainer;
+    private timeout;
+    private timeoutId;
+    private helpOverlay;
+    private immediateExecution;
+    private previewDelay;
+    private previewTimeoutId;
+    private isPreviewActive;
+    private onStateChange;
+    constructor(config: ShortcutManagerConfig);
+    private initialize;
+    private handleKeydown;
+    private handleNormalState;
+    private handleAwaitingArgsState;
+    private executeCurrentCommand;
+    private executeShortcut;
+    private schedulePreviewExecution;
+    private cancelPreviewExecution;
+    private executePreview;
+    private cancelCurrentPreview;
+    private resetState;
+    private startTimeout;
+    private resetTimeout;
+    private clearTimeout;
+    private updateStateIndicator;
+    private showHelp;
+    private hideHelp;
+    private generateHelpContent;
+    destroy(): void;
+    getState(): KeyboardState;
+    getCurrentCommand(): string;
+    getCurrentArgs(): string;
+}
+
+export { BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, EventBus, type EventHandler, type EventSubscriber, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, LifecycleController, type LifecycleEventType, LifecycleEventTypes, MobileBottomDrawer, Modal, type ShortcutConfig, type ShortcutManagerConfig, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, shouldIgnoreShortcut };