@bbki.ng/bb-msg-history 0.6.0 → 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/authors.js

@@ -6,7 +6,7 @@ import { THEME } from './theme.js';
 export const AUTHOR_CONFIG = {
     'bbki.ng': {
         avatar: `<svg xmlns="http://www.w3.org/2000/svg" width="28" height="28" viewBox="0 0 48 48" fill="none"><path d="M29.1152 21.3106C32.0605 21.3106 34.4481 18.9101 34.4481 15.9489V24.6457C34.4481 25.7585 33.5508 26.6607 32.444 26.6607H15.1207C14.0138 26.6607 13.1166 25.7585 13.1166 24.6457V15.9489C13.1166 18.9101 15.5042 21.3106 18.4494 21.3106C21.3947 21.3106 23.7823 18.9101 23.7823 15.9489C23.7823 18.9101 26.17 21.3106 29.1152 21.3106Z" fill="${THEME.gray[400]}"/><path d="M23.7823 15.9373L23.7823 15.9489C23.7823 15.9451 23.7823 15.9412 23.7823 15.9373Z" fill="${THEME.gray[400]}"/><path d="M23.1143 28.004C23.1205 30.9598 25.5057 33.3541 28.4472 33.3541C31.3886 33.3541 33.7738 30.9598 33.7801 28.004H23.1143Z" fill="${THEME.gray[400]}"/><path d="M13.7846 28.004C13.7846 28.0079 13.7846 28.0117 13.7846 28.0156C13.7908 30.9714 16.1761 33.3657 19.1175 33.3657C22.0589 33.3657 24.4442 30.9714 24.4504 28.0156H13.7846V28.004Z" fill="${THEME.gray[400]}"/><path d="M14.4527 15.9373C14.4527 16.6792 13.8545 17.2806 13.1166 17.2806C12.3786 17.2806 11.7805 16.6792 11.7805 15.9373C11.7805 15.1954 12.3786 14.594 13.1166 14.594C13.8545 14.594 14.4527 15.1954 14.4527 15.9373Z" fill="${THEME.gray[400]}"/><path d="M25.1184 15.2657C25.1184 16.0076 24.5202 16.609 23.7823 16.609C23.0444 16.609 22.4462 16.0076 22.4462 15.2657C22.4462 14.5238 23.0444 13.9224 23.7823 13.9224C24.5202 13.9224 25.1184 14.5238 25.1184 15.2657Z" fill="${THEME.gray[400]}"/><path d="M35.7842 15.9373C35.7842 16.6792 35.186 17.2806 34.4481 17.2806C33.7102 17.2806 33.112 16.6792 33.112 15.9373C33.112 15.1954 33.7102 14.594 34.4481 14.594C35.186 14.594 35.7842 15.1954 35.7842 15.9373Z" fill="${THEME.gray[400]}"/></svg>`,
-        bubbleColor: THEME.gray[100],
+        bubbleColor: THEME.gray[200],
         textColor: THEME.gray[900],
         side: 'right',
     },

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

@@ -193,6 +193,7 @@ export const MAIN_STYLES = `
     display: flex;
     flex-direction: column;
     position: relative;
+    padding-bottom: 12px;
   }
 
   /* Timestamp styles */
@@ -204,7 +205,7 @@ export const MAIN_STYLES = `
     visibility: hidden;
     transition: opacity 0.2s ease, visibility 0.2s ease;
     white-space: nowrap;
-    bottom: -12px;
+    bottom: 1px;
     line-height: 1;
     pointer-events: none;
   }
