@panyam/tsappkit 0.0.3

package/src/Component.ts

@@ -0,0 +1,178 @@
+import { EventBus, EventSubscriber, ComponentEventTypes } from './EventBus';
+import { LCMComponent } from './LCMComponent';
+
+/**
+ * Base interface for all UI components
+ * Enforces separation of concerns and standard lifecycle
+ */
+export 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;
+
+    /**
+     * Clean up the component and release resources
+     * Should unsubscribe from events, clean up DOM, and release memory
+     */
+    // destroy(): 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.
+ */
+export abstract class BaseComponent implements Component, LCMComponent, EventSubscriber {
+    protected _eventBus: EventBus;
+
+    constructor(public readonly componentId: string, public readonly rootElement: HTMLElement, eventBus: EventBus | null = null, public readonly debugMode: boolean = false) {
+        // Mark as component in DOM for debugging
+        this._eventBus = eventBus || new EventBus();
+        this.rootElement.setAttribute('data-component', this.componentId);
+    }
+
+    public get eventBus(): EventBus {
+      return this._eventBus
+    }
+
+    public contentUpdated(newHTML: string): void {
+        this.log('Content updated, re-binding to DOM');
+
+        // Update the DOM
+        this.rootElement.innerHTML = newHTML;
+
+        // Note: In pure LCMComponent approach, re-binding should be handled
+        // by the component's LCMComponent lifecycle methods if needed
+    }
+
+    /**
+     * Subscribe to an event using the new EventSubscriber pattern
+     */
+    protected addSubscription(eventType: string, target: any = null): void {
+        this.eventBus.addSubscription(eventType, target, this);
+    }
+
+    /**
+     * Unsubscribe from an event using the new EventSubscriber pattern
+     */
+    protected removeSubscription(eventType: string, target: any = null): void {
+        this.eventBus.removeSubscription(eventType, target, this);
+    }
+
+    /**
+     * Emit an event from this component
+     */
+    protected emit<T = any>(eventType: string, data: T, target: any, emitter: any = null): void {
+        this.eventBus.emit(eventType, data, target, emitter || this);
+    }
+
+    /**
+     * Default implementation of EventSubscriber interface
+     * Components can override this to handle events
+     */
+    public handleBusEvent(eventType: string, data: any, target: any, emitter: any): void {
+        // Default: no event handling
+        // Subclasses should override this method to handle specific events
+        if (this.debugMode) {
+            console.log(`[${this.componentId}] Received unhandled event: ${eventType}`);
+        }
+    }
+
+    /**
+     * 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 {
+        return this.rootElement.querySelector<T>(selector);
+    }
+
+    /**
+     * Find multiple elements within this component's root element only
+     */
+    protected findElements<T extends HTMLElement = HTMLElement>(selector: string): T[] {
+        return Array.from(this.rootElement.querySelectorAll<T>(selector));
+    }
+
+    /**
+     * Log messages with component identification
+     */
+    protected log(message: string, data: any = null): void {
+        if (this.debugMode) {
+            console.log(`[${this.componentId}] ${message}`, data);
+        }
+    }
+
+    /**
+     * Default lifecycle method: discover and return child components
+     * Override this if your component creates child components that need lifecycle management
+     */
+    public performLocalInit(): Promise<LCMComponent[]>  | LCMComponent[] {
+        // Default: no child components
+        return [];
+    }
+
+    /**
+     * Default lifecycle method: inject dependencies
+     * Override this if your component needs dependencies from other components
+     */
+    public setupDependencies(): void | Promise<void> {
+        // Default: no dependencies needed
+    }
+
+    /**
+     * Default lifecycle method: activate component for coordination
+     * Override this if your component needs to coordinate with other components after initialization
+     */
+    public activate(): void | Promise<void> {
+        // Default: no coordination needed - component is already auto-initialized
+    }
+
+    /**
+     * Default lifecycle method: deactivate component
+     * Override this if your component needs cleanup during lifecycle management
+     */
+    public deactivate(): void | Promise<void> {
+        // Remove component marker from DOM
+        this.rootElement?.removeAttribute('data-component');
+
+        this.log('Component deactivated successfully');
+    }
+
+    set innerHTML(innerHTML: string) {
+      const [newHTML, allow] = this.shouldUpdateHtml(innerHTML)
+      if (allow) {
+        this.rootElement.innerHTML = newHTML
+        this.htmlUpdated(newHTML)
+      }
+    }
+
+    // Called BEFORE the HTML is about to be updated.  This is an opportunity
+    // for subclasses to fix/tweak html being updated and also ignore an update
+    // just in case.  Default behavior is to return the html as is
+    shouldUpdateHtml(html: string): [string, boolean] {
+      return [html, true]
+    }
+
+    // Called after the HTML for the component has been updated.
+    // This is an opportunity to rebind any event listeners etc
+    htmlUpdated(html: string) {
+      // Do nothing
+    }
+
+    // LCMComponent implementation with default empty methods
+    // Components can override these when they need coordination with other components
+}

package/src/DOMUtils.ts

