@bbki.ng/bb-msg-history 0.6.1 → 0.7.0

package/README.md

@@ -101,6 +101,35 @@ Returns `this` for chaining. This is ideal for chat applications where messages
 
 **Note:** Unlike modifying `textContent` directly, `appendMessage()` scrolls smoothly to the newly added message.
 
+### `setLoading(isLoading)`
+
+Show or hide a loading animation overlay. Useful when fetching messages from an API.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `isLoading` | `boolean` | `true` to show loading, `false` to hide |
+
+```js
+const el = document.querySelector('bb-msg-history');
+
+// Show loading
+el.setLoading(true);
+
+// Fetch messages
+fetchMessages().then(messages => {
+  // Hide loading and display messages
+  el.setLoading(false);
+});
+```
+
+You can also use the HTML attribute:
+
+```html
+<bb-msg-history loading>
+  alice: Loading previous messages...
+</bb-msg-history>
+```
+
 ## Customization
 
 ### CSS Custom Properties
@@ -138,6 +167,7 @@ define('my-chat-history');
 - Consecutive messages from the same author are grouped (avatar hidden)
 - Auto-scroll to the latest message on render
 - **`appendMessage()` API** — programmatically add messages with smooth scroll
+- **`setLoading()` API** — show loading animation while fetching messages
 - Long text word-wrap and overflow handling
 - Empty state when no messages are provided
 - Dark mode support via `prefers-color-scheme`
@@ -234,6 +264,34 @@ Use `appendMessage()` to add messages programmatically with smooth scrolling:
 </script>
 ```
 
+### Loading state
+
+Show a loading animation while fetching messages from an API:
+
+```html
+<bb-msg-history id="chat" loading>
+  <!-- Messages will be loaded -->
+</bb-msg-history>
+
+<script>
+  const el = document.getElementById('chat');
+
+  // Show loading (already set via HTML attribute above)
+  // el.setLoading(true);
+
+  // Fetch messages from API
+  fetch('/api/messages')
+    .then(res => res.json())
+    .then(messages => {
+      // Hide loading and populate messages
+      el.setLoading(false);
+      messages.forEach(msg => {
+        el.appendMessage({ author: msg.author, text: msg.text });
+      });
+    });
+</script>
+```
+
 ### Full page example
 
 ```html

package/dist/component.d.ts

