@nyaruka/temba-components 0.165.0 → 0.166.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyaruka/temba-components",
-  "version": "0.165.0",
+  "version": "0.166.0",
   "description": "Web components to support rapidpro and related projects",
   "author": "Nyaruka <code@nyaruka.coim>",
   "main": "dist/index.js",

package/src/display/Chat.ts

@@ -11,6 +11,10 @@ const BATCH_TIME_WINDOW = 60 * 60 * 1000;
 const SCROLL_FETCH_BUFFER = 200; // pixels from top
 const MIN_FETCH_TIME = 250;
 
+// how long a typing indicator lives without a fresh pulse - stop events can
+// be missed (they're excluded from history recovery) so indicators decay
+const TYPING_TIMEOUT = 10 * 1000;
+
 const getUnsendableReasonMessage = (reason: string): string => {
   switch (reason) {
     case 'no_route':
@@ -80,6 +84,7 @@ export interface Msg {
   urn: string;
   direction: string;
   type: string;
+  external_id?: string;
   attachments: string[];
   unsendable_reason?:
     | 'no_route'
@@ -114,6 +119,28 @@ export interface MsgEvent extends ContactEvent {
   _logs_url?: string;
 }
 
+export interface TypingEvent extends ContactEvent {
+  direction?: string;
+}
+
+// typing indicators group and side with real messages: a user typing
+// (outgoing) behaves like a reply, a contact typing (incoming) like a
+// received message
+const effectiveType = (event: ContactEvent): string => {
+  if (event.type === 'typing_started') {
+    return (event as TypingEvent).direction === 'incoming'
+      ? 'msg_received'
+      : 'msg_created';
+  }
+  return event.type;
+};
+
+// identifies who a typing indicator belongs to - the user when stamped,
+// otherwise the contact
+const getTypingKey = (event: TypingEvent): string => {
+  return event._user?.uuid || 'contact';
+};
+
 // whether a message has nothing to show in its bubble (and isn't deleted)
 const isEmptyMsg = (event: MsgEvent): boolean =>
   !event._deleted &&
@@ -371,6 +398,43 @@ export class Chat extends RapidElement {
         color: #aaa;
       }
 
+      .typing-dots {
+        display: flex;
+        align-items: center;
+        gap: 4px;
+        padding: 4px 0;
+      }
+
+      .typing-dots span {
+        width: 7px;
+        height: 7px;
+        border-radius: 50%;
+        background: currentColor;
+        opacity: 0.4;
+        animation: typing-bounce 1.2s ease-in-out infinite;
+      }
+
+      .typing-dots span:nth-child(2) {
+        animation-delay: 0.15s;
+      }
+
+      .typing-dots span:nth-child(3) {
+        animation-delay: 0.3s;
+      }
+
+      @keyframes typing-bounce {
+        0%,
+        60%,
+        100% {
+          transform: translateY(0);
+          opacity: 0.4;
+        }
+        30% {
+          transform: translateY(-3px);
+          opacity: 1;
+        }
+      }
+
       .message-text {
         white-space: pre-wrap;
         margin-bottom: 0;
@@ -849,10 +913,24 @@ export class Chat extends RapidElement {
   private msgMap = new Map<string, ContactEvent>();
   private metadataCache = new Map<string, ContactEvent>();
 
+  // ephemeral typing indicators by author key - they live in msgMap and
+  // messageGroups like real messages (so they group and render normally)
+  // but are added and removed through setTyping / clearTyping
+  private typingEvents = new Map<string, TypingEvent>();
+  private typingTimeouts = new Map<string, number>();
+
   // bumped on reset so deferred addMessages work from before a reset is
   // discarded rather than re-merged into the fresh view
   private resetGeneration = 0;
 
+  public disconnectedCallback(): void {
+    super.disconnectedCallback();
+    // clear pending typing decay timers so no callback fires on a detached
+    // element (typingEvents/msgMap are left intact for a possible reconnect)
+    this.typingTimeouts.forEach((timeout) => window.clearTimeout(timeout));
+    this.typingTimeouts.clear();
+  }
+
   public firstUpdated(
     changed: PropertyValueMap<any> | Map<PropertyKey, unknown>
   ): void {
@@ -911,9 +989,21 @@ export class Chat extends RapidElement {
         const isScrolledAway =
           scrollableHeight > 0 && Math.abs(ele.scrollTop) > 50;
 
+        // a real message from someone typing replaces their indicator, and
+        // any remaining indicators re-float below the appended messages
+        if (append) {
+          this.clearTypingForAuthors(
+            newMessages.map((uuid) => this.msgMap.get(uuid))
+          );
+        }
+
         const grouped = this.groupMessages(newMessages);
         this.insertGroups(grouped, append);
 
+        if (append) {
+          this.refloatTyping();
+        }
+
         // show notification if new messages are appended and user is scrolled away from bottom
         // but not during search (searchHighlight is set)
         if (
@@ -986,6 +1076,115 @@ export class Chat extends RapidElement {
     return isNew;
   }
 
+  /**
+   * Shows a typing indicator for the event's author, appended to the
+   * newest messages so it groups with them. Repeat pulses from the same
+   * author just refresh the decay timer; without fresh pulses or an
+   * explicit clearTyping the indicator decays on its own.
+   */
+  public setTyping(event: TypingEvent) {
+    const key = getTypingKey(event);
+    const shown = this.typingEvents.get(key);
+    if (shown) {
+      // keep the indicator's timestamp fresh so a long-lived one doesn't
+      // drift across the grouping time window and split into its own group
+      shown.created_on = event.created_on;
+    } else {
+      this.typingEvents.set(key, event);
+      this.addMessage(event);
+      this.insertGroups(this.groupMessages([event.uuid]), true);
+    }
+
+    const existing = this.typingTimeouts.get(key);
+    if (existing) {
+      window.clearTimeout(existing);
+    }
+    this.typingTimeouts.set(
+      key,
+      window.setTimeout(() => this.removeTyping(key), TYPING_TIMEOUT)
+    );
+  }
+
+  /**
+   * Clears the typing indicator for the event's author, or all indicators
+   * when no event is given.
+   */
+  public clearTyping(event?: TypingEvent) {
+    if (event) {
+      this.removeTyping(getTypingKey(event));
+    } else {
+      for (const key of [...this.typingEvents.keys()]) {
+        this.removeTyping(key);
+      }
+    }
+  }
+
+  private removeTyping(key: string) {
+    const timeout = this.typingTimeouts.get(key);
+    if (timeout) {
+      window.clearTimeout(timeout);
+      this.typingTimeouts.delete(key);
+    }
+
+    const event = this.typingEvents.get(key);
+    if (event) {
+      this.typingEvents.delete(key);
+      this.removeEvent(event.uuid);
+    }
+  }
+
+  private removeEvent(uuid: string) {
+    this.msgMap.delete(uuid);
+    for (let i = 0; i < this.messageGroups.length; i++) {
+      const group = this.messageGroups[i];
+      const idx = group.messages.indexOf(uuid);
+      if (idx >= 0) {
+        group.messages.splice(idx, 1);
+        if (group.messages.length === 0) {
+          this.messageGroups.splice(i, 1);
+        }
+        break;
+      }
+    }
+    this.requestUpdate('messageGroups');
+  }
+
+  // an author's real message replaces their typing indicator
+  private clearTypingForAuthors(events: ContactEvent[]) {
+    for (const event of events) {
+      if (event.type === 'typing_started') {
+        continue;
+      }
+      const key = event._user?.uuid
+        ? event._user.uuid
+        : event.type === 'msg_received'
+          ? 'contact'
+          : null;
+      if (key && this.typingEvents.has(key)) {
+        this.removeTyping(key);
+      }
+    }
+  }
+
+  // re-appends active typing indicators so they always sit below the
+  // newest messages
+  private refloatTyping() {
+    if (this.typingEvents.size === 0) {
+      return;
+    }
+    const events = [...this.typingEvents.values()];
+    for (const event of events) {
+      this.removeEvent(event.uuid);
+    }
+    for (const event of events) {
+      this.addMessage(event);
+    }
+    this.insertGroups(
+      this.groupMessages(events.map((event) => event.uuid)),
+      true
+    );
+  }
+
   public messageExists(msg: ContactEvent): boolean {
     return this.msgMap.has(msg.uuid);
   }
@@ -1002,18 +1201,19 @@ export class Chat extends RapidElement {
     // for type equivalence, treat all non-message types as the same.
     // Notes are treated like messages so they group with other notes
     // only when type + author match (and split from non-note events).
+    const type1 = effectiveType(msg1);
+    const type2 = effectiveType(msg2);
     const isMsg1 =
-      msg1.type === 'msg_created' ||
-      msg1.type === 'msg_received' ||
-      msg1.type === 'ivr_created' ||
-      msg1.type === 'ticket_note_added';
+      type1 === 'msg_created' ||
+      type1 === 'msg_received' ||
+      type1 === 'ivr_created' ||
+      type1 === 'ticket_note_added';
     const isMsg2 =
-      msg2.type === 'msg_created' ||
-      msg2.type === 'msg_received' ||
-      msg2.type === 'ivr_created' ||
-      msg2.type === 'ticket_note_added';
-    const typeMatch =
-      isMsg1 && isMsg2 ? msg1.type === msg2.type : isMsg1 === isMsg2;
+      type2 === 'msg_created' ||
+      type2 === 'msg_received' ||
+      type2 === 'ivr_created' ||
+      type2 === 'ticket_note_added';
+    const typeMatch = isMsg1 && isMsg2 ? type1 === type2 : isMsg1 === isMsg2;
 
     // check time first - if BATCH_TIME_WINDOW has passed since last time_elapsed reason
     // compare the current message (msg1) against the last break point to detect
@@ -1233,17 +1433,18 @@ export class Chat extends RapidElement {
     const mostRecentId = msgIds[msgIds.length - 1];
     const currentMsg = this.msgMap.get(mostRecentId);
 
+    const currentType = effectiveType(currentMsg);
     const incoming = this.agent
-      ? currentMsg.type !== 'msg_received'
-      : currentMsg.type === 'msg_received';
+      ? currentType !== 'msg_received'
+      : currentType === 'msg_received';
 
     const name = currentMsg._user?.name;
 
     const isMessageType =
-      currentMsg.type === 'msg_received' ||
-      currentMsg.type === 'msg_created' ||
-      currentMsg.type === 'ivr_created' ||
-      currentMsg.type === 'ticket_note_added';
+      currentType === 'msg_received' ||
+      currentType === 'msg_created' ||
+      currentType === 'ivr_created' ||
+      currentType === 'ticket_note_added';
     const showAvatar =
       this.avatars && ((isMessageType && this.agent) || !incoming);
 
@@ -1255,7 +1456,7 @@ export class Chat extends RapidElement {
     // messages carry no `_user`, so first_name/last_name aren't available and
     // getFullName falls back to `name`); the fallback only applies when there
     // is no `_user` on the event.
-    const fromContact = currentMsg.type === 'msg_received' && !currentMsg._user;
+    const fromContact = currentType === 'msg_received' && !currentMsg._user;
     const avatarName = currentMsg._user
       ? currentMsg._user.name
       : fromContact
@@ -1340,10 +1541,11 @@ export class Chat extends RapidElement {
               const latestClass = index === msgIds.length - 1 ? 'latest' : '';
               const eventClass = msg._rendered ? 'is-event' : '';
               const noteClass = msg.type === 'ticket_note_added' ? 'note' : '';
+              const typingClass = msg.type === 'typing_started' ? 'typing' : '';
               const matchClass =
                 this.highlightMessageUuid === msg.uuid ? 'search-match' : '';
               return html`<div
-                class="row message ${statusClass} ${unsendableClass} ${deletedClass} ${emptyClass} ${latestClass} ${eventClass} ${noteClass} ${matchClass}"
+                class="row message ${statusClass} ${unsendableClass} ${deletedClass} ${emptyClass} ${latestClass} ${eventClass} ${noteClass} ${typingClass} ${matchClass}"
                 data-uuid=${msg.uuid || nothing}
               >
                 ${this.renderMessage(
@@ -1412,6 +1614,15 @@ export class Chat extends RapidElement {
       return this.renderNote(event as TicketEvent, name, isLast);
     }
 
+    if (event.type === 'typing_started') {
+      return html`<div class="bubble-wrap">
+        <div class="bubble">
+          ${name ? html`<div class="name">${name}</div>` : null}
+          <div class="typing-dots"><span></span><span></span><span></span></div>
+        </div>
+      </div>`;
+    }
+
     const message = event as MsgEvent;
 
     // safety check: if msg doesn't exist, return nothing
@@ -1521,6 +1732,9 @@ export class Chat extends RapidElement {
 
   public reset() {
     this.resetGeneration++;
+    this.typingTimeouts.forEach((timeout) => window.clearTimeout(timeout));
+    this.typingTimeouts.clear();
+    this.typingEvents.clear();
     this.msgMap.clear();
     this.metadataCache.clear();
     this.messageGroups = [];

package/src/interfaces.ts

@@ -18,6 +18,26 @@ export interface Language {
   name: string;
 }
 
+export interface Notification {
+  created_on: string;
+  type: string;
+  url: string;
+  is_seen: boolean;
+  export?: {
+    type: string;
+    num_records: number;
+  };
+  import?: {
+    type: string;
+    num_records: number;
+  };
+  incident?: {
+    type: string;
+    started_on: string;
+    ended_on?: string;
+  };
+}
+
 export interface Attachment {
   uuid: string;
   content_type: string;
@@ -468,6 +488,7 @@ export enum CustomEventType {
   Error = 'temba-error',
   Interrupt = 'temba-interrupt',
   Opened = 'temba-opened',
+  NotificationReceived = 'temba-notification',
   TicketUpdated = 'temba-ticket-updated',
   Moved = 'temba-moved',
   DateRangeChanged = 'temba-date-range-changed',

package/src/list/NotificationList.ts

@@ -1,31 +1,28 @@
-import { css, html, TemplateResult } from 'lit';
+import { css, html, PropertyValues, TemplateResult } from 'lit';
 import { TembaList } from './TembaList';
 import { Options } from '../display/Options';
 import { Icon } from '../Icons';
-
-interface Notification {
-  created_on: string;
-  type: string;
-  url: string;
-  is_seen: boolean;
-  export?: {
-    type: string;
-    num_records: number;
-  };
-  import?: {
-    type: string;
-    num_records: number;
-  };
-  incident?: {
-    type: string;
-    started_on: string;
-    ended_on?: string;
-  };
-}
+import { CustomEventType, Notification } from '../interfaces';
+import {
+  RealtimeSubscription,
+  subscribeToNotifications
+} from '../live/Realtime';
+import { deleteRequest } from '../utils';
 
 export class NotificationList extends TembaList {
   reverseRefresh = false;
   internalFocusDisabled = true;
+
+  // fed by socket publications instead of interval polling
+  protected pollingEnabled = false;
+
+  private realtimeSubscription: RealtimeSubscription = null;
+
+  // publications that arrived before the initial fetch completed - a direct
+  // prepend would be clobbered when the fetch lands, so they wait for it
+  private pendingPubs: Notification[] = [];
+  private fetchedOnce = false;
+  private subscribedOnce = false;
   static get styles() {
     return css`
       :host {
@@ -134,6 +131,119 @@ export class NotificationList extends TembaList {
     };
   }
 
+  public connectedCallback() {
+    super.connectedCallback();
+    this.realtimeSubscription = subscribeToNotifications(
+      (notification) => this.handleNotification(notification),
+      () => this.handleSubscribed()
+    );
+  }
+
+  public disconnectedCallback() {
+    super.disconnectedCallback();
+    if (this.realtimeSubscription) {
+      this.realtimeSubscription.unsubscribe();
+      this.realtimeSubscription = null;
+    }
+  }
+
+  public willUpdate(changed: PropertyValues): void {
+    super.willUpdate(changed);
+    if (changed.has('loading') && !this.loading) {
+      this.fetchedOnce = true;
+      const pending = this.pendingPubs;
+      this.pendingPubs = [];
+      pending.forEach((notification) => this.prependNotification(notification));
+    }
+  }
+
+  private handleNotification(notification: Notification) {
+    // ignore redeliveries of notifications we already have so e.g. the
+    // menu's unseen badge only lights for genuinely new ones
+    if (
+      this.items.some((item) => item.url === notification.url) ||
+      this.pendingPubs.some((item) => item.url === notification.url)
+    ) {
+      return;
+    }
+
+    // announce arrival, even mid-fetch - e.g. the menu's unseen badge
+    this.fireCustomEvent(CustomEventType.NotificationReceived, {
+      notification
+    });
+
+    if (this.loading || !this.fetchedOnce) {
+      this.pendingPubs.push(notification);
+    } else {
+      this.prependNotification(notification);
+    }
+  }
+
+  private prependNotification(notification: Notification) {
+    // dedupe by url (our valueKey) and prepend
+    this.items = [
+      notification,
+      ...this.items.filter((item) => item.url !== notification.url)
+    ];
+    this.mostRecentItem = notification;
+  }
+
+  /**
+   * Fires on every (re)subscribe including after reconnects. The initial
+   * endpoint fetch covers the first one regardless of which completes first,
+   * so only refetch page one on resubscribes, to catch anything missed
+   * while offline.
+   */
+  private handleSubscribed() {
+    if (this.subscribedOnce && this.fetchedOnce) {
+      this.refresh();
+    }
+    this.subscribedOnce = true;
+  }
+
+  // urls marked seen on the server but still shown bold for this viewing
+  private seenUrls = new Set<string>();
+
+  /**
+   * Marks everything currently unseen as seen on the server, without any
+   * refetching - the socket keeps our items current and seen state is fully
+   * known here. Items stay bold for the current viewing and unbold on the
+   * next call (e.g. the next popup open). Resolves false if the server
+   * didn't record it, in which case nothing advances and the next call
+   * retries.
+   */
+  public markSeen(): Promise<boolean> {
+    // unbold whatever was marked seen last time
+    if (this.seenUrls.size > 0) {
+      this.items = this.items.map((item) =>
+        this.seenUrls.has(item.url) ? { ...item, is_seen: true } : item
+      );
+    }
+
+    const unseen = this.items.filter((item) => !item.is_seen);
+    if (unseen.length === 0 || !this.endpoint) {
+      return Promise.resolve(true);
+    }
+
+    // only advance our seen state if the server actually recorded it,
+    // otherwise we'd unbold items the server still considers unseen
+    return deleteRequest(this.endpoint)
+      .then((response) => {
+        if (!response.ok) {
+          console.warn(
+            `failed marking notifications seen (${response.status})`
+          );
+          return false;
+        }
+        this.seenUrls = new Set(unseen.map((item) => item.url));
+        return true;
+      })
+      .catch((error) => {
+        console.warn('failed marking notifications seen', error);
+        return false;
+      });
+  }
+
   public renderHeader(): TemplateResult {
     return html`<div class="header">
       <temba-icon name="notification"></temba-icon>

package/src/list/TembaList.ts

@@ -68,6 +68,9 @@ export class TembaList extends RapidElement {
 
   reverseRefresh = true;
 
+  // subclasses that get realtime updates can opt out of interval polling
+  protected pollingEnabled = true;
+
   // our next page from our endpoint
   nextPage: string = null;
 
@@ -108,14 +111,17 @@ export class TembaList extends RapidElement {
 
   public connectedCallback() {
     super.connectedCallback();
-    this.refreshInterval = setInterval(() => {
-      if (!this.paused) {
-        this.refreshKey = 'default_' + new Date().getTime();
-      }
-    }, DEFAULT_REFRESH);
+    if (this.pollingEnabled) {
+      this.refreshInterval = setInterval(() => {
+        if (!this.paused) {
+          this.refreshKey = 'default_' + new Date().getTime();
+        }
+      }, DEFAULT_REFRESH);
+    }
   }
 
   public disconnectedCallback() {
+    super.disconnectedCallback();
     clearInterval(this.refreshInterval);
   }
 

package/src/list/TembaMenu.ts

@@ -787,17 +787,40 @@ export class TembaMenu extends ResizeElement {
     }
 
     this.loadItems(item);
-
-    // refresh any embedded lists
-    this.shadowRoot
-      .querySelectorAll('temba-notification-list')
-      .forEach((ele: NotificationList) => {
-        ele.refresh();
-      });
   }
 
   public refresh = debounce(this.doRefresh, 200);
 
+  /**
+   * Opening a popup with notifications in it marks them all seen - the badge
+   * clears now, the items unbold next open. No fetching; the socket keeps
+   * the list itself current.
+   */
+  private handlePopupOpened(event: CustomEvent, menuItem: MenuItem) {
+    const dropdown = event.currentTarget as HTMLElement;
+    const lists = dropdown.querySelectorAll('temba-notification-list');
+    if (lists.length === 0) {
+      return;
+    }
+
+    // clear the badge optimistically, restoring it if marking seen fails so
+    // the unseen indicator isn't silently lost
+    const bubble = menuItem.bubble;
+    if (bubble) {
+      menuItem.bubble = null;
+      this.requestUpdate('root');
+    }
+
+    lists.forEach((list: NotificationList) => {
+      list.markSeen().then((marked) => {
+        if (!marked && bubble && !menuItem.bubble) {
+          menuItem.bubble = bubble;
+          this.requestUpdate('root');
+        }
+      });
+    });
+  }
+
   // eslint-disable-next-line @typescript-eslint/no-empty-function
   private loadItems(item: MenuItem, event: MouseEvent = null) {
     if (item && item.endpoint) {
@@ -1111,6 +1134,13 @@ export class TembaMenu extends ResizeElement {
     if (menuItem.type === 'temba-notification-list') {
       return html`<temba-notification-list
         endpoint=${menuItem.href}
+        @temba-notification=${() => {
+          // light the unseen badge on our popup item as they arrive
+          if (parent && parent.bubble !== 'tomato') {
+            parent.bubble = 'tomato';
+            this.requestUpdate('root');
+          }
+        }}
       ></temba-notification-list>`;
     }
 
@@ -1254,7 +1284,11 @@ export class TembaMenu extends ResizeElement {
 
     if (menuItem.popup) {
       return html`
-        <temba-dropdown id="dd-${menuItem.id}">
+        <temba-dropdown
+          id="dd-${menuItem.id}"
+          @temba-opened=${(event: CustomEvent) =>
+            this.handlePopupOpened(event, menuItem)}
+        >
           <div slot="toggle">${item}</div>
 
           <div slot="dropdown">