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

package/dist/core/renderer.js

@@ -0,0 +1,196 @@
+import { EMPTY_STYLES, LOADING_STYLES, MAIN_STYLES } from '../const/styles.js';
+import { resolveAuthorConfig } from '../utils/author-resolver.js';
+import { buildMessageRowHtml } from '../utils/message-builder.js';
+import { buildScrollButtonHtml } from '../utils/scroll-button.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;
+        }
+        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);
+        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/parsers/base.d.ts

@@ -0,0 +1,21 @@
+import type { Message } from '../types/index.js';
+/**
+ * Parser interface for message parsing
+ * Allows custom parsers to be plugged in
+ */
+export interface MessageParser {
+    /**
+     * Parse text content into message array
+     * @param textContent - Raw text content to parse
+     * @returns Array of parsed messages
+     */
+    parse(textContent: string | null): Message[];
+}
+/**
+ * Input type for appending messages
+ */
+export interface MessageInput {
+    author: string;
+    text: string;
+    timestamp?: string;
+}

package/dist/parsers/base.js

@@ -0,0 +1 @@
+export {};

package/dist/parsers/default-parser.d.ts

@@ -0,0 +1,10 @@
+import type { Message } from '../types/index.js';
+import type { MessageParser } from './base.js';
+/**
+ * Default message parser implementation
+ * Format: `[timestamp] author: text` or `author: text` (one message per line)
+ * Timestamp is optional for backward compatibility
+ */
+export declare class DefaultMessageParser implements MessageParser {
+    parse(textContent: string | null): Message[];
+}

package/dist/parsers/default-parser.js

@@ -0,0 +1,40 @@
+/**
+ * Default message parser implementation
+ * Format: `[timestamp] author: text` or `author: text` (one message per line)
+ * Timestamp is optional for backward compatibility
+ */
+export class DefaultMessageParser {
+    parse(textContent) {
+        const raw = textContent || '';
+        const messages = [];
+        // Pattern: [timestamp] author: text (space between timestamp and author is optional)
+        const timestampPattern = /^\[([^\]]+)\]\s*(.+)$/;
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let remainingLine = trimmed;
+            let timestamp;
+            // Try to extract timestamp
+            const timestampMatch = trimmed.match(timestampPattern);
+            if (timestampMatch) {
+                timestamp = timestampMatch[1].trim();
+                remainingLine = timestampMatch[2];
+            }
+            // Find the author:text separator (colon followed by space)
+            const colonIdx = remainingLine.indexOf(':');
+            if (colonIdx <= 0)
+                continue;
+            const author = remainingLine.slice(0, colonIdx).trim();
+            const text = remainingLine.slice(colonIdx + 1).trim();
+            if (author && text) {
+                const message = { author, text };
+                if (timestamp) {
+                    message.timestamp = timestamp;
+                }
+                messages.push(message);
+            }
+        }
+        return messages;
+    }
+}

package/dist/parsers/index.d.ts

@@ -0,0 +1,2 @@
+export type { MessageParser, MessageInput } from './base.js';
+export { DefaultMessageParser } from './default-parser.js';

package/dist/parsers/index.js

@@ -0,0 +1 @@
+export { DefaultMessageParser } from './default-parser.js';

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/dist/utils/message-builder.d.ts