@@ -7,7 +7,7 @@ export declare class BBMsgHistory extends HTMLElement {
     private _scrollButtonVisible;
     static get observedAttributes(): string[];
     constructor();
-    attributeChangedCallback(): void;
+    attributeChangedCallback(name: string): void;
     /**
      * Configure an author's avatar, side, and colors.
      * Call before or after rendering — the component re-renders automatically.
@@ -21,6 +21,14 @@ export declare class BBMsgHistory extends HTMLElement {
      * Remove a previously set author config.
      */
     removeAuthor(name: string): this;
+    /**
+     * Show or hide the loading overlay.
+     *
+     * @example
+     * el.setLoading(true);  // Show loading animation
+     * el.setLoading(false); // Hide loading animation
+     */
+    setLoading(isLoading: boolean): this;
     /**
      * Append a message to the history.
      * Automatically scrolls to the new message with smooth animation.

package/dist/component.js

@@ -1,4 +1,4 @@
-import { MAIN_STYLES, EMPTY_STYLES } from './const/styles.js';
+import { EMPTY_STYLES, LOADING_STYLES, MAIN_STYLES } from './const/styles.js';
 import { parseMessages } from './utils/message-parser.js';
 import { resolveAuthorConfig } from './utils/author-resolver.js';
 import { setupTooltips } from './utils/tooltip.js';
@@ -6,7 +6,7 @@ import { buildMessageRowHtml, setupTooltipForElement } from './utils/message-bui
 import { buildScrollButtonHtml } from './utils/scroll-button.js';
 export class BBMsgHistory extends HTMLElement {
     static get observedAttributes() {
-        return ['theme'];
+        return ['theme', 'loading'];
     }
     constructor() {
         super();
@@ -15,8 +15,10 @@ export class BBMsgHistory extends HTMLElement {
         this._scrollButtonVisible = false;
         this.attachShadow({ mode: 'open' });
     }
-    attributeChangedCallback() {
-        this.render();
+    attributeChangedCallback(name) {
+        if (name === 'theme' || name === 'loading') {
+            this.render();
+        }
     }
     /**
      * Configure an author's avatar, side, and colors.
@@ -39,6 +41,17 @@ export class BBMsgHistory extends HTMLElement {
         this.render();
         return this;
     }
+    /**
+     * Show or hide the loading overlay.
+     *
+     * @example
+     * el.setLoading(true);  // Show loading animation
+     * el.setLoading(false); // Hide loading animation
+     */
+    setLoading(isLoading) {
+        this.toggleAttribute('loading', isLoading);
+        return this;
+    }
     /**
      * Append a message to the history.
      * Automatically scrolls to the new message with smooth animation.
@@ -191,12 +204,18 @@ export class BBMsgHistory extends HTMLElement {
         })
             .join('');
         this._lastAuthor = lastAuthor;
+        const loadingOverlay = this.hasAttribute('loading')
+            ? `<div class="loading-overlay" role="status" aria-label="Loading messages">
+          <div class="loading-spinner"></div>
+        </div>`
+            : '';
         this.shadowRoot.innerHTML = `
-      <style>${MAIN_STYLES}</style>
+      <style>${MAIN_STYLES}${LOADING_STYLES}</style>
       <div class="history" role="log" aria-live="polite" aria-label="Message history">
         ${messagesHtml}
       </div>
       ${buildScrollButtonHtml()}
+      ${loadingOverlay}
     `;
         requestAnimationFrame(() => {
             const container = this.shadowRoot.querySelector('.history');
@@ -217,10 +236,24 @@ export class BBMsgHistory extends HTMLElement {
         });
     }
     _renderEmpty() {
-        this.shadowRoot.innerHTML = `
-      <style>${EMPTY_STYLES}</style>
-      <div class="empty-state">No messages</div>
-    `;
+        const isLoading = this.hasAttribute('loading');
+        if (isLoading) {
+            // Show loading overlay with minimum height for better appearance
+            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>
+      `;
+        }
     }
     _setupScrollTracking(container, button) {
         const checkScrollPosition = () => {

package/dist/const/styles.d.ts

@@ -6,6 +6,10 @@ export declare const MAIN_STYLES: string;
  * Empty state styles
  */
 export declare const EMPTY_STYLES: string;
+/**
+ * Loading overlay styles with elegant spinner
+ */
+export declare const LOADING_STYLES: string;
 /**
  * Fallback styles for when custom elements are not supported
  */

package/dist/const/styles.js

@@ -444,6 +444,68 @@ export const EMPTY_STYLES = `
     font-family: inherit;
   }
 `;
+/**
+ * Loading overlay styles with elegant spinner
+ */
+export const LOADING_STYLES = `
+  .loading-overlay {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: rgba(255, 255, 255, 0.6);
+    backdrop-filter: blur(1px);
+    z-index: 20;
+    border-radius: 0.5rem;
+    min-height: 120px;
+  }
+
+  .loading-spinner {
+    width: 24px;
+    height: 24px;
+    border: 2px solid ${THEME.gray[200]};
+    border-top-color: ${THEME.gray[500]};
+    border-radius: 50%;
+    animation: spin 0.8s linear infinite;
+  }
+
+  @keyframes spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+
+  /* Dark mode support */
+  :host([theme="dark"]) .loading-overlay {
+    background: rgba(17, 24, 39, 0.6);
+  }
+
+  :host([theme="dark"]) .loading-spinner {
+    border-color: ${THEME.gray[700]};
+    border-top-color: ${THEME.gray[400]};
+  }
+
+  /* System dark mode preference */
+  @media (prefers-color-scheme: dark) {
+    :host .loading-overlay {
+      background: rgba(17, 24, 39, 0.6);
+    }
+
+    :host .loading-spinner {
+      border-color: ${THEME.gray[700]};
+      border-top-color: ${THEME.gray[400]};
+    }
+  }
+
+  /* Reduced motion */
+  @media (prefers-reduced-motion: reduce) {
+    .loading-spinner {
+      animation-duration: 1.5s;
+      opacity: 0.8;
+    }
+  }
+`;
 /**
  * Fallback styles for when custom elements are not supported
  */

package/package.json

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

package/src/component.ts

@@ -1,5 +1,5 @@
 import type { AuthorOptions, Message } from './types/index.js';
-import { MAIN_STYLES, EMPTY_STYLES } from './const/styles.js';
+import { EMPTY_STYLES, LOADING_STYLES, MAIN_STYLES } from './const/styles.js';
 import { parseMessages } from './utils/message-parser.js';
 import { resolveAuthorConfig } from './utils/author-resolver.js';
 import { setupTooltips } from './utils/tooltip.js';
@@ -14,7 +14,7 @@ export class BBMsgHistory extends HTMLElement {
   private _scrollButtonVisible = false;
 
   static get observedAttributes() {
-    return ['theme'];
+    return ['theme', 'loading'];
   }
 
   constructor() {
@@ -22,8 +22,10 @@ export class BBMsgHistory extends HTMLElement {
     this.attachShadow({ mode: 'open' });
   }
 
-  attributeChangedCallback() {
-    this.render();
+  attributeChangedCallback(name: string) {
+    if (name === 'theme' || name === 'loading') {
+      this.render();
+    }
   }
 
   /**
@@ -49,6 +51,18 @@ export class BBMsgHistory extends HTMLElement {
     return this;
   }
 
+  /**
+   * Show or hide the loading overlay.
+   *
+   * @example
+   * el.setLoading(true);  // Show loading animation
+   * el.setLoading(false); // Hide loading animation
+   */
+  setLoading(isLoading: boolean): this {
+    this.toggleAttribute('loading', isLoading);
+    return this;
+  }
+
   /**
    * Append a message to the history.
    * Automatically scrolls to the new message with smooth animation.
@@ -246,12 +260,19 @@ export class BBMsgHistory extends HTMLElement {
 
     this._lastAuthor = lastAuthor;
 
+    const loadingOverlay = this.hasAttribute('loading')
+      ? `<div class="loading-overlay" role="status" aria-label="Loading messages">
+          <div class="loading-spinner"></div>
+        </div>`
+      : '';
+
     this.shadowRoot!.innerHTML = `
-      <style>${MAIN_STYLES}</style>
+      <style>${MAIN_STYLES}${LOADING_STYLES}</style>
       <div class="history" role="log" aria-live="polite" aria-label="Message history">
         ${messagesHtml}
       </div>
       ${buildScrollButtonHtml()}
+      ${loadingOverlay}
     `;
 
     requestAnimationFrame(() => {
@@ -277,10 +298,24 @@ export class BBMsgHistory extends HTMLElement {
   }
 
   private _renderEmpty() {
-    this.shadowRoot!.innerHTML = `
-      <style>${EMPTY_STYLES}</style>
-      <div class="empty-state">No messages</div>
-    `;
+    const isLoading = this.hasAttribute('loading');
+
+    if (isLoading) {
+      // Show loading overlay with minimum height for better appearance
+      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>
+      `;
+    }
   }
 
   private _setupScrollTracking(container: HTMLElement, button: HTMLButtonElement): void {

package/src/const/styles.ts

@@ -447,6 +447,69 @@ export const EMPTY_STYLES = `
   }
 `;
 
+/**
+ * Loading overlay styles with elegant spinner
+ */
+export const LOADING_STYLES = `
+  .loading-overlay {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: rgba(255, 255, 255, 0.6);
+    backdrop-filter: blur(1px);
+    z-index: 20;
+    border-radius: 0.5rem;
+    min-height: 120px;
+  }
+
+  .loading-spinner {
+    width: 24px;
+    height: 24px;
+    border: 2px solid ${THEME.gray[200]};
+    border-top-color: ${THEME.gray[500]};
+    border-radius: 50%;
+    animation: spin 0.8s linear infinite;
+  }
+
+  @keyframes spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+
+  /* Dark mode support */
+  :host([theme="dark"]) .loading-overlay {
+    background: rgba(17, 24, 39, 0.6);
+  }
+
+  :host([theme="dark"]) .loading-spinner {
+    border-color: ${THEME.gray[700]};
+    border-top-color: ${THEME.gray[400]};
+  }
+
+  /* System dark mode preference */
+  @media (prefers-color-scheme: dark) {
+    :host .loading-overlay {
+      background: rgba(17, 24, 39, 0.6);
+    }
+
+    :host .loading-spinner {
+      border-color: ${THEME.gray[700]};
+      border-top-color: ${THEME.gray[400]};
+    }
+  }
+
+  /* Reduced motion */
+  @media (prefers-reduced-motion: reduce) {
+    .loading-spinner {
+      animation-duration: 1.5s;
+      opacity: 0.8;
+    }
+  }
+`;
+
 /**
  * Fallback styles for when custom elements are not supported
  */