@sphoro/bugcatch-web-sdk 0.16.0 → 0.18.0

package/src/panel/picks.js

@@ -0,0 +1,61 @@
+// Questions the assistant answers by itself, offered as one tap above the form.
+
+import * as ICONS from './icons.js';
+import { escapeHtml } from './render.js';
+
+export function mountPicks(ctx) {
+  const {
+    client, cfg, titleInput, descInput, picks,
+  } = ctx;
+
+  // One tap instead of a sentence: the report's title becomes the question,
+  // and the assistant knows exactly what is being asked — it looks the
+  // reporter up, answers from their account, and asks whether that settled
+  // it. Tapping the chosen one again lets it go.
+  let agentIssues = [];
+  let pickedIssue = null;
+
+  function drawPicks() {
+    if (!agentIssues.length) { picks.hidden = true; picks.innerHTML = ''; return; }
+    picks.hidden = false;
+    picks.innerHTML = `
+      <p class="picks-h">Get an answer right away</p>
+      <div class="picks-grid" role="group" aria-label="Common questions">
+        ${agentIssues.map((issue) => `
+          <button type="button" class="pick" data-pick="${escapeHtml(issue.key)}"
+            aria-pressed="${pickedIssue?.key === issue.key}">
+            <span class="t">${escapeHtml(issue.title)}</span>
+            ${issue.hint ? `<span class="h">${escapeHtml(issue.hint)}</span>` : ''}
+          </button>`).join('')}
+      </div>
+      ${pickedIssue ? `<p class="picks-note">${ICONS.check}<span>Our assistant will check your account and reply here. Add anything else below, then send.</span></p>` : ''}`;
+  }
+
+  picks.addEventListener('click', (e) => {
+    const btn = e.target.closest('[data-pick]');
+    if (!btn) return;
+    const issue = agentIssues.find((i) => i.key === btn.dataset.pick);
+    if (!issue) return;
+    const titleWasPick = pickedIssue && titleInput.value.trim() === pickedIssue.title;
+    if (pickedIssue?.key === issue.key) {
+      pickedIssue = null;
+      if (titleWasPick) titleInput.value = '';
+    } else {
+      pickedIssue = issue;
+      // Their own words are never overwritten — only an empty title, or the
+      // one the previous tap put there.
+      if (!titleInput.value.trim() || titleWasPick) titleInput.value = issue.title;
+    }
+    titleInput.dispatchEvent(new Event('input', { bubbles: true }));
+    drawPicks();
+    if (pickedIssue) descInput.focus();
+  });
+
+  if (cfg.agentIssues !== false && typeof client.agentIssues === 'function') {
+    client.agentIssues()
+      .then((rows) => { agentIssues = rows; drawPicks(); })
+      .catch(() => { /* no tiles is the safe answer to every failure */ });
+  }
+
+  ctx.pickedIssue = () => pickedIssue;
+}

package/src/panel/refs.js

