@arcforgelabs/flow 2026.10.46 → 2026.10.48-1

package/server/integrations/xero/drafts.js

@@ -5,7 +5,8 @@ import { getInvoice, listInvoiceVersions } from '../../core/invoices.js';
 import { sendModeFor } from '../../core/invoicing-rules.js';
 import { contacts as flowContacts, invoices as flowInvoices, priceItems } from '../../db/schema.js';
 import { readConnection } from './connections.js';
-import { itemsByCode, lastSuccessfulSyncAt, matchContact, normaliseName } from './catalogue.js';
+import { itemsByCode, lastSuccessfulSyncAt, matchContactFor, normaliseName } from './catalogue.js';
+import { writesAllowed } from './settings.js';
 import { xeroError } from './client.js';
 import { withXeroLane } from './governor.js';
 import { mirrorState } from './lookup.js';
@@ -24,8 +25,9 @@ import { mirrorState } from './lookup.js';
 //   version is never changed, here or in Xero: Flow never updates a Xero
 //   invoice. A revised invoice (version 2) goes to Xero only after the
 //   earlier version's Xero invoice is deleted or voided there.
-// - Flow never creates a Xero contact. The customer must match one Xero
-//   contact by name (the synced copy, catalogue.js).
+// - The customer must match one Xero contact, by the identity-map link or by
+//   name (the synced copy, catalogue.js). When Create missing clients is on,
+//   a missing contact can be created from the Flow contact (create-contact.js).
 // - Before it creates, Flow asks Xero for invoices with the same reference.
 //   One for the same contact and total is the same work: Flow records it and
 //   creates nothing. One for the same contact at another total within 90
