@nyaruka/temba-components 0.168.1 → 0.170.0

package/package.json

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

package/src/display/Chat.ts

@@ -2,7 +2,7 @@ import { TemplateResult, html, nothing, PropertyValueMap, css } from 'lit';
 import { property } from 'lit/decorators.js';
 import { repeat } from 'lit/directives/repeat.js';
 import { RapidElement } from '../RapidElement';
-import { CustomEventType } from '../interfaces';
+import { CustomEventType, QuickReply } from '../interfaces';
 import { TicketEvent } from '../events';
 import { renderEventSummary } from '../events/eventRenderers';
 import { DEFAULT_AVATAR } from '../webchat/assets';
@@ -81,7 +81,7 @@ interface User extends ObjectReference {
 export interface Msg {
   text: string;
   channel: ObjectReference;
-  quick_replies: string[];
+  quick_replies: (string | QuickReply)[];
   urn: string;
   direction: string;
   type: string;

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/display/Dropdown.ts

@@ -9,9 +9,6 @@ import { styleMap } from 'lit-html/directives/style-map.js';
 export class Dropdown extends RapidElement {
   static get styles() {
     return css`
-      :host {
-      }
-
       .wrapper {
         position: relative;
       }
@@ -25,9 +22,6 @@ export class Dropdown extends RapidElement {
         overflow: auto;
       }
 
-      .dropdown:focus {
-      }
-
       .dropdown.dormant {
         height: 0;
         overflow: hidden;
@@ -35,7 +29,16 @@ export class Dropdown extends RapidElement {
 
       .dropdown {
         position: fixed;
-        z-index: 2;
+        /* open popups sit above floating windows (simulator, 5000) and
+           other page chrome, but below dialogs and toasts (10000);
+           temba-content-menu mirrors this value on its temba-dropdown
+           flex item (see ContentMenu.ts) */
+        z-index: 9000;
+        /* the dormant (height: 0) rule is applied 250ms after close, so
+           until then this stays a laid-out, invisible fixed box at
+           z-index 9000 over whatever it was covering — ignore pointer
+           events unless we're actually open */
+        pointer-events: none;
         padding: 0;
         opacity: 0;
         border-radius: calc(var(--curvature) * 1.5);
@@ -67,6 +70,7 @@ export class Dropdown extends RapidElement {
 
       .open .dropdown {
         opacity: 1;
+        pointer-events: auto;
         transform: translateY(0.5em) scale(1);
       }
 

package/src/display/Options.ts

@@ -338,6 +338,13 @@ export class Options extends RapidElement {
   @property({ attribute: false })
   renderOption: { (option: any, selected: boolean): TemplateResult };
 
+  // renders between rows (and above the first) when the data crosses a
+  // grouping boundary - the result sits outside the option rows so it never
+  // picks up their hover or selection treatment. Returning null means the
+  // rows aren't a boundary and nothing is rendered between them.
+  @property({ attribute: false })
+  renderDivider: { (prev: any, option: any): TemplateResult | null };
+
   @property({ attribute: false })
   renderOptionName: { (option: any, selected: boolean): TemplateResult };
 
@@ -816,20 +823,26 @@ export class Options extends RapidElement {
           <div class="${classesInner}" style=${styleMap(optionsStyle)}>
             ${options.length > 0
               ? options.map((option, index) => {
-                  return html`<div
-                    data-option-index="${index}"
-                    @mousemove=${this.handleMouseMove}
-                    @mousedown=${this.handleOptionClick}
-                    class="option ${index === this.cursorIndex &&
-                    !this.internalFocusDisabled
-                      ? 'focused'
-                      : ''}"
-                  >
-                    ${this.resolvedRenderOption(
-                      option,
-                      index === this.cursorIndex
-                    )}
-                  </div>`;
+                  return html`${this.renderDivider
+                      ? this.renderDivider(
+                          index > 0 ? options[index - 1] : null,
+                          option
+                        )
+                      : null}
+                    <div
+                      data-option-index="${index}"
+                      @mousemove=${this.handleMouseMove}
+                      @mousedown=${this.handleOptionClick}
+                      class="option ${index === this.cursorIndex &&
+                      !this.internalFocusDisabled
+                        ? 'focused'
+                        : ''}"
+                    >
+                      ${this.resolvedRenderOption(
+                        option,
+                        index === this.cursorIndex
+                      )}
+                    </div>`;
                 })
               : this.visible && this.showEmptyMessage
                 ? html`<div

package/src/display/TembaDate.ts

@@ -1,4 +1,4 @@
-import { css, html, PropertyValues, TemplateResult } from 'lit';
+import { css, html, nothing, PropertyValues, TemplateResult } from 'lit';
 import { property } from 'lit/decorators.js';
 import { RapidElement } from '../RapidElement';
 import { Store } from '../store/Store';
@@ -47,7 +47,14 @@ export class TembaDate extends RapidElement {
     }
   }
 
-  public render(): TemplateResult {
+  public render(): TemplateResult | typeof nothing {
+    // unparseable values and zero-value times (e.g. go's zero time,
+    // 0001-01-01T00:00:00Z, for a contact that has never been seen) aren't
+    // real dates - render nothing rather than something like "2025 years ago"
+    if (this.datetime && !(this.datetime.isValid && this.datetime.year > 1)) {
+      return nothing;
+    }
+
     if (this.datetime && this.store) {
       this.datetime.setLocale(this.store.getLocale());
 

package/src/form/Compose.ts

@@ -1,7 +1,13 @@
 import { TemplateResult, html, css, PropertyValues, nothing } from 'lit';
 import { FieldElement } from './FieldElement';
 import { property } from 'lit/decorators.js';
-import { Attachment, CustomEventType, Language, Shortcut } from '../interfaces';
+import {
+  Attachment,
+  CustomEventType,
+  Language,
+  QuickReply,
+  Shortcut
+} from '../interfaces';
 import { Icon } from '../Icons';
 import { DEFAULT_MEDIA_ENDPOINT } from '../utils';
 import { Select } from './select/Select';
@@ -12,7 +18,7 @@ import { setCaretOffset } from '../excellent/caret-utils';
 export interface ComposeValue {
   text: string;
   attachments: { uuid: string }[];
-  quick_replies: string[];
+  quick_replies: (string | QuickReply)[];
   optin: string;
   template: string;
   variables: string[];
@@ -236,7 +242,7 @@ export class Compose extends FieldElement {
     [lang: string]: {
       text: string;
       attachments: Attachment[];
-      quick_replies: string[];
+      quick_replies: (string | QuickReply)[];
       optin?: { name: string; uuid: string };
       template?: string;
       variables?: string[];
@@ -357,11 +363,12 @@ export class Compose extends FieldElement {
       this.currentText = langValue.text || '';
       this.initialText = langValue.text || '';
       this.currentAttachments = langValue.attachments || [];
-      this.currentQuickReplies = (langValue.quick_replies || []).map(
-        (value) => {
-          return { name: value, value };
-        }
-      );
+      this.currentQuickReplies = (langValue.quick_replies || [])
+        .map((reply) =>
+          typeof reply === 'string' ? reply : (reply.text ?? null)
+        )
+        .filter((reply): reply is string => reply !== null)
+        .map((value) => ({ name: value, value }));
       this.currentOptin = langValue['optin'] ? [langValue['optin']] : [];
     }
 
@@ -410,25 +417,14 @@ export class Compose extends FieldElement {
     // own keydown inserts a newline (which would flash before the send
     // clears it); bubble keeps Enter-to-send working from anywhere else
     // in the compose after inner widgets have had their shot at it
-    this.addEventListener(
-      'keydown',
-      this.handleHostKeyDown as EventListener,
-      true
-    );
-    this.addEventListener('keydown', this.handleHostKeyDown as EventListener);
+    this.addEventListener('keydown', this.handleHostKeyDownCapture, true);
+    this.addEventListener('keydown', this.handleHostKeyDownBubble);
   }
 
   disconnectedCallback() {
     super.disconnectedCallback();
-    this.removeEventListener(
-      'keydown',
-      this.handleHostKeyDown as EventListener,
-      true
-    );
-    this.removeEventListener(
-      'keydown',
-      this.handleHostKeyDown as EventListener
-    );
+    this.removeEventListener('keydown', this.handleHostKeyDownCapture, true);
+    this.removeEventListener('keydown', this.handleHostKeyDownBubble);
   }
 
   private handleShortcutIconClick() {
@@ -454,7 +450,18 @@ export class Compose extends FieldElement {
     });
   }
 
-  private handleHostKeyDown = (evt: KeyboardEvent) => {
+  // events from inside our shadow tree are retargeted to the host, so
+  // both registrations see eventPhase as AT_TARGET — the phase can't
+  // tell us which registration is firing, so each binds it explicitly
+  private handleHostKeyDownCapture = (evt: KeyboardEvent) => {
+    this.handleHostKeyDown(evt, true);
+  };
+
+  private handleHostKeyDownBubble = (evt: KeyboardEvent) => {
+    this.handleHostKeyDown(evt, false);
+  };
+
+  private handleHostKeyDown = (evt: KeyboardEvent, capture: boolean) => {
     if (evt.key === 'Escape' && this.showShortcuts) {
       evt.preventDefault();
       evt.stopPropagation();
@@ -474,10 +481,12 @@ export class Compose extends FieldElement {
       // during capture only editor presses are claimed — anything else
       // (quick replies, attachments) waits for the bubble so the widget
       // it targets keeps first claim on the event
-      if (
-        evt.eventPhase === Event.CAPTURING_PHASE &&
-        !(editor && evt.composedPath().includes(editor))
-      ) {
+      if (capture && !(editor && evt.composedPath().includes(editor))) {
+        return;
+      }
+      // by the bubble an inner widget may have claimed the Enter for
+      // itself (e.g. the quick reply select adding a tag) — not a send
+      if (!capture && evt.defaultPrevented) {
         return;
       }
       if (editor) {

package/src/interfaces.ts

@@ -47,6 +47,14 @@ export interface Attachment {
   error: string;
 }
 
+/** A quick reply as stored/served by the server (engine shape) —
+ * `text` buttons carry text, `location` requests may omit it. */
+export interface QuickReply {
+  type?: string;
+  text?: string;
+  extra?: string;
+}
+
 export enum DateStyle {
   DayFirst = 'day_first',
   MonthFirst = 'month_first',
@@ -231,8 +239,9 @@ export interface Broadcast {
   /** Base-language attachments (`{content_type, url}` objects or
    * `contentType:url` strings). */
   attachments?: (string | Attachment)[];
-  /** Base-language quick replies. */
-  quick_replies?: string[];
+  /** Base-language quick replies — engine `{text}` objects, with
+   * plain strings tolerated for older data. */
+  quick_replies?: (string | QuickReply)[];
   /** The opt-in the broadcast requests, when it is one. */
   optin?: ObjectReference | null;
   /** The WhatsApp template the broadcast sends, when it uses one. */
@@ -271,7 +280,7 @@ export interface Msg {
   text: string;
   status: string;
   channel: ObjectReference;
-  quick_replies: string[];
+  quick_replies: (string | QuickReply)[];
   urn: string;
   /** The message's contact — populated by the messages CRUDL
    * endpoint. Carries whichever of name/urn the endpoint exposes. */
@@ -479,6 +488,7 @@ export enum CustomEventType {
   StoreUpdated = 'temba-store-updated',
   Ready = 'temba-ready',
   OrderChanged = 'temba-order-changed',
+  ColumnOrderChanged = 'temba-column-order-changed',
   DragStart = 'temba-drag-start',
   DragStop = 'temba-drag-stop',
   DragExternal = 'temba-drag-external',

package/src/list/BroadcastList.ts

@@ -872,7 +872,9 @@ export class BroadcastList extends ContentList<Broadcast> {
                           ${broadcast.quick_replies.map(
                             (reply) =>
                               html`<temba-label type="neutral"
-                                >${reply}</temba-label
+                                >${typeof reply === 'string'
+                                  ? reply
+                                  : (reply.text ?? reply.type)}</temba-label
                               >`
                           )}
                         </div>`

package/src/list/ContactList.ts

@@ -3,13 +3,19 @@ import { property, state } from 'lit/decorators.js';
 import { ContentList, ContentListColumn } from './ContentList';
 import { Icon } from '../Icons';
 import { Contact } from '../interfaces';
-import { getUrl } from '../utils';
+import { getUrl, postJSON } from '../utils';
+import { getStore } from '../store/Store';
 
 const FIELD_PREFIX = 'field:';
 
 /** Placeholder shown in any cell whose value is empty. */
 const EMPTY = '--';
 
+/** Ceiling on how many pages of fields we'll walk. The API serves 250
+ * per page, so this is far past any real workspace — it exists only so
+ * an endpoint that keeps handing back a `next` can't spin forever. */
+const MAX_FIELD_PAGES = 20;
+
 /**
  * Contact CRUDL list — drop-in replacement for the rapidpro
  * `contacts/contact_list.html` table. Each row carries a contact
@@ -22,6 +28,11 @@ const EMPTY = '--';
  * {@link ContactList.fieldsEndpoint} on connect; cells read each
  * contact's value out of `item.fields[<key>]`. Date/time fields
  * render as a relative duration, matching the Last-seen column.
+ *
+ * When {@link ContactList.priorityEndpoint} is set the field columns
+ * can be dragged into a new order, which is saved as the workspace's
+ * featured-field order (the list renders featured fields by priority,
+ * so column order and field order are the same thing).
  */
 export class ContactList extends ContentList<Contact> {
   static get styles() {
@@ -45,10 +56,25 @@ export class ContactList extends ContentList<Contact> {
   }
 
   /** Endpoint returning `{ results: ContactField[] }`. Fields where
-   * `featured: true` become extra columns. */
+   * `featured: true` become extra columns.
+   *
+   * The list deliberately fetches fields itself instead of reading the
+   * global store: it has to work standalone (and against a custom
+   * endpoint), and it may mount before any store exists on the page.
+   * The store, when present, is only *told* about changes — see the
+   * refresh after a priority save. The endpoint has no featured filter,
+   * so the fetch pages through all fields and filters client-side. */
   @property({ type: String, attribute: 'fields-endpoint' })
   fieldsEndpoint = '/api/v2/fields.json';
 
+  /** Endpoint accepting `{ featured: [keys...] }` to save featured-field
+   * order (the same one the fields management page posts to). When set,
+   * the field columns become drag-reorderable and a drop saves the new
+   * order org-wide; the host only sets it for users holding the
+   * update-priority permission. */
+  @property({ type: String, attribute: 'priority-endpoint' })
+  priorityEndpoint = '';
+
   /** Anonymous workspaces mask URN values, so instead of the URN
    * column the list shows each contact's ref (served as its own
    * anon-only key by the endpoint). */
@@ -104,7 +130,7 @@ export class ContactList extends ContentList<Contact> {
     // Rebuilding here (rather than in updated()) means a mounted
     // anon attribute is reflected in the first paint instead of
     // flashing the URN header for a frame.
-    if (changes.has('anon')) {
+    if (changes.has('anon') || changes.has('priorityEndpoint')) {
       this.columns = this.buildColumns();
     }
   }
@@ -127,11 +153,27 @@ export class ContactList extends ContentList<Contact> {
     const controller = new AbortController();
     this.pendingFieldsController = controller;
     try {
-      const response = await getUrl(this.fieldsEndpoint, controller);
-      // If the controller has been swapped or cleared, the response
-      // is from a stale request — drop it on the floor.
-      if (this.pendingFieldsController !== controller) return;
-      const all = response.json?.results || [];
+      // The fields API is cursor paginated (250 per page), and the
+      // featured list a drop posts back is authoritative — any featured
+      // field we never read would be silently un-featured org-wide. So
+      // walk every page before deciding what's featured. Nothing is
+      // assigned until the whole walk lands, so a page that fails leaves
+      // the previous (complete) list in place rather than a truncated one.
+      const all: any[] = [];
+      const fetched = new Set<string>();
+      let url: string = this.fieldsEndpoint;
+      for (let page = 0; url && page < MAX_FIELD_PAGES; page++) {
+        // an endpoint whose `next` points back at a page we've already
+        // read would otherwise loop until the page cap
+        if (fetched.has(url)) break;
+        fetched.add(url);
+        const response = await getUrl(url, controller);
+        // If the controller has been swapped or cleared, the response
+        // is from a stale request — drop it on the floor.
+        if (this.pendingFieldsController !== controller) return;
+        all.push(...(response.json?.results || []));
+        url = response.json?.next || '';
+      }
       this.featuredFields = all
         .filter((f: any) => f.featured)
         .sort((a: any, b: any) => (b.priority ?? 0) - (a.priority ?? 0));
@@ -173,7 +215,11 @@ export class ContactList extends ContentList<Contact> {
         sortable: true,
         resizeMinWidth: '40px',
         maxWidth: '200px',
-        resizable: true
+        resizable: true,
+        // Field columns can be dragged into a new order, but only when
+        // the host wired up somewhere to save it — reordering that
+        // silently reverts on reload would read as broken.
+        reorderable: !!this.priorityEndpoint
       })
     );
     // Name + URN are the pinned identity columns and are not
@@ -224,6 +270,64 @@ export class ContactList extends ContentList<Contact> {
     ];
   }
 
+  /** A committed header drag reordered the field columns — keep
+   * featuredFields aligned with the new column order (so any rebuild
+   * preserves it) and save it as the workspace's featured-field order.
+   * Column order maps directly onto priority: leftmost = highest, the
+   * same contract as the fields management page, whose endpoint this
+   * posts to with the full featured list. */
+  protected onColumnOrderChanged(columns: ContentListColumn[]): void {
+    // A fields fetch still in flight was started against the old order
+    // and would land on top of the drop, snapping the columns back with
+    // the new order already on its way to the server.
+    if (this.pendingFieldsController) {
+      this.pendingFieldsController.abort();
+      this.pendingFieldsController = undefined;
+    }
+    const keys = columns
+      .filter((c) => c.key.startsWith(FIELD_PREFIX))
+      .map((c) => c.key.substring(FIELD_PREFIX.length));
+    this.featuredFields = keys
+      .map((key) => (this.featuredFields || []).find((f: any) => f.key === key))
+      .filter(Boolean);
+    if (!this.priorityEndpoint) return;
+    postJSON(this.priorityEndpoint, { featured: keys })
+      .then((response) => {
+        // postUrl only rejects on 5xx, so a 400/403/404 arrives here as a
+        // perfectly resolved promise — the order was never stored and we
+        // have to treat it as the failure it is.
+        if (response.status < 200 || response.status >= 300) {
+          throw response;
+        }
+      })
+      .catch((error) => {
+        console.warn('failed to save featured field order', error);
+        // The list went away while the save was in flight — there are no
+        // columns left to put back, and refetching would only leave a
+        // request outstanding against a detached element.
+        if (!this.isConnected) return;
+        // Nothing made the dragged order durable, so stop showing it —
+        // refetch and fall back on whatever the server still holds. The
+        // success path deliberately doesn't refetch: we already display
+        // exactly what we just saved, and a read-replica answering with
+        // pre-write data would yank the columns back for no reason.
+        this.loadFields();
+      })
+      .finally(() => {
+        // Featured fields are workspace state other components on the
+        // page read from the store (contact details, the fields page),
+        // so its cached copy has to hear about the new order too. Looked
+        // up here rather than cached on connect so a list that mounted
+        // ahead of the store still finds it.
+        getStore()
+          ?.refreshFields()
+          .catch(() => {
+            // a stale store cache is cosmetic and elsewhere; the list
+            // itself is already showing the saved order
+          });
+      });
+  }
+
   protected getRowIcon(_item: Contact): string | null {
     return Icon.contact;
   }