@bbki.ng/bb-msg-history 0.14.1 → 1.0.0

package/dist/core/renderer.js

@@ -0,0 +1,204 @@
+import { EMPTY_STYLES, LOADING_STYLES, MAIN_STYLES } from '../const/styles.js';
+import { resolveAuthorConfig } from '../utils/author-resolver.js';
+import { buildMessageRowHtml, setupTooltipForElement } from '../utils/message-builder.js';
+import { buildScrollButtonHtml } from '../utils/scroll-button.js';
+import { setupTooltips } from '../utils/tooltip.js';
+/**
+ * Renderer - Manages all DOM rendering operations
+ *
+ * Centralizes DOM manipulation logic:
+ * - Full render of all messages
+ * - Incremental update when appending single messages
+ * - Empty state rendering
+ * - Loading overlay management
+ */
+export class Renderer {
+    constructor(shadowRoot) {
+        this.shadowRoot = shadowRoot;
+    }
+    /**
+     * Render the complete message history
+     *
+     * @param messages - Processed messages with grouping metadata
+     * @param authors - User-defined author configurations
+     * @param isLoading - Whether to show loading overlay
+     * @param hideScrollButton - Whether to hide the scroll-to-bottom button
+     * @returns Result indicating if we were at bottom before render
+     */
+    render(messages, authors, isLoading, hideScrollButton) {
+        // Check if we need to create or update the structure
+        const historyContainer = this.shadowRoot.querySelector('.history');
+        const needsFullSetup = !historyContainer;
+        // Build messages HTML
+        const messagesHtml = this.buildMessagesHtml(messages, authors);
+        if (needsFullSetup) {
+            // First render - create full structure
+            return this.renderFullStructure(messagesHtml, isLoading, hideScrollButton);
+        }
+        else {
+            // Update only - preserve DOM structure
+            return this.updateContent(historyContainer, messagesHtml, isLoading);
+        }
+    }
+    /**
+     * Build HTML string for all messages
+     */
+    buildMessagesHtml(messages, authors) {
+        return messages
+            .map(msg => {
+            const config = resolveAuthorConfig(msg.author, authors);
+            return buildMessageRowHtml(msg.author, msg.text, config, !msg.isFirstFromAuthor, // isSubsequent
+            msg.groupTimestamp, msg.isLastInGroup);
+        })
+            .join('');
+    }
+    /**
+     * Render full structure including styles, container, and scroll button
+     */
+    renderFullStructure(messagesHtml, isLoading, hideScrollButton) {
+        // For initial render, we consider it as "was at bottom" to scroll down
+        const wasAtBottom = true;
+        const loadingOverlay = isLoading
+            ? `<div class="loading-overlay" role="status" aria-label="Loading messages">
+          <div class="loading-spinner"></div>
+        </div>`
+            : '';
+        this.shadowRoot.innerHTML = `
+      <style>${MAIN_STYLES}${LOADING_STYLES}</style>
+      <div class="history" role="log" aria-live="polite" aria-label="Message history">
+        ${messagesHtml}
+      </div>
+      ${hideScrollButton ? '' : buildScrollButtonHtml()}
+      ${loadingOverlay}
+    `;
+        return { wasAtBottom };
+    }
+    /**
+     * Update content while preserving DOM structure
+     */
+    updateContent(historyContainer, messagesHtml, isLoading) {
+        // Check scroll position before update
+        const scrollContainer = historyContainer;
+        const wasAtBottom = scrollContainer.scrollHeight - scrollContainer.scrollTop - scrollContainer.clientHeight < 50;
+        // Update messages content only
+        historyContainer.innerHTML = messagesHtml;
+        // Update loading overlay
+        this.updateLoadingOverlay(isLoading);
+        // Restore scroll position or scroll to bottom if we were there
+        if (wasAtBottom) {
+            scrollContainer.scrollTop = scrollContainer.scrollHeight;
+        }
+        // Re-setup tooltips for new content
+        setupTooltips(this.shadowRoot);
+        return { wasAtBottom };
+    }
+    /**
+     * Append a single message without full re-render
+     *
+     * @param message - The message to append
+     * @param authors - User-defined author configurations
+     * @param lastState - Previous state for grouping logic
+     * @returns Result indicating success and updated state
+     */
+    appendSingleMessage(message, authors, lastState) {
+        const container = this.shadowRoot.querySelector('.history');
+        // If empty state or no container, signal that full render is needed
+        if (!container) {
+            return { success: false, lastAuthor: lastState.author };
+        }
+        const config = resolveAuthorConfig(message.author, authors);
+        // Determine grouping
+        const prevMessage = lastState.author
+            ? { author: lastState.author, text: '', timestamp: lastState.groupTimestamp }
+            : null;
+        const canGroupWithLast = this.canGroupMessages(prevMessage, message);
+        const isFirstFromAuthor = !canGroupWithLast;
+        // Calculate new state
+        let lastGroupTimestamp = lastState.groupTimestamp;
+        if (isFirstFromAuthor) {
+            lastGroupTimestamp = message.timestamp;
+        }
+        else if (!lastGroupTimestamp && message.timestamp) {
+            lastGroupTimestamp = message.timestamp;
+        }
+        // Build and append HTML
+        const msgHtml = buildMessageRowHtml(message.author, message.text, config, !isFirstFromAuthor, // isSubsequent
+        lastGroupTimestamp, true // isLastInGroup - when appending, this is always last (for now)
+        );
+        container.insertAdjacentHTML('beforeend', msgHtml);
+        // Setup tooltip for new element
+        const newWrapper = container.lastElementChild?.querySelector('.avatar-wrapper');
+        if (newWrapper) {
+            setupTooltipForElement(newWrapper);
+        }
+        return {
+            success: true,
+            lastAuthor: message.author,
+            lastGroupTimestamp,
+        };
+    }
+    /**
+     * Check if two messages can be grouped
+     */
+    canGroupMessages(prev, curr) {
+        if (!prev)
+            return false;
+        if (prev.author !== curr.author)
+            return false;
+        if (prev.timestamp && curr.timestamp && prev.timestamp !== curr.timestamp) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Render empty state (no messages)
+     */
+    renderEmpty(isLoading) {
+        if (isLoading) {
+            // Show loading overlay with minimum height
+            this.shadowRoot.innerHTML = `
+        <style>${EMPTY_STYLES}${LOADING_STYLES}</style>
+        <div style="position: relative; min-height: 120px;">
+          <div class="loading-overlay" role="status" aria-label="Loading messages">
+            <div class="loading-spinner"></div>
+          </div>
+        </div>
+      `;
+        }
+        else {
+            this.shadowRoot.innerHTML = `
+        <style>${EMPTY_STYLES}</style>
+        <div class="empty-state">No messages</div>
+      `;
+        }
+    }
+    /**
+     * Update loading overlay visibility
+     */
+    updateLoadingOverlay(shouldShow) {
+        const existingOverlay = this.shadowRoot.querySelector('.loading-overlay');
+        if (shouldShow && !existingOverlay) {
+            const overlay = document.createElement('div');
+            overlay.className = 'loading-overlay';
+            overlay.setAttribute('role', 'status');
+            overlay.setAttribute('aria-label', 'Loading messages');
+            overlay.innerHTML = '<div class="loading-spinner"></div>';
+            this.shadowRoot.appendChild(overlay);
+        }
+        else if (!shouldShow && existingOverlay) {
+            existingOverlay.remove();
+        }
+    }
+    /**
+     * Get the history container element
+     */
+    getHistoryContainer() {
+        return this.shadowRoot.querySelector('.history');
+    }
+    /**
+     * Get the scroll-to-bottom button element
+     */
+    getScrollButton() {
+        return this.shadowRoot.querySelector('.scroll-to-bottom');
+    }
+}

package/dist/core/scroll-manager.d.ts

@@ -0,0 +1,54 @@
+import type { EventTracker } from '../utils/event-tracker.js';
+/**
+ * ScrollManager - Handles scroll behavior, position detection, and scroll button visibility
+ *
+ * Isolates all scroll-related logic from the main component:
+ * - Scroll to bottom with smooth animation
+ * - Detect when user is near/at bottom of content
+ * - Control scroll button visibility based on scroll position
+ * - Dispatch custom events for scroll button state changes
+ */
+export declare class ScrollManager {
+    private host;
+    private shadowRoot;
+    private eventTracker;
+    private onVisibilityChange;
+    private container?;
+    private button?;
+    private isButtonVisible;
+    private readonly BOTTOM_THRESHOLD;
+    constructor(host: HTMLElement, shadowRoot: ShadowRoot, eventTracker: EventTracker, onVisibilityChange: (visible: boolean) => void);
+    /**
+     * Initialize scroll tracking on the container
+     *
+     * @param container - The scrollable history container
+     * @param button - Optional scroll-to-bottom button element
+     * @param skipInitialCheck - If true, skip the initial position check (for initial render)
+     */
+    init(container: HTMLElement, button?: HTMLButtonElement | null, skipInitialCheck?: boolean): void;
+    /**
+     * Check current scroll position and update button visibility
+     * Dispatches custom events when visibility changes
+     */
+    checkPosition(): void;
+    /**
+     * Scroll the container to the bottom
+     *
+     * @param behavior - Scroll behavior: 'smooth' or 'auto'
+     */
+    scrollToBottom(behavior?: ScrollBehavior): void;
+    /**
+     * Check if the container is currently at or near the bottom
+     *
+     * @returns true if within threshold pixels of bottom
+     */
+    isAtBottom(): boolean;
+    /**
+     * Get the current button visibility state
+     */
+    get isVisible(): boolean;
+    /**
+     * Get the scrollable container element
+     */
+    getContainer(): HTMLElement | undefined;
+}

package/dist/core/scroll-manager.js

@@ -0,0 +1,119 @@
+/**
+ * ScrollManager - Handles scroll behavior, position detection, and scroll button visibility
+ *
+ * Isolates all scroll-related logic from the main component:
+ * - Scroll to bottom with smooth animation
+ * - Detect when user is near/at bottom of content
+ * - Control scroll button visibility based on scroll position
+ * - Dispatch custom events for scroll button state changes
+ */
+export class ScrollManager {
+    constructor(host, shadowRoot, eventTracker, onVisibilityChange) {
+        this.host = host;
+        this.shadowRoot = shadowRoot;
+        this.eventTracker = eventTracker;
+        this.onVisibilityChange = onVisibilityChange;
+        this.isButtonVisible = false;
+        // Threshold in pixels from bottom to consider "at bottom"
+        this.BOTTOM_THRESHOLD = 50;
+    }
+    /**
+     * Initialize scroll tracking on the container
+     *
+     * @param container - The scrollable history container
+     * @param button - Optional scroll-to-bottom button element
+     * @param skipInitialCheck - If true, skip the initial position check (for initial render)
+     */
+    init(container, button, skipInitialCheck = false) {
+        this.container = container;
+        this.button = button ?? null;
+        if (!skipInitialCheck) {
+            this.checkPosition();
+        }
+        // Listen for scroll events with passive listener for performance
+        this.eventTracker.add(container, 'scroll', () => this.checkPosition(), { passive: true });
+        // Also check on resize
+        this.eventTracker.add(window, 'resize', () => this.checkPosition());
+        // Setup button click handler
+        if (button && !this.host.hasAttribute('infinite')) {
+            button.addEventListener('click', () => this.scrollToBottom());
+        }
+    }
+    /**
+     * Check current scroll position and update button visibility
+     * Dispatches custom events when visibility changes
+     */
+    checkPosition() {
+        if (!this.container)
+            return;
+        const isAtBottom = this.isAtBottom();
+        const hasOverflow = this.container.scrollHeight > this.container.clientHeight;
+        // Show button when not at bottom and content has overflow
+        const shouldShow = !isAtBottom && hasOverflow;
+        if (shouldShow !== this.isButtonVisible) {
+            this.isButtonVisible = shouldShow;
+            // Update button UI
+            if (this.button) {
+                this.button.classList.toggle('visible', shouldShow);
+            }
+            // Notify parent component
+            this.onVisibilityChange(shouldShow);
+            // Dispatch custom event
+            this.host.dispatchEvent(new CustomEvent(shouldShow ? 'bb-scrollbuttonshow' : 'bb-scrollbuttonhide', {
+                bubbles: true,
+                composed: true,
+                detail: { visible: shouldShow },
+            }));
+        }
+    }
+    /**
+     * Scroll the container to the bottom
+     *
+     * @param behavior - Scroll behavior: 'smooth' or 'auto'
+     */
+    scrollToBottom(behavior = 'smooth') {
+        if (!this.container || this.host.hasAttribute('infinite')) {
+            return;
+        }
+        this.container.scrollTo({
+            top: this.container.scrollHeight,
+            behavior,
+        });
+        // Hide button since we're scrolling to bottom
+        if (this.isButtonVisible) {
+            this.isButtonVisible = false;
+            if (this.button) {
+                this.button.classList.remove('visible');
+            }
+            this.onVisibilityChange(false);
+            this.host.dispatchEvent(new CustomEvent('bb-scrollbuttonhide', {
+                bubbles: true,
+                composed: true,
+                detail: { visible: false },
+            }));
+        }
+    }
+    /**
+     * Check if the container is currently at or near the bottom
+     *
+     * @returns true if within threshold pixels of bottom
+     */
+    isAtBottom() {
+        if (!this.container)
+            return true;
+        const distanceFromBottom = this.container.scrollHeight - this.container.scrollTop - this.container.clientHeight;
+        return distanceFromBottom < this.BOTTOM_THRESHOLD;
+    }
+    /**
+     * Get the current button visibility state
+     */
+    get isVisible() {
+        return this.isButtonVisible;
+    }
+    /**
+     * Get the scrollable container element
+     */
+    getContainer() {
+        return this.container;
+    }
+}

package/dist/utils/event-tracker.d.ts

@@ -0,0 +1,23 @@
+/**
+ * EventTracker - Utility class for tracking and managing event listeners
+ *
+ * Provides centralized event listener registration and cleanup,
+ * preventing memory leaks by ensuring all listeners are removed when no longer needed.
+ */
+export declare class EventTracker {
+    private listeners;
+    /**
+     * Add an event listener and track it for automatic cleanup
+     *
+     * @param el - Event target element
+     * @param type - Event type (e.g., 'scroll', 'click')
+     * @param fn - Event listener function
+     * @param options - Optional addEventListener options
+     */
+    add(el: EventTarget, type: string, fn: EventListener, options?: AddEventListenerOptions): void;
+    /**
+     * Remove all tracked event listeners
+     * Should be called when the component is disconnected to prevent memory leaks
+     */
+    cleanup(): void;
+}

package/dist/utils/event-tracker.js

@@ -0,0 +1,33 @@
+/**
+ * EventTracker - Utility class for tracking and managing event listeners
+ *
+ * Provides centralized event listener registration and cleanup,
+ * preventing memory leaks by ensuring all listeners are removed when no longer needed.
+ */
+export class EventTracker {
+    constructor() {
+        this.listeners = [];
+    }
+    /**
+     * Add an event listener and track it for automatic cleanup
+     *
+     * @param el - Event target element
+     * @param type - Event type (e.g., 'scroll', 'click')
+     * @param fn - Event listener function
+     * @param options - Optional addEventListener options
+     */
+    add(el, type, fn, options) {
+        el.addEventListener(type, fn, options);
+        this.listeners.push({ el, type, fn, options });
+    }
+    /**
+     * Remove all tracked event listeners
+     * Should be called when the component is disconnected to prevent memory leaks
+     */
+    cleanup() {
+        this.listeners.forEach(({ el, type, fn, options }) => {
+            el.removeEventListener(type, fn, options);
+        });
+        this.listeners = [];
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bbki.ng/bb-msg-history",
-  "version": "0.14.1",
+  "version": "1.0.0",
   "description": "A chat-style message history web component",
   "main": "dist/index.js",
   "type": "module",