@@ -66,6 +68,13 @@ function xeroDate(value) {
 
 const problem = (code, message, extra = {}) => ({ code, message, ...extra });
 
+function missingContact(name, { offerCreate }) {
+  const message = offerCreate
+    ? `No Xero contact is named "${name}". Create the client in Xero from this contact.`
+    : `No Xero contact is named "${name}". Add it in Xero, then sync.`;
+  return problem('xero_contact_missing', message, { short: 'Client not in Xero', ...(offerCreate ? { offerCreate: true } : {}) });
+}
+
 // ---------------------------------------------------------------------------
 // The document to send
 
@@ -288,8 +297,9 @@ async function previewOne(db, runtime, organisationId, invoiceId) {
   const problems = [];
   if (invoice.status === 'void') problems.push(problem('invoice_void', 'This invoice is void. Flow does not send it to Xero.'));
   if (invoice.status === 'draft') problems.push(problem('invoice_not_issued', 'This invoice is a draft. Issue it, then send it to Xero.'));
-  const match = await matchContact(db, organisationId, document.contact.name);
-  if (match.state === 'missing') problems.push(problem('xero_contact_missing', `No Xero contact is named "${document.contact.name}". Add it in Xero (Flow never creates Xero contacts), then sync.`, { short: 'Client not in Xero' }));
+  const match = await matchContactFor(db, organisationId, { contactId: invoice.contactId, name: document.contact.name });
+  const offerCreate = match.state === 'missing' && runtime.settings.createContacts && writesAllowed(runtime.settings);
+  if (match.state === 'missing') problems.push(missingContact(document.contact.name, { offerCreate }));
   if (match.state === 'ambiguous') problems.push(problem('xero_contact_ambiguous', `More than one Xero contact is named "${document.contact.name}". Merge or rename them in Xero, then sync.`, { short: 'Client twice in Xero' }));
   const items = await itemsByCode(db, organisationId, document.lines.map((l) => l.itemCode));
   const sendMode = await sendModeFor(db, organisationId, invoice.contactId);
@@ -389,7 +399,7 @@ export async function checkDrafts(db, runtime, { organisationId, invoiceIds }) {
     for (const preview of invoices) {
       found.set(preview.invoiceId, preview.problems
         .filter((p) => p.blocking !== false && p.code !== 'invoice_not_issued')
-        .map(({ code, message, short }) => ({ code, message, ...(short ? { short } : {}) })));
+        .map(({ code, message, short, offerCreate }) => ({ code, message, ...(short ? { short } : {}), ...(offerCreate ? { offerCreate: true } : {}) })));
     }
   }
   return found;
@@ -468,11 +478,12 @@ async function pushOne(db, runtime, client, organisationId, invoiceId, { pushedB
     }
   }
 
-  const match = await matchContact(db, organisationId, document.contact.name);
+  const match = await matchContactFor(db, organisationId, { contactId: invoice.contactId, name: document.contact.name });
   if (match.state !== 'matched') {
+    const offerCreate = match.state === 'missing' && runtime.settings.createContacts && writesAllowed(runtime.settings);
     throw xeroError(match.state === 'missing' ? 'xero_contact_missing' : 'xero_contact_ambiguous',
       match.state === 'missing'
-        ? `No Xero contact is named "${document.contact.name}". Add it in Xero (Flow never creates Xero contacts), then sync.`
+        ? missingContact(document.contact.name, { offerCreate }).message
         : `More than one Xero contact is named "${document.contact.name}". Merge or rename them in Xero, then sync.`,
       { status: 409 });
   }

package/server/integrations/xero/index.js

@@ -1,6 +1,8 @@
 import { fileURLToPath } from 'node:url';
 import { sql } from 'drizzle-orm';
 import { guardAlerts } from '../call-guard.js';
+import { deleteXeroInvoice } from './delete-invoice.js';
+import { createCustomer } from './create-contact.js';
 import { checkDrafts, documentFacts, pushInvoice, pushInvoices } from './drafts.js';
 import { readConnection } from './connections.js';
 import { createImportWorker } from './import.js';
@@ -41,6 +43,7 @@ export const XERO_SETUP = {
     { name: 'XERO_CLIENT_SECRET', label: 'Client secret', secret: true, help: 'Stored encrypted. Flow never shows it again.' },
     { name: 'XERO_TENANT_NAME', label: 'Xero organisation name', help: 'Live mode connects only the organisation with this exact name.' },
     { name: 'XERO_ALLOW_LIVE_WRITES', label: 'Create draft invoices in live Xero', kind: 'onoff', help: 'Off: Flow only reads from Xero.' },
+    { name: 'XERO_CREATE_CONTACTS', label: 'Create missing clients', kind: 'onoff', default: 'on', help: 'On: a pending invoice whose client is not in Xero offers Create. Off: add the client in Xero, then sync.' },
     { name: 'XERO_WEBHOOK_KEY', label: 'Webhook key', secret: true, help: 'From the Xero app\'s Webhooks page. Empty: Flow reads Xero\'s changes every 15 minutes instead.' },
   ],
   derivedKeys: ['XERO_TOKEN_KEY'],
@@ -115,6 +118,9 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       // One issued invoice to a Xero draft (drafts.js). The Flow invoice id
       // and version are the idempotency key.
       pushInvoice: ({ organisationId, invoiceId, pushedBy = null }) => pushInvoice(database, current(), { organisationId, invoiceId, pushedBy }),
+      // Read the linked Xero invoice, and delete it only while it is a draft
+      // (delete-invoice.js). The core voids in Flow after deleted or gone.
+      deleteInvoice: ({ organisationId, invoiceId, actor = null }) => deleteXeroInvoice(database, current(), { organisationId, invoiceId, actor }),
       // Several issued invoices, in batches of MAX_BATCH (drafts.js).
       pushInvoices: ({ organisationId, invoiceIds, pushedBy = null }) => pushInvoices(database, current(), { organisationId, invoiceIds, pushedBy }),
       // The Invoices page tab of each issued invoice (reconcile.js), from
@@ -141,6 +147,9 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       readChanges: ({ organisationId }) => readChangesFirst(database, current(), organisationId),
       // Active Xero contacts, from Flow's copy (lookup.js).
       listCustomers: ({ organisationId }) => listCustomers(database, organisationId),
+      // Create the Xero contact for one Flow contact, when that setting is on
+      // (create-contact.js). The Flow contact id is the idempotency key.
+      createCustomer: ({ organisationId, contactId, actor = null }) => createCustomer(database, current(), { organisationId, contactId, actor }),
       // Sales invoices from the mirror, with the mirror's state (lookup.js).
       findInvoices: ({ organisationId, ...query }) => findInvoices(database, organisationId, query),
       // Xero items, from Flow's copy, for the price list (lookup.js).

package/server/integrations/xero/migrations/0011_xero_invoice_deleted.sql

@@ -0,0 +1,11 @@
+-- Who deleted a Xero draft from Flow, and when. The push keeps Xero's status
+-- (DELETED or VOIDED). A link made on the Import page has no push, so it
+-- keeps the same who and when. The Xero adapter's own table: the core does
+-- not store this.
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN IF NOT EXISTS "deleted_by" text;
+--> statement-breakpoint
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN IF NOT EXISTS "deleted_at" timestamp with time zone;
+--> statement-breakpoint
+ALTER TABLE "xero_invoice_links" ADD COLUMN IF NOT EXISTS "deleted_by" text;
+--> statement-breakpoint
+ALTER TABLE "xero_invoice_links" ADD COLUMN IF NOT EXISTS "deleted_at" timestamp with time zone;

package/server/integrations/xero/migrations/0012_xero_contact_details.sql

@@ -0,0 +1,16 @@
+-- Billing fields on Flow's copy of a Xero contact, so a created client and
+-- a synced client keep the same record (docs/CONTACTS.md). The Xero adapter's
+-- own table: the core does not store this.
+ALTER TABLE "xero_contacts" ADD COLUMN IF NOT EXISTS "first_name" text;
+--> statement-breakpoint
+ALTER TABLE "xero_contacts" ADD COLUMN IF NOT EXISTS "last_name" text;
+--> statement-breakpoint
+ALTER TABLE "xero_contacts" ADD COLUMN IF NOT EXISTS "phone" text;
+--> statement-breakpoint
+ALTER TABLE "xero_contacts" ADD COLUMN IF NOT EXISTS "mobile" text;
+--> statement-breakpoint
+ALTER TABLE "xero_contacts" ADD COLUMN IF NOT EXISTS "account_number" text;
+--> statement-breakpoint
+ALTER TABLE "xero_contacts" ADD COLUMN IF NOT EXISTS "tax_number" text;
+--> statement-breakpoint
+ALTER TABLE "xero_contacts" ADD COLUMN IF NOT EXISTS "address" jsonb;

package/server/integrations/xero/migrations/meta/_journal.json

@@ -78,6 +78,20 @@
       "when": 1792530000000,
       "tag": "0010_xero_call_usage",
       "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1792540000000,
+      "tag": "0011_xero_invoice_deleted",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1792550000000,
+      "tag": "0012_xero_contact_details",
+      "breakpoints": true
     }
   ]
 }