@@ -0,0 +1,321 @@
+// Which record is this about.
+//
+// What this project asks for, and what the reporter has answered.
+//
+// The question is asked at Send and not before, which is the whole design of
+// it. A form that opens with "loan number" above "what went wrong" tells
+// somebody they have paperwork to do before they may complain, and most of
+// them will not — while the same question, asked once, after they have said
+// their piece, and only when what they said did not already contain the
+// answer, is a reasonable thing to be asked. Most reporters never see it: the
+// loan number was in the sentence.
+
+import * as ICONS from './icons.js';
+import { readReferences, validateReference } from '../references.js';
+import { escapeHtml } from './render.js';
+
+export function mountReferences(ctx) {
+  const {
+    client, say, titleInput, descInput, sendBtn, refsBox,
+  } = ctx;
+
+  let refConfig = { policy: 'off', fields: [] };
+  let refOpen = false;
+  let refChoice = null;   // which field they are answering; null = not picked yet
+  let refValue = '';
+  let refError = '';
+  // What we read in their text but could not place for sure, offered as taps:
+  // [{ value, kinds: [{ key, label }] }]. `refMode` says why the card is open —
+  // 'confirm' when the text had two answers, 'suggest' when it had an unlabelled
+  // one, 'ask' when it had none.
+  let refCandidates = [];
+  let refMode = 'ask';
+  // Set once they have answered or explicitly skipped, so Send stops asking.
+  let refSettled = false;
+  // Set once we have said "that does not look right" about the current value.
+  // Its own flag rather than reusing refSettled, which was the first attempt
+  // and was a loop: the warning returns early, the next press re-validates the
+  // same unchanged value, warns again, and the report can never be sent. One
+  // warning per value, and then it is their call.
+  let refWarned = false;
+
+  client.referenceFields()
+    .then((cfg) => { refConfig = cfg; showFound(); })
+    .catch(() => { /* off is the safe answer to every failure */ });
+
+  /** What the text says: found (sure), conflicts (ask which), loose (offer). */
+  function readText() {
+    if (refConfig.policy === 'off' || !refConfig.fields.length) return { found: [], conflicts: [], loose: [] };
+    return readReferences(refConfig.fields, [titleInput.value, descInput.value]);
+  }
+
+  /** Sure enough to send without a question: something found, nothing contested. */
+  function textAnswers(read = readText()) {
+    return read.found.length > 0 && read.conflicts.length === 0;
+  }
+
+  /** The answer to send, or an empty list. */
+  function answeredReference() {
+    if (!refChoice || !refValue.trim()) return [];
+    return [{ key: refChoice, value: refValue.trim().slice(0, 120) }];
+  }
+
+  // A quiet line under the description while they type, so somebody who put
+  // their loan number in the sentence can see it was read and does not go
+  // looking for a box to type it into again.
+  const foundNote = document.createElement('p');
+  foundNote.className = 'ref-found';
+  foundNote.setAttribute('aria-live', 'polite');
+  foundNote.hidden = true;
+  descInput.closest('.field').after(foundNote);
+  let foundTimer;
+  function showFound() {
+    const read = readText();
+    if (textAnswers(read)) {
+      const list = read.found.slice(0, 2).map((r) => `${escapeHtml(r.label)} <b>${escapeHtml(shortId(r.value))}</b>`).join(', ');
+      foundNote.innerHTML = `${ICONS.check}<span>Found your ${list} — no need to add it again.</span>`;
+      foundNote.hidden = false;
+      // They have answered in the text; a card still asking would be not listening.
+      if (refOpen && !answeredReference().length) { refOpen = false; drawRefs(); }
+    } else {
+      foundNote.hidden = true;
+      foundNote.innerHTML = '';
+    }
+  }
+  const queueFound = () => { clearTimeout(foundTimer); foundTimer = setTimeout(showFound, 250); };
+  titleInput.addEventListener('input', queueFound);
+  descInput.addEventListener('input', queueFound);
+
+  /** A UUID is long; the chip shows its ends, the title shows all of it. */
+  function shortId(value) {
+    return value.length > 20 ? `${value.slice(0, 8)}…${value.slice(-4)}` : value;
+  }
+
+  function candidateFor(value) {
+    const v = value.trim().toLowerCase();
+    return refCandidates.find((c) => c.value.toLowerCase() === v) || null;
+  }
+
+  /** Pick a candidate: its value, and its kind when only one kind fits. */
+  function takeCandidate(c) {
+    refValue = c.value;
+    if (c.kinds.length === 1) refChoice = c.kinds[0].key;
+    else if (!c.kinds.some((k) => k.key === refChoice)) refChoice = null;
+    refError = '';
+    refWarned = false;
+  }
+
+  function drawRefs() {
+    if (!refOpen) { refsBox.hidden = true; refsBox.innerHTML = ''; return; }
+    const field = refConfig.fields.find((f) => f.key === refChoice) || null;
+    const optional = refConfig.policy !== 'required';
+    const current = candidateFor(refValue);
+    // Kinds worth offering: the ones the picked value could be, when we know;
+    // every kind otherwise. Never zero — a guess of ours must not lock out the
+    // right answer.
+    const kinds = current && current.kinds.length > 1
+      ? refConfig.fields.filter((f) => current.kinds.some((k) => k.key === f.key))
+      : refConfig.fields;
+    // Two loan numbers: the kind is not in question, only which one — so the
+    // kind chips would be a second question nobody needs to answer.
+    const sharedKind = refCandidates.length > 1
+      && refCandidates.every((c) => c.kinds.length === 1 && c.kinds[0].key === refCandidates[0].kinds[0].key);
+
+    const head = {
+      confirm: refCandidates.length > 1
+        ? ['Which one is this about?', 'We found more than one ID in your message. Pick the one this problem is about.']
+        : ['Is this the right ID?', 'This could be more than one kind of ID. Tell us which it is.'],
+      suggest: ['Is this your ID?', 'We spotted this in your message. Tell us what it is so we can find your record.'],
+      ask: optional
+        ? ['One more thing', 'So we can find your record — this helps us answer faster.']
+        : ['We need one detail', 'We need one of these to look this up.'],
+    }[refMode];
+
+    refsBox.hidden = false;
+    // A handful of kinds read best as chips to tap; a long list goes back to
+    // a select so the card does not turn into a wall of pills.
+    const many = kinds.length > 6;
+    refsBox.innerHTML = `
+      <div class="ask-head">
+        <span class="avatar" aria-hidden="true">${ICONS.sparkle}</span>
+        <div>
+          <strong>${escapeHtml(head[0])}</strong>
+          <p class="why">${escapeHtml(head[1])}</p>
+        </div>
+      </div>
+      ${refCandidates.length > 1 ? `
+      <div class="chips cands" role="group" aria-label="IDs found in your message">
+        ${refCandidates.map((c, i) => `
+          <button type="button" data-ref-cand="${i}" title="${escapeHtml(c.value)}"
+            aria-pressed="${!!current && current === c}">${escapeHtml(shortId(c.value))}</button>
+        `).join('')}
+      </div>` : ''}
+      ${kinds.length > 1 && !many && !sharedKind ? `
+      <div class="chips" role="group" aria-label="Which detail you are giving">
+        ${kinds.map((f) => `
+          <button type="button" data-ref-kind="${escapeHtml(f.key)}" aria-pressed="${!!field && f.key === field.key}">${escapeHtml(f.label)}</button>
+        `).join('')}
+      </div>` : ''}
+      <div class="row">
+        ${many ? `
+        <select class="ref-kind" aria-label="Which detail you are giving">
+          ${field ? '' : '<option value="" selected disabled>What is it?</option>'}
+          ${kinds.map((f) => `
+            <option value="${escapeHtml(f.key)}" ${field && f.key === field.key ? 'selected' : ''}>${escapeHtml(f.label)}</option>
+          `).join('')}
+        </select>` : ''}
+        <input class="ref-value${refError ? ' invalid' : ''}" type="${field?.inputMode === 'email' ? 'email' : 'text'}"
+          inputmode="${escapeHtml(field?.inputMode === 'numeric' || field?.inputMode === 'tel' ? 'numeric' : 'text')}"
+          value="${escapeHtml(refValue)}"
+          placeholder="${escapeHtml(field ? (field.placeholder || field.label) : 'Your ID')}"
+          aria-label="${escapeHtml(field ? field.label : 'Your ID')}" ${refError ? 'aria-invalid="true"' : ''} />
+      </div>
+      ${field?.hint ? `<p class="hint">${escapeHtml(field.hint)}</p>` : ''}
+      ${refError ? `<p class="field-err" role="alert">${ICONS.alert}<span>${escapeHtml(refError)}</span></p>` : ''}
+      ${optional ? `<button type="button" class="link" data-act="ref-skip">${
+        refMode === 'ask' ? 'I don\'t have this — send without it' : 'Not sure — send as it is'}</button>` : ''}`;
+
+    refsBox.querySelectorAll('[data-ref-cand]').forEach((chip) => {
+      chip.addEventListener('click', () => {
+        takeCandidate(refCandidates[Number(chip.dataset.refCand)]);
+        drawRefs();
+      });
+    });
+    refsBox.querySelectorAll('[data-ref-kind]').forEach((chip) => {
+      chip.addEventListener('click', () => {
+        refChoice = chip.dataset.refKind;
+        refError = '';
+        refWarned = false;
+        drawRefs();
+      });
+    });
+    const value = refsBox.querySelector('.ref-value');
+    value.addEventListener('input', () => {
+      refValue = value.value;
+      refError = '';
+      // A changed value has not been warned about yet.
+      refWarned = false;
+    });
+    // Enter in the box is the same gesture as pressing Send, which is what
+    // somebody who has just been asked one question expects it to be.
+    value.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') { e.preventDefault(); sendBtn.click(); }
+    });
+    refsBox.querySelector('.ref-kind')?.addEventListener('change', (e) => {
+      refChoice = e.target.value;
+      refError = '';
+      drawRefs();
+      refsBox.querySelector('.ref-value')?.focus();
+    });
+    refsBox.querySelector('[data-act="ref-skip"]')?.addEventListener('click', () => {
+      // Skipping is answering. Without this the panel asks again on the next
+      // press and the reporter is in a loop with a button that does nothing.
+      // The text still goes; the server reads it either way.
+      refSettled = true;
+      refOpen = false;
+      refChoice = null;
+      refValue = '';
+      refError = '';
+      refWarned = false;
+      drawRefs();
+      say('');
+    });
+
+    // Focus where the next decision is: the kind, when that is all that is
+    // missing; the box otherwise.
+    const next = !field && refValue ? refsBox.querySelector('[data-ref-kind], .ref-kind') : null;
+    (next || value).focus();
+  }
+
+  /**
+   * Open the question, pre-filled with the best of what the text offered.
+   *
+   * Conflicts first — the text said two things and only the reporter knows
+   * which — then loose IDs, which are probably the answer and only need a
+   * name. Nothing, and it is the plain question it always was.
+   */
+  function openRefs(read) {
+    refCandidates = read.conflicts.length ? read.conflicts : read.loose.slice(0, 4);
+    refMode = read.conflicts.length ? 'confirm' : read.loose.length ? 'suggest' : 'ask';
+    refOpen = true;
+    if (refCandidates.length) {
+      // One contested value: pre-fill it so they only choose what it is. Two
+      // or more: pick nothing, because picking is the question.
+      if (refCandidates.length === 1) takeCandidate(refCandidates[0]);
+      else {
+        refValue = '';
+        const [first] = refCandidates;
+        const same = refCandidates.every((c) => c.kinds.length === 1 && c.kinds[0].key === first.kinds[0].key);
+        refChoice = same ? first.kinds[0].key : null;
+      }
+    } else {
+      refChoice = refChoice || refConfig.fields[0].key;
+    }
+    drawRefs();
+  }
+
+  /**
+   * Whether Send should stop and ask.
+   *
+   * Never when the text answered it outright. Once when the text said two
+   * things or something unlabelled — on every policy, because sending the
+   * wrong record's id with confidence is worse than one extra tap. And the
+   * plain question on `optional`/`required` projects as before.
+   */
+  function needsReference() {
+    if (refConfig.policy === 'off' || !refConfig.fields.length) return false;
+    if (answeredReference().length) return false;
+    const read = readText();
+    if (textAnswers(read)) return false;
+    if (refSettled && refConfig.policy !== 'required') return false;
+    return read;
+  }
+
+  /**
+   * Whether Send should stop here: true when it asked, or warned, instead.
+   *
+   * Ask, if this project asks and nothing they wrote answered it. The first
+   * press opens the question rather than sending; the second sends. That
+   * costs one extra press on projects that want an identifier, and it is the
+   * only shape that does not put paperwork in front of a person who came here
+   * to say something is broken.
+   */
+  function holdForReference() {
+    // First, though: a value in the box but no kind picked. Asked rather than
+    // guessed — a wrong kind joins on the wrong table.
+    if (refOpen && refValue.trim() && !refChoice) {
+      refError = 'Pick what this ID is.';
+      drawRefs();
+      return true;
+    }
+
+    const read = needsReference();
+    if (read) {
+      if (!refOpen) openRefs(read); else drawRefs();
+      say('');
+      return true;
+    }
+
+    // They chose a field and typed something that is not that shape. Advisory
+    // on the server — a value that fails is still what they believe identifies
+    // them, and it is kept — but worth one chance to fix a typo here, where the
+    // number is still on screen.
+    if (refChoice && refValue.trim()) {
+      const field = refConfig.fields.find((f) => f.key === refChoice);
+      if (!refWarned && field && !validateReference(field, refValue)) {
+        refError = `That does not look like a ${field.label.toLowerCase()}. Press Send again to use it anyway.`;
+        // Once, and then it is their call. Our idea of the shape of somebody's
+        // account number is not better than theirs, and refusing outright is
+        // how a genuine reference gets lost — so the second press sends it and
+        // the API keeps it, marked as not matching the expected format.
+        refWarned = true;
+        drawRefs();
+        return true;
+      }
+    }
+    return false;
+  }
+
+  ctx.holdForReference = holdForReference;
+  ctx.answeredReference = answeredReference;
+}

