@nyaruka/temba-components 0.168.0 → 0.169.0

package/package.json

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

package/src/display/ContactName.ts

@@ -1,7 +1,20 @@
-import { css, html, TemplateResult } from 'lit';
+import { css, html, PropertyValues, TemplateResult } from 'lit';
 import { property } from 'lit/decorators.js';
 import { RapidElement } from '../RapidElement';
+import { Contact, CustomEventType } from '../interfaces';
+import { Events } from '../events/eventRenderers';
+import { getDestinationURN } from '../live/ContactStoreElement';
+import { watchContact } from '../live/ContactWatch';
+import { RealtimeSubscription } from '../live/Realtime';
 
+/**
+ * A contact's name, optionally with the URN that will be used to message
+ * them. Given a contact uuid it manages itself: it registers interest in name
+ * events with the central contact watcher, which delivers the initial value
+ * and any live changes through the same handler - the component never fetches
+ * anything. Alternatively the name and urn can be set explicitly for static
+ * rendering (e.g. rows of a list that arrived in one fetch).
+ */
 export class ContactName extends RapidElement {
   @property({ type: String })
   name: string;
@@ -9,9 +22,25 @@ export class ContactName extends RapidElement {
   @property({ type: String })
   urn: string;
 
+  // when set, name and urn are kept live by the central contact watcher
+  @property({ type: String })
+  contact: string;
+
   @property({ type: Number, attribute: 'icon-size' })
   size = 20;
 
+  private watch: RealtimeSubscription = null;
+  private watchedContact: string = null;
+
+  // the contact the name and urn on screen came from - only what we put there
+  // is ours to clear, and only when we're pointed somewhere else
+  private displayedContact: string = null;
+
+  // the contact behind a refresh notification we've already queued - a name
+  // and a urn change arrive as separate deliveries, as does a burst of live
+  // events, so the notification is coalesced into a microtask
+  private pendingRefresh: Contact = null;
+
   static get styles() {
     return css`
       :host {
@@ -34,6 +63,99 @@ export class ContactName extends RapidElement {
       }
     `;
   }
+
+  public connectedCallback(): void {
+    super.connectedCallback();
+    this.syncWatch();
+  }
+
+  public disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.syncWatch();
+  }
+
+  public willUpdate(changed: PropertyValues): void {
+    super.willUpdate(changed);
+    if (changed.has('contact')) {
+      this.syncWatch();
+    }
+  }
+
+  /**
+   * Keeps our watch in sync with the contact we're pointed at, clearing the
+   * previous contact's values when we switch contacts on the page. Explicitly
+   * set name/urn never pass through here since they involve no watch.
+   */
+  private syncWatch() {
+    const target = (this.isConnected && this.contact) || null;
+    if (target === this.watchedContact) {
+      return;
+    }
+
+    if (this.watch) {
+      this.watch.unsubscribe();
+      this.watch = null;
+    }
+
+    // only values we put there are ours to clear - a name and urn supplied
+    // alongside the contact render until the watcher has something better.
+    // Leaving the DOM isn't a switch, and blanking there would flash empty
+    // and refetch when we're only being moved - but a swap made while we were
+    // detached is, so compare against the contact on screen rather than the
+    // one we were last watching
+    if (
+      this.isConnected &&
+      this.displayedContact &&
+      this.displayedContact !== target
+    ) {
+      this.name = null;
+      this.urn = null;
+      this.displayedContact = null;
+    }
+    this.watchedContact = target;
+
+    if (target) {
+      this.watch = watchContact(
+        target,
+        [Events.CONTACT_NAME_CHANGED, Events.CONTACT_URNS_CHANGED],
+        (event, contact) => this.handleContactEvent(event, contact)
+      );
+    }
+  }
+
+  private handleContactEvent(event: any, contact: Contact) {
+    if (contact) {
+      // the watcher keeps the contact current, so it's authoritative whether
+      // this delivery is an event or an initial value. Anon workspaces have
+      // no names, show the contact's ref instead
+      this.name = contact.name || contact.ref || null;
+
+      // show the URN that will be used when messaging the contact, falling
+      // back to their highest priority URN if none are sendable
+      const urn = getDestinationURN(contact) || (contact.urns || [])[0] || null;
+      this.urn = urn ? `${urn.scheme}:${urn.display || urn.path}` : null;
+      this.displayedContact = this.watchedContact;
+      this.fireRefreshed(contact);
+    } else if (event && event.type === Events.CONTACT_NAME_CHANGED) {
+      // a live event can outrun the initial fetch - show the name we have
+      this.name = event.name || null;
+      this.displayedContact = this.watchedContact;
+    }
+  }
+
+  private fireRefreshed(contact: Contact) {
+    if (!this.pendingRefresh) {
+      Promise.resolve().then(() => {
+        const refreshed = this.pendingRefresh;
+        this.pendingRefresh = null;
+        if (refreshed) {
+          this.fireCustomEvent(CustomEventType.Refreshed, { data: refreshed });
+        }
+      });
+    }
+    this.pendingRefresh = contact;
+  }
+
   public render(): TemplateResult {
     const urn = this.urn
       ? html`<temba-urn size=${this.size} urn=${this.urn}></temba-urn>`

package/src/list/ContactList.ts

@@ -79,6 +79,8 @@ export class ContactList extends ContentList<Contact> {
         labelsEndpoint: '/api/v2/groups.json?manual_only=1',
         labelsKey: 'groups'
       },
+      // Archive trails the reversible actions; Delete, when offered,
+      // always goes last.
       { key: 'archive', label: 'Archive', icon: Icon.archive },
       { key: 'delete', label: 'Delete', icon: Icon.delete, destructive: true }
     ];

package/src/list/ContentList.ts

@@ -214,7 +214,9 @@ export class ContentList<T = any> extends RapidElement {
          the select-all checkbox — rather than replacing the page header.
          Positioned in the table-frame (not the scrolling table) so it
          stays put horizontally, with an opaque header-tint background to
-         hide the labels underneath, above the sticky header (z 2/3). */
+         hide the labels underneath, above every header layer — pinned
+         header cells reach z 5 (see tr.header th.pinned), so the bar
+         sits at 6 to cover them too. */
       .bulk-bar {
         position: absolute;
         top: 0;
@@ -225,7 +227,7 @@ export class ContentList<T = any> extends RapidElement {
         left: var(--cl-firstcol-left, 44px);
         right: var(--cl-scrollbar-w, 0px);
         height: var(--cl-header-height, 36px);
-        z-index: 4;
+        z-index: 6;
         display: flex;
         align-items: center;
         gap: 4px;
@@ -567,8 +569,10 @@ export class ContentList<T = any> extends RapidElement {
 
       /* The header row sticks to the top of the scroll frame so the
          column labels stay put while the rows scroll under them.
-         z-index 2 lifts it above the body; a pinned header cell
-         needs 3 to also clear the body's pinned column (z-index 1). */
+         z-index 2 lifts it above the body; a pinned header cell needs
+         more to also clear the body's pinned column (z-index 1) and the
+         resize-handle layers (z 4) — but must stay under the bulk-action
+         bar (z 6), which overlays the whole header row on selection. */
       tr.header th {
         height: 36px;
         vertical-align: middle;

package/src/list/MsgList.ts

@@ -118,11 +118,13 @@ export class MsgList extends ContentList<Msg> {
         resizable: true
       },
       { key: 'text', label: 'Message', grow: true },
+      // Sent is deliberately not resizable: it's the last column, so its
+      // only possible handle would sit on the table's outer edge (Message
+      // is the grow column and owns the boundary between them).
       {
         key: 'created_on',
         label: 'Sent',
-        align: 'right',
-        resizable: true
+        align: 'right'
       }
     ];
     this.bulkActions = [
@@ -132,6 +134,8 @@ export class MsgList extends ContentList<Msg> {
         icon: Icon.label,
         labelsEndpoint: '/api/v2/labels.json'
       },
+      // Archive trails the reversible actions; Delete, when offered,
+      // always goes last.
       { key: 'archive', label: 'Archive', icon: Icon.archive },
       { key: 'delete', label: 'Delete', icon: Icon.delete, destructive: true }
     ];

package/src/live/ContactChat.ts

@@ -74,6 +74,12 @@ interface SearchResult {
 }
 
 export class ContactChat extends ContactStoreElement {
+  // we run our own firehose subscription below (history rendering, typing,
+  // ephemeral state) with its own contact/ticket channel choreography, so we
+  // opt out of the central watcher entirely - our data loads and syncs
+  // through the store as before
+  protected watchTypes: string[] = null;
+
   public static get styles() {
     return css`
       ${designTokens}

package/src/live/ContactDetails.ts

@@ -1,13 +1,14 @@
 import { css, html, PropertyValues, TemplateResult } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { Icon } from '../Icons';
-import { CustomEventType, Group, URN } from '../interfaces';
+import { Contact, CustomEventType, Group, URN } from '../interfaces';
 import { getLanguageName } from '../languages';
 import { capitalize, WebResponse } from '../utils';
 import { Select } from '../form/select/Select';
 import { TextInput } from '../form/TextInput';
 import { ContactFieldEditor } from './ContactFieldEditor';
 import { ContactStoreElement, getDestinationURN } from './ContactStoreElement';
+import { Events } from '../events/eventRenderers';
 
 interface Option {
   name: string;
@@ -22,6 +23,16 @@ const STATUS_OPTIONS: Option[] = [
 ];
 
 export class ContactDetails extends ContactStoreElement {
+  // the contact state we render - live changes to any of these reach us
+  // through the central watcher
+  protected watchTypes = [
+    Events.CONTACT_NAME_CHANGED,
+    Events.CONTACT_URNS_CHANGED,
+    Events.CONTACT_LANGUAGE_CHANGED,
+    Events.CONTACT_STATUS_CHANGED,
+    Events.CONTACT_GROUPS_CHANGED
+  ];
+
   @property({ type: Boolean })
   editable = false;
 
@@ -430,6 +441,26 @@ export class ContactDetails extends ContactStoreElement {
     }
   }
 
+  /**
+   * A watcher delivery carries server state from before the writes we still
+   * have in flight, so keep our own value for anything mid-save - the save
+   * itself applies the server's version when it lands.
+   */
+  protected mergeWatchedContact(contact: Contact, previous: Contact): Contact {
+    if (!previous || this.fieldSaveGenerations.size === 0) {
+      return contact;
+    }
+
+    const merged = { ...contact };
+    this.fieldSaveGenerations.forEach((generation, field) => {
+      if (field in previous) {
+        const value = previous[field];
+        merged[field] = Array.isArray(value) ? [...value] : value;
+      }
+    });
+    return merged;
+  }
+
   public willUpdate(changed: PropertyValues): void {
     if (changed.has('contact') || changed.has('endpoint')) {
       const url = this.contact ? `${this.endpoint}${this.contact}` : null;

package/src/live/ContactFields.ts

@@ -10,11 +10,16 @@ import { getClasses, postJSON } from '../utils';
 import { ContactFieldEditor } from './ContactFieldEditor';
 import { ContactStoreElement } from './ContactStoreElement';
 import { Checkbox } from '../form/Checkbox';
-import { ContactField, CustomEventType } from '../interfaces';
+import { Contact, ContactField, CustomEventType } from '../interfaces';
+import { Events } from '../events/eventRenderers';
 
 const MIN_FOR_FILTER = 10;
 
 export class ContactFields extends ContactStoreElement {
+  // we render field values, so field changes are the only events we need -
+  // the central watcher hands us a refetched contact when they happen
+  protected watchTypes = [Events.CONTACT_FIELD_CHANGED];
+
   static get styles() {
     return css`
       .field {
@@ -154,6 +159,34 @@ export class ContactFields extends ContactStoreElement {
     );
   }
 
+  /**
+   * A watcher delivery carries server state from before an edit the user is
+   * still making, so keep the value we already have for any field whose
+   * editor is dirty - rebinding it would drop what they typed.
+   */
+  protected mergeWatchedContact(contact: Contact, previous: Contact): Contact {
+    if (!previous || !previous.fields) {
+      return contact;
+    }
+
+    const editors = Array.from(
+      this.shadowRoot?.querySelectorAll('temba-contact-field') || []
+    ) as ContactFieldEditor[];
+    const editing = editors.filter(
+      (editor) => editor.dirty && editor.key in previous.fields
+    );
+
+    if (editing.length === 0) {
+      return contact;
+    }
+
+    const fields = { ...contact.fields };
+    editing.forEach((editor) => {
+      fields[editor.key] = previous.fields[editor.key];
+    });
+    return { ...contact, fields };
+  }
+
   public willUpdate(changed: PropertyValues): void {
     super.willUpdate(changed);
     if (

package/src/live/ContactNotepad.ts

@@ -6,6 +6,10 @@ import { ContactNote, CustomEventType } from '../interfaces';
 import { designTokens } from '../styles/designTokens';
 
 export class ContactNotepad extends ContactStoreElement {
+  // notes have no contact events - an empty interest list still receives
+  // eventless deliveries (initial values, refetches and page-local edits)
+  protected watchTypes: string[] = [];
+
   @property({ type: Object, attribute: false })
   note: ContactNote;
 
@@ -116,6 +120,10 @@ export class ContactNotepad extends ContactStoreElement {
   private resizer: ResizeObserver;
   private lastWidth = 0;
 
+  // the contact our current note was taken off - an edit only belongs to the
+  // contact it was typed against, so a switch to another one re-derives
+  private noteContact: string = null;
+
   public connectedCallback(): void {
     super.connectedCallback();
     // text rewraps when our width changes (browser resize, layout mode
@@ -163,26 +171,53 @@ export class ContactNotepad extends ContactStoreElement {
       '.notepad'
     ) as HTMLInputElement;
     const note = notepad.value;
+    // our own write is the one delivery the dirty guard below holds out for,
+    // so take the note from it once it lands
     this.postChanges({ note }).then(() => {
-      this.markClean();
+      this.syncNote();
     });
   }
 
+  // takes the newest note off the contact, copied so editing it never writes
+  // into the contact data we share with everything else
+  private syncNote() {
+    this.noteContact = this.data?.uuid || null;
+    this.note =
+      this.data?.notes?.length > 0
+        ? { ...this.data.notes[this.data.notes.length - 1] }
+        : null;
+    this.fireCustomEvent(CustomEventType.DetailsChanged, {
+      count: this.note && this.note.text.length > 0 ? 1 : 0,
+      dirty: false
+    });
+    this.markClean();
+
+    // lit dirty checks the .value binding against the last string it wrote,
+    // not what's actually in the textarea, so re-deriving an unchanged note
+    // wouldn't take the user's typing back off - write the note through
+    const notepad = this.shadowRoot?.querySelector(
+      '.notepad'
+    ) as HTMLTextAreaElement;
+    if (notepad) {
+      notepad.value = this.note ? this.note.text : '';
+    }
+  }
+
   protected updated(
     changes: PropertyValueMap<any> | Map<PropertyKey, unknown>
   ): void {
     super.updated(changes);
 
-    if (changes.has('data')) {
-      this.note =
-        this.data?.notes?.length > 0
-          ? { ...this.data.notes[this.data.notes.length - 1] }
-          : null;
-      this.fireCustomEvent(CustomEventType.DetailsChanged, {
-        count: this.note && this.note.text.length > 0 ? 1 : 0,
-        dirty: false
-      });
-      this.markClean();
+    // the central watcher re-delivers the contact on any activity, not just
+    // note changes, so a delivery mid-edit would otherwise drop what the user
+    // has typed - hold the note until the edit is saved or abandoned. Only
+    // for the contact it was typed against though: on a switch the edit goes
+    // with the contact we left, so the new one's note lands right away
+    if (
+      changes.has('data') &&
+      (!this.dirty || (this.data?.uuid || null) !== this.noteContact)
+    ) {
+      this.syncNote();
     }
 
     if (changes.has('note') || changes.has('data')) {

package/src/live/ContactStoreElement.ts

@@ -1,7 +1,14 @@
 import { PropertyValues } from 'lit';
 import { property } from 'lit/decorators.js';
-import { Contact, Group, URN } from '../interfaces';
+import { Contact, CustomEventType, Group, URN } from '../interfaces';
 import { EndpointMonitorElement } from '../store/EndpointMonitorElement';
+import {
+  CONTACT_STATE_TYPES,
+  refreshContact,
+  updateContact,
+  watchContact
+} from './ContactWatch';
+import { RealtimeSubscription } from './Realtime';
 
 /**
  * Returns the URN that will be used to message the given contact — URNs are
@@ -18,6 +25,15 @@ export class ContactStoreElement extends EndpointMonitorElement {
   @property({ type: Object, attribute: false })
   data: Contact;
 
+  // the contact events this component registers interest in with the central
+  // watcher - subclasses narrow this to what they actually render. An empty
+  // list still receives eventless deliveries (initial values and refetches);
+  // null opts out of watching entirely
+  protected watchTypes: string[] = CONTACT_STATE_TYPES;
+
+  private watch: RealtimeSubscription = null;
+  private watchedContact: string = null;
+
   // Resolve each URN against a channel while retaining the user's priority
   // order. Consumers can select the first channel-backed URN for messaging.
   @property({ type: String })
@@ -70,6 +86,35 @@ export class ContactStoreElement extends EndpointMonitorElement {
     // make sure contact data is properly prepped
     this.data = this.prepareData([contact]);
     this.store.updateCache(`${this.endpoint}${contactId}`, this.data);
+
+    // sync every watcher on the page with the change immediately, without
+    // waiting for it to echo back over the socket
+    if (this.data) {
+      updateContact(this.data.uuid, this.data);
+    }
+  }
+
+  /**
+   * Refetches the contact. When watched we also go through the central
+   * watcher so every watcher on the page gets the fresh contact, not just us,
+   * while the store fetch keeps the cache fresh for the components that read
+   * it without watching. Two fetches for what is a rare manual operation.
+   */
+  public refresh(): void {
+    if (this.watchedContact) {
+      refreshContact(this.watchedContact);
+    }
+    super.refresh();
+  }
+
+  public connectedCallback(): void {
+    super.connectedCallback();
+    this.syncWatch();
+  }
+
+  public disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.syncWatch();
   }
 
   public willUpdate(changed: PropertyValues): void {
@@ -81,7 +126,64 @@ export class ContactStoreElement extends EndpointMonitorElement {
       } else {
         this.url = null;
       }
+      this.syncWatch();
     }
     super.willUpdate(changed);
   }
+
+  // keeps our registration with the central watcher in sync with the
+  // contact we're pointed at
+  private syncWatch() {
+    const target =
+      (this.isConnected && this.watchTypes && this.contact) || null;
+    if (target === this.watchedContact) {
+      return;
+    }
+
+    if (this.watch) {
+      this.watch.unsubscribe();
+      this.watch = null;
+    }
+    this.watchedContact = target;
+
+    if (target) {
+      this.watch = watchContact(target, this.watchTypes, (event, contact) =>
+        this.handleWatchedContact(event, contact)
+      );
+    }
+  }
+
+  /**
+   * A delivery from the central watcher - an event we registered interest in
+   * or an eventless delivery carrying initial or refetched values. Either
+   * way the contact is current, so it simply becomes our data.
+   */
+  protected handleWatchedContact(event: any, contact: Contact) {
+    if (contact && contact.uuid === this.watchedContact) {
+      const previous = this.data;
+      // fresh identity so change detection sees every delivery, copying the
+      // parts prepareData mutates so we never write into the registry's
+      // snapshot
+      const copy = {
+        ...contact,
+        groups: (contact.groups || []).map((group) => ({ ...group })),
+        fields: { ...contact.fields }
+      };
+      this.data = this.prepareData(this.mergeWatchedContact(copy, previous));
+      this.fireCustomEvent(CustomEventType.Refreshed, {
+        data: this.data,
+        previous
+      });
+    }
+  }
+
+  /**
+   * Lets subclasses keep values they have a write in flight for. A delivery
+   * carries server state that predates our own unsaved edits, so anything
+   * mid-save would otherwise flip back to its old value until the write
+   * lands. Returns the contact to become our data.
+   */
+  protected mergeWatchedContact(contact: Contact, _previous: Contact): Contact {
+    return contact;
+  }
 }