@nyaruka/temba-components 0.159.4 → 0.159.6

package/package.json

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

package/src/Icons.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-duplicate-enum-values */
 // for cache busting we dynamically generate a fingerprint, use pnpm svg to update
-export const SVG_FINGERPRINT = 'ed78045b1cf74b0b9242822c54badf99';
+export const SVG_FINGERPRINT = '45268f1573f1e352c7d62232863725bb';
 
 // only icons below are included in the sprite sheet
 export enum Icon {
@@ -98,8 +98,10 @@ export enum Icon {
   issue = 'alert-square',
   label = 'tag-01',
   language = 'translate-01',
+  language_default = 'switch-horizontal-01',
   link = 'link-external-01',
   location = 'marker-pin-01',
+  shuffle = 'shuffle-01',
   log = 'file-02',
   logout = 'log-out-04',
   menu = 'menu-01',

package/src/flow/Editor.ts

@@ -97,7 +97,8 @@ export type ToolbarAction =
   | { action: 'revisions' }
   | { action: 'search' }
   | { action: 'language-change'; isPrimary?: boolean; languageCode?: string }
-  | { action: 'auto-translate' };
+  | { action: 'auto-translate' }
+  | { action: 'make-default-language' };
 const EMPTY_FLOW_ISSUES: FlowIssue[] = [];
 
 // How long the pending-changes auto-save countdown runs (in ms).
@@ -1707,6 +1708,191 @@ export class Editor extends RapidElement {
     zustand.getState().setLanguageCode(languageCode);
   }
 
+  private buildMakeDefaultBody(
+    newLanguage: string,
+    currentLanguage: string
+  ): HTMLElement {
+    // Build with textContent rather than innerHTML: language names fall back to
+    // the raw, server-derived language code when Intl/ADDITIONAL_LANGUAGE_NAMES
+    // can't resolve them, so they must never be interpolated into markup.
+    const body = document.createElement('div');
+    body.style.cssText = 'padding: 20px; line-height: 1.5;';
+    const newName = document.createElement('b');
+    newName.textContent = newLanguage;
+    const currentName = document.createElement('b');
+    currentName.textContent = currentLanguage;
+    body.append(
+      'Make ',
+      newName,
+      ' the default language for this flow? ',
+      currentName,
+      ' will be kept as a translation.'
+    );
+    return body;
+  }
+
+  private showMakeDefaultLanguageConfirmation(): void {
+    if (this.viewingRevision) {
+      return;
+    }
+
+    const languageCode = this.languageCode;
+    const baseLanguage = this.definition?.language;
+    if (!languageCode || !baseLanguage || languageCode === baseLanguage) {
+      return;
+    }
+
+    // don't stack a second confirmation if one is already open
+    if (document.body.querySelector('temba-dialog[data-make-default]')) {
+      return;
+    }
+
+    const newLanguageName = getLanguageName(languageCode);
+    const currentLanguageName = getLanguageName(baseLanguage);
+
+    const dialog = document.createElement('temba-dialog') as Dialog;
+    dialog.setAttribute('data-make-default', '');
+    dialog.header = 'Change Default Language';
+    dialog.primaryButtonName = 'Update';
+    dialog.cancelButtonName = 'Cancel';
+    dialog.submittingName = 'Updating';
+    dialog.appendChild(
+      this.buildMakeDefaultBody(newLanguageName, currentLanguageName)
+    );
+
+    // closes the dialog and removes its node once the close animation finishes.
+    // The dialog never fires temba-dialog-hidden (hideOnClick is not set), so we
+    // must drive removal explicitly rather than relying on that event.
+    const cleanup = () => {
+      // drop the marker first so a fresh confirmation can be opened immediately,
+      // even though the node lingers briefly for the close animation
+      dialog.removeAttribute('data-make-default');
+      dialog.open = false;
+      window.setTimeout(() => dialog.remove(), 500);
+    };
+
+    // created lazily on first error and reused across retries so server-
+    // controlled text is only ever set via textContent, never parsed as HTML.
+    let errorNode: HTMLElement | null = null;
+    const clearError = () => {
+      if (errorNode) {
+        errorNode.remove();
+        errorNode = null;
+      }
+    };
+
+    let submitting = false;
+    dialog.addEventListener('temba-button-clicked', async (event: any) => {
+      // Cancel/Escape route through this same event; tear the dialog down.
+      // Ignore cancel while a swap is in flight — the request can't be recalled,
+      // so closing here would let the change land after an apparent cancel.
+      if (event.detail.button.name !== 'Update') {
+        if (submitting) {
+          return;
+        }
+        cleanup();
+        return;
+      }
+
+      // guard against double-submit: the primary button stays clickable while
+      // the request is in flight, so ignore re-entrant clicks.
+      if (submitting) {
+        return;
+      }
+      submitting = true;
+      dialog.submitting = true;
+      dialog.disabled = true;
+      // Drop the Cancel affordance while the request is in flight. A
+      // `closes:true` button (Cancel, and Escape which clicks it) bypasses
+      // `dialog.disabled`, so leaving it would let the user close the dialog
+      // even though the POST can't be recalled — the swap would land after an
+      // apparent cancel. Removing the name un-renders the button entirely.
+      dialog.cancelButtonName = '';
+      const { error, flushFailed } =
+        await this.changeDefaultLanguage(languageCode);
+      submitting = false;
+      dialog.submitting = false;
+      dialog.disabled = false;
+      dialog.cancelButtonName = 'Cancel';
+
+      if (flushFailed) {
+        // flushSave already surfaced its own "Save Failed" dialog via the
+        // reactive saveError path; close this one rather than stacking a
+        // duplicate message on top of it.
+        cleanup();
+        return;
+      }
+
+      if (error) {
+        // keep the dialog open so the user can retry or cancel
+        if (!errorNode) {
+          errorNode = document.createElement('div');
+          errorNode.style.cssText =
+            'padding: 0 20px 16px; color: var(--color-error, #e34f4f);';
+          dialog.appendChild(errorNode);
+        }
+        errorNode.textContent = error;
+        return;
+      }
+
+      clearError();
+      cleanup();
+    });
+
+    document.body.appendChild(dialog);
+    dialog.open = true;
+  }
+
+  /**
+   * Asks the backend to promote a fully-translated language to be the flow's
+   * base language, then reloads the swapped definition. Resolves to null on
+   * success or an error message string on failure.
+   */
+  private async changeDefaultLanguage(
+    languageCode: string
+  ): Promise<{ error: string | null; flushFailed: boolean }> {
+    // persist any pending edits so mailroom swaps the latest saved definition
+    await this.flushSave();
+
+    // A successful save clears dirtyDate; saveChanges leaves it in place on
+    // failure. So if it's still set the flush did not land — abort rather than
+    // letting mailroom swap a stale definition and silently drop the latest
+    // edits. dirtyDate alone is the signal: the failed save also sets saveError,
+    // which surfaces the standard "Save Failed" dialog via updated(), so the
+    // caller closes its own dialog instead of duplicating that message.
+    if (this.dirtyDate) {
+      return { error: null, flushFailed: true };
+    }
+
+    try {
+      const response = await getStore().postJSON(
+        `/flow/change_language/${this.flow}/`,
+        { language: languageCode }
+      );
+
+      if (response.status < 200 || response.status >= 300) {
+        return {
+          error: this.extractErrorMessage(response),
+          flushFailed: false
+        };
+      }
+
+      // reload the swapped definition; fetchRevision resets the editing
+      // language to the new base language
+      await getStore().getState().fetchRevision(`/flow/revisions/${this.flow}`);
+
+      // refresh the revisions list if it's currently open
+      this.getRevisionsWindow()?.refresh();
+      return { error: null, flushFailed: false };
+    } catch (error) {
+      console.error('Failed to change default language:', error);
+      return {
+        error: 'Unable to change the default language. Please try again.',
+        flushFailed: false
+      };
+    }
+  }
+
   private getAvailableLanguages(): Array<{ code: string; name: string }> {
     // Use languages from workspace if available
     if (this.workspace?.languages && this.workspace.languages.length > 0) {
@@ -3694,6 +3880,16 @@ export class Editor extends RapidElement {
     const hasPendingTranslations =
       Boolean(activeLanguage) && progress.total > 0;
 
+    // a fully-translated language can be promoted to be the flow's base
+    // language (not while viewing a historical revision). Gate on the raw
+    // counts rather than the rounded percent — e.g. 199/200 rounds to 100%
+    // but is not actually complete, and the server does no completeness check.
+    const canMakeDefault =
+      Boolean(activeLanguage) &&
+      progress.total > 0 &&
+      progress.localized === progress.total &&
+      !this.viewingRevision;
+
     return html`
       <temba-editor-toolbar
         ?message-view=${this.showMessageTable}
@@ -3709,6 +3905,7 @@ export class Editor extends RapidElement {
         ?is-base-language=${isBaseSelected}
         .languagePercent=${percent}
         ?show-localization-tools=${Boolean(activeLanguage)}
+        ?can-make-default=${canMakeDefault}
         ?has-pending-translations=${hasPendingTranslations ||
         this.autoTranslating}
         ?auto-translate-disabled=${this.viewingRevision}
@@ -3751,6 +3948,9 @@ export class Editor extends RapidElement {
       case 'auto-translate':
         this.handleAutoTranslateClick();
         break;
+      case 'make-default-language':
+        this.showMakeDefaultLanguageConfirmation();
+        break;
       case 'language-change':
         if (detail.isPrimary) {
           this.handleLanguageChange(this.definition?.language || '');

package/src/flow/EditorToolbar.ts

@@ -192,6 +192,11 @@ export class EditorToolbar extends RapidElement {
         color: #1a7f37;
       }
 
+      .toolbar-btn.make-default {
+        width: var(--toolbar-translation-control-height);
+        height: var(--toolbar-translation-control-height);
+      }
+
       .toolbar-zoom-level {
         font-size: 12px;
         min-width: 40px;
@@ -249,6 +254,9 @@ export class EditorToolbar extends RapidElement {
   @property({ type: Boolean, attribute: 'show-localization-tools' })
   showLocalizationTools = false;
 
+  @property({ type: Boolean, attribute: 'can-make-default' })
+  canMakeDefault = false;
+
   @property({ type: Boolean, attribute: 'has-pending-translations' })
   hasPendingTranslations = false;
 
@@ -457,6 +465,7 @@ export class EditorToolbar extends RapidElement {
                       min-width="230"
                     ></temba-options>
                   </div>
+                  ${this.canMakeDefault ? this.renderMakeDefaultButton() : ''}
                   ${this.showLocalizationTools
                     ? this.renderTranslationTools()
                     : ''}
@@ -567,6 +576,21 @@ export class EditorToolbar extends RapidElement {
     `;
   }
 
+  private renderMakeDefaultButton(): TemplateResult {
+    return this.renderTip(
+      `Make ${this.currentLanguageName} the default`,
+      html`
+        <button
+          class="toolbar-btn language-tool make-default"
+          @click=${() => this.fireToolbarAction('make-default-language')}
+          aria-label="Make default language"
+        >
+          <temba-icon name=${Icon.language_default} size="1"></temba-icon>
+        </button>
+      `
+    );
+  }
+
   private renderTranslationTools(): TemplateResult {
     if (!this.hasPendingTranslations && !this.autoTranslating) {
       return html``;

package/src/interfaces.ts

@@ -114,9 +114,9 @@ export interface Flow {
   /** Completion ratio in the range 0–1. */
   completion: number;
   has_issues: boolean;
-  status: 'active' | 'archived' | string;
   labels: ObjectReference[];
-  /** Recent run counts, oldest to newest — rendered as a sparkline. */
+  /** Recent daily engagement counts, oldest to newest — rendered as
+   * a sparkline. Empty when there's been no recent engagement. */
   activity: number[];
 }
 
@@ -367,6 +367,10 @@ export enum CustomEventType {
   RowClick = 'temba-row-click',
   SelectionChange = 'temba-selection-change',
   BulkAction = 'temba-bulk-action',
+  /** The label dropdown's "New Label…" row was clicked — detail
+   * carries the action key and the selected row ids so the host can
+   * open its create modal seeded with the selection. */
+  LabelCreate = 'temba-label-create',
   /** A restorable piece of component state changed (page, sort, …).
    * Fired by lists so the host SPA can persist the state into the
    * browser's history entry (typically via `history.replaceState`).

package/src/list/ContentList.ts

@@ -73,6 +73,12 @@ export interface ContentListBulkAction {
    * selected rows. Defaults to `labels` (messages); the contact list
    * sets it to `groups`. */
   labelsKey?: string;
+  /** When true (and `labelsEndpoint` is set), the dropdown gets a
+   * trailing "New Label…" row that fires `temba-label-create` with
+   * the selected ids — the host opens its create modal seeded with
+   * them. Sent by the server only when the viewer holds the create
+   * permission. */
+  allowCreate?: boolean;
   /** When true, the component does not POST the action to
    * `actionEndpoint` — it only fires the `temba-bulk-action` event
    * with the selected ids and leaves the work to the host. Used for
@@ -308,6 +314,33 @@ export class ContentList<T = any> extends RapidElement {
         color: var(--text-3);
         font-size: 12.5px;
       }
+      /* "New Label…" creation row — separated from the toggle rows
+         above it (mirrors the legacy dropdown's add-label row). */
+      .lbl-create {
+        border-top: 1px solid var(--border-1);
+        margin-top: 4px;
+        padding: 10px 12px 6px;
+        cursor: pointer;
+        color: var(--text-2);
+        border-radius: var(--r-sm);
+      }
+      .lbl-create:hover {
+        background: var(--accent-50);
+        color: var(--text-1);
+      }
+      /* Blocked while a label-toggle POST is in flight, matching the
+         treatment of the label rows above. */
+      .lbl-create.blocked,
+      .lbl-create.blocked:hover {
+        cursor: not-allowed;
+        background: transparent;
+        color: var(--text-3);
+      }
+      .lbl-create:first-child {
+        border-top: none;
+        margin-top: 0;
+        padding-top: 6px;
+      }
       .lbl-menu {
         display: flex;
         align-items: center;
@@ -918,14 +951,12 @@ export class ContentList<T = any> extends RapidElement {
         color: var(--accent-700);
       }
 
-      /* Leading entity-type icon — a small icon shared by every row
-         (contact silhouette, flow type icon, etc.). It rides inside the
+      /* Leading entity-type icon — a small icon flagging a row (contact
+         silhouette, voice/background flow, etc.). It rides inside the
          first column's cell rather than in its own column, so the column
-         header aligns with the icon (the row's leading content) rather
-         than the value beside it — and the alignment reads the same
-         whether or not the list has a leading icon. Subclasses override
-         {@link getRowIcon}; when it returns null for every row no space
-         is reserved (see {@link reservesIcon}). */
+         header aligns with the row's leading content. Subclasses
+         override {@link getRowIcon}; a row whose icon is null renders
+         its value flush at the column edge with no reserved gutter. */
       .lead-wrap {
         display: flex;
         align-items: center;
@@ -934,12 +965,12 @@ export class ContentList<T = any> extends RapidElement {
       .lead-wrap .cell-inner {
         min-width: 0;
       }
-      /* Reserve the icon's 1em footprint plus a snug 5px gap to the
-         value whether or not this row has an icon, so values stay
-         aligned down the column. The fixed box also keeps the column's
-         intrinsic width stable while <temba-icon> upgrades — without it
-         the column briefly measures narrow and downstream pinned columns
-         jump, which races with whatever moment we snapshot. */
+      /* The icon's 1em footprint plus a snug 5px gap to the value.
+         The fixed box keeps the column's intrinsic width stable while
+         <temba-icon> upgrades — without it the column briefly measures
+         narrow and downstream pinned columns jump, which races with
+         whatever moment we snapshot. Rows without an icon don't render
+         this box at all — their value sits flush at the column edge. */
       .lead-icon {
         flex: 0 0 auto;
         display: flex;
@@ -1797,8 +1828,11 @@ export class ContentList<T = any> extends RapidElement {
 
   /** Public API — programmatic refresh, mirrors `refreshKey` bump.
    * Re-requests the current page (cursor lists included) rather than
-   * resetting to the first. */
+   * resetting to the first. Also drops the cached label-dropdown
+   * lists — a refresh often follows label/group creation, and the
+   * next dropdown open should see the new entry. */
   public refresh(): void {
+    this.labelsByActionKey = {};
     this.fetchPage(this.currentUrl || undefined);
   }
 
@@ -2127,7 +2161,10 @@ export class ContentList<T = any> extends RapidElement {
   }
 
   private renderLabelDropdown(action: ContentListBulkAction): TemplateResult {
-    const labels = this.labelsByActionKey[action.key] || [];
+    // Undefined means the list hasn't been fetched yet (the dropdown
+    // fetches lazily on first open); an empty array is a real
+    // "no labels exist" state.
+    const labels = this.labelsByActionKey[action.key];
     return html`
       <temba-dropdown
         class="label-dropdown"
@@ -2144,14 +2181,38 @@ export class ContentList<T = any> extends RapidElement {
           <span class="bulk-label">${action.label}</span>
         </span>
         <div slot="dropdown" class="label-menu">
-          ${labels.length === 0
+          ${!labels
             ? html`<div class="label-menu-empty">Loading&hellip;</div>`
-            : labels.map((label) => this.renderLabelOption(label, action))}
+            : labels.length === 0 && !action.allowCreate
+              ? html`<div class="label-menu-empty">No labels</div>`
+              : labels.map((label) => this.renderLabelOption(label, action))}
+          ${labels && action.allowCreate
+            ? html`<div
+                class="lbl-create ${this.pendingLabel !== null
+                  ? 'blocked'
+                  : ''}"
+                @click=${() => this.handleLabelCreate(action)}
+              >
+                New Label&hellip;
+              </div>`
+            : null}
         </div>
       </temba-dropdown>
     `;
   }
 
+  /** The dropdown's "New Label…" row — fire the event with the
+   * current selection and let the click bubble so the dropdown
+   * closes; the host opens its create modal seeded with the ids.
+   * Blocked while a toggle POST is in flight, like the label rows. */
+  private handleLabelCreate(action: ContentListBulkAction): void {
+    if (this.pendingLabel !== null) return;
+    this.fireCustomEvent(CustomEventType.LabelCreate, {
+      action: action.key,
+      ids: Array.from(this.selectedIds)
+    });
+  }
+
   private renderLabelOption(
     label: any,
     action: ContentListBulkAction
@@ -2198,6 +2259,14 @@ export class ContentList<T = any> extends RapidElement {
         [action.key]: labels
       };
     } catch (err) {
+      // Mark the list as fetched-empty rather than leaving it
+      // undefined — otherwise the dropdown shows "Loading…" until
+      // it's closed and reopened. A later refresh() clears the cache
+      // so a retry still happens.
+      this.labelsByActionKey = {
+        ...this.labelsByActionKey,
+        [action.key]: []
+      };
       // eslint-disable-next-line no-console
       console.error('failed to fetch labels', err);
     }
@@ -2380,11 +2449,14 @@ export class ContentList<T = any> extends RapidElement {
    * cells pin alongside them so identity stays anchored); right-
    * pinned columns contiguous to the last. */
   private computePinLayout(): void {
-    // Reserve an empty leading-icon column when any row would carry
-    // an icon — probe a representative row, then skip the icon
-    // per-row if that row's own getRowIcon returns null.
-    this.reservesIcon =
-      this.items.length > 0 && this.getRowIcon(this.items[0]) !== null;
+    // Whether any row on this page carries a leading icon — probe
+    // every row (a page can lead with icon-less rows, e.g. message
+    // flows). Rows render their icon inline (no gutter on icon-less
+    // rows); this flag just marks the first column's cells as
+    // lead-cells for alignment lookups.
+    this.reservesIcon = this.items.some(
+      (item) => this.getRowIcon(item) !== null
+    );
     this.pinIndexByColumn = new Map();
     this.rightPinIndexByColumn = new Map();
     this.checkPinIndex = -1;
@@ -2728,8 +2800,9 @@ export class ContentList<T = any> extends RapidElement {
     `;
     // The first column carries the row's leading icon (when the list
     // reserves one), so its header aligns with the icon rather than the
-    // value. A row with no icon still reserves the space to keep values
-    // aligned down the column.
+    // value. A row with no icon renders its value flush at the column
+    // edge — the icon is an inline flag on the rows that have one (e.g.
+    // voice flows), not a gutter every row indents around.
     const lead = isLead && this.reservesIcon;
     const icon = lead ? this.getRowIcon(item) : null;
     return html`
@@ -2738,12 +2811,10 @@ export class ContentList<T = any> extends RapidElement {
         ''} ${column.grow ? 'grow' : ''} ${this.columnPinClass(column)}"
         style=${this.columnPinStyle(column)}
       >
-        ${lead
+        ${icon
           ? html`<div class="lead-wrap">
               <span class="lead-icon"
-                >${icon
-                  ? html`<temba-icon name=${icon} size="1"></temba-icon>`
-                  : null}</span
+                ><temba-icon name=${icon} size="1"></temba-icon></span
               >${inner}
             </div>`
           : inner}

package/src/list/FlowList.ts

@@ -5,10 +5,10 @@ import { Flow, ObjectReference } from '../interfaces';
 
 /**
  * Flow CRUDL list — drop-in replacement for the rapidpro
- * `flows/flow_list.html` table. Each row's leading icon reflects
- * the flow type (messaging / voice / background / surveyor).
- * Columns: name, status, runs, ongoing, completion bar, activity
- * sparkline.
+ * `flows/flow_list.html` table. Rows of the unusual flow types
+ * (voice / background / surveyor) carry a leading type icon;
+ * message flows don't. Columns: name, runs, ongoing, completion
+ * bar, activity sparkline.
  */
 export class FlowList extends ContentList<Flow> {
   static get styles() {
@@ -92,7 +92,6 @@ export class FlowList extends ContentList<Flow> {
         width: '280px',
         pinned: true
       },
-      { key: 'status', label: 'Status', width: '110px' },
       {
         key: 'runs',
         label: 'Runs',
@@ -137,7 +136,9 @@ export class FlowList extends ContentList<Flow> {
       case 'survey':
         return Icon.flow_surveyor;
       default:
-        return Icon.flow_message;
+        // message flows are the common case and carry no icon — only
+        // the unusual types get flagged, matching the legacy table
+        return null;
     }
   }
 
@@ -183,8 +184,6 @@ export class FlowList extends ContentList<Flow> {
         return this.renderCompletion(item);
       case 'activity':
         return this.renderSparkline(item.activity || []);
-      case 'status':
-        return this.renderFlowStatus(item);
       default:
         return super.renderCell(item, column);
     }
@@ -235,11 +234,4 @@ export class FlowList extends ContentList<Flow> {
       </svg>
     `;
   }
-
-  private renderFlowStatus(item: Flow): TemplateResult {
-    const status = (item.status || 'active').toString().toLowerCase();
-    const kind = status === 'archived' ? 'archived' : 'active';
-    const label = status === 'archived' ? 'Archived' : 'Active';
-    return this.renderStatusPill(kind, label);
-  }
 }

package/src/live/ContactFields.ts

@@ -94,9 +94,32 @@ export class ContactFields extends ContactStoreElement {
   @property({ type: Boolean })
   disabled = false;
 
+  // tracks whether the store's contact field definitions have loaded. these
+  // load independently of the contact data this element fetches, so we can't
+  // render field rows until they're present (see render). this is reactive so
+  // that flipping it re-renders once the definitions arrive.
+  @property({ type: Boolean, attribute: false })
+  fieldsReady = false;
+
   connectedCallback(): void {
     super.connectedCallback();
     this.handleFieldChanged = this.handleFieldChanged.bind(this);
+
+    // field definitions are usually already loaded by the time this element
+    // connects, but during a cold load they may still be in flight
+    this.fieldsReady =
+      !!this.store &&
+      (this.store.ready ||
+        (this.store.getKeyedAssets()['fields'] || []).length > 0);
+  }
+
+  protected storeUpdated(event: CustomEvent) {
+    super.storeUpdated(event);
+    // the store fires a StoreUpdated for the fields endpoint once the field
+    // definitions have loaded; that's our signal that it's safe to render
+    if (this.store && event.detail.url === this.store.fieldsEndpoint) {
+      this.fieldsReady = true;
+    }
   }
 
   private isAgent(): boolean {
@@ -148,9 +171,17 @@ export class ContactFields extends ContactStoreElement {
   }
 
   public render(): TemplateResult {
-    if (this.data) {
-      const fieldsToShow = Object.entries(this.data.fields).sort(
-        (a: [string, string], b: [string, string]) => {
+    // we need both the contact data and the field definitions (loaded during
+    // store init) before we can render. these load independently, so the
+    // contact data can arrive first; rendering then would crash on missing
+    // field definitions and leave the tab empty (see getContactField below).
+    if (this.data && this.fieldsReady) {
+      // guard against keys with no matching field definition (mid-load races
+      // or fields that have since been deleted) so a single missing
+      // definition can't throw and blank out the entire tab
+      const fieldsToShow = Object.entries(this.data.fields)
+        .filter(([key]: [string, string]) => !!this.store.getContactField(key))
+        .sort((a: [string, string], b: [string, string]) => {
           const [ak] = a;
           const [bk] = b;
           const fieldA = this.store.getContactField(ak);
@@ -212,8 +243,7 @@ export class ContactFields extends ContactStoreElement {
           }
 
           return ak.localeCompare(bk);
-        }
-      );
+        });
 
       if (fieldsToShow.length == 0) {
         return html`<slot name="empty"></slot>`;