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

package/src/core/renderer.ts

@@ -0,0 +1,286 @@
+import type { AuthorOptions, Message } from '../types/index.js';
+import type { ProcessedMessage } from './message-processor.js';
+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';
+
+/**
+ * State for incremental message appending
+ */
+export interface LastState {
+  author: string;
+  groupTimestamp?: string;
+}
+
+/**
+ * Result of a full render operation
+ */
+export interface RenderResult {
+  wasAtBottom: boolean;
+}
+
+/**
+ * Result of an incremental append operation
+ */
+export interface AppendResult {
+  success: boolean;
+  lastAuthor: string;
+  lastGroupTimestamp?: string;
+}
+
+/**
+ * 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(private 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: ProcessedMessage[],
+    authors: Map<string, AuthorOptions>,
+    isLoading: boolean,
+    hideScrollButton: boolean
+  ): RenderResult {
+    // Check if we need to create or update the structure
+    const historyContainer = this.shadowRoot.querySelector('.history') as HTMLElement | null;
+    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
+   */
+  private buildMessagesHtml(
+    messages: ProcessedMessage[],
+    authors: Map<string, AuthorOptions>
+  ): string {
+    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
+   */
+  private renderFullStructure(
+    messagesHtml: string,
+    isLoading: boolean,
+    hideScrollButton: boolean
+  ): RenderResult {
+    // 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
+   */
+  private updateContent(
+    historyContainer: HTMLElement,
+    messagesHtml: string,
+    isLoading: boolean
+  ): RenderResult {
+    // 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: Message,
+    authors: Map<string, AuthorOptions>,
+    lastState: LastState
+  ): AppendResult {
+    const container = this.shadowRoot.querySelector('.history') as HTMLElement | null;
+
+    // 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: Message | null = 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
+   */
+  private canGroupMessages(prev: Message | null, curr: Message): boolean {
+    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: boolean): void {
+    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: boolean): void {
+    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(): HTMLElement | null {
+    return this.shadowRoot.querySelector('.history') as HTMLElement | null;
+  }
+
+  /**
+   * Get the scroll-to-bottom button element
+   */
+  getScrollButton(): HTMLButtonElement | null {
+    return this.shadowRoot.querySelector('.scroll-to-bottom') as HTMLButtonElement | null;
+  }
+}

package/src/core/scroll-manager.ts

@@ -0,0 +1,148 @@
+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 class ScrollManager {
+  private container?: HTMLElement;
+  private button?: HTMLButtonElement | null;
+  private isButtonVisible = false;
+
+  // Threshold in pixels from bottom to consider "at bottom"
+  private readonly BOTTOM_THRESHOLD = 50;
+
+  constructor(
+    private host: HTMLElement,
+    private shadowRoot: ShadowRoot,
+    private eventTracker: EventTracker,
+    private 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 = false): void {
+    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(): void {
+    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: ScrollBehavior = 'smooth'): void {
+    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(): boolean {
+    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(): boolean {
+    return this.isButtonVisible;
+  }
+
+  /**
+   * Get the scrollable container element
+   */
+  getContainer(): HTMLElement | undefined {
+    return this.container;
+  }
+}

package/src/utils/event-tracker.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 {
+  private listeners: Array<{
+    el: EventTarget;
+    type: string;
+    fn: EventListener;
+    options?: AddEventListenerOptions;
+  }> = [];
+
+  /**
+   * 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 {
+    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(): void {
+    this.listeners.forEach(({ el, type, fn, options }) => {
+      el.removeEventListener(type, fn, options);
+    });
+    this.listeners = [];
+  }
+}