@arcforgelabs/flow 2026.10.32-beta.1 → 2026.10.32

package/server/ui/invoicing.js

@@ -6,12 +6,13 @@
 // zero, server/core/money.js). Data comes from /api/invoicing
 // (server/api/invoicing.js). app.js passes in its shared pieces as `ui`.
 import { alertStrip } from '/assets/ui/alerts.js';
+import { draftNote, sendModeNote } from '/assets/ui/invoice-notes.js';
 
 const STATUS_LABEL = { draft: 'Draft', issued: 'Issued', void: 'Void' };
 const STATUS_TONE = { draft: 'info', issued: 'success', void: 'mute' };
 // Drafts (to check), Problem and Ready are views (server/core/sending.js):
-// every draft is in one of them. A person marks a checked draft ready; any
-// later change sends it back. An issued invoice that failed to send is a
+// every draft is in one of them. A person marks a checked draft ready; a
+// saved change keeps it there. An issued invoice that failed to send is a
 // problem.
 // Ready first: it opens by default, as the drafts most often wait there to send.
 const TABS = [['ready', 'Ready'], ['to_check', 'Drafts'], ['problem', 'Problem'], ['issued', 'Issued'], ['void', 'Void']];
@@ -75,29 +76,18 @@ function localDate(date = new Date()) {
 
 const showDate = (iso) => (iso ? new Date(`${iso}T00:00:00`).toLocaleDateString('en-AU', { day: 'numeric', month: 'short', year: 'numeric' }) : '—');
 
-// What happens to a ready invoice in the accounting system, one fact per
-// sentence. It follows the integration's settings: its connection, whether it
-// takes writes, and the send mode on its page.
-export function sendModeNote(to, sendMode) {
-  if (!to) return 'No accounting system is on. Flow keeps each invoice here only.';
-  if (sendMode && !sendMode.connected) return `${to} is not connected. Connect it in Integrations before you send.`;
-  if (sendMode && !sendMode.writesAllowed) return `${to} does not take invoices from Flow yet. Turn this on in Integrations, ${to}.`;
-  const text = sendMode?.mode === 'approve_and_email'
-    ? [`Flow sends each invoice to ${to} as approved.`, `${to} emails it to the customer at once.`]
-    : [`Flow sends each invoice to ${to} as a draft.`, `You approve and send it in ${to}.`];
-  const others = sendMode?.otherCustomers ?? 0;
-  if (others) text.push(`${others} ${others === 1 ? 'customer has' : 'customers have'} a different setting.`);
-  return text.join(' ');
-}
-
 // ── The list ───────────────────────────────────────────────────────────────
 
 export async function renderInvoiceList(main, ui) {
   const { h, flow, pageHeader, notice, go, toast } = ui;
   const saved = sessionStorage.getItem('flow_invoice_tab');
-  const state = { status: TABS.some(([id]) => id === saved) ? saved : 'ready', q: '', ticked: new Set() };
+  // 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 tabs = h('div', { class: 'fx-tabs', role: 'tablist' });
-  const search = h('input', { class: 'fx-input fx-search', type: 'search', placeholder: 'Find a number, client or reference', 'aria-label': 'Find an invoice' });
+  const search = h('input', { class: 'fx-input fx-search', type: 'search', placeholder: 'Find a number, client or reference', 'aria-label': 'Find an invoice', value: state.q });
   const bar = h('div', { class: 'fx-sendbar', hidden: true });
   const host = h('div', { class: 'fx-panel' }, h('div', { class: 'fx-skeleton' }));
   const context = await flow('/api/invoicing/context').catch(() => ({ canIssue: false }));
@@ -156,7 +146,7 @@ export async function renderInvoiceList(main, ui) {
       parts.push(h('p', { class: 'fx-dim' }, sendModeNote(to, body.sendMode)));
       const buttons = [];
       if (ticked.length) {
-        buttons.push(action(`Back to drafts (${ticked.length})`, 'mark-not-ready', () => ({ invoiceIds: ticked }),
+        buttons.push(action(`Move ${ticked.length} to Drafts`, 'mark-not-ready', () => ({ invoiceIds: ticked }),
           (res) => [`${plural(res.moved, 'invoice', 'invoices')} back in Drafts.`, 'success'], 'ghost'));
       }
       if (context.canIssue && body.counts.ready > 0) {
@@ -199,6 +189,9 @@ export async function renderInvoiceList(main, ui) {
         : EMPTY[state.status] ?? `No ${STATUS_LABEL[state.status].toLowerCase()} invoices yet.`));
       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 ticks = TICKS[state.status];
     const showProblem = state.status === 'problem';
     const created = ['to_check', 'problem', 'ready'].includes(state.status);
@@ -231,13 +224,13 @@ export async function renderInvoiceList(main, ui) {
         const href = `/invoices/${invoice.id}`;
         const first = invoice.problems?.[0];
         const view = invoice.status === 'void' ? null : invoice.view;
-        return h('tr', { tabindex: '0', onclick: () => go(href), onkeydown: (event) => { if (event.key === 'Enter') go(href); } },
+        return h('tr', { tabindex: '0', onclick: () => open(href), onkeydown: (event) => { if (event.key === 'Enter') open(href); } },
           ticks ? h('td', { class: 'fx-tick-cell', onclick: (event) => event.stopPropagation() }, tickBox(invoice)) : null,
-          h('td', {}, h('a', { class: 'fx-strong', href, onclick: go }, invoice.number ?? 'Draft')),
+          h('td', {}, h('a', { class: 'fx-strong', href, onclick: (event) => { event.preventDefault(); event.stopPropagation(); open(href); } }, invoice.number ?? 'Draft')),
           h('td', {}, invoice.contactName ?? '—'),
           showProblem
             ? h('td', { class: 'fx-problem' }, first?.message ?? '—', invoice.problems.length > 1 ? h('span', { class: 'fx-dim' }, ` +${invoice.problems.length - 1} more`) : null)
-            : h('td', { class: 'fx-dim' }, invoice.job?.caseRef ?? invoice.reference ?? '—'),
+            : 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)),
           (() => {
@@ -259,6 +252,51 @@ export async function renderInvoiceList(main, ui) {
     }
   }
   await load();
+  if (returning && back?.scrollY) window.scrollTo(0, back.scrollY);
+}
+
+// The list an invoice was opened from: its tab, search, invoice ids in order,
+// and scroll. The invoice page's bar steps through it and goes back to it.
+const NAV = 'flow_invoice_nav';
+const NAV_BACK = 'flow_invoice_back';
+function readNav() {
+  try { return JSON.parse(sessionStorage.getItem(NAV) ?? 'null'); } catch { return null; }
+}
+function saveNav(nav) {
+  try { sessionStorage.setItem(NAV, JSON.stringify(nav)); } catch { /* the bar then shows Back only */ }
+}
+
+// The bar above one invoice: Back to the list as it was, and the previous and
+// next invoice of that list.
+function navBar(ui, id) {
+  const { h, go } = ui;
+  const nav = readNav();
+  const ids = nav?.ids ?? [];
+  const at = ids.indexOf(id);
+  const back = () => { sessionStorage.setItem(NAV_BACK, '1'); go('/invoices'); };
+  const step = (to, label, path) => {
+    const button = h('button', {
+      class: 'fx-pager__step', type: 'button', disabled: !to, 'aria-label': label, title: label,
+      onclick: () => go(`/invoices/${to}`),
+    });
+    button.innerHTML = `<svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true"><path d="${path}" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/></svg>`;
+    return button;
+  };
+  return h('nav', { class: 'fx-pager', 'aria-label': 'Invoices' },
+    h('button', { class: 'fx-pager__back', type: 'button', onclick: back }, '← Back'),
+    at >= 0 ? h('span', { class: 'fx-pager__count' }, `${at + 1} of ${ids.length}`) : null,
+    at >= 0 ? h('span', { class: 'fx-pager__steps' }, step(ids[at - 1], 'Previous invoice', 'M14.5 6l-6 6 6 6'), step(ids[at + 1], 'Next invoice', 'M9.5 6l6 6-6 6')) : null);
+}
+
+// After a send, the next invoice of the list opens; at its end, the list.
+function openNext(ui, id) {
+  const nav = readNav();
+  const ids = nav?.ids ?? [];
+  const at = ids.indexOf(id);
+  const next = at >= 0 ? (ids[at + 1] ?? ids[at - 1]) : null;
+  if (at >= 0) saveNav({ ...nav, ids: ids.filter((other) => other !== id) });
+  if (next) ui.go(`/invoices/${next}`);
+  else { sessionStorage.setItem(NAV_BACK, '1'); ui.go('/invoices'); }
 }
 
 // ── One invoice ────────────────────────────────────────────────────────────
@@ -285,17 +323,11 @@ export async function renderInvoice(main, ui, id) {
   const draw = (current) => {
     host.replaceChildren(...(current?.status && current.status !== 'draft'
       ? issuedView(current, ui, context, draw)
-      : draftView(current, ui, context, draw)));
+      : draftView(current, ui, context, draw)).filter(Boolean));
   };
   draw(invoice);
 }
 
-function crumbs(ui, label) {
-  const { h, go } = ui;
-  return h('nav', { class: 'fx-crumbs', 'aria-label': 'Breadcrumb' },
-    h('a', { href: '/invoices', onclick: go }, 'Invoices'), h('span', { 'aria-hidden': 'true' }, '/'), h('span', {}, label));
-}
-
 function totalsBox(ui, { subtotalCents, taxCents, totalCents }) {
   const { h } = ui;
   return h('dl', { class: 'fx-totals' },
@@ -304,13 +336,13 @@ function totalsBox(ui, { subtotalCents, taxCents, totalCents }) {
     h('dt', { class: 'fx-totals__grand' }, 'Total'), h('dd', { class: 'fx-totals__grand' }, formatCents(totalCents)));
 }
 
+// The job an invoice bills. The case id stays on the record, not on screen.
 function jobCard(ui, job) {
   const { h } = ui;
   if (!job) return null;
   return h('section', { class: 'fx-card fx-side-card' },
     h('h3', { class: 'fx-label' }, 'Job'),
     h('dl', { class: 'fx-facts' },
-      h('dt', {}, 'Case'), h('dd', {}, job.caseRef ?? job.sourceJobRef),
       job.practitioner ? [h('dt', {}, 'Practitioner'), h('dd', {}, job.practitioner)] : null,
       job.shippedOn ? [h('dt', {}, 'Shipped'), h('dd', {}, showDate(job.shippedOn))] : null,
       h('dt', {}, 'From'), h('dd', {}, job.sourceSystem === 'seazona' ? 'Seazona' : job.sourceSystem)));
@@ -471,24 +503,56 @@ 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. Saving keeps the invoice where it is.
   const saveButton = h('button', {
-    class: 'fx-btn', type: 'button',
+    class: 'fx-btn', type: 'button', hidden: !isNew,
     onclick: async () => {
       const saved = await save();
       if (!saved) return;
-      toast('Draft saved.', 'success');
+      toast(isNew ? 'Draft saved.' : 'Changes saved.', 'success');
       if (isNew) go(`/invoices/${saved.id}`, { replace: true });
       else redraw(saved);
     },
-  }, 'Save draft');
-  const issueButton = context.canIssue ? h('button', {
+  }, isNew ? 'Save draft' : 'Save changes');
+  const opened = JSON.stringify(body());
+  const changed = () => !isNew && JSON.stringify(body()) !== opened;
+  const watchChanges = () => { if (!isNew) saveButton.hidden = !changed(); };
+  // With an accounting system on, a ready invoice is sent there: Flow issues
+  // it and queues it, the same as Send all ready. With none, Flow issues it
+  // and keeps it. A draft that is not ready has no send: mark it ready first.
+  const to = invoice?.sendsTo ?? null;
+  const ready = invoice?.view === 'ready';
+  const nextNumber = `${context.organisations[0]?.invoicePrefix ?? ''}${String(context.organisations[0]?.nextInvoiceNumber ?? '').padStart(4, '0')}`;
+  const emails = invoice?.sendMode?.mode === 'approve_and_email';
+  const sendButton = context.canIssue && to && ready ? h('button', {
+    class: 'fx-btn fx-btn--primary', type: 'button',
+    onclick: async () => {
+      if (changed() && !(await save())) return;
+      const ok = await ui.dialog({
+        title: `Send this invoice to ${to}?`,
+        body: h('p', {}, `It gets the next number (${nextNumber}). ${sendModeNote(to, invoice.sendMode, 'it')}`),
+        confirm: emails ? 'Send and email' : 'Send',
+      });
+      if (!ok) return;
+      try {
+        await flow('/api/invoicing/invoices/send-ready', { method: 'POST', body: JSON.stringify({ issueDate: localDate(), invoiceIds: [invoice.id] }) });
+        const { invoice: fresh } = await flow(`/api/invoicing/invoices/${invoice.id}`);
+        toast(`${fresh.number} is on the way to ${to}.`, 'success');
+        openNext(ui, invoice.id);
+      } catch (error) {
+        toast(error.message, 'danger');
+      }
+    },
+  }, emails ? `Send to ${to} and email` : `Send to ${to}`) : null;
+  const issueButton = context.canIssue && !to ? h('button', {
     class: 'fx-btn fx-btn--primary', type: 'button',
     onclick: async () => {
       const saved = await save();
       if (!saved) return;
       const ok = await ui.dialog({
         title: 'Issue this invoice?',
-        body: h('p', {}, `It gets the next number (${context.organisations[0]?.invoicePrefix ?? ''}${String(context.organisations[0]?.nextInvoiceNumber ?? '').padStart(4, '0')}) and is kept exactly as issued. To change it later, revise it.`),
+        body: h('p', {}, `It gets the next number (${nextNumber}). Flow keeps it exactly as issued. To change it later, revise it.`),
         confirm: 'Issue',
       });
       if (!ok) { if (isNew) go(`/invoices/${saved.id}`, { replace: true }); else redraw(saved); return; }
@@ -504,40 +568,51 @@ function draftView(invoice, ui, context, redraw) {
   }, 'Issue invoice') : null;
 
   // Mark ready: the draft is saved, then Flow checks it; one with a problem
-  // stays a draft. Back to drafts undoes it.
-  const ready = invoice?.view === 'ready';
-  const readyButton = isNew ? null : h('button', {
+  // stays a draft. Move to Drafts, on the Status card, undoes it.
+  const markReadyButton = isNew || ready ? null : h('button', {
     class: 'fx-btn', type: 'button',
     onclick: async () => {
-      const current = ready ? invoice : await save();
-      if (!current) return;
+      if (!(await save())) return;
       try {
-        if (ready) {
-          await flow('/api/invoicing/invoices/mark-not-ready', { method: 'POST', body: JSON.stringify({ invoiceIds: [invoice.id] }) });
-          toast('Back in Drafts.', 'success');
-        } else {
-          const res = await flow('/api/invoicing/invoices/mark-ready', { method: 'POST', body: JSON.stringify({ invoiceIds: [invoice.id] }) });
-          if (res.marked) toast('Ready to send.', 'success');
-          else toast(res.refused[0]?.problems.map((p) => p.message).join(' ') ?? 'It has a problem.', 'danger');
-        }
+        const res = await flow('/api/invoicing/invoices/mark-ready', { method: 'POST', body: JSON.stringify({ invoiceIds: [invoice.id] }) });
+        if (res.marked) toast('Ready to send.', 'success');
+        else toast(res.refused[0]?.problems.map((p) => p.message).join(' ') ?? 'It has a problem.', 'danger');
         const { invoice: fresh } = await flow(`/api/invoicing/invoices/${invoice.id}`);
         redraw(fresh);
       } catch (error) {
         toast(error.message, 'danger');
       }
     },
-  }, ready ? 'Back to drafts' : 'Mark ready');
+  }, 'Mark ready');
+  // A ready invoice can go back to Drafts. It is a status change, so it sits
+  // with the status, not with the page's main buttons.
+  const statusCard = ready ? h('section', { class: 'fx-card fx-side-card' },
+    h('h3', { class: 'fx-label' }, 'Status'),
+    h('p', {}, 'Ready to send.'),
+    h('button', {
+      class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button',
+      onclick: async () => {
+        try {
+          await flow('/api/invoicing/invoices/mark-not-ready', { method: 'POST', body: JSON.stringify({ invoiceIds: [invoice.id] }) });
+          toast('Moved to Drafts.', 'success');
+          const { invoice: fresh } = await flow(`/api/invoicing/invoices/${invoice.id}`);
+          redraw(fresh);
+        } catch (error) {
+          toast(error.message, 'danger');
+        }
+      },
+    }, 'Move to Drafts')) : null;
   const problems = invoice?.problems?.length
     ? notice(invoice.problems.map((p) => p.message).join(' '), 'danger', 'Problem.')
     : null;
 
   return [
-    crumbs(ui, isNew ? 'New invoice' : ready ? 'Ready' : 'Draft'),
+    navBar(ui, invoice?.id ?? null),
     h('header', { class: 'fx-ph' },
       h('div', { class: 'fx-ph__text' },
         h('h1', { class: 'fx-title' }, isNew ? 'New invoice' : ready ? 'Ready invoice' : 'Draft invoice'),
-        h('p', { class: 'fx-ph__sub' }, ready ? 'A person checked it. Send all ready issues it. A change sends it back to Drafts.' : 'The number is given when you issue it.')),
-      h('div', { class: 'fx-ph__actions' }, saveButton, readyButton, issueButton)),
+        h('p', { class: 'fx-ph__sub' }, draftNote(to, invoice, ready))),
+      h('div', { class: 'fx-ph__actions' }, saveButton, markReadyButton, sendButton ?? issueButton)),
     problems,
     h('div', { class: 'fx-invoice__grid' },
       h('div', { class: 'fx-invoice__main' },
@@ -556,8 +631,12 @@ function draftView(invoice, ui, context, redraw) {
           h('div', { class: 'fx-lines__foot' },
             h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button', onclick: () => { lines.push({ description: '', quantity: 1, unitAmountCents: null, taxCode: 'GST', priceItemId: null }); drawLines(); } }, '+ Add line'),
             totalsHost))),
-      h('aside', { class: 'fx-invoice__aside' }, jobCard(ui, invoice?.job))),
-  ];
+      h('aside', { class: 'fx-invoice__aside' }, statusCard, jobCard(ui, invoice?.job))),
+  ].map((part) => {
+    // Any edit on the page shows Save changes; undoing it hides it again.
+    for (const kind of ['input', 'change', 'click']) part?.addEventListener?.(kind, () => setTimeout(watchChanges));
+    return part;
+  });
 }
 
 // An issued or void invoice: the document as sent, and what can happen next.
@@ -601,7 +680,7 @@ function issuedView(invoice, ui, context, redraw) {
     sendToXero(invoice, ui, context),
   ] : [];
   return [
-    crumbs(ui, invoice.number),
+    navBar(ui, invoice.id),
     h('header', { class: 'fx-ph' },
       h('div', { class: 'fx-ph__text' },
         h('div', { class: 'fx-row' },
@@ -674,7 +753,7 @@ function xeroCard(invoice, ui, context, status, reload) {
 }
 
 // Send to Xero (POST /api/xero/invoices/push). The customer's send mode
-// (Settings, Invoicing) decides what Xero gets: a draft that a person approves
+// (Settings, Invoice rules) decides what Xero gets: a draft that a person approves
 // there, or an approved invoice that Xero emails to the customer.
 function sendToXero(invoice, ui, context) {
   const { h, flow, toast } = ui;

package/server/ui/routes.js

@@ -20,7 +20,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', 'invoicing-settings.js', 'automations.js', 'invoice-rules.js', 'line-mappings.js', 'price-list.js', 'jobs.js', 'job-board.js', 'monitoring.js', 'search.js', 'alerts.js', 'flow-mark.svg']);
+const UI_FILES = new Set(['flow.css', 'appearance.js', 'clerk-appearance.js', 'app.js', 'invoicing.js', 'invoice-notes.js', 'invoicing-settings.js', 'automations.js', 'invoice-rules.js', 'line-mappings.js', 'price-list.js', 'jobs.js', 'job-board.js', 'monitoring.js', 'search.js', 'alerts.js', 'flow-mark.svg']);
 const MAX_AGE = '1h';
 
 // Send one named file from dir. Passing dir as root limits the dotfile check