@@ -245,6 +246,15 @@ export const MAIN_STYLES = `
     color: ${THEME.gray[900]};
   }
 
+  /* Subsequent messages - all corners rounded */
+  .msg-row--subsequent .msg-bubble--left {
+    border-bottom-left-radius: 1rem;
+  }
+
+  .msg-row--subsequent .msg-bubble--right {
+    border-bottom-right-radius: 1rem;
+  }
+
   /* Empty state */
   .empty-state {
     text-align: center;
@@ -434,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/dist/utils/message-builder.js

@@ -43,10 +43,10 @@ export function buildMessageRowHtml(author, text, config, isSubsequent, timestam
       ${side === 'left' ? avatarHtml : ''}
 
       <div class="msg-content">
-        ${timestampHtml}
         <div class="msg-bubble msg-bubble--${side}"${styleAttr}>
           ${escapeHtml(text)}
         </div>
+        ${timestampHtml}
       </div>
 
       ${side === 'right' ? avatarHtml : ''}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bbki.ng/bb-msg-history",
-  "version": "0.6.0",
+  "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/authors.ts

@@ -8,7 +8,7 @@ import { THEME } from './theme.js';
 export const AUTHOR_CONFIG: Record<string, Omit<AuthorConfig, 'isCustomAvatar'>> = {
   'bbki.ng': {
     avatar: `<svg xmlns="http://www.w3.org/2000/svg" width="28" height="28" viewBox="0 0 48 48" fill="none"><path d="M29.1152 21.3106C32.0605 21.3106 34.4481 18.9101 34.4481 15.9489V24.6457C34.4481 25.7585 33.5508 26.6607 32.444 26.6607H15.1207C14.0138 26.6607 13.1166 25.7585 13.1166 24.6457V15.9489C13.1166 18.9101 15.5042 21.3106 18.4494 21.3106C21.3947 21.3106 23.7823 18.9101 23.7823 15.9489C23.7823 18.9101 26.17 21.3106 29.1152 21.3106Z" fill="${THEME.gray[400]}"/><path d="M23.7823 15.9373L23.7823 15.9489C23.7823 15.9451 23.7823 15.9412 23.7823 15.9373Z" fill="${THEME.gray[400]}"/><path d="M23.1143 28.004C23.1205 30.9598 25.5057 33.3541 28.4472 33.3541C31.3886 33.3541 33.7738 30.9598 33.7801 28.004H23.1143Z" fill="${THEME.gray[400]}"/><path d="M13.7846 28.004C13.7846 28.0079 13.7846 28.0117 13.7846 28.0156C13.7908 30.9714 16.1761 33.3657 19.1175 33.3657C22.0589 33.3657 24.4442 30.9714 24.4504 28.0156H13.7846V28.004Z" fill="${THEME.gray[400]}"/><path d="M14.4527 15.9373C14.4527 16.6792 13.8545 17.2806 13.1166 17.2806C12.3786 17.2806 11.7805 16.6792 11.7805 15.9373C11.7805 15.1954 12.3786 14.594 13.1166 14.594C13.8545 14.594 14.4527 15.1954 14.4527 15.9373Z" fill="${THEME.gray[400]}"/><path d="M25.1184 15.2657C25.1184 16.0076 24.5202 16.609 23.7823 16.609C23.0444 16.609 22.4462 16.0076 22.4462 15.2657C22.4462 14.5238 23.0444 13.9224 23.7823 13.9224C24.5202 13.9224 25.1184 14.5238 25.1184 15.2657Z" fill="${THEME.gray[400]}"/><path d="M35.7842 15.9373C35.7842 16.6792 35.186 17.2806 34.4481 17.2806C33.7102 17.2806 33.112 16.6792 33.112 15.9373C33.112 15.1954 33.7102 14.594 34.4481 14.594C35.186 14.594 35.7842 15.1954 35.7842 15.9373Z" fill="${THEME.gray[400]}"/></svg>`,
-    bubbleColor: THEME.gray[100],
+    bubbleColor: THEME.gray[200],
     textColor: THEME.gray[900],
     side: 'right',
   },

package/src/const/styles.ts

@@ -194,6 +194,7 @@ export const MAIN_STYLES = `
     display: flex;
     flex-direction: column;
     position: relative;
+    padding-bottom: 12px;
   }
 
   /* Timestamp styles */
@@ -205,7 +206,7 @@ export const MAIN_STYLES = `
     visibility: hidden;
     transition: opacity 0.2s ease, visibility 0.2s ease;
     white-space: nowrap;
-    bottom: -12px;
+    bottom: 1px;
     line-height: 1;
     pointer-events: none;
   }
@@ -246,6 +247,15 @@ export const MAIN_STYLES = `
     color: ${THEME.gray[900]};
   }
 
+  /* Subsequent messages - all corners rounded */
+  .msg-row--subsequent .msg-bubble--left {
+    border-bottom-left-radius: 1rem;
+  }
+
+  .msg-row--subsequent .msg-bubble--right {
+    border-bottom-right-radius: 1rem;
+  }
+
   /* Empty state */
   .empty-state {
     text-align: center;
@@ -437,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
  */

package/src/utils/message-builder.ts

@@ -58,10 +58,10 @@ export function buildMessageRowHtml(
       ${side === 'left' ? avatarHtml : ''}
 
       <div class="msg-content">
-        ${timestampHtml}
         <div class="msg-bubble msg-bubble--${side}"${styleAttr}>
           ${escapeHtml(text)}
         </div>
+        ${timestampHtml}
       </div>
 
       ${side === 'right' ? avatarHtml : ''}