package/src/panel/render.js

@@ -0,0 +1,124 @@
+// Markup the panel's screens share: the header, empty and loading states, and
+// the small formatting helpers every screen reaches for — dates, statuses and
+// escaping. Pure functions of their arguments; nothing here touches the DOM
+// except the two scroll helpers, which are handed the element they move.
+
+import * as ICONS from './icons.js';
+
+/**
+ * The panel's header, on every screen. The assistant's avatar carries the
+ * identity; `back` adds the way out of a report to the list of them.
+ */
+export function headHtml({ title, sub, id = '', back = false }) {
+  return `
+    <div class="head">
+      ${back ? `<button class="icon-btn back" type="button" data-act="back" aria-label="Back to your reports">${ICONS.back}</button>` : ''}
+      <div class="mark" aria-hidden="true">${ICONS.sparkle}</div>
+      <div class="titles">
+        <h2${id ? ` id="${id}"` : ''}>${escapeHtml(title)}</h2>
+        <p>${escapeHtml(sub)}</p>
+      </div>
+      <button class="icon-btn" type="button" data-act="close" aria-label="Close">${ICONS.close}</button>
+    </div>`;
+}
+
+export function emptyHtml(text, icon) {
+  return `<div class="empty"><span class="empty-ico" aria-hidden="true">${icon}</span>${escapeHtml(text)}</div>`;
+}
+
+/** Placeholder rows while the list loads — the shape of what is coming. */
+export function skeletonRows(n) {
+  return Array.from({ length: n }, () => `
+    <div class="row" aria-hidden="true">
+      <span class="row-ico"></span>
+      <span class="who"><span class="skel" style="width:70%"></span><span class="skel" style="width:40%;height:9px"></span></span>
+    </div>`).join('') + '<span class="sr-only">Loading…</span>';
+}
+
+export function skeletonBubbles() {
+  return `
+    <div aria-hidden="true" style="display:flex;flex-direction:column;gap:10px;padding-top:6px">
+      <span class="skel" style="width:42%;height:34px;border-radius:16px;align-self:center"></span>
+      <span class="skel" style="width:66%;height:52px;border-radius:18px"></span>
+      <span class="skel" style="width:48%;height:38px;border-radius:18px;align-self:flex-end"></span>
+    </div>
+    <span class="sr-only">Loading…</span>`;
+}
+
+export function initials(name) {
+  const parts = String(name).trim().split(/\s+/).filter(Boolean);
+  if (!parts.length) return '?';
+  return (parts[0][0] + (parts.length > 1 ? parts[parts.length - 1][0] : '')).toUpperCase();
+}
+
+export function dayKey(iso) {
+  const d = new Date(iso);
+  return Number.isFinite(d.getTime()) ? `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}` : null;
+}
+
+/** "Today" / "Yesterday" / "Mon, 14 Sep" — the label on a day separator. */
+export function dayLabel(iso) {
+  const d = new Date(iso);
+  const today = new Date();
+  const yesterday = new Date(today.getFullYear(), today.getMonth(), today.getDate() - 1);
+  if (dayKey(d) === dayKey(today)) return 'Today';
+  if (dayKey(d) === dayKey(yesterday)) return 'Yesterday';
+  try {
+    return d.toLocaleDateString(undefined, {
+      weekday: 'short', day: 'numeric', month: 'short',
+      ...(d.getFullYear() !== today.getFullYear() ? { year: 'numeric' } : {}),
+    });
+  } catch {
+    return relativeDay(iso);
+  }
+}
+
+/** "14:05" or "2:05 PM", in the reader's own convention. */
+export function clockTime(iso) {
+  const d = new Date(iso);
+  if (!Number.isFinite(d.getTime())) return '';
+  try {
+    return d.toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' });
+  } catch {
+    return '';
+  }
+}
+
+/** Whether the reader is at the foot of the thread, within a line or two. */
+export function atLatest(thread) {
+  return thread.scrollHeight - thread.scrollTop - thread.clientHeight < 40;
+}
+
+export function scrollToLatest(thread, { smooth = false } = {}) {
+  const calm = typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+  if (smooth && !calm && thread.scrollTo) thread.scrollTo({ top: thread.scrollHeight, behavior: 'smooth' });
+  else thread.scrollTop = thread.scrollHeight;
+}
+
+/** Status as a word a reporter would use, not the enum the database stores. */
+export function statusWord(status) {
+  return {
+    OPEN: 'Open',
+    IN_PROGRESS: 'In progress',
+    RESOLVED: 'Fixed',
+    CLOSED: 'Closed',
+  }[status] || String(status || '').toLowerCase();
+}
+
+/** "today" / "3 days ago" — enough for a history list, no library. */
+export function relativeDay(iso) {
+  const then = new Date(iso).getTime();
+  if (!Number.isFinite(then)) return '';
+  const days = Math.floor((Date.now() - then) / 86400000);
+  if (days <= 0) return 'today';
+  if (days === 1) return 'yesterday';
+  if (days < 30) return `${days} days ago`;
+  const months = Math.floor(days / 30);
+  return months === 1 ? 'a month ago' : `${months} months ago`;
+}
+
+export function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+  ));
+}