@arcforgelabs/flow 2026.10.42 → 2026.10.43

package/server/ui/jobs.js

@@ -15,6 +15,7 @@
 import { bulkBar } from '/assets/ui/bulk-bar.js';
 import { lucide } from '/assets/ui/custom-fields.js';
 import { formatCents } from '/assets/ui/invoicing.js';
+import { jobChangeReview } from '/assets/ui/job-change.js';
 import {
   caseNumber, FINAL_RANK, fixes, INVOICE_STAGES, invoiceStage, matches, NO_STATUS, orderStatuses, problemSummary, statusRank,
 } from '/assets/ui/job-board.js';
@@ -22,10 +23,14 @@ import {
   COLUMNS, DEFAULT_VIEW, fieldGroup, fieldIdOf, fieldLanes, FILTER_FIELDS, filterJobs, groupJobs, GROUPS, KIND_OF_TYPE, keptStatuses, laneOf,
   normaliseJobsView, NOT_SET, OPERATORS, sortJobs, SORTS,
 } from '/assets/ui/job-view.js';
+import { sidecar } from '/assets/ui/sidecar.js';
 import { findBox, ICONS, svg, today, viewBar } from '/assets/ui/view-bar.js';
 
 const LAYOUT_KEY = 'flow_jobs_layout';
 const FOLDED_KEY = 'flow_jobs_folded';