@@ -11,7 +11,3 @@ export declare function buildTimestampHtml(timestamp: string, side: 'left' | 'ri
  * Build a single message row HTML string
  */
 export declare function buildMessageRowHtml(author: string, text: string, config: AuthorConfig, isSubsequent: boolean, timestamp?: string, isLastInGroup?: boolean): string;
-/**
- * Setup tooltip for a single avatar wrapper element
- */
-export declare function setupTooltipForElement(wrapper: Element): void;

package/dist/utils/message-builder.js

@@ -8,7 +8,6 @@ export function buildAvatarHtml(author, config, showAvatar) {
     <div class="avatar-wrapper ${showAvatar ? '' : 'avatar-wrapper--hidden'}"
          data-author="${escapeHtml(author)}">
       <div class="avatar">${config.avatar}</div>
-      <div class="avatar-tooltip">${escapeHtml(author)}</div>
     </div>
   `;
 }
@@ -53,17 +52,3 @@ export function buildMessageRowHtml(author, text, config, isSubsequent, timestam
     </div>
   `;
 }
-/**
- * Setup tooltip for a single avatar wrapper element
- */
-export function setupTooltipForElement(wrapper) {
-    wrapper.addEventListener('mouseenter', () => {
-        const tooltip = wrapper.querySelector('.avatar-tooltip');
-        if (!tooltip)
-            return;
-        const rect = wrapper.getBoundingClientRect();
-        const tooltipRect = tooltip.getBoundingClientRect();
-        tooltip.style.left = `${rect.left + rect.width / 2 - tooltipRect.width / 2}px`;
-        tooltip.style.top = `${rect.top - tooltipRect.height - 8}px`;
-    });
-}

package/dist/utils/tooltip.d.ts

@@ -1,5 +1,14 @@
 /**
- * Setup dynamic tooltip positioning
- * Tooltips are positioned fixed to avoid overflow clipping from parent containers
+ * Tooltip utilities for avatar hover effects
+ *
+ * Tooltips use position: fixed to escape overflow clipping from scrollable containers.
+ * Position is calculated on mouseenter and updated on scroll to prevent staleness.
+ */
+/**
+ * Setup tooltip positioning for a single avatar wrapper element
+ */
+export declare function setupTooltipForElement(wrapper: Element): void;
+/**
+ * Setup tooltips for all avatar wrappers in the shadow root
  */
 export declare function setupTooltips(shadowRoot: ShadowRoot): void;

package/dist/utils/tooltip.js

@@ -1,17 +1,60 @@
 /**
- * Setup dynamic tooltip positioning
- * Tooltips are positioned fixed to avoid overflow clipping from parent containers
+ * Tooltip utilities for avatar hover effects
+ *
+ * Tooltips use position: fixed to escape overflow clipping from scrollable containers.
+ * Position is calculated on mouseenter and updated on scroll to prevent staleness.
+ */
+/**
+ * Position a tooltip relative to its avatar wrapper
+ * Centers horizontally and places above the avatar
+ */
+function positionTooltip(wrapper, tooltip) {
+    const rect = wrapper.getBoundingClientRect();
+    const tooltipRect = tooltip.getBoundingClientRect();
+    // Center horizontally relative to viewport
+    let left = rect.left + rect.width / 2 - tooltipRect.width / 2;
+    // Viewport boundary check - keep tooltip within viewport
+    const padding = 8;
+    left = Math.max(padding, Math.min(left, window.innerWidth - tooltipRect.width - padding));
+    // Position above avatar
+    const top = rect.top - tooltipRect.height - 8;
+    tooltip.style.left = `${left}px`;
+    tooltip.style.top = `${top}px`;
+}
+/**
+ * Setup tooltip positioning for a single avatar wrapper element
+ */
+export function setupTooltipForElement(wrapper) {
+    const tooltip = wrapper.querySelector('.avatar-tooltip');
+    if (!tooltip)
+        return;
+    let scrollContainer = null;
+    const handleMouseEnter = () => {
+        // Find the scrollable container (if any)
+        scrollContainer = wrapper.closest('.history');
+        // Initial position
+        positionTooltip(wrapper, tooltip);
+        // Add scroll listener to update position during scroll
+        if (scrollContainer) {
+            scrollContainer.addEventListener('scroll', handleScroll, { passive: true });
+        }
+    };
+    const handleMouseLeave = () => {
+        // Remove scroll listener when not hovering
+        if (scrollContainer) {
+            scrollContainer.removeEventListener('scroll', handleScroll);
+            scrollContainer = null;
+        }
+    };
+    const handleScroll = () => {
+        positionTooltip(wrapper, tooltip);
+    };
+    wrapper.addEventListener('mouseenter', handleMouseEnter);
+    wrapper.addEventListener('mouseleave', handleMouseLeave);
+}
+/**
+ * Setup tooltips for all avatar wrappers in the shadow root
  */
 export function setupTooltips(shadowRoot) {
-    shadowRoot.querySelectorAll('.avatar-wrapper').forEach(wrapper => {
-        wrapper.addEventListener('mouseenter', () => {
-            const tooltip = wrapper.querySelector('.avatar-tooltip');
-            if (!tooltip)
-                return;
-            const rect = wrapper.getBoundingClientRect();
-            const tooltipRect = tooltip.getBoundingClientRect();
-            tooltip.style.left = `${rect.left + rect.width / 2 - tooltipRect.width / 2}px`;
-            tooltip.style.top = `${rect.top - tooltipRect.height - 8}px`;
-        });
-    });
+    shadowRoot.querySelectorAll('.avatar-wrapper').forEach(setupTooltipForElement);
 }

package/package.json

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