package/server/integrations/xero/routes.js

@@ -4,6 +4,7 @@ import { FlowError } from '../../core/errors.js';
 import { createActionGuard } from '../call-guard.js';
 import { billingObligations, organisations } from '../../db/schema.js';
 import { lastSync, listContacts, listItems, syncCatalogue } from './catalogue.js';
+import { createCustomer, matchCustomer } from './create-contact.js';
 import { createXeroClient } from './client.js';
 import { describePush, listPushes, MAX_BATCH, previewDrafts, pushDrafts } from './drafts.js';
 import { recordXeroEvidence, recordXeroPayments } from './ledger.js';
@@ -27,6 +28,9 @@ import { messagePage as themedMessagePage } from '../../ui/page.js';
 //   POST /disconnect               owner: revokes and forgets the connection
 //   POST /sync                     owner or admin: copies Xero contacts and items
 //   GET  /contacts?organisationId=&q=   any signed-in person: the copy
+//   GET  /contacts/match?organisationId=&contactId=   any signed-in person:
+//                                  whether this Flow contact is in the copy
+//   POST /contacts                 owner or admin: create the Xero contact
 //   GET  /items?organisationId=    any signed-in person: the copy
 //   POST /invoices/preview         any signed-in person: the Xero drafts Flow
 //                                  would make, and what stops them (no Xero calls)
@@ -59,6 +63,7 @@ export const XERO_ACTIONS = Object.freeze({
   sync: { cooldownMs: 5 * 60_000 },
   recheck: { cooldownMs: 30_000 },
   push: { cooldownMs: 0, budget: false },
+  createContact: { cooldownMs: 30_000 },
   obligationCheck: { cooldownMs: 30_000 },
   paymentsSync: { cooldownMs: 5 * 60_000 },
   mirror: { cooldownMs: 2 * 60_000 },
@@ -272,6 +277,22 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
     res.json({ ok: true, contacts: await listContacts(db, organisationId, { q: typeof req.query.q === 'string' ? req.query.q : '' }) });
   }));
 