@@ -0,0 +1,72 @@
+/**
+ * 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
+ */
+export function isInInputContext(element: HTMLElement | null): boolean {
+    if (!element) return false;
+
+    const tagName = element.tagName.toLowerCase();
+
+    // Direct input elements
+    if (tagName === 'input' || tagName === 'textarea' || tagName === 'select') {
+        return true;
+    }
+
+    // Contenteditable elements
+    if (element.contentEditable === 'true' || element.isContentEditable) {
+        return true;
+    }
+
+    // Check if element is inside input-related containers
+    if (element.closest('input') !== null ||
+        element.closest('textarea') !== null ||
+        element.closest('select') !== null ||
+        element.closest('[contenteditable="true"]') !== null ||
+        element.closest('[contenteditable=""]') !== null) {
+        return true;
+    }
+
+    // Check if element is inside a modal (modals often contain forms)
+    if (element.closest('.modal') !== null) {
+        return true;
+    }
+
+    // Check for specific input field IDs that might be problematic
+    const inputFieldIds = ['map-title-input'];
+    if (inputFieldIds.includes(element.id) ||
+        inputFieldIds.some(id => element.closest(`#${id}`) !== null)) {
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * 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
+ */
+export function hasModifierKeys(event: KeyboardEvent): boolean {
+    return event.ctrlKey || event.altKey || event.metaKey || event.shiftKey;
+}
+
+/**
+ * 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
+ */
+export function shouldIgnoreShortcut(event: KeyboardEvent): boolean {
+    const target = event.target as HTMLElement;
+    return hasModifierKeys(event) || isInInputContext(target);
+}

package/src/EventBus.ts

@@ -0,0 +1,272 @@
+/**
+ * Simple event system for component communication
+ * Provides error isolation and idempotent subscriptions
+ */
+
+/**
+ * Simple event handler function type
+ */
+export type EventHandler = (data?: any) => void;
+
+/**
+ * Interface for components that want to receive events via the EventBus
+ */
+export 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;
+}
+
+/**
+ * Internal wrapper to adapt a simple function handler to EventSubscriber interface
+ */
+class FunctionSubscriber implements EventSubscriber {
+    constructor(public readonly handler: EventHandler) {}
+
+    handleBusEvent(eventType: string, data: any, subject: any, emitter: any): void {
+        this.handler(data);
+    }
+}
+
+/**
+ * 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
+ */
+export class EventBus {
+    private subscribers: Map<string, Set<EventSubscriber>> = new Map();
+    private functionSubscribers: Map<string, Map<EventHandler, FunctionSubscriber>> = new Map();
+    private onceHandlers: Map<string, Set<FunctionSubscriber>> = new Map();
+    private debugMode: boolean = false;
+
+    constructor(debugMode: boolean = false) {
+        this.debugMode = debugMode;
+    }
+
+    // ============== Simple Function-Based API ==============
+
+    /**
+     * Subscribe to an event with a simple handler function
+     */
+    public on(eventType: string, handler: EventHandler): void {
+        if (!this.functionSubscribers.has(eventType)) {
+            this.functionSubscribers.set(eventType, new Map());
+        }
+
+        const handlersMap = this.functionSubscribers.get(eventType)!;
+        if (handlersMap.has(handler)) {
+            if (this.debugMode) {
+                console.log(`[EventBus] Handler already registered for '${eventType}'`);
+            }
+            return;
+        }
+
+        const subscriber = new FunctionSubscriber(handler);
+        handlersMap.set(handler, subscriber);
+        this.addSubscription(eventType, null, subscriber);
+    }
+
+    /**
+     * Unsubscribe a handler function from an event
+     */
+    public off(eventType: string, handler: EventHandler): void {
+        const handlersMap = this.functionSubscribers.get(eventType);
+        if (!handlersMap) return;
+
+        const subscriber = handlersMap.get(handler);
+        if (subscriber) {
+            handlersMap.delete(handler);
+            this.removeSubscription(eventType, null, subscriber);
+
+            if (handlersMap.size === 0) {
+                this.functionSubscribers.delete(eventType);
+            }
+        }
+    }
+
+    /**
+     * Subscribe to an event for one-time execution
+     */
+    public once(eventType: string, handler: EventHandler): void {
+        if (!this.onceHandlers.has(eventType)) {
+            this.onceHandlers.set(eventType, new Set());
+        }
+
+        const subscriber = new FunctionSubscriber(handler);
+        this.onceHandlers.get(eventType)!.add(subscriber);
+
+        if (this.debugMode) {
+            console.log(`[EventBus] Added once handler for '${eventType}'`);
+        }
+    }
+
+    // ============== EventSubscriber-Based API ==============
+
+    /**
+     * Add a subscription using the EventSubscriber pattern
+     * Provides automatic idempotency - same subscriber object won't be added twice
+     */
+    public addSubscription(eventType: string, subject: any, subscriber: EventSubscriber): void {
+        if (!this.subscribers.has(eventType)) {
+            this.subscribers.set(eventType, new Set());
+        }
+
+        const subscribers = this.subscribers.get(eventType)!;
+        const wasAdded = !subscribers.has(subscriber);
+
+        if (wasAdded) {
+            subscribers.add(subscriber);
+            if (this.debugMode) {
+                console.log(`[EventBus] Added subscription to '${eventType}' for ${subscriber.constructor.name}`);
+            }
+        } else if (this.debugMode) {
+            console.log(`[EventBus] Subscription already exists for '${eventType}' and ${subscriber.constructor.name}`);
+        }
+    }
+
+    /**
+     * Remove a subscription using the EventSubscriber pattern
+     */
+    public removeSubscription(eventType: string, subject: any, subscriber: EventSubscriber): void {
+        const subscribers = this.subscribers.get(eventType);
+
+        if (subscribers) {
+            const wasRemoved = subscribers.delete(subscriber);
+
+            if (this.debugMode && wasRemoved) {
+                console.log(`[EventBus] Removed subscription from '${eventType}' for ${subscriber.constructor.name}`);
+            }
+
+            // Clean up empty subscription sets
+            if (subscribers.size === 0) {
+                this.subscribers.delete(eventType);
+            }
+        }
+    }
+
+    /**
+     * 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)
+     */
+    public emit<T = any>(eventType: string, data?: T, subject?: any, emitter?: any): void {
+        const subscribers = this.subscribers.get(eventType);
+        const onceHandlers = this.onceHandlers.get(eventType);
+
+        const subscriberCount = (subscribers?.size || 0) + (onceHandlers?.size || 0);
+        if (subscriberCount === 0) {
+            return;
+        }
+
+        if (this.debugMode) {
+            console.log(`[EventBus] Emitting '${eventType}' to ${subscriberCount} subscribers`);
+        }
+
+        let successCount = 0;
+        let errorCount = 0;
+
+        // Call regular EventSubscriber handlers with error isolation
+        if (subscribers) {
+            subscribers.forEach(subscriber => {
+                try {
+                    subscriber.handleBusEvent(eventType, data, subject, emitter);
+                    successCount++;
+                } catch (error) {
+                    errorCount++;
+                    console.error(
+                        `[EventBus] Error in EventSubscriber handler for '${eventType}' ` +
+                        `in subscriber '${subscriber.constructor.name}':`,
+                        error
+                    );
+                }
+            });
+        }
+
+        // Call one-time handlers and then remove them
+        if (onceHandlers && onceHandlers.size > 0) {
+            onceHandlers.forEach(subscriber => {
+                try {
+                    subscriber.handleBusEvent(eventType, data, subject, emitter);
+                    successCount++;
+                } catch (error) {
+                    errorCount++;
+                    console.error(
+                        `[EventBus] Error in once handler for '${eventType}':`,
+                        error
+                    );
+                }
+            });
+            // Clear once handlers after execution
+            this.onceHandlers.delete(eventType);
+        }
+
+        if (this.debugMode) {
+            console.log(
+                `[EventBus] Event '${eventType}' completed: ` +
+                `${successCount} success, ${errorCount} errors`
+            );
+        }
+    }
+
+    /**
+     * Get all event types that have subscribers
+     */
+    public getEventTypes(): string[] {
+        return Array.from(this.subscribers.keys());
+    }
+
+    /**
+     * Get subscriber count for an event type
+     */
+    public getSubscriberCount(eventType: string): number {
+        return this.subscribers.get(eventType)?.size || 0;
+    }
+
+    /**
+     * Clear all subscriptions (useful for cleanup)
+     */
+    public clear(): void {
+        this.subscribers.clear();
+        this.functionSubscribers.clear();
+        this.onceHandlers.clear();
+        if (this.debugMode) {
+            console.log('[EventBus] All subscriptions cleared');
+        }
+    }
+
+    /**
+     * Enable or disable debug logging
+     */
+    public setDebugMode(enabled: boolean): void {
+        this.debugMode = enabled;
+    }
+}
+
+export const ComponentEventTypes= {
+    COMPONENT_INITIALIZED: 'component-initialized',
+    COMPONENT_HYDRATED: 'component-hydrated',
+    COMPONENT_ERROR: 'component-error'
+} as const;
+
+export const LifecycleEventTypes = {
+    LOCAL_INIT_STARTED: "lifecycle-local-init-started",
+    LOCAL_INIT_FINISHED: "lifecycle-local-init-finished",
+    DEPENDENCIES_INJECTED: "lifecycle-dependencies-injected",
+    ACTIVATION_STARTED: "lifecycle-activation-started",
+    ACTIVATION_FINISHED: "lifecycle-activation-finished",
+    DEACTIVATION_STARTED: "lifecycle-deactivation-started",
+    DEACTIVATION_FINISHED: "lifecycle-deactivation-finished",
+} as const;
+
+export type LifecycleEventType = typeof LifecycleEventTypes[keyof typeof LifecycleEventTypes];
+export type ComponentEventType = typeof ComponentEventTypes[keyof typeof ComponentEventTypes];