+// The job panel's sidecar: the tab last open, or closed.
+const SIDE_KEY = 'flow_job_side';
+const SIDE_TABS = ['activity', 'review', 'closed'];
 const SYSTEM_NAME = { seazona: 'Seazona', xero: 'Xero' };
 // A job's events (server/core/ledger.js), in plain words.
 const ACTIVITY = {
@@ -85,6 +90,17 @@ function saveFolded(folded) {
   try { localStorage.setItem(FOLDED_KEY, JSON.stringify(folded)); } catch { /* a convenience only */ }
 }
 
+function readSide() {
+  try {
+    const value = localStorage.getItem(SIDE_KEY);
+    return SIDE_TABS.includes(value) ? value : 'activity';
+  } catch { return 'activity'; }
+}
+
+function saveSide(tab) {
+  try { localStorage.setItem(SIDE_KEY, tab ?? 'closed'); } catch { /* a convenience only */ }
+}
+
 
 const WARN_ICON = '<svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 1.5 15 14H1z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linejoin="round"/><path d="M8 6v3.6" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/><circle cx="8" cy="11.6" r=".9" fill="currentColor"/></svg>';
 const PERSON_ICON = '<svg width="13" height="13" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="5.5" r="3" fill="none" stroke="currentColor" stroke-width="1.3"/><path d="M2.5 14c.6-2.8 2.8-4.3 5.5-4.3s4.9 1.5 5.5 4.3" fill="none" stroke="currentColor" stroke-width="1.3" stroke-linecap="round"/></svg>';
@@ -116,9 +132,8 @@ export async function renderJobs(main, ui) {
   const controls = h('div', { class: 'fx-viewbar', role: 'group', 'aria-label': 'Group, sort and filter' });
   // In the list, ticked rows get the same floating bar as Invoices.
   const bulk = bulkBar(ui, { label: 'Ticked jobs' });
-  main.classList.add('fx-main--wide');
   main.append(
-    pageHeader('Jobs', { subtitle: 'Every job in the lab system, by its status there.' }),
+    pageHeader('Jobs'),
     h('div', { class: 'fx-toolbar fx-toolbar--plain' }, controls, h('div', { class: 'fx-toolbar__end' }, find.element, toggle)),
     host,
     bulk.element);
@@ -1086,25 +1101,8 @@ export async function renderJobs(main, ui) {
     if (!o) return [];
     if (o.invoiceId) {
       const label = o.invoiceStatus === 'draft' ? 'Open draft invoice' : `Open invoice ${o.invoiceNumber ?? ''}`.trim();
-      const open = h('a', { class: 'fx-btn', href: `/invoices/${o.invoiceId}`, onclick: (event) => { close(); ui.go(event); } }, label);
-      // Only the job changed and the draft is not sent (ledger.js): one tap
-      // puts the job's new lines on Flow's own draft. Nothing goes elsewhere.
-      if (!o.canUseNewLines) return [open];
-      const system = SYSTEM_NAME[job.sourceSystem] ?? job.sourceSystem;
-      return [h('button', {
-        class: 'fx-btn fx-btn--primary', type: 'button',
-        onclick: async (event) => {
-          event.currentTarget.disabled = true;
-          try {
-            await flow(`/api/invoicing/jobs/${o.id}/use-new-lines`, { method: 'POST', body: '{}' });
-            ui.toast(`The draft invoice now matches ${system}.`, 'success');
-          } catch (error) {
-            ui.toast(error.message, 'danger');
-          }
-          close();
-          await load();
-        },
-      }, `Adopt ${system} changes`), open];
+      // A changed job is accepted in the panel's Review sidecar.
+      return [h('a', { class: 'fx-btn', href: `/invoices/${o.invoiceId}`, onclick: (event) => { close(); ui.go(event); } }, label)];
     }
     // Flow's own stage: a person marks a job ready to invoice, or an
     // automation does (Settings, Automations).
@@ -1147,15 +1145,20 @@ export async function renderJobs(main, ui) {
 
   // The job's page: a large panel over the board, like a task page. A
   // breadcrumb, the client's name, the stage, the job's fields, what to fix
-  // and its lines; its activity at the side (below on a phone). Esc, the X
-  // or a click outside closes it. `atFix` scrolls to what to fix. The job's
-  // custom fields can be changed here (in Flow only), and its stage moved
-  // (a hand-off to the work system).
+  // and its lines. At the side (below on a phone), the sidecar: Activity,
+  // and Review when the job changed after its draft (what changed, and
+  // Accept change). The sidecar closes, and the main area takes its room.
+  // Esc, the X or a click outside closes the panel. `atFix` scrolls to what
+  // to fix, and opens Review when there is one. The job's custom fields can
+  // be changed here (in Flow only), and its stage moved (a hand-off to the
+  // work system).
   function openJob(job, { atFix = false } = {}) {
     const o = job.obligation;
     const stage = invoiceStage(o);
     const found = problemsOf(job);
     const choose = found.find((f) => f.go === 'choose') ?? null;
+    // The job changed after its draft: the sidecar has a Review tab.
+    const reviewable = Boolean(o?.invoiceId) && found.some((f) => f.go === 'review');
     const system = SYSTEM_NAME[job.sourceSystem] ?? job.sourceSystem;
     const status = job.status ?? NO_STATUS;
     const late = isLate(job);
@@ -1170,9 +1173,14 @@ export async function renderJobs(main, ui) {
       : choose ? h('span', { class: 'fx-task__none' }, svg(WARN_ICON), 'Needs invoice')
         : stage ? INVOICE_STAGES[stage] : o ? 'Not ready to invoice' : 'No invoice yet';
     const rest = found.filter((f) => f.go !== 'choose');
+    // One short line a fix: its label, what is wrong, and its link. What to
+    // do is the link's tip.
     const fixBox = rest.length ? h('section', { class: 'fx-task__fix', 'aria-label': 'Fix' },
       h('h3', {}, 'Fix'),
-      rest.map((f) => h('div', { class: 'fx-task__fixrow' }, h('span', {}, [f.text, f.todo].filter(Boolean).join(' ')), fixLink(f.go)))) : null;
+      rest.map((f) => {
+        const go = fixLink(f.go, f.todo);
+        return h('div', { class: 'fx-task__fixrow', title: go ? null : f.todo }, h('strong', {}, f.label), h('span', {}, f.text), go);
+      })) : null;
     // No invoice, and the match is unclear: one line and two buttons. The
     // possible matches are compared on the Reconcile page, not here.
     const chooseBox = choose ? h('section', { class: 'fx-task__choose', 'aria-label': 'Invoice' },
@@ -1200,8 +1208,12 @@ export async function renderJobs(main, ui) {
     }
     // Each fix's link: Flow's own invoice, the job in the work system, or
     // the Flow page where the fix is made (job-board.js GO).
-    function fixLink(go) {
-      const inFlow = (href, text) => h('a', { class: 'fx-task__link', href, onclick: (event) => { close(); ui.go(event); } }, text);
+    function fixLink(go, tip = null) {
+      const inFlow = (href, text) => h('a', { class: 'fx-task__link', href, title: tip, onclick: (event) => { close(); ui.go(event); } }, text);
+      if (go === 'review' && reviewable) {
+        return h('button', { class: 'fx-task__link fx-task__linkbtn', type: 'button', title: tip, onclick: () => side.open('review') }, 'Review');
+      }
+      if (go === 'review' && o?.invoiceId) return inFlow(`/invoices/${o.invoiceId}`, 'Open invoice');
       if (go === 'invoice' && o?.invoiceId) return inFlow(`/invoices/${o.invoiceId}`, 'Open invoice');
       if (go === 'work' && job.link?.url) {
         return h('a', { class: 'fx-task__link', href: job.link.url, target: '_blank', rel: 'noopener' }, job.link.exact ? `Open case in ${system} ↗` : `Open ${system} ↗`);
@@ -1213,12 +1225,55 @@ export async function renderJobs(main, ui) {
     }
     const lines = job.lines ?? [];
     const activity = h('ol', {}, h('li', { class: 'fx-dim' }, 'Loading…'));
+    const activityBody = h('div', { class: 'fx-task__activity' },
+      o ? activity : h('p', { class: 'fx-dim' }, `Flow has no invoice record for this job yet. It makes one when ${system} reports the job complete.`));
+    // Review: the job's change as the invoice page shows it (job-change.js),
+    // read from the invoice when the sidecar first needs it.
+    const reviewBody = h('div', { class: 'fx-task__review' }, h('p', { class: 'fx-dim' }, 'Loading…'));
+    let reviewRead = false;
+    const readReview = () => {
+      if (reviewRead) return;
+      reviewRead = true;
+      flow(`/api/invoicing/invoices/${o.invoiceId}`).then(({ invoice }) => drawReview(invoice))
+        .catch(() => reviewBody.replaceChildren(h('p', {}, 'Flow could not read the change.')));
+    };
+    function drawReview(invoice) {
+      const change = invoice?.jobChange ?? null;
+      reviewBody.replaceChildren(change
+        ? jobChangeReview(ui, change, { money: formatCents, canAccept: state.canDraft, done: reopen })
+        : h('p', { class: 'fx-dim' }, `The draft matches ${system}.`));
+    }
+    // After Accept change or a recheck: the board reads again, and this
+    // job's panel opens again with its new facts.
+    async function reopen() {
+      await load();
+      const fresh = state.jobs.find((j) => jobKey(j) === jobKey(job));
+      close();
+      if (fresh) openJob(fresh);
+    }
+    const sideButton = h('button', {
+      class: 'fx-btn fx-btn--ghost fx-btn--icon', type: 'button', 'aria-label': 'Side panel', title: 'Side panel', 'aria-pressed': 'false',
+      onclick: () => (side.isOpen() ? side.close() : side.open(readSide() === 'review' && reviewable ? 'review' : 'activity')),
+    }, lucide(h, 'panel-right'));
+    const side = sidecar(h, {
+      label: 'Job side panel',
+      tabs: [
+        { id: 'activity', label: 'Activity', icon: 'history', render: () => activityBody },
+        reviewable ? { id: 'review', label: 'Review', icon: 'git-compare', mark: true, render: () => { readReview(); return reviewBody; } } : null,
+      ].filter(Boolean),
+      onChange: (tab) => {
+        saveSide(tab);
+        sideButton.setAttribute('aria-pressed', String(Boolean(tab)));
+      },
+    });
+    side.element.classList.add('fx-task__side');
     element.append(h('div', { class: 'fx-task__grid' },
       h('div', { class: 'fx-task__main' },
         h('header', { class: 'fx-task__head' },
           h('nav', { class: 'fx-task__crumb', 'aria-label': 'Breadcrumb' },
             h('span', {}, 'Jobs'), h('span', { class: 'fx-task__slash', 'aria-hidden': 'true' }, '/'), h('span', {}, status)),
-          h('button', { class: 'fx-btn fx-btn--ghost fx-btn--icon', type: 'button', 'aria-label': 'Close', onclick: close }, '✕')),
+          h('div', { class: 'fx-task__tools' }, sideButton,
+            h('button', { class: 'fx-btn fx-btn--ghost fx-btn--icon', type: 'button', 'aria-label': 'Close', title: 'Close', onclick: close }, '✕'))),
         h('h2', { class: 'fx-task__title' }, clientOf(job)),
         h('div', { class: 'fx-task__stage' }, stagePill(status)),
         h('dl', { class: 'fx-task__fields' },
@@ -1255,13 +1310,14 @@ export async function renderJobs(main, ui) {
               h('td', { class: 'fx-num' }, job.totalCents == null ? '—' : formatCents(job.totalCents)))))
             : h('p', { class: 'fx-dim' }, 'No lines.')),
         h('div', { class: 'fx-task__actions' }, actions(job, close))),
-      h('aside', { class: 'fx-task__activity', 'aria-label': 'Activity' },
-        h('h3', {}, 'Activity'),
-        o ? activity : h('p', { class: 'fx-dim' }, `Flow has no invoice record for this job yet. It makes one when ${system} reports the job complete.`))));
+      side.element));
     element.addEventListener('click', (event) => { if (event.target === element) close(); });
     element.addEventListener('close', () => element.remove());
     document.body.append(element);
     element.showModal();
+    const last = readSide();
+    if (atFix && reviewable) side.open('review');
+    else if (last !== 'closed') side.open(last === 'review' && reviewable ? 'review' : 'activity');
     if (atFix && (chooseBox ?? fixBox)) (chooseBox ?? fixBox).scrollIntoView({ block: 'start' });
     if (!o) return;
     const when = (iso) => new Date(iso).toLocaleString('en-AU', { day: 'numeric', month: 'short', hour: 'numeric', minute: '2-digit' });

package/server/ui/monitoring.js

@@ -99,6 +99,7 @@ export async function startMonitoring({ flow, person }) {
     integrations,
     tracesSampleRate,
     beforeSendSpan: scrubSpan,
+    initialScope: { tags: config.tags ?? {} },
   });
   Sentry.getClient()?.on('beforeSendFeedback', tagNotify);
   // Who reported or met the error, so the lab can follow up.

package/server/ui/price-list.js

@@ -29,7 +29,7 @@ export async function renderPriceList(main, ui) {
   const addButton = h('button', { class: 'fx-btn fx-btn--primary', type: 'button', disabled }, 'Add code');
   const reconcileButton = h('button', { class: 'fx-btn fx-btn--ghost', type: 'button', hidden: true, onclick: () => ui.go('/price-list/reconcile') }, 'Reconcile');
   const alerts = alertStrip(ui, 'price-list');
-  main.append(pageHeader('Price list', { subtitle: 'The codes and prices that Flow puts on invoice lines.', actions: [reconcileButton, addButton] }), alerts.element, host);
+  main.append(pageHeader('Price list', { help: { href: DOCS, label: 'How the price list works' }, actions: [reconcileButton, addButton] }), alerts.element, host);
 
   let data = null;
   let query = '';
@@ -176,8 +176,7 @@ export async function renderPriceList(main, ui) {
       table,
     ];
     const settings = h('section', { class: 'fx-set fx-price__settings' }, h('h2', { class: 'fx-set__title' }, 'Invoice lines'), h('div', { class: 'fx-skeleton' }));
-    linePriceRow().then((r) => settings.replaceChildren(settings.firstChild, r,
-      h('p', { class: 'fx-dim', style: { margin: '8px 0 0' } }, h('a', { href: DOCS, target: '_blank', rel: 'noopener' }, 'How the price list works'))));
+    linePriceRow().then((r) => settings.replaceChildren(settings.firstChild, r));
     sections.push(settings);
     host.replaceChildren(...sections.filter(Boolean));
     // Opened from Reconcile's "Edit code": that code's dialog, once.

package/server/ui/price-reconcile.js

@@ -26,17 +26,16 @@ export async function renderPriceReconcile(main, ui) {
   const icon = (name, label) => lucide(h, name, label);
   let view = new URLSearchParams(location.search).get('view') === 'list' ? 'list' : 'card';
   const host = h('div', { class: 'fx-xi fx-prc' }, h('p', { class: 'fx-dim' }, 'Loading…'));
-  const subtitle = h('span', {});
+  const tally = h('span', {});
   const toggle = (name, label, glyph) => h('button', {
     class: 'fx-xi__view', type: 'button', role: 'tab', 'aria-selected': String(view === name), 'aria-label': label, title: label, 'data-view': name,
     onclick: () => setView(name),
   }, icon(glyph));
   const bulk = bulkBar(ui, { label: 'Ticked records' });
   main.append(
-    h('nav', { class: 'fx-crumbs', 'aria-label': 'Breadcrumb' },
-      h('a', { href: '/price-list', onclick: (event) => ui.go(event) }, 'Price list'), h('span', { 'aria-hidden': 'true' }, '›'), h('span', {}, 'Reconcile')),
+    ui.crumbs(['/price-list', 'Price list'], 'Reconcile'),
     ui.pageHeader('Reconcile prices', {
-      subtitle,
+      count: tally,
       actions: [h('div', { class: 'fx-xi__views', role: 'tablist', 'aria-label': 'View' }, toggle('card', 'One at a time', 'square'), toggle('list', 'List, tick many', 'list-checks'))],
     }),
     host, bulk.element);
@@ -129,13 +128,13 @@ export async function renderPriceReconcile(main, ui) {
     if (!data) return;
     bulk.draw({ count: 0 });
     if (!data.systems.length) {
-      subtitle.replaceChildren('');
+      tally.replaceChildren('');
       host.replaceChildren(h('p', { class: 'fx-empty' }, 'No integration with a price list is on. Flow uses its own list alone.'),
         h('a', { href: '/price-list', onclick: (event) => ui.go(event) }, '← Price list'));
       return;
     }
     if (!rows.length) {
-      subtitle.replaceChildren('');
+      tally.replaceChildren('');
       host.replaceChildren(h('div', { class: 'fx-xi__done' }, icon('check-check'), h('p', {}, 'Every record has a code, and every price agrees.'),
         h('a', { href: '/price-list', onclick: (event) => ui.go(event) }, 'Price list')));
       return;
@@ -184,7 +183,7 @@ export async function renderPriceReconcile(main, ui) {
   // One record (or one differing code) at a time.
   function drawCard() {
     const row = rows[at];
-    subtitle.replaceChildren(`${rows.length} to check`);
+    tally.replaceChildren(`${rows.length} to check`);
     const next = () => { at = (at + 1) % rows.length; pick = 0; chosen = null; drawCard(); };
     const record = row.record;
     const item = row.kind === 'differs' ? row.item : chosen ?? row.candidates[pick]?.item ?? null;
@@ -267,7 +266,7 @@ export async function renderPriceReconcile(main, ui) {
 
   // Every record and code to check; ticked rows go from the bulk bar.
   function drawList() {
-    subtitle.replaceChildren(`${rows.length} to check`);
+    tally.replaceChildren(`${rows.length} to check`);
     const ticked = new Set();
     const boxes = new Map();
     const picked = () => rows.filter((r) => ticked.has(r.key));

package/server/ui/routes.js

@@ -21,7 +21,7 @@ const themeDir = join(here, '..', 'theme');
 const logoDir = join(here, 'logos');
 const LOGO_FILES = new Set(['xero.svg', 'seazona.svg', 'sentry.svg']);
 const THEME_FILES = new Set(['themes.js', 'color-contrast.js', 'openclaw-palettes.js', 'font-families.js']);
-const UI_FILES = new Set(['flow.css', 'appearance.js', 'clerk-appearance.js', 'app.js', 'invoicing.js', 'invoice-notes.js', 'job-change.js', 'invoicing-settings.js', 'automations.js', 'invoice-rules.js', 'line-mappings.js', 'price-list.js', 'price-match.js', 'price-reconcile.js', 'custom-fields.js', 'jobs.js', 'job-board.js', 'reconcile.js', 'xero-import.js', 'job-view.js', 'monitoring.js', 'search.js', 'alerts.js', 'bulk-bar.js', 'view-bar.js', 'flow-mark.svg']);
+const UI_FILES = new Set(['flow.css', 'appearance.js', 'clerk-appearance.js', 'app.js', 'invoicing.js', 'invoice-notes.js', 'job-change.js', 'sidecar.js', 'invoicing-settings.js', 'automations.js', 'invoice-rules.js', 'line-mappings.js', 'price-list.js', 'price-match.js', 'price-reconcile.js', 'custom-fields.js', 'jobs.js', 'job-board.js', 'reconcile.js', 'xero-import.js', 'job-view.js', 'monitoring.js', 'search.js', 'alerts.js', 'bulk-bar.js', 'view-bar.js', 'tip.js', 'flow-mark.svg']);
 const iconDir = join(dirname(require.resolve('lucide-static/package.json')), 'icons');
 const ICON_FILE = /^[a-z0-9]+(?:-[a-z0-9]+)*\.svg$/;
 const MAX_AGE = '1h';

package/server/ui/sidecar.js

@@ -0,0 +1,72 @@
+// The sidecar, as in ClickUp: a panel at the right of a page or a dialog.
+// The Custom fields manager opens it over its table (`overlay`); a job's
+// panel keeps it as its right column, with tabs (Activity, Review). Closed,
+// it takes no room, so the main area gets the full width.
+//
+// sidecar(h, { label, overlay, escape, tabs, onChange }) answers
+// { element, isOpen, open, show, close, tab, setTabs }:
+//   open(id)     selects tab `id` (or the first) and draws its `render()`
+//   show(node)   draws one node with no tabs (the overlay's own form)
+//   close()      hides it and empties it
+// `tabs` is [{ id, label, icon, render }]; each tab is an icon and one word.
+// `escape` closes it on Esc when no dialog or menu is open over the page.
+// `onChange(id)` hears each open (the tab id) and close (null).
+
+import { lucide } from '/assets/ui/custom-fields.js';
+
+export function sidecar(h, { label, overlay = false, escape = false, tabs = [], onChange = null } = {}) {
+  const element = h('aside', { class: `fx-sidecar${overlay ? ' fx-sidecar--over' : ''}`, 'aria-label': label, hidden: true });
+  let list = tabs;
+  let current = null;
+
+  const closeButton = () => h('button', { class: 'fx-sidecar__close', type: 'button', 'aria-label': 'Close', title: 'Close', onclick: () => api.close() }, lucide(h, 'x'));
+
+  function drawTabs() {
+    const head = h('header', { class: 'fx-sidecar__head' },
+      h('div', { class: 'fx-sidecar__tabs', role: 'tablist', 'aria-label': label },
+        list.map((t) => h('button', {
+          class: 'fx-sidecar__tab', type: 'button', role: 'tab', 'data-tab': t.id,
+          'aria-selected': String(t.id === current), onclick: () => api.open(t.id),
+        }, lucide(h, t.icon), h('span', {}, t.label), t.mark ? h('span', { class: 'fx-sidecar__mark', 'aria-hidden': 'true' }) : null))),
+      closeButton());
+    const tab = list.find((t) => t.id === current);
+    element.replaceChildren(head, h('div', { class: 'fx-sidecar__body', role: 'tabpanel' }, tab?.render?.() ?? null));
+  }
+
+  const api = {
+    element,
+    isOpen: () => !element.hidden,
+    tab: () => (element.hidden ? null : current),
+    open(id = null) {
+      current = list.find((t) => t.id === id)?.id ?? list[0]?.id ?? null;
+      drawTabs();
+      element.hidden = false;
+      onChange?.(current);
+    },
+    show(node) {
+      current = null;
+      element.replaceChildren(node);
+      element.hidden = false;
+    },
+    close() {
+      if (element.hidden) return;
+      element.hidden = true;
+      element.replaceChildren();
+      current = null;
+      onChange?.(null);
+    },
+    // New tabs (a tab's data came in): an open tab draws again.
+    setTabs(next) {
+      list = next;
+      if (!element.hidden && current) drawTabs();
+    },
+    closeButton,
+  };
+
+  if (escape) {
+    document.addEventListener('keydown', (event) => {
+      if (event.key === 'Escape' && element.isConnected && !element.hidden && !document.querySelector('dialog[open], .fx-pop:popover-open')) api.close();
+    });
+  }
+  return api;
+}

package/server/ui/tip.js

@@ -0,0 +1,99 @@
+// Tips: every control that shows only an icon says its name on hover and on
+// keyboard focus, in one small tip beside it. One listener on the document
+// serves the whole app, so a new icon button needs only a name:
+//
+//   data-tip="Clear"       the tip, when it differs from the spoken name
+//   aria-label="Close"     an icon-only control's name is its tip
+//   title="Search"         taken over as the tip (no second, native tip)
+//
+// A control with words on it shows no tip. Clerk's own components keep their
+// own tips. The tip floats on <body>, so a scrolling list cannot cut it off.
+
+const INTERACTIVE = 'button, a[href], [role="button"], [role="tab"], [role="radio"], [role="menuitem"], [role="switch"], summary';
+const CANDIDATE = `[data-tip], ${INTERACTIVE.split(', ').map((s) => `${s}[aria-label], ${s}[title]`).join(', ')}, [role="img"][aria-label], [role="img"][title]`;
+
+// True when the element shows no word of its own: only icons or a symbol.
+export function iconOnly(text) {
+  return !/[\p{L}\p{N}]/u.test(String(text ?? ''));
+}
+
+// The tip for this element, or null. `el` needs getAttribute, textContent
+// and closest (a DOM element, or a test's stand-in).
+export function tipText(el) {
+  if (!el || el.closest?.('[class*="cl-"]')) return null;
+  if (!iconOnly(el.textContent) && !el.getAttribute('data-tip')) return null;
+  return el.getAttribute('title') || el.getAttribute('data-tip') || el.getAttribute('aria-label') || null;
+}
+
+// Marks a control icon-only: its spoken name and its tip. Returns the node.
+export function named(node, label, tip = label) {
+  node.setAttribute('aria-label', label);
+  node.setAttribute('data-tip', tip);
+  node.removeAttribute('title');
+  return node;
+}
+
+let bubble = null;
+let anchor = null;
+
+function place() {
+  if (!bubble || !anchor) return;
+  const box = anchor.getBoundingClientRect();
+  const tip = bubble.getBoundingClientRect();
+  const gap = 6;
+  // A folded sidebar's icons take their tip at the right, as in ClickUp.
+  if (anchor.dataset.tipSide === 'right') {
+    bubble.style.transform = `translate(${Math.round(box.right + gap)}px, ${Math.round(box.top + box.height / 2 - tip.height / 2)}px)`;
+    return;
+  }
+  const above = box.top - tip.height - gap;
+  const top = above >= 4 ? above : box.bottom + gap;
+  const left = Math.min(Math.max(4, box.left + box.width / 2 - tip.width / 2), window.innerWidth - tip.width - 4);
+  bubble.style.transform = `translate(${Math.round(left)}px, ${Math.round(top)}px)`;
+}
+
+function show(el) {
+  const text = tipText(el);
+  if (!text) return;
+  // A native title would show a second tip after a pause, so the tip takes
+  // it over (a title set again later wins).
+  if (el.hasAttribute('title')) {
+    if (!el.hasAttribute('aria-label')) el.setAttribute('aria-label', el.getAttribute('title'));
+    el.setAttribute('data-tip', el.getAttribute('title'));
+    el.removeAttribute('title');
+    return show(el);
+  }
+  if (!bubble) {
+    bubble = document.createElement('div');
+    bubble.className = 'fx-tip';
+    bubble.setAttribute('role', 'tooltip');
+    bubble.setAttribute('aria-hidden', 'true');
+  }
+  bubble.textContent = text;
+  anchor = el;
+  (el.closest('dialog[open]') ?? document.body).append(bubble);
+  place();
+}
+
+function hide(el) {
+  if (el && el !== anchor) return;
+  anchor = null;
+  bubble?.remove();
+}
+
+export function startTips() {
+  document.addEventListener('pointerover', (event) => {
+    if (event.pointerType === 'touch') return;
+    const el = event.target.closest?.(CANDIDATE);
+    if (el && el !== anchor) show(el);
+    else if (!el) hide();
+  });
+  document.addEventListener('focusin', (event) => {
+    const el = event.target.closest?.(CANDIDATE);
+    if (el && el.matches(':focus-visible')) show(el);
+  });
+  document.addEventListener('focusout', (event) => hide(event.target.closest?.(CANDIDATE)));
+  document.addEventListener('pointerdown', () => hide());
+  document.addEventListener('keydown', (event) => { if (event.key === 'Escape') hide(); });
+  window.addEventListener('scroll', () => hide(), true);
+}

package/server/ui/xero-import.js

@@ -49,7 +49,7 @@ export async function renderXeroImport(main, ui) {
   const history = params.get('show') === 'all';
   const icon = (name, label) => lucide(h, name, label);
   const host = h('div', { class: 'fx-xi' }, h('p', { class: 'fx-dim' }, 'Loading…'));
-  const subtitle = h('span', {});
+  const tally = h('span', {});
   const actions = [];
   let view = params.get('view') === 'list' ? 'list' : 'card';
   if (!history) {
@@ -66,11 +66,8 @@ export async function renderXeroImport(main, ui) {
     renderReview();
   }
   main.append(
-    h('nav', { class: 'fx-crumbs', 'aria-label': 'Breadcrumb' },
-      h('a', { href: '/integrations', onclick: (event) => ui.go(event) }, 'Integrations'), h('span', { 'aria-hidden': 'true' }, '›'),
-      h('a', { href: '/integrations/xero', onclick: (event) => ui.go(event) }, 'Xero'), h('span', { 'aria-hidden': 'true' }, '›'),
-      h('span', {}, history ? 'History' : 'Review')),
-    ui.pageHeader(history ? 'Xero history' : 'Review', { subtitle, actions }),
+    ui.crumbs(['/integrations', 'Integrations'], ['/integrations/xero', 'Xero'], history ? 'History' : 'Review'),
+    ui.pageHeader(history ? 'Xero history' : 'Review', { count: tally, actions }),
     host);
 
   let organisationId;
@@ -117,7 +114,7 @@ export async function renderXeroImport(main, ui) {
       return;
     }
     if (!rows.length) {
-      subtitle.replaceChildren('');
+      tally.replaceChildren('');
       host.replaceChildren(h('div', { class: 'fx-xi__done' }, icon('check-check'), h('p', {}, 'Nothing to check.'), go('/xero-import?show=all', 'Xero history')));
       return;
     }
@@ -134,7 +131,7 @@ export async function renderXeroImport(main, ui) {
       const fit = flowFit(row, pick);
       const bar = h('span', { class: 'fx-xi__progress', role: 'progressbar', 'aria-valuemin': '1', 'aria-valuemax': String(rows.length), 'aria-valuenow': String(at + 1) },
         h('span', { style: { width: `${((at + 1) / rows.length) * 100}%` } }));
-      subtitle.replaceChildren(h('span', { class: 'fx-xi__count' }, bar, `${at + 1} / ${rows.length}`));
+      tally.replaceChildren(h('span', { class: 'fx-xi__count' }, bar, `${at + 1} / ${rows.length}`));
       const days = daysApart(row.issuedOn, fit.date);
       const facts = [
         ['hash', 'Number', h('span', { class: 'fx-num' }, row.number ?? '—'), h('span', { class: 'fx-num' }, fit.name), null],
@@ -195,7 +192,7 @@ export async function renderXeroImport(main, ui) {
 
   // Every one to check, best fit beside it; ticked rows go from the bulk bar.
   function reviewList(rows) {
-    subtitle.replaceChildren(`${rows.length} to check`);
+    tally.replaceChildren(`${rows.length} to check`);
     const ticked = new Set();
     const boxes = new Map();
     const drawBar = () => {
@@ -315,7 +312,7 @@ export async function renderXeroImport(main, ui) {
         return;
       }
       const total = Object.values(page.counts).reduce((a, b) => a + b, 0);
-      subtitle.replaceChildren(h('span', { class: 'fx-xi__count' }, icon('check', 'In Flow'), `${page.counts.linked} / ${total}`));
+      tally.replaceChildren(h('span', { class: 'fx-xi__count' }, icon('check', 'In Flow'), `${page.counts.linked} / ${total}`));
       shown = offset === 0 ? page.rows : [...shown, ...page.rows];
       const rows = page.rows.map(rowOf);
       if (offset === 0) body.replaceChildren(...(rows.length ? rows : [h('tr', {}, h('td', { colspan: '8', class: 'fx-empty' }, q.trim() ? 'No match.' : 'No Xero invoices copied yet.'))]));