+  // Whether this Flow contact is a Xero contact, and whether Create is offered.
+  // No Xero calls: it reads Flow's copy.
+  router.get('/contacts/match', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.query.organisationId);
+    if (typeof req.query.contactId !== 'string' || !UUID.test(req.query.contactId)) throw new FlowError('invalid', 'contactId must be a Flow contact id');
+    res.json({ ok: true, ...(await matchCustomer(db, runtime, { organisationId, contactId: req.query.contactId })) });
+  }));
+
+  router.post('/contacts', ...manager, act('createContact', (req) => req.body?.contactId), handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    if (typeof req.body?.contactId !== 'string' || !UUID.test(req.body.contactId)) throw new FlowError('invalid', 'contactId must be a Flow contact id');
+    const result = await createCustomer(db, runtime, { organisationId, contactId: req.body.contactId, actor: `person:${req.person.id}` });
+    log.info?.(`[xero] organisation ${organisationId}: person ${req.person.id} ${result.outcome} Xero contact ${result.contact.xeroContactId} for Flow contact ${req.body.contactId}`);
+    res.status(result.outcome === 'created' ? 201 : 200).json({ ok: true, ...result });
+  }));
+
   router.get('/items', ...signedIn, handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.query.organisationId);
     res.json({ ok: true, items: await listItems(db, organisationId) });

package/server/integrations/xero/settings.js

