@arcforgelabs/flow 2026.10.43 → 2026.10.44

package/server/ui/invoicing.js

@@ -10,7 +10,11 @@ import { bulkBar } from '/assets/ui/bulk-bar.js';
 import { draftNote, sendModeNote } from '/assets/ui/invoice-notes.js';
 import { caseNumber } from '/assets/ui/job-board.js';
 import { jobChangeReview } from '/assets/ui/job-change.js';
-import { findBox } from '/assets/ui/view-bar.js';
+import { columnTable, rowCells, viewSaver } from '/assets/ui/columns.js';
+import { filterJobs, INVOICE_COLUMNS, normaliseListView } from '/assets/ui/job-view.js';
+import { INVOICE_FILTER_FIELDS, normaliseInvoicesView } from '/assets/ui/list-views.js';
+import { savedViews } from '/assets/ui/saved-views.js';
+import { findBox, today, viewBar } from '/assets/ui/view-bar.js';
 
 // The tabs, left to right (server/api/invoicing.js, TABS): Pending (a
 // person must look), Ready (checks pass), then the accounting system's
@@ -110,14 +114,57 @@ const showDate = (iso) => (iso ? new Date(`${iso}T00:00:00`).toLocaleDateString(
 
 // ── The list ───────────────────────────────────────────────────────────────
 
+// The filter's fields: list-views.js (the server checks saved views with them).
+const FILTER_FIELDS = INVOICE_FILTER_FIELDS;
+const PROBLEM_OPS = { yes: 'Has one', no: 'Has none' };
+const FILTER_KEY = 'flow_invoice_filters';
+const filterKind = (field) => FILTER_FIELDS[field]?.kind ?? null;
+
+// An invoice's value for a filter field, as the filter compares it.
+export function invoiceValue(invoice, field) {
+  switch (field) {
+    case 'client': return invoice.contactName ?? null;
+    case 'number': return invoice.number ?? null;
+    case 'reference': return invoice.reference ?? null;
+    case 'date': return invoice.issueDate ?? invoice.createdAt?.slice(0, 10) ?? null;
+    case 'total': return invoice.totalCents == null ? null : invoice.totalCents / 100;
+    case 'problem': return (invoice.problems?.length ?? 0) > 0;
+    default: return null;
+  }
+}
+
+// The invoices a filter view keeps.
+export const keptInvoices = (invoices, view, now = today()) => filterJobs(invoices, view, { valueOf: invoiceValue, kindOf: filterKind, today: now });
+
+function readFilters() {
+  try { return normaliseInvoicesView(JSON.parse(localStorage.getItem(FILTER_KEY))); } catch { return normaliseInvoicesView(null); }
+}
+
 export async function renderInvoiceList(main, ui) {
-  const { h, flow, pageHeader, notice, go, toast } = ui;
+  const { h, flow, listHead, listFrame, notice, go, toast } = ui;
   const saved = OLD_TAB[sessionStorage.getItem('flow_invoice_tab')] ?? sessionStorage.getItem('flow_invoice_tab');
   // Back from an invoice comes here with the tab, search and scroll it left.
   const back = readNav();
   const returning = sessionStorage.getItem(NAV_BACK) === '1';
   sessionStorage.removeItem(NAV_BACK);
-  const state = { status: TABS.some(([id]) => id === saved) ? saved : 'ready', q: returning ? back?.q ?? '' : '', ticked: new Set() };
+  const state = {
+    status: TABS.some(([id]) => id === saved) ? saved : 'ready', q: returning ? back?.q ?? '' : '', ticked: new Set(), view: readFilters(),
+    columns: normaliseListView(ui.me?.views?.invoices, INVOICE_COLUMNS),
+  };
+  // The list's columns: resize, move, hide, kept with the account. A tab
+  // has some of them (`available`, set as it draws).
+  let available = Object.keys(INVOICE_COLUMNS);
+  const saveColumns = viewSaver(ui, 'invoices');
+  const heads = columnTable(h, {
+    order: () => state.columns.columns,
+    widths: () => state.columns.widths,
+    change: (patch) => {
+      state.columns = normaliseListView({ ...state.columns, ...patch }, INVOICE_COLUMNS);
+      saveColumns(state.columns);
+      if (raw) draw(raw);
+    },
+    hidden: () => available.filter((id) => !state.columns.columns.includes(id)).map((id) => ({ id, label: INVOICE_COLUMNS[id] })),
+  });
   const tabs = h('div', { class: 'fx-tabs', role: 'tablist' });
   let timer;
   const find = findBox(h, {
@@ -127,31 +174,50 @@ export async function renderInvoiceList(main, ui) {
       timer = setTimeout(() => { state.q = words.trim(); load(); }, 200);
     },
   });
+  // The Filter chip: the same panel as on Jobs and Reconcile (view-bar.js).
+  // It filters the rows of the tab shown, on this device.
+  // A change to the filter: kept in this browser, and drawn.
+  function setView(patch) {
+    state.view = normaliseInvoicesView({ ...state.view, ...patch });
+    try { localStorage.setItem(FILTER_KEY, JSON.stringify(state.view)); } catch { /* the page still works, it forgets */ }
+    views.draw();
+    if (raw) draw(raw);
+  }
+  // The person's named views (saved-views.js): their default opens on a
+  // new visit.
+  const views = savedViews(ui, { page: 'invoices', current: () => state.view, apply: setView });
+  const opening = views.opening();
+  if (opening) state.view = normaliseInvoicesView(opening);
+  views.draw();
+  const labels = (list) => [...new Set(list.filter(Boolean))].sort((a, b) => a.localeCompare(b)).map((v) => ({ value: v, label: v }));
+  const filterMenu = viewBar(h).filterMenu({
+    fields: () => Object.entries(FILTER_FIELDS).map(([value, f]) => ({ value, label: f.label, icon: f.icon })),
+    kindOf: filterKind,
+    opsOf: (field) => (field === 'problem' ? PROBLEM_OPS : null),
+    choicesOf: (field) => (field === 'client' ? labels((raw?.invoices ?? []).map((i) => i.contactName)) : []),
+    view: () => state.view,
+    change: setView,
+    first: 'client',
+    empty: 'No filters. Every invoice in the tab shows.',
+  });
+  const controls = h('div', { class: 'fx-viewbar', role: 'group', 'aria-label': 'Filter' }, ...filterMenu.node);
   const host = h('div', { class: 'fx-panel' }, h('div', { class: 'fx-skeleton' }));
   const bulk = bulkBar(ui);
   const context = await flow('/api/invoicing/context').catch(() => ({ canIssue: false }));
   let body = null;
+  let raw = null;
   const openTab = (id) => { state.status = id; state.ticked.clear(); sessionStorage.setItem('flow_invoice_tab', id); load(); };
   const alerts = alertStrip(ui, 'invoices', { onTab: openTab });
   // The tabs and search stay at the top while the rows scroll up under them;
   // the bulk bar floats at the foot (ClickUp's layout). Sending is a bulk
   // action: tick rows (the head tick takes every row shown), then Send.
-  const head = h('div', { class: 'fx-listhead' }, h('div', { class: 'fx-toolbar' }, tabs, find.element));
-  const edge = h('div', { class: 'fx-listhead__edge', 'aria-hidden': 'true' });
-  main.append(
-    pageHeader('Invoices', {
-      actions: [h('a', { class: 'fx-btn fx-btn--primary', href: '/invoices/new', onclick: go }, 'New invoice')],
-    }),
-    alerts.element,
-    edge,
-    head,
-    host,
-    bulk.element);
-  // A shadow under the head shows once rows scroll under it.
-  if (typeof IntersectionObserver === 'function') {
-    new IntersectionObserver(([entry]) => head.toggleAttribute('data-stuck', !entry.isIntersecting), { rootMargin: `-${head.offsetTop > 0 && window.matchMedia?.('(max-width: 820px)').matches ? 61 : 1}px 0px 0px 0px` }).observe(edge);
-  }
-
+  const head = listHead('Invoices', {
+    actions: [h('a', { class: 'fx-btn fx-btn--primary', href: '/invoices/new', onclick: go }, 'New invoice')],
+    views: views.element, start: tabs, end: [controls, find.element], line: true, sticky: true,
+  });
+  const [title, ...top] = head.nodes;
+  const frame = listFrame(main, host);
+  main.append(title, alerts.element, ...top, frame.element, bulk.element);
 
   const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
   // The bulk bar for the ticked rows: what a person can do with this view.
@@ -346,20 +412,25 @@ export async function renderInvoiceList(main, ui) {
   }
 
   async function draw(answer) {
-    body = answer;
+    raw = answer;
+    filterMenu.draw();
+    body = { ...answer, invoices: keptInvoices(answer.invoices, state.view) };
     const shown = new Set(body.invoices.map((i) => i.id));
+    frame.count(plural(body.invoices.length, 'invoice', 'invoices'));
     for (const id of state.ticked) if (!shown.has(id)) state.ticked.delete(id);
     drawTabs(body.counts);
     drawBar();
     if (!body.invoices.length) {
-      host.replaceChildren(h('p', { class: 'fx-empty' }, state.q
+      host.replaceChildren(h('p', { class: 'fx-empty' }, answer.invoices.length
+        ? 'No invoice in this tab passes the filter.'
+        : state.q
         ? 'No invoice matches that search.'
         : EMPTY[state.status] ?? `No ${TAB_LABEL[state.status].toLowerCase()} invoices.`));
       return;
     }
     // The invoice page steps through this list, in this order (navBar).
     saveNav({ tab: state.status, q: state.q, ids: body.invoices.map((i) => i.id) });
-    const open = (href) => { saveNav({ ...readNav(), scrollY: window.scrollY }); go(href); };
+    const open = (href) => { saveNav({ ...readNav(), scrollY: window.scrollY, frameY: frame.body.scrollTop }); go(href); };
     const link = (href, label) => h('a', { class: 'fx-strong', href, onclick: (event) => { event.preventDefault(); event.stopPropagation(); open(href); } }, label);
     const showProblem = state.status === 'pending';
     const created = ['pending', 'ready'].includes(state.status);
@@ -391,37 +462,47 @@ export async function renderInvoiceList(main, ui) {
       },
     });
     const statusCells = new Map();
-    host.replaceChildren(h('table', { class: 'fx-table fx-table--rows' },
-      h('thead', {}, h('tr', {},
-        h('th', { class: 'fx-tick-cell' }, all),
-        numbered ? h('th', {}, 'Number') : null, h('th', {}, 'Client'), h('th', {}, showProblem ? 'Problem' : 'Reference'),
-        h('th', {}, created ? 'Created' : 'Date'), h('th', { class: 'fx-num' }, 'Total'), h('th', {}, 'Status'),
-        linked ? h('th', {}, 'Linked') : null)),
-      h('tbody', {}, body.invoices.map((invoice) => {
-        const href = `/invoices/${invoice.id}`;
-        const first = invoice.problems?.[0];
-        return h('tr', { tabindex: '0', onclick: () => open(href), onkeydown: (event) => { if (event.key === 'Enter') open(href); } },
-          h('td', { class: 'fx-tick-cell', onclick: (event) => event.stopPropagation() }, tickBox(invoice)),
-          numbered ? h('td', {}, link(href, invoice.number ?? 'Draft')) : null,
-          h('td', {}, numbered ? (invoice.contactName ?? '—') : link(href, invoice.contactName ?? 'No client')),
-          showProblem
-            ? h('td', { class: 'fx-problem', title: invoice.problems.map((p) => p.message).join(' ') }, first?.short ?? first?.message ?? '—', invoice.problems.length > 1 ? h('span', { class: 'fx-dim' }, ` +${invoice.problems.length - 1}`) : null)
-            : h('td', { class: 'fx-dim' }, invoice.reference ?? '—'),
-          h('td', { class: 'fx-dim' }, showDate(invoice.issueDate ?? invoice.createdAt?.slice(0, 10))),
-          h('td', { class: 'fx-num fx-strong' }, formatCents(invoice.totalCents)),
-          (() => {
-            const cell = h('td', { class: 'fx-status-cell' }, invoice.sending
-              ? h('span', { class: 'fx-status', 'data-tone': 'info' }, 'Sending')
-              : h('span', { class: 'fx-status', 'data-tone': TAB_TONE[invoice.tab] ?? 'mute' }, TAB_LABEL[invoice.tab] ?? ''));
-            if (!linked) statusCells.set(invoice.id, cell);
-            return cell;
-          })(),
-          linked ? (() => {
-            const cell = h('td', { class: 'fx-links' }, systems.filter((s) => s.kind === 'work').map((s) => workIcon(ui, s, invoice.job)));
-            statusCells.set(invoice.id, cell);
-            return cell;
-          })() : null);
-      }))));
+    // The columns this tab has, in the person's order (columns.js).
+    const statusCell = (invoice) => {
+      const cell = h('span', {}, invoice.sending
+        ? h('span', { class: 'fx-status', 'data-tone': 'info' }, 'Sending')
+        : h('span', { class: 'fx-status', 'data-tone': TAB_TONE[invoice.tab] ?? 'mute' }, TAB_LABEL[invoice.tab] ?? ''));
+      if (!linked) statusCells.set(invoice.id, cell);
+      return cell;
+    };
+    const linkCell = (invoice) => {
+      const cell = h('span', { class: 'fx-links' }, systems.filter((s) => s.kind === 'work').map((s) => workIcon(ui, s, invoice.job)));
+      statusCells.set(invoice.id, cell);
+      return cell;
+    };
+    const problemCell = (invoice) => {
+      const first = invoice.problems?.[0];
+      return h('span', { class: 'fx-problem', title: invoice.problems.map((p) => p.message).join(' ') },
+        first?.short ?? first?.message ?? '—', invoice.problems.length > 1 ? h('span', { class: 'fx-dim' }, ` +${invoice.problems.length - 1}`) : null);
+    };
+    const href = (invoice) => `/invoices/${invoice.id}`;
+    const ALL = {
+      number: numbered ? { kind: 'number', cell: (i) => link(href(i), i.number ?? 'Draft') } : null,
+      client: { kind: 'client', cell: (i) => (numbered ? (i.contactName ?? '—') : link(href(i), i.contactName ?? 'No client')) },
+      reference: showProblem
+        ? { label: 'Problem', kind: 'text', cell: problemCell }
+        : { kind: 'text', className: 'fx-dim', cell: (i) => i.reference ?? '—' },
+      date: { label: created ? 'Created' : 'Date', kind: 'date', className: 'fx-dim', cell: (i) => showDate(i.issueDate ?? i.createdAt?.slice(0, 10)) },
+      total: { kind: 'total', num: true, className: 'fx-strong', cell: (i) => formatCents(i.totalCents) },
+      status: { kind: 'status', className: 'fx-status-cell', cell: statusCell },
+      linked: linked ? { kind: 'link', cell: linkCell } : null,
+    };
+    available = Object.keys(ALL).filter((id) => ALL[id]);
+    const columns = state.columns.columns.filter((id) => ALL[id]).map((id) => ({ id, label: INVOICE_COLUMNS[id], ...ALL[id] }));
+    host.replaceChildren(heads.table({
+      className: 'fx-table--rows',
+      columns,
+      lead: [h('th', { class: 'fx-tick-cell' }, all)],
+      rows: h('tbody', {}, body.invoices.map((invoice) => h('tr', { tabindex: '0', onclick: () => open(href(invoice)), onkeydown: (event) => { if (event.key === 'Enter') open(href(invoice)); } },
+        h('td', { class: 'fx-tick-cell', onclick: (event) => event.stopPropagation() }, tickBox(invoice)),
+        rowCells(h, columns, invoice),
+        h('td', { class: 'fx-c-end' })))),
+    }));
     // Issued and void invoices also show Xero's status, from Flow's copy:
     // in the Linked column every one gets an icon, so one not in Xero
     // stands out.
@@ -437,6 +518,7 @@ export async function renderInvoiceList(main, ui) {
   }
   await load();
   if (returning && back?.scrollY) window.scrollTo(0, back.scrollY);
+  if (returning && back?.frameY) frame.body.scrollTop = back.frameY;
 }
 
 // A file the browser saves, from a blob made on this page.
@@ -499,7 +581,8 @@ function navBar(ui, invoice) {
   return bar;
 }
 
-// After a send, an Approve or a Save as draft, the next invoice of the list
+// After a send, an Approve or a Save that makes a Pending invoice Ready, the
+// next invoice of the list
 // opens; at its end, the list. So a person reviews drafts one after another
 // without going back. The invoice stays in the bar's list, so the count holds
 // (2 of 35) and Previous opens it again, now done. Back reloads the list
@@ -595,9 +678,13 @@ function linkedCard(ui, invoice, accountingStatus = null) {
     facts);
 }
 
+// The first sentence of a problem: what is wrong. The red field shows where,
+// so the banner holds no how-to.
+const brief = (text) => String(text ?? '').match(/^.*?[.!?](?=\s|$)/s)?.[0] ?? String(text ?? '');
+
 // A draft, or a new invoice before its first save.
 function draftView(invoice, ui, context, redraw) {
-  const { h, flow, toast, go, notice } = ui;
+  const { h, flow, toast, go, notice, fieldError } = ui;
   const isNew = !invoice;
   const lines = (invoice?.lines ?? []).map((line) => ({ ...line }));
   if (!lines.length) lines.push({ description: '', quantity: 1, unitAmountCents: null, taxCode: 'GST', priceItemId: null });
@@ -636,9 +723,18 @@ function draftView(invoice, ui, context, redraw) {
   });
   clientInput.addEventListener('blur', () => { setTimeout(() => { clientList.hidden = true; }, 120); });
 
-  const reference = h('input', { class: 'fx-input', type: 'text', value: invoice?.reference ?? '', placeholder: 'Practitioner - Patient' });
+  const reference = h('input', { class: 'fx-input', type: 'text', value: invoice?.reference ?? '', placeholder: 'Type a reference', 'aria-label': 'Reference' });
   const dueDate = h('input', { class: 'fx-input', type: 'date', value: invoice?.dueDate ?? '' });
 
+  // The fields a failed check reads go red (problem.fields): a rule on the
+  // Reference marks the Reference box, a line with no price item marks its
+  // item. A check on something this page cannot change (the job's
+  // practitioner) marks nothing; the banner says it.
+  const problemList = invoice?.problems ?? [];
+  const failed = new Set(problemList.flatMap((p) => p.fields ?? []));
+  const badLines = new Set(problemList.filter((p) => p.fields?.includes('line_item')).map((p) => p.line));
+  const boxes = { reference };
+
   // Lines.
   let items = null;
   const itemsReady = flow('/api/invoicing/price-items').then((body) => { items = body.priceItems ?? body.items ?? []; return items; }).catch(() => { items = []; return items; });
@@ -665,9 +761,10 @@ function draftView(invoice, ui, context, redraw) {
       };
       showAmount();
       const item = h('input', {
-        class: 'fx-input', type: 'text', list: 'fx-price-items', placeholder: 'Code or name', autocomplete: 'off',
+        class: 'fx-input', type: 'text', list: 'fx-price-items', placeholder: 'Code', autocomplete: 'off',
         value: line.itemCode ?? '', 'aria-label': `Item, line ${index + 1}`,
       });
+      if (badLines.has(index + 1)) fieldError(item);
       const description = h('input', { class: 'fx-input', type: 'text', value: line.description ?? '', 'aria-label': `Description, line ${index + 1}` });
       const quantity = h('input', { class: 'fx-input fx-num', type: 'number', min: '1', step: '1', value: String(line.quantity ?? 1), 'aria-label': `Quantity, line ${index + 1}` });
       const price = h('input', { class: 'fx-input fx-num', type: 'text', inputmode: 'decimal', value: fromCents(line.unitAmountCents), placeholder: '0.00', 'aria-label': `Unit price, line ${index + 1}` });
@@ -693,7 +790,7 @@ function draftView(invoice, ui, context, redraw) {
       gst.addEventListener('change', () => { line.taxCode = gst.value; preview(); });
       const remove = h('button', {
         class: 'fx-btn fx-btn--ghost fx-btn--sm fx-btn--icon', type: 'button', title: 'Remove line', 'aria-label': `Remove line ${index + 1}`,
-        onclick: () => { lines.splice(index, 1); if (!lines.length) lines.push({ description: '', quantity: 1, unitAmountCents: null, taxCode: 'GST', priceItemId: null }); drawLines(); preview(); },
+        onclick: () => { badLines.clear(); lines.splice(index, 1); if (!lines.length) lines.push({ description: '', quantity: 1, unitAmountCents: null, taxCode: 'GST', priceItemId: null }); drawLines(); preview(); },
       }, '×');
       return h('tr', {},
         h('td', { class: 'fx-lines__item' }, item),
@@ -734,7 +831,7 @@ function draftView(invoice, ui, context, redraw) {
   });
 
   const check = () => {
-    if (!contact) return 'Choose a client from the list.';
+    if (!contact) { fieldError(clientInput); return 'Choose a client from the list.'; }
     if (lines.some((line) => (line.description?.trim() || line.priceItemId) && line.unitAmountCents == null)) return 'Each line needs a price.';
     return null;
   };
@@ -753,22 +850,38 @@ function draftView(invoice, ui, context, redraw) {
     }
   };
 
-  // Save shows only when there is something to save: a new invoice, or a
-  // change since the page opened. Save as draft opens the next invoice.
-  // Save as draft: a draft that is not ready always offers it. A ready
-  // invoice offers Save changes only once something changed.
+  // Save is the check, like CI: it saves, and Flow runs every check again
+  // (Flow's own, the lab's rules, the accounting system's). A Pending
+  // invoice that now passes is Ready: a toast says so and the next invoice
+  // of the list opens. One that still fails stays Pending, with its red
+  // fields. A new invoice and a Pending one always offer Save; a Ready one
+  // only once something changed. There is no Flow "draft" step: Draft is
+  // the accounting system's word for an invoice it holds.
   const keepsSave = isNew || invoice?.view !== 'ready';
   const saveButton = h('button', {
     class: 'fx-btn', type: 'button', hidden: !keepsSave,
     onclick: async () => {
+      saveButton.disabled = true;
       const saved = await save();
+      saveButton.disabled = false;
       if (!saved) return;
-      toast(keepsSave ? 'Saved as a draft.' : 'Changes saved.', 'success');
-      if (isNew) go(`/invoices/${saved.id}`, { replace: true });
-      else if (keepsSave) openNext(ui, invoice.id);
-      else redraw(saved);
+      const passes = saved.view === 'ready';
+      const why = brief(saved.problems?.[0]?.message);
+      if (isNew) {
+        toast(passes ? 'Saved. It is Ready.' : `Saved. It is Pending. ${why}`, passes ? 'success' : 'warn');
+        go(`/invoices/${saved.id}`, { replace: true });
+      } else if (passes && keepsSave) {
+        toast('Saved. It is Ready.', 'success');
+        openNext(ui, invoice.id);
+      } else if (passes) {
+        toast('Saved.', 'success');
+        redraw(saved);
+      } else {
+        toast(`Still Pending. ${why}`, 'danger');
+        redraw(saved);
+      }
     },
-  }, keepsSave ? 'Save as draft' : 'Save changes');
+  }, 'Save');
   const opened = JSON.stringify(body());
   const changed = () => !isNew && JSON.stringify(body()) !== opened;
   const watchChanges = () => { if (!keepsSave) saveButton.hidden = !changed(); };
@@ -852,8 +965,16 @@ function draftView(invoice, ui, context, redraw) {
   const problems = [
     // Accepting changes the draft for the business: owners and admins only.
     jobChange ? jobChangeReview(ui, jobChange, { money: formatCents, canAccept: context.canIssue, unsaved: changed, done: redraw }) : null,
-    otherProblems.length ? notice(otherProblems.map((p) => p.message).join(' '), 'danger', 'Problem.') : null,
+    otherProblems.length ? notice([...new Set(otherProblems.map((p) => brief(p.message)))].join(' '), 'danger', 'Problem.') : null,
   ];
+  // A red field names the banner as its reason (for a screen reader).
+  const banner = problems[1];
+  if (banner) banner.id = 'fx-invoice-problem';
+  for (const name of failed) {
+    if (!boxes[name]) continue;
+    fieldError(boxes[name]);
+    if (banner) boxes[name].setAttribute('aria-describedby', banner.id);
+  }
 
   return [
     navBar(ui, invoice),