@@ -171,6 +171,9 @@ export function resolveXeroSettings(env = process.env) {
     // Free text on Xero records (references, line descriptions) is the lab's
     // own data, and the Import matches on it. On unless the lab turns it off.
     keepReference: readOnOff(env, 'XERO_KEEP_REFERENCE', true),
+    // On unless the lab turns it off: a pending invoice whose client is not
+    // in Xero offers to create that client (docs/CONTACTS.md).
+    createContacts: readOnOff(env, 'XERO_CREATE_CONTACTS', true),
     mirrorPageSize: Math.min(readPositiveInteger(env, 'XERO_MIRROR_PAGE_SIZE', DEFAULT_MIRROR_PAGE_SIZE), MAX_MIRROR_PAGE_SIZE),
     // The share of the day's calls the mirror leaves for drafts and people.
     mirrorReserveFraction: readFraction(env, 'XERO_MIRROR_RESERVE_FRACTION', 0.3),

package/server/ui/alerts.js

@@ -33,8 +33,9 @@ export function alertStrip(ui, page, { onTab = () => {}, scope = null, onLoad =
     let action = null;
     if (first.action?.href && first.action.href !== location.pathname) action = h('a', { class: 'fx-alerts__action', href: first.action.href, onclick: go }, first.action.label);
     else if (first.action?.tab) action = h('button', { class: 'fx-alerts__action', type: 'button', onclick: () => onTab(first.action.tab) }, first.action.label);
+    const line = first.moneyAtRiskCents > 0 ? `${first.title} ${money.format(first.moneyAtRiskCents / 100)} at risk.` : first.title;
     element.replaceChildren(...[
-      h('p', { class: 'fx-alerts__text' },
+      h('p', { class: 'fx-alerts__text', title: line },
         first.title,
         first.moneyAtRiskCents > 0 ? h('span', { class: 'fx-alerts__money' }, ` ${money.format(first.moneyAtRiskCents / 100)} at risk.`) : null),
       action,

package/server/ui/app.js

@@ -10,6 +10,7 @@ import { getAppearance, onAppearanceChange, setAppearance, loadFonts } from '/as
 import { flowClerkAppearance } from '/assets/ui/clerk-appearance.js';
 import { ACCENT_PRESETS, normalizeAccent, THEME_FAMILIES, tokensFor } from '/assets/theme/themes.js';
 import { renderInvoice, renderInvoiceList } from '/assets/ui/invoicing.js';
+import { renderContacts } from '/assets/ui/contacts.js';
 import { automationSection, renderAutomations } from '/assets/ui/automations.js';
 import { renderInvoicingSettings, sendModeSection } from '/assets/ui/invoicing-settings.js';
 import { renderPriceList } from '/assets/ui/price-list.js';
@@ -25,6 +26,7 @@ import { alertStrip } from '/assets/ui/alerts.js';
 import { initialsOf, personLabel } from '/assets/ui/person.js';
 import { startTips } from '/assets/ui/tip.js';
 import { crumbs, dialog, edgeFade, fieldError, h, holdButton, linksOpenWith, listFrame, listHead, notice, pageHeader, rowMenu, sectionTitle, settingRow, tileCard, tileSection, toast } from '/assets/ui/kit.js';
+import { NAV_DEFAULT, NAV_LOCKED } from '/assets/ui/nav-pins.js';
 
 const $ = (id) => document.getElementById(id);
 
@@ -143,19 +145,21 @@ function roleSelect(value, attrs = {}) {
 
 let me = null;
 
-// Where each view sits: the sidebar, in this order, daily work first (no
-// `place`); the sidebar's More menu (`place: 'more'`, `more` names its Lucide
-// icon); the account menu (`place: 'account'`). `sidebar: false` views open
-// by link and Search only.
+// Where each view sits, in sidebar order, daily work first. No `place`: a
+// sidebar page, pinned until the person unpins it. `place: 'more'`: a sidebar
+// page that starts in More until they pin it. `place: 'account'`: the account
+// menu. `sidebar: false`: opened by a link or Search only. Jobs and Invoices
+// cannot be unpinned (nav-pins.js).
 const VIEWS = {
   jobs: { label: 'Jobs', icon: 'jobs', render: (main) => renderJobs(main, ui()) },
   invoices: { label: 'Invoices', icon: 'invoices', render: (main, id) => (id ? renderInvoice(main, ui(), id) : renderInvoiceList(main, ui())) },
+  contacts: { label: 'Contacts', icon: 'contacts', render: (main, id) => renderContacts(main, ui(), id) },
   reconcile: { label: 'Reconcile', icon: 'reconcile', render: (main, id) => renderReconcile(main, ui(), id) },
   'price-list': { label: 'Price list', icon: 'tag', render: (main, id) => (id === 'reconcile' ? renderPriceReconcile(main, ui()) : renderPriceList(main, ui())) },
   'invoicing-settings': { label: 'Rules', icon: 'rules', render: (main, id) => renderInvoicingSettings(main, ui(), id) },
-  automations: { label: 'Automations', icon: 'bolt', place: 'more', more: 'zap', render: (main) => renderAutomations(main, ui()) },
-  'custom-fields': { label: 'Custom fields', icon: 'fields', place: 'more', more: 'form-input', render: (main) => renderCustomFields(main, ui()) },
-  integrations: { label: 'Integrations', icon: 'plug', place: 'more', more: 'plug', ownerOnly: true, render: (main, id) => (id ? renderIntegration(main, id) : renderIntegrations(main)) },
+  automations: { label: 'Automations', icon: 'bolt', place: 'more', render: (main) => renderAutomations(main, ui()) },
+  'custom-fields': { label: 'Custom fields', icon: 'fields', place: 'more', render: (main) => renderCustomFields(main, ui()) },
+  integrations: { label: 'Integrations', icon: 'plug', place: 'more', ownerOnly: true, render: (main, id) => (id ? renderIntegration(main, id) : renderIntegrations(main)) },
   people: { label: 'People', icon: 'people', place: 'account', ownerOnly: true, render: renderPeople },
   // Not in the sidebar: "Manage account" in the account menu opens the same
   // Clerk profile. The page stays for links and Search.
@@ -169,6 +173,7 @@ const VIEWS = {
 const ICON_PATHS = {
   jobs: '<rect x="3" y="4" width="5" height="16" rx="1"/><rect x="10" y="4" width="5" height="11" rx="1"/><rect x="17" y="4" width="4" height="14" rx="1"/>',
   invoices: '<path d="M6 3h9l4 4v14H6z"/><path d="M14 3v5h5M9 13h7M9 17h5"/>',
+  contacts: '<rect x="3" y="4" width="18" height="16" rx="2"/><circle cx="9" cy="10" r="2"/><path d="M6 16c.4-1.6 1.5-2.4 3-2.4s2.6.8 3 2.4M14 9h5M14 13h4"/>',
   bolt: '<path d="M13 3L5 13h6l-1 8 8-10h-6z"/>',
   rules: '<path d="M3 6l2 2 4-4M3 16l2 2 4-4M13 6h8M13 12h8M13 18h8"/>',
   reconcile: '<path d="M4 8h13M13 4l4 4-4 4M20 16H7M11 12l-4 4 4 4"/>',
@@ -301,11 +306,7 @@ async function route() {
   const [view, id] = currentView();
   const path = id ? `/${view}/${id}` : `/${view}`;
   if (location.pathname !== path) history.replaceState(null, '', path);
-  for (const link of document.querySelectorAll('a[data-nav]')) {
-    link.setAttribute('aria-current', link.dataset.nav === view ? 'page' : 'false');
-  }
-  // More shows as current while one of its pages is open.
-  document.querySelector('[data-nav="more"]')?.setAttribute('aria-current', VIEWS[view].place === 'more' ? 'page' : 'false');
+  markNavCurrent(view);
   main.replaceChildren();
   main.className = 'fx-main';
   document.title = `${VIEWS[view].label} · Flow`;
@@ -359,26 +360,108 @@ function renderSignedOut() {
   });
 }
 
+// Sidebar pages this person may open. Account pages stay in the account menu.
+function sidebarViews() {
+  return Object.entries(VIEWS).filter(([, view]) => view.sidebar !== false && view.place !== 'account' && (!view.ownerOnly || me?.person.role === 'owner'));
+}
+
+// Null until the shell reads the account. Jobs and Invoices are always in it.
+let pinned = null;
+let pinEpoch = 0;
+let pinWrite = Promise.resolve();
+let morePanel = null;
+
+function pinSet() {
+  if (!pinned) {
+    pinned = new Set(me?.views?.nav?.pinned ?? NAV_DEFAULT);
+    for (const name of NAV_LOCKED) pinned.add(name);
+  }
+  return pinned;
+}
+
+function navLink(name, view) {
+  return h('a', { href: `/${name}`, 'data-nav': name, 'data-label': view.label, onclick: navigate }, icon(view.icon), h('span', { class: 'fx-nav__label' }, view.label));
+}
+
+// More is the current page while the open page is a sidebar page that is
+// not pinned, so it has no row of its own.
+function markNavCurrent(view = currentView()[0]) {
+  for (const link of document.querySelectorAll('a[data-nav]')) {
+    link.setAttribute('aria-current', link.dataset.nav === view ? 'page' : 'false');
+  }
+  const shown = [...document.querySelectorAll('a[data-nav]')].some((link) => link.dataset.nav === view);
+  const inSidebar = sidebarViews().some(([name]) => name === view);
+  document.querySelector('[data-nav="more"]')?.setAttribute('aria-current', inSidebar && !shown ? 'page' : 'false');
+}
+
+function syncSidebar() {
+  const nav = $('nav');
+  const moreButton = nav?.querySelector('[data-nav="more"]');
+  if (!moreButton) return;
+  for (const link of [...nav.querySelectorAll('a[data-nav]')]) link.remove();
+  const links = sidebarViews().filter(([name]) => pinSet().has(name)).map(([name, view]) => navLink(name, view));
+  if (links.length) moreButton.before(...links);
+  morePanel?.refresh?.();
+  drawMenu();
+  markNavCurrent();
+}
+
+function moreItems() {
+  const pins = pinSet();
+  return sidebarViews().map(([name, view]) => {
+    const on = pins.has(name);
+    const locked = NAV_LOCKED.includes(name);
+    return {
+      icon: icon(view.icon),
+      text: view.label,
+      run: () => { closeMenu(); go(`/${name}`); },
+      trailing: locked
+        ? { icon: 'pin', label: 'Pinned', pressed: true, locked: true }
+        : { icon: 'pin', label: on ? 'Unpin' : 'Pin', pressed: on, run: () => togglePin(name) },
+    };
+  });
+}
+
+function togglePin(name) {
+  if (NAV_LOCKED.includes(name)) return;
+  const next = new Set(pinSet());
+  if (next.has(name)) next.delete(name);
+  else next.add(name);
+  for (const locked of NAV_LOCKED) next.add(locked);
+  const epoch = ++pinEpoch;
+  pinned = next;
+  syncSidebar();
+  const body = { pinned: [...next] };
+  pinWrite = pinWrite.then(() => savePins(body, epoch), () => savePins(body, epoch));
+}
+
+async function savePins(body, epoch) {
+  try {
+    const saved = await flow('/api/me/views/nav', { method: 'PUT', body: JSON.stringify(body) });
+    if (epoch !== pinEpoch) return;
+    pinned = new Set(saved.view.pinned);
+    me.views = { ...(me.views ?? {}), nav: saved.view };
+    syncSidebar();
+  } catch (error) {
+    if (epoch !== pinEpoch) return;
+    pinned = new Set(me?.views?.nav?.pinned ?? NAV_DEFAULT);
+    for (const locked of NAV_LOCKED) pinned.add(locked);
+    syncSidebar();
+    toast(error.message, 'danger');
+  }
+}
+
 function renderShell() {
   document.body.dataset.state = 'signed-in';
   const nav = $('nav');
-  const items = [];
-  const more = [];
-  for (const [name, view] of Object.entries(VIEWS)) {
-    if (view.ownerOnly && me?.person.role !== 'owner') continue;
-    if (view.sidebar === false || view.place === 'account') continue;
-    if (view.place === 'more') more.push({ icon: view.more, text: view.label, run: () => { closeMenu(); go(`/${name}`); } });
-    else items.push(h('a', { href: `/${name}`, 'data-nav': name, 'data-label': view.label, onclick: navigate }, icon(view.icon), h('span', { class: 'fx-nav__label' }, view.label)));
-  }
-  // The rest of the setup pages, behind More (the shared ⋯ menu).
-  const [moreButton, morePanel] = rowMenu('More', more, { trigger: [icon('more'), h('span', { class: 'fx-nav__label' }, 'More')], className: 'fx-nav__more', align: 'start' });
+  const [moreButton, panel] = rowMenu('More', moreItems, { trigger: [icon('more'), h('span', { class: 'fx-nav__label' }, 'More')], className: 'fx-nav__more', align: 'start', place: 'side' });
+  morePanel = panel;
   Object.assign(moreButton.dataset, { nav: 'more', label: 'More' });
-  items.push(moreButton, morePanel);
   // "Report a problem" sits at the foot of the menu, above the account chip,
   // while Sentry and its report form are on (monitoring.js).
   const report = h('button', { type: 'button', class: 'fx-nav__report', 'data-nav': 'report', 'data-label': 'Report a problem', hidden: true },
     icon('flag'), h('span', { class: 'fx-nav__label' }, 'Report a problem'));
-  nav.replaceChildren(...items, report);
+  nav.replaceChildren(moreButton, panel, report);
   // Folded or narrow, the logo is the sidebar button: it shows the mark and
   // turns into the sidebar icon under the pointer or keyboard focus.
   const mark = h('span', { class: 'fx-toggle__mark', 'aria-hidden': 'true' });
@@ -387,7 +470,7 @@ function renderShell() {
   sidebar.classList.add('fx-toggle__icon');
   $('menu-toggle').replaceChildren(mark, sidebar);
   $('menu-toggle').onclick = toggleMenu;
-  drawMenu();
+  syncSidebar();
   // The sidebar foot shows who is signed in: photo or initial, then the name
   // (the email when the account has no name). It opens the account menu.
   // People (owners) and Appearance live in the account menu.
@@ -676,9 +759,10 @@ async function renderIntegration(main, id) {
       let input;
       if (field.kind === 'choice' || field.kind === 'onoff') {
         const choices = field.kind === 'onoff' ? [{ value: 'off', label: 'Off' }, { value: 'on', label: 'On' }] : field.choices;
-        input = h('select', { class: 'fx-select', disabled },
+        const fallback = field.kind === 'onoff' ? (field.default === 'on' || field.default === 'off' ? field.default : 'off') : '';
+        input = h('select', { class: 'fx-select', disabled, 'data-fallback': fallback },
           field.kind === 'choice' ? h('option', { value: '' }, 'Choose…') : null,
-          choices.map((c) => h('option', { value: c.value, selected: (field.value ?? (field.kind === 'onoff' ? 'off' : '')) === c.value }, c.label)));
+          choices.map((c) => h('option', { value: c.value, selected: (field.value ?? fallback) === c.value }, c.label)));
       } else if (field.secret) {
         input = h('input', { class: 'fx-input', type: 'password', autocomplete: 'off', disabled, placeholder: field.set ? 'Saved' : 'Paste it here' });
       } else {
@@ -701,7 +785,8 @@ async function renderIntegration(main, id) {
       for (const [name, { field, input }] of inputs) {
         const value = input.value.trim();
         if (field.secret) { if (value) out[name] = value; continue; }
-        if (value !== (field.value ?? (field.kind === 'onoff' ? 'off' : ''))) out[name] = value || null;
+        const fallback = input.dataset.fallback ?? (field.kind === 'onoff' ? 'off' : '');
+        if (value !== (field.value ?? fallback)) out[name] = value || null;
       }
       return out;
     };

package/server/ui/bulk-bar.js

@@ -9,16 +9,19 @@
 // bar for a screen reader ("Ticked invoices", "Ticked jobs"). state = { count, onClear,
 // groups: [[action]], more: [{ head, actions: [action] }] }; an action is
 // { icon, label, title?, run, primary?, iconOnly?, tone? }. title is the
-// long name, for the hover tip and the More menu. A count of 0 hides the
-// bar; Esc clears the ticks while it shows.
+// long name, for the hover tip and the More menu. run(working) may call
+// working('Sending') once the step really starts (after its dialog): the
+// pressed button then shows a spinner and that word until run ends. A count
+// of 0 hides the bar; Esc clears the ticks while it shows.
 import { lucide } from '/assets/ui/custom-fields.js';
+import { applyPhoneRule } from './mobile.js';
 
 let barCount = 0;
 
 export function bulkBar(ui, { label = 'Ticked invoices' } = {}) {
   const { h } = ui;
   const id = `fx-bulk-more-${++barCount}`;
-  const element = h('div', { class: 'fx-bulk', role: 'toolbar', 'aria-label': label, hidden: true });
+  const element = applyPhoneRule(h('div', { class: 'fx-bulk', role: 'toolbar', 'aria-label': label, hidden: true }), 'bulkBar');
   const panel = h('div', { class: 'fx-pop fx-bulk__more', id, popover: 'auto', role: 'menu' });
   let current = null;
   let busy = false;
@@ -27,14 +30,24 @@ export function bulkBar(ui, { label = 'Ticked invoices' } = {}) {
     if (busy) return;
     busy = true;
     element.setAttribute('aria-busy', 'true');
-    try { await action.run(); } finally {
+    // The step is on its way: its button (on the bar, or More's) spins.
+    const working = (word) => {
+      const pressed = [...element.querySelectorAll('.fx-bulk__act')].find((b) => b.dataset.action === action.label);
+      if (!pressed) return;
+      pressed.dataset.busy = '';
+      pressed.firstChild?.replaceWith(h('span', { class: 'fx-spinner fx-spinner--sm', 'aria-hidden': 'true' }));
+      const text = pressed.querySelector('.fx-bulk__word');
+      if (text && word) text.textContent = `${word}…`;
+    };
+    try { await action.run(working); } finally {
       busy = false;
       element.removeAttribute('aria-busy');
+      if (current) draw(current);
     }
   };
 
   const button = (action) => h('button', {
-    type: 'button',
+    type: 'button', 'data-action': action.label,
     class: `fx-bulk__act${action.primary ? ' fx-bulk__act--primary' : ''}${action.iconOnly ? ' fx-bulk__act--icon' : ''}`,
     ...(action.tone ? { 'data-tone': action.tone } : {}),
     ...(action.iconOnly ? { 'aria-label': action.title ?? action.label, 'data-tip': action.title ?? action.label } : action.title ? { title: action.title } : {}),

package/server/ui/columns.js

@@ -31,6 +31,7 @@
 // Jobs and on Invoices, where it is the invoice's job's value).
 import { lucide } from '/assets/ui/custom-fields.js';
 import { endWidth, LEAD_WIDTH, MAX_WIDTH, minWidth, moveColumn, TAIL_WIDTH, tableWidth, widthOf } from '/assets/ui/job-view.js';
+import { applyPhoneRule, assignPhoneSlots, phoneSlot } from './mobile.js';
 import { initialsOf } from '/assets/ui/person.js';
 
 const fullDate = (iso) => new Date(`${iso}T00:00:00`).toLocaleDateString('en-AU', { day: 'numeric', month: 'short', year: 'numeric' });
@@ -81,10 +82,12 @@ export function fieldColumn(h, field, { id, valueOf, people }) {
 // A row's cells for the shown columns: a class per kind, the label for
 // the phone layout, the full text as the cell's name on hover.
 export function rowCells(h, columns, row) {
-  return columns.map((c) => {
+  return assignPhoneSlots(columns).map((c) => {
+    const slot = phoneSlot(c);
     const td = h('td', {
       class: [`fx-c-${c.kind}`, c.num ? 'fx-num' : null, c.className].filter(Boolean).join(' '),
       'data-label': c.label,
+      ...(slot ? { 'data-phone-slot': slot } : {}),
     }, c.cell(row));
     // A cell stays on one line and ends in "…" when the column is narrow
     // (flow.css, .fx-table--sized); the whole text shows on hover.
@@ -173,7 +176,7 @@ export function columnTable(h, config) {
       h('colgroup', {}, leadCols, cols, endCol),
       h('thead', {}, h('tr', {}, lead, heads, tail)),
       rows);
-    const box = h('div', { class: 'fx-table-scroll' }, node);
+    const box = applyPhoneRule(h('div', { class: 'fx-table-scroll' }, node), 'columnTable');
     // The width the columns need; past the window the table scrolls
     // sideways. A browser shares spare width among fixed columns, so the
     // end column is sized here, and again when the window changes size.